PlotBasinOutput: Plot a suite of time series plots from a HYPE basin output file

Description

Plot a standard suite of time series plots from a basin output file, typically used for model performance inspection and/or during manual calibration

Usage

PlotBasinOutput(
  x,
  filename,
  driver = c("default", "pdf", "png", "screen"),
  timestep = attr(x, "timestep"),
  hype.vars = "all",
  vol.err = TRUE,
  log.q = FALSE,
  start.mon = 1,
  from = 1,
  to = nrow(x),
  date.format = "",
  name = "",
  area = NULL,
  subid = attr(x, "subid"),
  gd = NULL,
  bd = NULL,
  ylab.t1 = "Conc."
)

Value

Returns a multi-panel plot in a new graphics device.

Arguments

x: Data frame, with column-wise equally-spaced time series of HYPE variables. Date-times in POSIXct format in first column. Typically an imported basin output file from HYPE using ReadBasinOutput. See details for HYPE output variables required for plotting.
filename: String, file name for plotting to file device, see argument driver. No file extension! Ignored with plotting to screen device. Device dimensions are currently hard-coded, see Details.
driver: String, device driver name, one of default, pdf, png, or screen. Defaults to default, which plots using default plotting device getOption("device").
timestep: Character string, timestep of x, one of "month", "week", "day", or "nhour" (n = number of hours). If not provided, an attribute timestep is required in x.
hype.vars: Either a keyword string or a character vector of HYPE output variables. User-specified selection of HYPE variables to plot. Default ("all") is to plot all variables which the function knows and which are available in x. See details for a list of known variables. Other possible keywords are "hydro" and "wq" (water quality), for which a pre-selected range of (available) result variables is plotted. Alternatively, a character vector holding HYPE output variables to be plotted. Variables unknown to the function will be ignored with a warning.
vol.err: Logical, if TRUE and both observed and simulated discharge are available in x, the accumulated volume error will be plotted.
log.q: Logical, y-axis scaling for flow duration curve and discharge time series, set to TRUE for log-scaling.
start.mon: Integer between 1 and 12, starting month of the hydrological year. For runoff regime plot, see also AnnualRegime.
from, to: Integer or date string of format \ interpreted as row indices of x.
date.format: String format for x-axis dates/times. See strptime.
name: Character string, name to be printed on the plot.
area: Numeric, upstream area of sub-basin in m^2. Required for calculation of accumulated volume error. Optional argument, either this or arguments subid, gd, and bd are required.
subid: Integer, HYPE SUBID of a target sub-catchment (must exist in gd). Mandatory in combination with gd and optionally bd if argument area is not defined. If not provided, an attribute subid is required in x. Used to calculate upstream area internally with function SumUpstreamArea. For repeated calls to PlotBasinOutput providing area in combination with a one-off separate call to SumUpstreamArea saves computation time, especially in basins with many upstream sub-basins.
gd: A data frame, containing 'SUBID' and 'MAINDOWN' columns, e.g. an imported 'GeoData.txt' file. Mandatory with argument subid, details see there.
bd: A data frame, containing 'BRANCHID' and 'SOURCEID' columns, e.g. an imported 'BranchData.txt' file. Optional with argument subid, details see there.
ylab.t1: String or plotmath expression, y axis label for T1 tracer time series panel (tracer concentration units are not prescribed in HYPE).

Details

PlotBasinOutput plots a suite of time series along with a flow duration curve, a flow regime plot, and a selection of goodness-of-fit measures from an imported HYPE basin output file. The function selects from a range of "known" variables, and plots those which are available in the user-supplied basin output. It is mostly meant as a support tool during calibration, manual or automatic, providing a quick and comprehensive overview of model dynamics in a subbasin of interest.

HYPE outputs which are known to PlotBasinOutput include:

precipitation
air temperature
discharge
lake water level
water temperature
evapotranspiration
snow water equivalent
sub-surface storage components
nitrogen concentrations
phosphorus concentrations
suspended sediment concentrations
total sediment concentrations
tracer concentration

Below a complete list of HYPE variables known to the function in HYPE info.txt format, ready to copy-paste into an info.txt file. For a detailed description of the variables, see the HYPE online documentation.

basinoutput variable upcprf upcpsf temp upepot upevap cout rout soim sm13 upsmfp snow upcprc cct2 ret2 ccin rein ccon reon cctn retn ccsp resp ccpp repp cctp retp wcom wstr ccss ress ccts rets cct1 ret1

Device dimensions are hard-coded to a width of 15 inches and height depending on the number of plotted time series. When plotting to a screen device, a maximum height of 10 inches is enforced in order to prevent automatic resizing with slow redrawing. PlotBasinOutput throws a warning if the plot height exceeds 10 inches, which can lead to overlapping plot elements. On screens with less than 10 inch screen, redrawing is inhibited, which can lead to an empty plot. The recommended solution for both effects is to plot to pdf or png file devices instead.

Examples

Run this code

# Source data, HYPE basin output with a number of result variables
te1 <- ReadBasinOutput(filename = system.file("demo_model",
"results","0003587.txt", package = "HYPEtools"))
te2 <- ReadGeoData(filename = system.file("demo_model",
"GeoData.txt", package = "HYPEtools"))

if (FALSE) { 
# Plot selected water variables on screen device
PlotBasinOutput(x = te1, gd = te2, driver = "screen",hype.vars = c("cout", "rout", 
"snow", "upcprf", "upcpsf"))
}