PlotSimObsRegime: Plot annual regimes of simulated and observed variables

Description

A combined plot for annual regimes with box plot elements for observed variables and ribbon elements for simulated variables. Particularly designed for comparisons of sparse observations with high-density model results, e.g. for in-stream nutrients.

Usage

PlotSimObsRegime(
  x,
  sim,
  obs,
  ts.in = NULL,
  ts.out = "month",
  start.mon = 1,
  add.legend = TRUE,
  pos.legend = "topright",
  inset = 0,
  l.legend = NULL,
  log = FALSE,
  ylim = NULL,
  xlab = NULL,
  ylab = NULL,
  mar = c(3, 3, 1, 1) + 0.1
)

Value

PlotSimObsRegime returns a plot to the currently active plot device, and invisibly a list object containing three elements with the plotted data and variable IDs. Element obs contains a list as returned by AnnualRegime. Element obs contains a list with two elements, a vector refdate with x positions of box plots elements, and a list reg.obs with observations for the monthly box plot elements. Element variable contains a named vector with HYPE variable IDs for observations and simulations. sim and obs returned empty if corresponding function argument was NULL.

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.
sim, obs: Character string keywords, observed and simulated HYPE variable IDs to plot. Not case-sensitive, but must exist in x. Set to NULL to omit corresponding elements in plot.
ts.in: Character string, timestep of x, searches for an attribute timestep in x per default. Otherwise one of "month", "week", "day", or "nhour" (n = number of hours).
ts.out: Character string, aggregation timestep for simulation results, defaults to ts.in. This timestep must be equal to or longer than ts.in.
start.mon: Integer between 1 and 12, starting month of the hydrological year, used to order the output.
add.legend: Logical. If TRUE, a legend will be added to the plot.
pos.legend: Character string keyword for legend positioning. See Details in link{legend}.
inset: Integer, legend inset as fraction of plot region, one or two values for x and y. See link{legend}.
l.legend: Character vector of length 2 containing variable labels for legend, first for sim, then for obs. If non-NULL, variable labels are read from here instead of sim and obs.
log: Logical, if TRUE, y-axis will be log-scaled.
ylim: Numeric vector of length two, giving y-axis limits. Defaults to min-max range of all plotted data.
xlab: Character string or plotmath expression string, x-axis label. Defaults to a string giving the time period on which the regime is based.
ylab: Character or plotmath expression string. Y-axis label. Defaults to a HYPE variable unit string taken from x attributes 'hypeunit'.
mar: Numeric vector of length 4, margin specification passed to par.

Details

PlotSimObsRegime combines ribbons and box plot elements. Box plot elements are composed as defaults from boxplot, i.e. boxes with 25\ extreme values as points. Observation counts per month over the observation period are printed above the x-axis.

Aggregation time length of the simulated variable can be chosen in argument ts.out, resulting in more or less smoothed ribbons. For the observed variable, the aggregation is fixed to months, in order to aggregate enough values for each box plot element.

Examples

Run this code

# Plot observed and simulated discharge
te <- ReadBasinOutput(filename = system.file("demo_model",
"results", "0003587.txt", package = "HYPEtools"))
PlotSimObsRegime(x = te, sim = "cout", obs = "rout", start.mon = 10)