Standardized plot functions for HydroBOT. — plot

Provides a common interface to plotting of an outcome_col, which may be plotted on y or fill/color or both. Handles consistent data preparation steps for that outcome variable, along with error and data checking. This keeps data arrangement in-function and controlled for consistency and accuracy, no matter what plot type is desired. Currently supports lines, points, bars, maps, and heatmaps. All plots are just standardizatons of ggplot2::ggplot(), and return ggplot objects that can then be tweaked with standard ggplot calls. Unlike ggplot, arguments that would typically go in ggplot2::aes() should not be bare names, but characters.

Usage

plot_outcomes(
  outdf,
  outcome_col,
  outcome_lab = outcome_col,
  y_col = outcome_col,
  y_lab = y_col,
  x_col = "scenario",
  x_lab = x_col,
  colorset = "scenario",
  pal_list = "scico::berlin",
  pal_direction = rep(1, length(pal_list)),
  colorgroups = NULL,
  color_lab = ifelse(is.null(colorgroups), colorset, colorgroups),
  plot_type = "2d",
  facet_row = NULL,
  facet_col = NULL,
  facet_wrapper = NULL,
  point_group = NULL,
  sceneorder = NULL,
  scales = "fixed",
  transoutcome = "identity",
  transy = "identity",
  transx = "identity",
  zero_adjust = 0,
  position = "stack",
  map_outlinecolor = "grey35",
  base_list = NULL,
  smooth_arglist = NULL,
  underlay_list = NULL,
  overlay_list = NULL,
  contour_arglist = NULL,
  setLimits = NULL
)

Arguments

outdf

dataframe of outcomes

outcome_col

character, name of outcome column. This is the data of interest being plotted. All data operations in plot_data_prep() happen to this column, and plot_style_prep() bases styling on it. For 2d plots, it is the y-axis, and for maps, heatmaps, and network plots, it is color/fill. It is entirely possible to also use it as color/fill for 2d plots in addition to the y-axis.

outcome_lab

character, default outcome_col, allows changing label of the outcome_col (y-axis or color/fill)

y_col

character, default outcome_col. Allows separately specifying y-axis from outcome (e.g. maps, heatmaps, networks)

y_lab

character, default y_col, allows changing y-label

x_col

character, name of column for the x-axis. Default 'scenario'

x_lab

character, default x_col, allows changing x-label

colorset

character, column name to use for color or fill

pal_list

list of palettes for defining colors for colorset. Should be length of colorgroups

pal_direction

vector of length pal_list, either 1 (default) or -1 (reversed) direction of the palettes

colorgroups

character, column name for grouping colorset to allow multiple palettes. Default NULL just uses colorset to define color

color_lab

character, default either colorgroups or colorset (if is.null(colorgroups)). Allows changing the color legend label

plot_type

one of '2d' (default), 'heatmap', 'contour', 'map', or 'network'. Typically, '2d' can be inferred. Both 'heatmap' and 'contour' call plot_heatmap, but do so differently. 'network' is being held for future use (use make_causal_plot() in the interim)

facet_row

NULL (default) or character for facet row. Can be '.' to have one row and column-facets

facet_col

NULL (default) or character for facet column. Can be '.' to have one column and row-facets

facet_wrapper

NULL (default) or character for column to use for facet_wrap

point_group

character, column to add additional point groupings to, e.g. if plotting color by an environmental group, but need separate lines/points for each environmental objective.

sceneorder

Default NULL, otherwise, character or factor giving the order to present scenario levels

scales

facet scales, as in ggplot2::facet_wrap(). Default scales = 'fixed' holds them the same, most common change will be to scales = 'free_y' if e.g. gauges have very different flows.

transoutcome

transformation for outcome as in ggplot2::scale_y_continuous() or ggplot2::scale_fill_continuous(). Default transoutcome = 'identity' just uses the data. Most common change likely transoutcome = 'log10

transy

transformation of y-axis, if the outcome is not y, when transoutcome should be used. Default 'identity'. Ignored if outcome_col is on the y-axis, because transoutcome should be used.

transx

transformation for x axis as in ggplot2::scale_x_continuous(). Default transx = 'identity' just uses the data. Most common change likely transx = 'log10.

zero_adjust

adjustment of zeros in plot_data_prep(), useful especially for axis trans arguments. See ?plot_data_prep; this is not the same as for baselining, which should go in base_list

position

character or position function, position arguments from ggplot2::geom_col() and ggplot2::geom_point() (depending on plot type), to change from stacked to dodged bars or jitter points. Can be character, e.g. 'jitter' or a function, e.g. ggplot2::position_jitter(width = 0.1, height = 0)

map_outlinecolor

color specification for the outline of filled areas on maps. Default 'grey35' seems to be the sf default. NA removes the outline.

base_list

NULL (default) or named list of arguments to baseline_compare();

base_lev
comp_fun
group_cols plot_data_prep() handles zero_adjust, and other arguments are inferred or not supported If comp_fun is 'difference' or 'relative', midpoint auto-set at 0 or 1 respectively unless otherwise specified with setLimits

smooth_arglist

NULL (default) or limited list of arguments to ggplot2::geom_smooth(). If NULL and x is quantitative, defaults to straight lines. If just list(), it uses the defaults in ggplot2::geom_smooth(). Available arguments:

method
method.args
se
linewidth
alpha If others are desired, we can develop something more general.

underlay_list

default NULL, otherwise named list (or list of named lists for multiple underlay levels) of arguments to plot a map underlying the main map data. Only required value is either 'underlay' or 'underover' (interchangeable), defining the data to be plotted. Other arguments as for the main plot. Typical examples

underlay_list = 'basin' simply plot the basin outline
underlay_list = list(underlay = 'basin', pal_list = 'azure') same, but filled
underlay_list = list(underlay = outputs_on_sdl_scale, outcome_col = ewr_achieved, pal_list = 'scico::oslo') plot the ewr outcomes in the sdls A named palette (e.g. variation in color/fill) only works if the main data is not the same type- we can't use different palettes for underlay fill and main data fill, for example, but can if the underlay is fill (polygons) and the main data is points.

overlay_list

as underlay_list, but first item might be named "overlay or "underover"

contour_arglist

default NULL

NULL builds a heatmap with ggplot2::geom_tile(),
list(interpolate = TRUE) builds an interpolated heatmap with ggplot2::geom_raster() with interpolate = TRUE
list() builds a ggplot2::geom_contour() with all defaults
a named list with names other than 'interpolate' passes those as arguments to ggplot2::geom_contour()

setLimits

sets user-supplied color/fill limits or midpoints for maps, heatmaps, and networks, or y limits for other plots. Also sets underlay and overlay limits for consistency.

NULL (default) use internally-calculated limits
length-1 numeric, sets midpoint, limits stay auto-calculated. V. useful for divergent
length-2 numeric, sets lower and upper limits
length-3 numeric, sets limits and midpoint c(lower, mid, upper), with caveat that one limit may be ignored (must be symmetrical about the midpoint)
if base_list is 'difference' or 'relative', midpoints are auto-set at 0 or 1 (respectively) unless otherwise specified here.

Value

a ggplot stacked bar plot with standard formatting and data cleaning

Details

I do not provide an argument to drop legend labels on purpose- it's dangerous to auto-drop them. The user can always + theme(legend.position = 'none') to the returned object. As much as possible, arguments for specific plot types have been put in *_list arguments, which should be NULL (typically the default) or lists of the arguments that the user wants to change.