Generate a scatterplot using ggplot2::ggplot to visualize the relationship between two continuous variables.

plot_points(
  data,
  x,
  y,
  horiz = NULL,
  horiz2 = NULL,
  vert = NULL,
  vert2 = NULL,
  jitter.height = 0,
  jitter.width = 0,
  color = NULL,
  relative.error = FALSE,
  axes.free = TRUE,
  print = TRUE
)

Arguments

data

A valid data frame containing scalar or timeseries values from a ss3sim simulation. That data are generated from get_results_all.

x

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.

y

A character string denoting which column to use as the y variable. Must be a numeric column.

horiz, horiz2

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.

vert, vert2

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.

jitter.height, jitter.width

Parameters for ggplot2::position_jitter() that specify the vertical and horizontal spread added to points. Where, added values are both positive and negative, so the total spread is twice the value specified here. If NULL, the spread will be 40% of the resolution of the data; this means the jitter values will occupy 80% of the implied bins. Categorical data is aligned on the integers, so a width or height of 0.5 will spread the data so it's not possible to see the distinction between the categories. The default within ss3sim is to not jitter, i.e., a spread of 0.0.

color

A character string denoting which column to use to map color. Not valid for boxplot functions. Useful for looking at EM performance criteria against other dimensions of the EM or OM. See example below for how to merge in a metric from a scalar dataset to a ts dataset.

relative.error

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.

axes.free

Boolean for whether the y-axis scales should be free in facet_grid.

print

A logical for whether the plot is printed or not.

Details

Points are placed on the figure using the width setting in ggplot2::position_jitter() that defaults to 40% resolution of the data, meaning that the jitter values will occupy 80% of the implied bins. The previous information was found in the documentation for ggplot2::position_jitter().

Values of NA are removed prior to plotting such that the typical error message from ggplot2 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.

Output

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.

Author

Cole Monnahan

Examples

# 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) { # \dontrun{
plot_points(re,
  x = "E", y = "depletion_re", horiz = "D",
  color = "max_grad", relative.error = TRUE
)
} # }
rm(re)
# Merge scalar and time-series values to plot time series with color
data("ts_dat", package = "ss3sim")
re <- merge(
  by = "ID",
  calculate_re(ts_dat, add = FALSE),
  calculate_re(scalar_dat, add = FALSE)[, c("ID", "max_grad")]
)
#> Warning: number of columns of result is not a multiple of vector length (arg 1)
#> Warning: number of columns of result is not a multiple of vector length (arg 1)
if (FALSE) { # \dontrun{
plot_points(re,
  x = "year", y = "SpawnBio_re",
  horiz = "scenario", color = "max_grad", relative.error = TRUE
)
} # }
rm(re)