Generate boxplots using ggplot2::ggplot() to visualize
outliers and central tendencies.
plot_boxplot(
data,
x,
y,
horiz = NULL,
horiz2 = NULL,
vert = NULL,
vert2 = NULL,
relative.error = FALSE,
axes.free = TRUE,
print = TRUE,
fill = NA
)A valid data frame containing scalar or timeseries values
from a ss3sim simulation. That data are generated from
get_results_all.
A character string denoting which column to use as the x variable.
For time-series data, setting x = "year" leads to a time-series plot.
A character string denoting which column to use as the y variable. Must be a numeric column.
A character string denoting which column to use as
the first (horiz) and second (horiz2) level of faceting in
the horizontal direction. E.g., "M" or "species". A value of NULL (default)
indicates no faceting in the horizontal space.
A character string denoting which column to use as
the first (vert) and second (vert2) level of faceting in
the vertical direction. E.g., "M" or "species". A value of NULL (default)
indicates no faceting in the vertical space.
Boolean for whether the y-axis scale should be
interpreted as relative error. If TRUE, ylim is set to
c(-1, 1), the y-axis label is changed automatically, and a
black, dashed line at y=0 is added. The argument can also accept a
color entry if you wish the line to be something other than black. E.g.,
"red" will add a red dashed line at zero as well as fix the y-axis
limits.
Boolean for whether the y-axis scales should be free
in facet_grid.
A logical for whether the plot is printed or not.
A character string that represents a single color that will
be used to fill the boxplots. The default value of NA leads to
unfilled boxplots.
Median, hinges, and whiskers as well as outliers are displayed to
summarize the data. The lower and upper hinges are the first and third
quantiles (i.e., 25th and 75th percentiles). The upper and lower
whiskers are 1.5*inner-quartile range, i.e., the distance between the first
and third quartiles. Outliers are those points that lie beyond the whiskers.
These explanations are detailed in ggplot2::geom_boxplot().
Values of NA are removed prior to plotting such that the typical
error message from ggplot2::ggplot() is not printed to the screen.
The ss3sim plotting functions are simply
wrappers for ggplot2 code, specific to the output from
ss3sim get_results_all() objects. They are
designed to quickly explore simulation output, rather than produce
publication-level figures. The functions use arguments passed as
characters that refer to columns of data.
Scalar plots requires a value for x; while,
for time-series plots, x = "year" will be necessary.
Note that there are some subtle differences between the
functions.
Boxplots cannot have a color mapped to them like points or lines,
and thus, color is not a
valid argument. The time-series point and line plots are grouped internally by
'ID', which is a combination of scenario and iteration and will be
automatically added to the data set if not already present.
These functions print the ggplot object, but
also return it invisibly for saving or printing again later.
For example, you could save the ggplot object and add a custom
theme or change an axis label before printing it.
# Plot scalar values
data("scalar_dat", package = "ss3sim")
re <- calculate_re(scalar_dat)
#> Warning: number of columns of result is not a multiple of vector length (arg 1)
if (FALSE) {
plot_boxplot(re,
x = "E", y = "depletion_re", horiz = "D",
relative.error = TRUE
)
}
rm(re)
# Merge scalar and time-series values to plot time series with color
# Be patient, the time-series boxplots take some time.
data("ts_dat", package = "ss3sim")
ts_dat[, "model_run"] <- factor(ts_dat[, "model_run"],
levels = c("om", "em")
)
if (FALSE) {
plot_boxplot(ts_dat,
x = "year", y = "SpawnBio",
horiz = "scenario", vert = "model_run"
)
}