`R/calc_monthly_cumulative_stats.R`

`calc_monthly_cumulative_stats.Rd`

Calculate cumulative monthly flow statistics for each month of the year of daily flow values from a daily streamflow
data set. Calculates statistics from all values from complete years, unless specified. Defaults to volumetric cumulative flows,
can use `use_yield`

and `basin_area`

to convert to area-based water yield. Returns a tibble with statistics.

```
calc_monthly_cumulative_stats(
data,
dates = Date,
values = Value,
groups = STATION_NUMBER,
station_number,
percentiles = c(5, 25, 75, 95),
use_yield = FALSE,
basin_area,
water_year_start = 1,
start_year,
end_year,
exclude_years,
months = 1:12,
transpose = FALSE
)
```

- 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.- percentiles
Numeric vector of percentiles to calculate. Set to

`NA`

if none required. Default`c(5,25,75,95)`

.- use_yield
Logical value indicating whether to calculate area-based water yield, in mm, instead of volumetric discharge. Default

`FALSE`

.- 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`

.- start_year
Numeric value of the first year to consider for analysis. Leave blank or set well before start date (i.e.

`1800`

) to use from the first year of the source data.- end_year
Numeric value of the last year to consider for analysis. Leave blank or set well after end date (i.e.

`2100`

) to use up to the last year of the source data.- exclude_years
Numeric vector of years to exclude from analysis. Leave blank or set to

`NULL`

to include all years.- months
Numeric vector of months to include in analysis. 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`

). Need to be consecutive months for given year/water year to work properly.- transpose
Logical value indicating whether to transpose rows and columns of results. Default

`FALSE`

.

A tibble data frame with the following columns, default units in cubic metres, or millimetres if use_yield and basin_area provided:

- Month
month (MMM-DD) of cumulative statistics

- Mean
monthly mean of all cumulative flows for a given month of the year

- Median
monthly mean of all cumulative flows for a given month of the year

- Maximum
monthly mean of all cumulative flows for a given month of the year

- Minimum
monthly mean of all cumulative flows for a given month of the year

- P'n'
each monthly n-th percentile selected of all cumulative flows for a given month of the year

Default percentile columns:

- P5
monthly 5th percentile of all cumulative flows for a given month of the year

- P25
monthly 25th percentile of all cumulative flows for a given month of the year

- P75
monthly 75th percentile of all cumulative flows for a given month of the year

- P95
monthly 95th percentile of all cumulative flows for a given month of the year

Transposing data creates a column of "Statistics" and subsequent columns for each year selected.

```
# Run if HYDAT database has been downloaded (using tidyhydat::download_hydat())
if (file.exists(tidyhydat::hy_downloaded_db())) {
# Calculate annual monthly cumulative volume statistics
calc_monthly_cumulative_stats(station_number = "08NM116")
# Calculate annual monthly cumulative volume statistics with default HYDAT basin area
calc_monthly_cumulative_stats(station_number = "08NM116",
use_yield = TRUE)
# Calculate annual monthly cumulative volume statistics with custom basin area
calc_monthly_cumulative_stats(station_number = "08NM116",
use_yield = TRUE,
basin_area = 800)
}
#> Warning: One or more years contained partial data and were excluded. Only years with complete data were used for calculations.
#> Warning: One or more years contained partial data and were excluded. Only years with complete data were used for calculations.
#> Warning: One or more years contained partial data and were excluded. Only years with complete data were used for calculations.
#> # A tibble: 12 × 10
#> STATION_NUM…¹ Month Mean Median Maximum Minimum P5 P25 P75 P95
#> <chr> <fct> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl>
#> 1 08NM116 Jan 3.60 2.87 20.5 1.06 1.57 2.43 4.09 6.41
#> 2 08NM116 Feb 6.90 5.81 30.7 2.16 3.27 4.49 7.39 12.4
#> 3 08NM116 Mar 12.5 10.6 47.8 3.86 6.11 7.94 14.6 23.3
#> 4 08NM116 Apr 37.1 33.6 92.6 9.86 13.2 24.4 44.4 74.4
#> 5 08NM116 May 122. 114. 208. 52.3 66.1 94.1 142. 196.
#> 6 08NM116 Jun 195. 198. 319. 95.3 104. 148. 233. 289.
#> 7 08NM116 Jul 215. 222. 377. 102. 111. 158. 255. 332.
#> 8 08NM116 Aug 222. 226. 390. 104. 115. 162. 271. 339.
#> 9 08NM116 Sep 229. 234. 405. 106. 118. 165. 282. 345.
#> 10 08NM116 Oct 236. 241. 422. 108. 122. 170. 287. 351.
#> 11 08NM116 Nov 242. 244. 433. 110. 127. 176. 292. 358.
#> 12 08NM116 Dec 247. 247. 439. 112. 130. 180. 297. 361.
#> # … with abbreviated variable name ¹STATION_NUMBER
```