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
)

## Arguments

data |
Data frame of daily data that contains columns of dates, flow values, and (optional) groups (e.g. station numbers).
Leave blank 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 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` . |

## Value

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

Cumul_Yield_mmcumulative yield flows for each day for each year, in units of millimetres

## Examples

#> # A tibble: 21,983 x 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 21,973 more rows