Skip to content

Commit dadc22b

Browse files
lou-herautlou-heraut
committed
rename and reshape CARD (sorry)
1 parent c815e28 commit dadc22b

1 file changed

Lines changed: 2 additions & 217 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 217 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# EXstat [<img src="figures/flower_hex.png" align="right" width=160 height=160 alt=""/>](https://github.com/louis-heraut/EXstat.CARD)
1+
# EXstat [<img src="figures/flower_hex.png" align="right" width=160 height=160 alt=""/>](https://github.com/louis-heraut/CARD)
22

33
<!-- badges: start -->
44
[![R-CMD-check](https://github.com/louis-heraut/EXstat/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/louis-heraut/EXstat/actions/workflows/R-CMD-check.yaml)
@@ -9,7 +9,7 @@
99

1010
**EXstat** is a R package which provide an efficient and simple solution to aggregate and analyze the stationarity of time series.
1111

12-
EXstat is highly customizable, but the **EXstat.CARD** extension provides a simpler solution for performing common hydroclimatic aggregations. See the [EXstat.CARD documentation](#extraction-process-with-card) or the [EXstat.CARD package](https://github.com/louis-heraut/EXstat.CARD) for advance understanding.
12+
EXstat is highly customizable, but the **CARD** extension provides a simpler solution for performing common hydroclimatic aggregations. See the [CARD documentation]() of the [CARD package](https://github.com/louis-heraut/CARD) for advance understanding.
1313

1414
This project was carried out for National Research Institute for Agriculture, Food and the Environment (Institut National de Recherche pour l’Agriculture, l’Alimentation et l’Environnement, [INRAE](https://agriculture.gouv.fr/inrae-linstitut-national-de-recherche-pour-lagriculture-lalimentation-et-lenvironnement) in french) and is at the core of [MAKAHO](https://github.com/louis-heraut/MAKAHO) which won the [2024 Open Science Research Data Award](https://www.enseignementsup-recherche.gouv.fr/fr/remise-des-prix-science-ouverte-des-donnees-de-la-recherche-2024-98045) in the “Creating the Conditions for Reuse” category.
1515

@@ -20,12 +20,6 @@ For latest development version
2020
remotes::install_github("louis-heraut/EXstat")
2121
```
2222

23-
And for [EXstat.CARD](https://github.com/louis-heraut/EXstat.CARD) extension latest development version
24-
``` R
25-
remotes::install_github("louis-heraut/EXstat.CARD")
26-
```
27-
(which will take care of EXstat installation also)
28-
2923

3024
## Documentation
3125
### Extraction process
@@ -134,215 +128,6 @@ library(EXstat)
134128
```
135129

136130

137-
### Extraction process with [CARD](https://github.com/louis-heraut/EXstat.CARD/)
138-
For a more user-friendly interaction, this package has been developed in symbiosis with predefined parameterisation files called CARD.
139-
140-
So you don't have to define complex parameters yourself to extract hydroclimatological variables. What's more, if the CARD you want doesn't exist, it's easy to create one based on the others.
141-
142-
To use CARD extraction with EXstat you need to install the [EXstat.CARD extension](https://github.com/louis-heraut/EXstat.CARD) as follows :
143-
``` R
144-
remotes::install_github("louis-heraut/EXstat.CARD")
145-
```
146-
147-
148-
#### Basic workflow
149-
For example, in hydrology, if you want to extract the annual mean daily discharge QA from hydrometric data
150-
``` R
151-
install.packages("airGRdatasets")
152-
library(dplyr)
153-
154-
data = tibble(airGRdatasets::A273011002$TS) %>%
155-
mutate(code="A273011002",
156-
Date=as.Date(Date)) %>%
157-
rename(Q=Qls)
158-
```
159-
160-
you can simply run
161-
``` R
162-
res = CARD_extraction(data, CARD_name="QA")
163-
```
164-
165-
which will return
166-
``` R
167-
> res
168-
$metaEX
169-
# A tibble: 1 × 19
170-
variable_en unit_en name_en description_en method_en sampling_period_en
171-
<chr> <chr> <chr> <chr> <chr> <chr>
172-
1 QA m^{3}.s^{-1} Annual… "" 1. annua… 09-01, 08-31
173-
# ℹ 13 more variables: topic_en <chr>, variable_fr <chr>, unit_fr <chr>,
174-
# name_fr <chr>, description_fr <chr>, method_fr <chr>,
175-
# sampling_period_fr <chr>, topic_fr <chr>,
176-
# preferred_hydrological_month <dbl>, is_date <lgl>, to_normalise <lgl>,
177-
# palette <chr>, script_path <chr>
178-
179-
$dataEX
180-
$dataEX$QA
181-
# A tibble: 21 × 3
182-
code Date QA
183-
<chr> <date> <dbl>
184-
1 A273011002 1998-09-01 NA
185-
2 A273011002 1999-09-01 7048.
186-
3 A273011002 2000-09-01 6409.
187-
4 A273011002 2001-09-01 6403.
188-
5 A273011002 2002-09-01 4850.
189-
6 A273011002 2003-09-01 3768.
190-
7 A273011002 2004-09-01 5044.
191-
8 A273011002 2005-09-01 4805.
192-
9 A273011002 2006-09-01 7095.
193-
10 A273011002 2007-09-01 5575.
194-
# ℹ 11 more rows
195-
# ℹ Use `print(n = ...)` to see more rows
196-
```
197-
198-
So the result is a list of the metadata of the extraction in the `metaEX` tibble and the result of the extraction in the `dataEX` tibble.
199-
200-
Many CARDs are available. If you want to have a look of every current possibilities, use the `CARD_list_all()` function
201-
``` R
202-
metaEX_all = CARD_list_all()
203-
```
204-
which gives
205-
``` R
206-
> metaEX_all
207-
# A tibble: 565 × 20
208-
variable_en unit_en name_en description_en method_en sampling_period_en
209-
<chr> <chr> <chr> <chr> <chr> <chr>
210-
1 ETPA mm Cumula… "" "" 09-01, 08-31
211-
2 BFI_Wal withou… Basefl… "Ratio betwe…" "1. no …" NA
212-
3 BFM withou… Basefl… "" "1. no …" NA
213-
4 delta{BFI}_LH_… withou… Change… "Ratio betwe…" "1. no …" NA
214-
5 delta{BFI}_LH_… withou… Change… "Ratio betwe…" "1. no …" NA
215-
6 delta{BFI}_LH_… withou… Change… "Ratio betwe…" "1. no …" NA
216-
7 delta{BFI}_Wal… withou… Change… "Ratio betwe…" "1. no …" NA
217-
8 delta{BFI}_Wal… withou… Change… "Ratio betwe…" "1. no …" NA
218-
9 delta{BFI}_Wal… withou… Change… "Ratio betwe…" "1. no …" NA
219-
10 delta{centerBF… day Averag… "Date when 5…" "1. ann…" 09-01, 08-31
220-
# ℹ 555 more rows
221-
# ℹ 14 more variables: topic_en <chr>, variable_fr <chr>, unit_fr <chr>,
222-
# name_fr <chr>, description_fr <chr>, method_fr <chr>,
223-
# sampling_period_fr <chr>, topic_fr <chr>, source <chr>,
224-
# preferred_hydrological_month <int>, is_date <lgl>, to_normalise <lgl>,
225-
# palette <chr>, script_path <chr>
226-
# ℹ Use `print(n = ...)` to see more rows
227-
```
228-
229-
Based on that, you can for example filter variables by their topic with
230-
``` R
231-
metaEX_low_flow = dplyr::filter(metaEX_all, grepl("Low Flow", topic_en))
232-
```
233-
and get the name of all those available CARDs with
234-
``` R
235-
metaEX_low_flow$variable_en
236-
```
237-
238-
239-
#### Complex workflow
240-
In a similar, more complex way, you can extract multiple variables at a time with more than one discharge series,
241-
``` R
242-
# For one station
243-
data1 = tibble(airGRdatasets::A273011002$TS) %>%
244-
mutate(code="A273011002",
245-
Date=as.Date(Date)) %>%
246-
rename(Q_obs=Qls)
247-
248-
# and an other
249-
data2 = tibble(airGRdatasets::H622101001$TS) %>%
250-
mutate(code="H622101001",
251-
Date=as.Date(Date)) %>%
252-
rename(Q_obs=Qls)
253-
# make one tibble
254-
data = bind_rows(data1, data2)
255-
256-
# add some noise for mock simulation data
257-
data$Q_sim = data$Q_obs + rnorm(nrow(data), mean=0, sd=100)
258-
259-
# and perfom an extraction
260-
res = CARD_extraction(data,
261-
CARD_name=c("QA", "QMNA", "VCN10-5"),
262-
suffix=c("obs", "sim"))
263-
```
264-
265-
which will return
266-
``` R
267-
> res
268-
$metaEX
269-
# A tibble: 3 × 19
270-
variable_en unit_en name_en description_en method_en sampling_period_en
271-
<chr> <chr> <chr> <chr> <chr> <chr>
272-
1 VCN10-5 m^{3}.s^{-1} Annual… "" "1. no t…" "Month of maximum …"
273-
2 QMNA m^{3}.s^{-1} Annual… "" "1. mont…" "Month of maximum …"
274-
3 QA m^{3}.s^{-1} Annual… "" "1. annu…" 09-01, 08-31
275-
# ℹ 13 more variables: topic_en <chr>, variable_fr <chr>, unit_fr <chr>,
276-
# name_fr <chr>, description_fr <chr>, method_fr <chr>,
277-
# sampling_period_fr <chr>, topic_fr <chr>,
278-
# preferred_hydrological_month <dbl>, is_date <lgl>, to_normalise <lgl>,
279-
# script_path <chr>, palette <chr>
280-
281-
$dataEX
282-
$dataEX$`VCN10-5`
283-
# A tibble: 2 × 3
284-
code `VCN10-5_obs` `VCN10-5_sim`
285-
<chr> <dbl> <dbl>
286-
1 A273011002 914. 901.
287-
2 H622101001 2770. 2769.
288-
289-
$dataEX$QMNA
290-
# A tibble: 40 × 4
291-
code Date QMNA_obs QMNA_sim
292-
<chr> <date> <dbl> <dbl>
293-
1 A273011002 1999-01-01 1050. 1070.
294-
2 A273011002 2000-01-01 2586. 2569.
295-
3 A273011002 2001-01-01 1401. 1408.
296-
4 A273011002 2002-01-01 1463. 1454.
297-
5 A273011002 2003-01-01 1182. 1167.
298-
6 A273011002 2004-01-01 1362. 1354.
299-
7 A273011002 2005-01-01 1245. 1264.
300-
8 A273011002 2006-01-01 1770 1778.
301-
9 A273011002 2007-01-01 1889. 1875.
302-
10 A273011002 2008-01-01 1669. 1659.
303-
# ℹ 30 more rows
304-
# ℹ Use `print(n = ...)` to see more rows
305-
306-
$dataEX$QA
307-
# A tibble: 42 × 4
308-
code Date QA_obs QA_sim
309-
<chr> <date> <dbl> <dbl>
310-
1 A273011002 1998-09-01 NA NA
311-
2 A273011002 1999-09-01 7048. 7049.
312-
3 A273011002 2000-09-01 6409. 6419.
313-
4 A273011002 2001-09-01 6403. 6407.
314-
5 A273011002 2002-09-01 4850. 4842.
315-
6 A273011002 2003-09-01 3768. 3763.
316-
7 A273011002 2004-09-01 5044. 5045.
317-
8 A273011002 2005-09-01 4805. 4805.
318-
9 A273011002 2006-09-01 7095. 7093.
319-
10 A273011002 2007-09-01 5575. 5562.
320-
# ℹ 32 more rows
321-
# ℹ Use `print(n = ...)` to see more rows
322-
```
323-
324-
325-
#### Custom workflow
326-
Maybe you can't find the CARD that you want so you want to try to customize one or even create a new one based on another example. To do so, get the example CARD you want in a local directory by running
327-
```R
328-
CARD_management(CARD_name = c("VCN10-5"), CARD_path = "CARD-WIP")
329-
```
330-
This will create the `VCN10-5.R` CARD in the `"CARD-WIP"` directory of your working directory.
331-
332-
From there, you can open this R file and, for example, change the metadata and the return period parameter from `5` to `10` to get the `VCN10-10` CARD, which represents the annual minimum of 10-day mean daily discharge with a return period of 10 years instead of 5.
333-
334-
For the extraction, simply run
335-
```R
336-
res = CARD_extraction(data, CARD_name = NULL,
337-
CARD_path = "CARD-WIP")
338-
```
339-
This will perform the extraction of all the CARDs in the `CARD_path` directory.
340-
341-
If you want to select specific variables to extract from your custom CARD directory, just use the `CARD_name` variable as seen in the [basic workflow](#basic-workflow) section.
342-
343-
For a deeper understanding of the CARD formatting, refer to the [EXstat.CARD documentation](https://github.com/louis-heraut/EXstat.CARD?tab=readme-ov-file#exstatcard-).
344-
345-
346131
### Trend analyse
347132
The stationarity analyse is computed with the `process_trend()` function on the extracted data `dataEX`. The **statistical test** used here is the **Mann-Kendall test**[^mann][^kendall].
348133

0 commit comments

Comments
 (0)