`R/add_cumulative_yield.R`

`add_cumulative_yield.Rd`

Add a column of rolling daily cumulative water yields on an annual basis to a daily streamflow data set. Adds the
water yields from each day with the previous day(s) for each year, in units of millimetres. Converts cumulative
discharge to a depth of water based on the upstream drainage basin area from `basin_area`

argument. The cumulative flows
restart every year and are only calculated in years with complete data.

```
add_cumulative_yield(
data,
dates = Date,
values = Value,
groups = STATION_NUMBER,
station_number,
basin_area,
water_year_start = 1,
months = 1:12
)
```

- data
Data frame of daily data that contains columns of dates, flow values, and (optional) groups (e.g. station numbers). Leave blank or set to

`NULL`

if using`station_number`

argument.- dates
Name of column in

`data`

that contains dates formatted YYYY-MM-DD. Only required if dates column name is not 'Date' (default). Leave blank or set to`NULL`

if using`station_number`

argument.- values
Name of column in

`data`

that contains numeric flow values, in units of cubic metres per second. Only required if values column name is not 'Value' (default). Leave blank if using`station_number`

argument.- groups
Name of column in

`data`

that contains unique identifiers for different data sets, if applicable. Only required if groups column name is not 'STATION_NUMBER'. Function will automatically group by a column named 'STATION_NUMBER' if present. Remove the 'STATION_NUMBER' column beforehand to remove this grouping. Leave blank if using`station_number`

argument.- station_number
Character string vector of seven digit Water Survey of Canada station numbers (e.g.

`"08NM116"`

) of which to extract daily streamflow data from a HYDAT database. Requires`tidyhydat`

package and a HYDAT database. Leave blank if using`data`

argument.- basin_area
Upstream drainage basin area, in square kilometres, to apply to observations. Three options:

(1) Leave blank if

`groups`

is STATION_NUMBER with HYDAT station numbers to extract basin areas from HYDAT.(2) A single numeric value to apply to all observations.

(3) List each basin area for each group/station in groups (can override HYDAT value if listed) as such

`c("08NM116" = 795, "08NM242" = 10)`

. If group is not listed the HYDAT area will be applied if it exists, otherwise it will be`NA`

.- water_year_start
Numeric value indicating the month (

`1`

through`12`

) of the start of water year for analysis. Default`1`

.- months
Numeric vector of months to add cumulative flows. For example,

`3`

for March,`6:8`

for Jun-Aug or`c(10:12,1)`

for first four months (Oct-Jan) when`water_year_start = 10`

(Oct). Default summarizes all months (`1:12`

).

A tibble data frame of the source data with an additional column:

- Cumul_Yield_mm
cumulative yield flows for each day for each year, in units of millimetres

```
# Run if HYDAT database has been downloaded (using tidyhydat::download_hydat())
if (file.exists(tidyhydat::hy_downloaded_db())) {
# Add a column based on water years starting in August
add_cumulative_yield(station_number = "08NM116",
water_year_start = 8)
# Add a column based on water years starting in August with a custom basin area to calculate yield
add_cumulative_yield(station_number = "08NM116",
water_year_start = 8,
basin_area = 800)
}
#> # A tibble: 23,079 × 6
#> STATION_NUMBER Date Parameter Value Symbol Cumul_Yield_mm
#> <chr> <date> <chr> <dbl> <chr> <dbl>
#> 1 08NM116 1949-04-01 Flow 1.13 E NA
#> 2 08NM116 1949-04-02 Flow 1.53 E NA
#> 3 08NM116 1949-04-03 Flow 2.07 E NA
#> 4 08NM116 1949-04-04 Flow 2.07 E NA
#> 5 08NM116 1949-04-05 Flow 2.21 E NA
#> 6 08NM116 1949-04-06 Flow 2.21 NA NA
#> 7 08NM116 1949-04-07 Flow 2.27 NA NA
#> 8 08NM116 1949-04-08 Flow 2.35 NA NA
#> 9 08NM116 1949-04-09 Flow 2.78 NA NA
#> 10 08NM116 1949-04-10 Flow 2.94 NA NA
#> # … with 23,069 more rows
```