seasonal_boxplot: Seasonal boxplots

Description

Annual time series for year of interest on top of long-term percentiles

Usage

seasonal_boxplot(swmpr_in, ...)
# S3 method for swmpr
seasonal_boxplot(
  swmpr_in,
  param = NULL,
  hist_rng = NULL,
  target_yr = NULL,
  criteria = NULL,
  free_y = FALSE,
  log_trans = FALSE,
  converted = FALSE,
  criteria_lab = "WQ Threshold",
  stat_lab = "Average",
  plot_title = FALSE,
  plot = TRUE,
  FUN = function(x) mean(x, na.rm = TRUE),
  ...
)

Arguments

swmpr_in

input swmpr object

...

additional arguments passed to other methods. See assign_season

param

chr string of variable to plot

hist_rng

numeric vector, if historic range is not specified then the min/max values of the data set will be used.

target_yr

numeric, the target year that should be compared against the historic range. If target year is not specified then dot will not be plotted

criteria

numeric, a numeric criteria that will be plotted as a horizontal line

free_y

logical, should the y-axis be free? Defaults to FALSE. If FALSE, defaults to zero, unless negative values are present. If TRUE, y-axis limits are selected by ggplot

log_trans

logical, should y-axis be log? Defaults to FALSE

converted

logical, were the units converted from the original units used by CDMO? Defaults to FALSE. See y_labeler for details.

criteria_lab

chr, label for the threshold criteria defined in criteria. Defaults to "WQ Threshold"

stat_lab

chr, label for the summary statistic defined in FUN. Defaults to "Average"

plot_title

logical, should the station name be included as the plot title? Defaults to FALSE

plot

logical, should a plot be returned? Defaults to TRUE

FUN

function used to aggregate daily SWMP data

Value

Returns a ggplot object or a data.frame if plot = FALSE

Details

This function uses boxplots to summarize statistics calculated on a daily basis across user-defined seasons for all years within the historic range (hist_rng). If hist_rng is not specified then the minimum and maximum years within the data set will be used. The summary statistics used to generate the boxplots are ggplot2 defaults: the center of the box is a median, and the lower/upper limits of the box are the 25-th and 75-th percentiles. The whiskers extend to the furthest data point within 1.5 * inter-quartile range (IQR). The dots beyond the whiskers are data points that are greater than 1.5 * IQR. If the user selects a target_yr, then a median summary statistic value will be plotted as a point against the boxplots.

Using the FUN argument, the user can specify the daily summary statistic to use. Commonly used statistics are min(x, na.rm = TRUE), mean(x, na.rm = TRUE), and max(x, na.rm = TRUE). After specifying FUN, the user should also specify stat_lab, which is used to construct appropriate legend labels.

The user also has the option to add a threshold hold line using the criteria argument. Typically, this value is a water quality threshold, which is why criteria_lab defaults to 'WQ Threshold'. Howver, the user has the option to specify any other type of threshold they wish. when doing so, the value for criteria_lab should be changed accordingly.

Examples

Run this code

# NOT RUN {
# }
# NOT RUN {
dat <- elksmwq
dat <- qaqc(dat, qaqc_keep = c('0', '3', '5'))

x <-
  seasonal_boxplot(dat, param = 'do_mgl')

y <-
    seasonal_boxplot(dat, param = 'do_mgl', target_yr = 2015,
    season_grps = list(c(1,2,3), c(4,5,6), c(7,8,9), c(10, 11, 12)),
    season_names = c('Winter', 'Spring', 'Summer', 'Fall'),
    season_start = 'Spring')

z_min <-
   seasonal_boxplot(dat, param = 'do_mgl',
   stat_lab = 'Minimum', FUN = function(x) min(x, na.rm = TRUE))

z_max <-
   seasonal_boxplot(dat, param = 'do_mgl',
   stat_lab = 'Maximum', FUN = function(x) max(x, na.rm = TRUE))
# }