R: Plot annual high and low flows for a specific year

plot_annual_extremes_year {fasstr}

R Documentation

Plot annual high and low flows for a specific year

Description

Plots an annual hydrograph for a specific year with the values and timing of annual n-day low and high flows. The 'normal' range of percentiles also plotted for reference and are calculated from only years of complete data. Shows the values and dates of max/mins for a specific year from the calc_annual_extremes() and plot_annual_extremes() functions. Can remove either low or high flows using plot_min = FALSE() or plot_max = FALSE(), respectively. Returns a list of plots.

Usage

plot_annual_extremes_year(
  data,
  dates = Date,
  values = Value,
  groups = STATION_NUMBER,
  station_number,
  year_to_plot = NA,
  roll_days = 1,
  roll_days_min = NA,
  roll_days_max = NA,
  roll_align = "right",
  water_year_start = 1,
  start_year,
  end_year,
  exclude_years,
  months = 1:12,
  months_min = NA,
  months_max = NA,
  log_discharge = TRUE,
  log_ticks = FALSE,
  include_title = FALSE,
  plot_normal_percentiles = TRUE,
  normal_percentiles = c(25, 75),
  plot_min = TRUE,
  plot_max = TRUE,
  complete_years = FALSE,
  ignore_missing = FALSE,
  allowed_missing = ifelse(ignore_missing, 100, 0)
)

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.
`year_to_plot`	Numeric value indicating the year/water year to plot flow data with normal category colours. Default `NA`.
`roll_days`	Numeric value of the number of days to apply a rolling mean. Default `1`.
`roll_days_min`	Numeric value of the number of days to apply a rolling mean for low flows. Will override 'roll_days' argument for low flows. Default `NA`.
`roll_days_max`	Numeric value of the number of days to apply a rolling mean for high flows. Will override 'roll_days' argument for high flows. Default `NA`.
`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'`.
`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 specific months to plot. For example, `3` for March, `6:8` for Jun-Aug. Will be overridden for low or high flow statistics if `months_min` or `months_max` set, but will still define the date limits on the x-axis. Default plots all months (`1:12`).
`months_min`	Numeric vector of specified months for window of low flows (3 for March, 6:8 for Jun-Aug). Will override 'months' argument for low flows. Default `NA`.
`months_max`	Numeric vector of specified months for window of high flows (3 for March, 6:8 for Jun-Aug). Will override 'months' argument for high flows. Default `NA`.
`log_discharge`	Logical value to indicate plotting the discharge axis (Y-axis) on a logarithmic scale. Default `FALSE`.
`log_ticks`	Logical value to indicate plotting logarithmic scale ticks when `log_discharge = TRUE`. Ticks will not appear when `log_discharge = FALSE`. Default to `TRUE` when `log_discharge = TRUE`.
`include_title`	Logical value to indicate adding the group/station number to the plot, if provided. Default `FALSE`.
`plot_normal_percentiles`	Logical value indicating whether to plot the normal percentiles ribbon. Default `TRUE`.
`normal_percentiles`	Numeric vector of two values, lower and upper percentiles, respectively indicating the limits of the normal range. Default `c(25,75)`.
`plot_min`	Logical value indicating whether to plot annual low flows. Default `TRUE`.
`plot_max`	Logical value indicating whether to plot annual high flows. Default `TRUE`.
`complete_years`	Logical values indicating whether to include only years with complete data in analysis. Default `FALSE`.
`ignore_missing`	Logical value indicating whether dates with missing values should be included in the calculation. If `TRUE` then a statistic will be calculated regardless of missing dates. If `FALSE` then only those statistics from time periods with no missing dates will be returned. Default `FALSE`.
`allowed_missing`	Numeric value between 0 and 100 indicating the percentage of missing dates allowed to be included to calculate a statistic (0 to 100 percent). If `'ignore_missing = FALSE'` then it defaults to `0` (zero missing dates allowed), if `'ignore_missing = TRUE'` then it defaults to `100` (any missing dates allowed); consistent with `ignore_missing` usage. Supersedes `ignore_missing` when used.

Value

A list of ggplot2 objects with the following for each station provided:

Annual_Extremes_Year

a plot that contains the an annual hydrograph and identified low and high flow periods

Examples

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

# Plot the year 2000 with the annual maximum and minimums       
plot_annual_extremes_year(station_number = "08NM116",
                          roll_days_max = 3,
                          roll_days_min = 7,
                          year_to_plot = 2001)
                 
}