add_rolling_means {fasstr}

Add rolling n-day average column(s) to daily flows

Description

Adds selected n-day rolling means to a daily streamflow data set. Based on selected n-days and alignment, the rolling mean for a given day is obtained by averaging the adjacent dates of daily mean values. For example, rolling days of '7' and 'right' alignment would obtain a mean of the given and previous 6 days of daily mean flow.

Usage

add_rolling_means(
  data,
  dates = Date,
  values = Value,
  groups = STATION_NUMBER,
  station_number,
  roll_days = c(3, 7, 30),
  roll_align = "right"
)

Arguments

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.

roll_days

Numeric values of the number of days to apply a rolling mean. Default c(3,7,30).

roll_align

Character string identifying the direction of the rolling mean from the specified date, either by the first ('left'), last ('right'), or middle ('center') day of the rolling n-day group of observations. Default 'right'.

Value

A data frame of the source data with an additional column(s):

QnDay

rolling means of the n-day flow values of the designated date and adjacent dates, direction of mean specified by roll_align

Default additional columns:

Q3Day

rolling means of the 3-day flow values of the designated date and previous 2 days (roll_align = "right")

Q7Day

rolling means of the 7-day flow values of the designated date and previous 6 days (roll_align = "right")

Q30Day

rolling means of the 30-day flow values of the designated date and previous 29 days (roll_align = "right")

Examples

# Run if HYDAT database has been downloaded (using tidyhydat::download_hydat())
if (file.exists(tidyhydat::hy_downloaded_db())) {

# Add default 3, 7, and 30-day rolling mean columns, with "right" alignment
add_rolling_means(station_number = "08NM116")

# Add custom 5 and 10-day rolling mean columns
add_rolling_means(station_number = "08NM116",
                  roll_days = c(5,10))
                  
# Add default 3, 7, and 30-day rolling mean columns, with "left" alignment
add_rolling_means(station_number = "08NM116",
                  roll_align = "left")                
                  
}