hydrometContinuous: Continuous hydromet data plotting

In YukonWRB/WRBplots: Make pretty, standardized plots for a variety of WRB uses

Continuous hydromet data plotting

Description

Generate plots of water level/flow, snow pillows, or other continuous data present in the local hydrometric database generated by package WRBdatabase. For any given start/end day of year. Integrates return periods if requested. Intended to supersede WRBfloods::levelPlot() and WRBfloods::flowPlot(): see details.

Notice: in many cases, you're better off using the Shiny app at WRBfloods::hydroApp() to generate and export your plot. Read on if you need additional control over the final product.

This function plots data from the local hydrometric database (maintained by the WRBdatabase package) and yields consistent-looking plots for continuous data. This function can only plot what's in the database, use the function DB_browse_ts() to see what's in there first. Plots will include bands representing the historic min, max, and 25th-75th percentiles based on the last year of data requested. If necessary for performance, data may be down-sampled to daily means: see details.

Usage

hydrometContinuous(
  location,
  parameter,
  startDay = 1,
  endDay = 365,
  tzone = "MST",
  years = NULL,
  datum = TRUE,
  title = TRUE,
  returns = "auto",
  return_type = "max",
  return_months = c(5:9),
  return_max_year = max(years) - 1,
  allowed_missing = 10,
  plot_scale = 1,
  save_path = NULL,
  dbPath = "default"
)

Arguments

location	The location for which you want a plot.
parameter	The parameter you wish to plot. The location:parameter combo must be in the local database.
startDay	The start day of year for the plot x-axis. Can be specified as a number from 1 to 365, as a character string of form "yyyy-mm-dd", or as a date object. Either way the day of year is the only portion used, specify years to plot under parameter years.
endDay	The end day of year for the plot x-axis. As per startDay.
tzone	The timezone to use for graphing. Only really evident for a small number of days.
years	The years to plot. If startDay and endDay cover December 31 - January 1, select the December year(s). Max 10 years, NULL = current year.
datum	Should a vertical datum be applied to the data, if available? TRUE or FALSE.
title	Should a title be included?
returns	Should returns be plotted? You have the option of using pre-determined level returns only (option "table"), auto-calculated values(option "calculate"), "auto" (priority to "table", fallback to "calculate"), or "none". Defaults to "auto".
return_type	Use minimum ("min") or maximum ("max") values for returns?
return_months	Numeric vector of months during which to look for minimum or maximum values. Only works with calculated returns. Does not have to be within startDay and endDay, but will only consider data up to the last year specified in years. For months overlapping the new year like November-April, should look like c(11:12,1:4). IMPORTANT: the first month in the range should be the first element of the vector: c(1:4, 11:12) would not be acceptable. Think of it as defining a season. Passed to 'months' argument of fasstr::calc_annual_extremes() and also used to set the 'water_year_start' parameter of this function.
return_max_year	The last year of data to consider when calculating returns. Default uses all years prior to the last year plotted, giving historical context. Cannot be greater than the last year plotted but can be earlier than the first.
allowed_missing	Allowable % of data missing during the months specified in 'return_months' to still retain the year for analysis when calculating returns. Passed to 'allowed_missing' argument of fasstr::calc_annual_extremes().
plot_scale	Adjusts/scales the size of plot text elements. 1 = standard size, 0.5 = half size, 2 = double the size, etc. Standard size works well in a typical RStudio environment.
save_path	Default is NULL and the graph will be visible in RStudio and can be assigned to an object. Option "choose" brings up the File Explorer for you to choose where to save the file, or you can also specify a save path directly.
dbPath	The path to the local hydromet database, passed to hydroConnect().

Details

Superseded functions WRBfloods::levelPlot() and WRBfloods::flowPlot() can be used in the event that this function does not yield your desired graph, or if you cannot use the local database and must use data directly from the Water Survey of Canada.

Down sampling of data

When requesting time periods where high-frequency (realtime) data is available, some of the data may be displayed as daily means instead to improve performance. Specifically, only day ranges of less than 60 days will have high-frequency data (61 days or more will be plotted with daily means). Additionally, daily means will be fetched once the number of high-frequency rows exceeds 20 000 after year specified under parameter years (this will plot up to two 60-day lines at 5 minute recording intervals). In all cases, high-frequency data will be fetched nearest to the specified endDate.

Return periods:

Return periods generated using the "calculate" option are calculated using all available after applying the parameter return_max_year. Extreme values are isolated for each year and passed to fasstr::compute_frequency_analysis() using a Log Pearson Type 3 distribution and the method of moments to fit a curve to the distribution. Years (or rather periods within years; see below) missing more than the percentage of data specified in allowed_missing are excluded from consideration.

As the time of year during which minimum or maximum values happen is variable and to prevent filtering out years that are missing irrelevant data (most rivers peak in spring, some peak in late summer, snow pack peaks in winter), the parameters return_months and allowed_missing should be carefully selected. This may require you to make a graph first to evaluate when the annual min/max of interest happens. Consider as well that you can ask for return periods specific for a month or season, such as return periods of minimum flows in September, or maximum flows in January. This also applies to levels or any other continuous parameter which this function can plot.

If specifying the option "table", the function will attempt to find returns for the location within the package internal data. The returns contained there are from consultant work involving a detailed analysis of which data to keep/discard, as well as a human determination of the most appropriate distribution and curve fitting methods. The caveat here is that these tables are not necessarily up to date, that most locations have no calculated return periods, and that return periods only exist for water levels.

Value

A .png file of the plot requested (if a save path has been selected), plus the plot displayed in RStudio. Assign the function to a variable to also get a plot in your global environment as a ggplot object which can be further modified

YukonWRB/WRBplots documentation built on Sept. 29, 2023, 2:05 p.m.