PlotSimObsRegime {HYPEtools}

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
)

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.

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.

See Also

PlotAnnualRegime for a more generic annual regime plot, AnnualRegime to compute annual regimes only.

Examples

# 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)