Plot observed and predicted landings

plot_landings(
  dat,
  unit_label = NULL,
  geom = "line",
  group = NULL,
  facet = NULL,
  lbs = FALSE,
  era = NULL,
  scale_amount = 1,
  module = NULL,
  interactive = TRUE,
  predicted = TRUE,
  interval = 0.95,
  tolerance = 0.001,
  make_rda = FALSE,
  figures_dir = getwd(),
  ...
)

Arguments

dat

Data frame or list. A tibble or named list of tibbles (input as list()) returned from convert_output.

If inputting a list of tibbles, the first tibble's reference point defined in ref_line is used to plot a reference line or calculate relative spawning biomass.

unit_label

String. Spawning biomass unit as indicated from the data. When setting a unit of pounds please use one of the following keywords: "lbs", "pounds", "lb". For example "1000s of lbs" would still be recognized as pounds. Do not set unit_label to the desired order of magnitude, rather the unit label reflected in the data. Please refer to the argument scale_amount.

Default: NULL

geom

String. How the landings are drawn. Default: "line". Options: "line" draws the predicted landings as lines (with intervals as ribbons) and the observed landings as points, or the observed landings as lines when there are no predicted landings to show; "bar" draws the observed landings of each fleet as side-by-side bars for each year (pass position = "stack" to stack them, as in r4ss::SSplotCatch()); "point" and "area" draw the observed landings only.

group

String. Single column that groups the data.

Set group = "none" to summarize data over all indexing values.

Default: NULL Options: Including, but not limited to: "year", "area", "fleet", "sex", "none", NULL

facet

Character vector. Column name or names used for faceting.

Default: NULL

lbs

[Deprecated] Logical. TRUE/FALSE; indicate whether to convert the y-axis values from kilograms to pounds. The default units match the default in the unit_label argument - 'mt'. – Deprecate

Default: FALSE

era

String. Era of data.

Default: "time"

Options: "early", "time", "fore" (forecast), or NULL (all data)

scale_amount

Number. A number to scale the y-axis values. If > 1, the magnitude of the scale amount will be added to the unit label (e.g. scale_amount = 1000 with a unit label of "1000s of lbs" will result in "thousands of 1000s of lbs")

Default: 1

module

Character vector. (Optional) Module name found in dat$module_name. If selecting >1 module, place them in a vector like c("module1", "module2").

Default: NULL

If the interactive and >1 module_name is found, user will select the module_name in the console. @seealso filter_data()

interactive

Logical. TRUE/FALSE; indicate whether the environment is interactive.

Default: FALSE

predicted

Logical. TRUE (Default) or FALSE; show the landings predicted by the model as lines, with the observed landings as points, to show the fit to the observed landings. The predicted landings are shown only when they differ from the observed landings by more than tolerance.

interval

Number. Coverage of the intervals drawn as ribbons around the lines (e.g., 0.95), based on the observation error of the landings. NULL draws no intervals. Default: 0.95

tolerance

Number. The predicted landings are shown only when the range of their differences from the observed landings is more than this proportion of the largest observed landings, as in r4ss::SSplotCatch(). Models that fit the landings almost exactly (e.g., Stock Synthesis with a small catch standard error) otherwise show two identical series. Use 0 to always show the predicted landings. Default: 0.001 (0.1%)

make_rda

Logical. TRUE/FALSE; indicate whether to save the object and make an automated caption and alternative text in the form of an rda object. If TRUE, the rda will be exported to the folder indicated in the argument "figures_dir".

Default: FALSE.

figures_dir

Path. Path to the "figures" folder.

Default: getwd()

The folder is created within the path if it does not exist.

...

Arguments passed to the geom that draws the main series (ggplot2::geom_line() for the predicted landings, ggplot2::geom_col() for bars, e.g., position = "stack").

Value

A plot showing the landings over time.

Details

The input is from an assessment model output file translated to a standardized output (convert_output). There are options to return a ggplot2 object or export an .rda object containing associated caption and alternative text for the figure.

The landings plotted are the observed landings: "landings_observed", "landings_observed_weight", "landings_observed_numbers", or "catch" when the output also has "catch_predicted" (the first of these in dat). When dat has none of these, the first label containing "landings" is plotted, with a message.

When predicted = TRUE and geom = "line", the matching predicted landings ("landings_predicted", "landings_predicted_weight", "landings_predicted_numbers", or "catch_predicted") are drawn as lines in the color of each fleet, with the observed landings as points, for the fleets and years with observed landings. Use facet = "fleet" to plot each fleet in its own panel. When the observed and predicted landings are the same (within tolerance), only the observed landings are drawn, as lines, with a message.

The intervals are lognormal, from the log-scale standard error or the coefficient of variation of the landings, as in plot_index(). Around the predicted landings, they show the range in which observations are expected given the fit and the observation error; observed landings outside the ribbon are poorly fit. Landings are often given a small observation error (e.g., a standard error of 0.01 in Stock Synthesis), so their intervals can be narrow.

Examples

plot_landings(
  dat = stockplotr::example_data,
  unit_label = "metric tons",
  group = "fleet",
  interactive = FALSE,
  make_rda = FALSE
)
#> ℹ The observed and predicted landings differ by less than `tolerance` (0.1% of the largest observed landings); plotting the observed landings only.
#> Ignoring unknown labels:
#> • linetype : "Fleet"
#> • shape : "Fleet"

# Fit to the landings: observed (points) and predicted (lines, with 95%
# intervals), one panel per fleet
plot_landings(
  dat = stockplotr::vermilion_snapper,
  facet = "fleet",
  interactive = FALSE
)

# Observed landings of each fleet as side-by-side bars
plot_landings(
  dat = stockplotr::vermilion_snapper,
  geom = "bar",
  interactive = FALSE
)

# ... or stacked, as in r4ss::SSplotCatch()
plot_landings(
  dat = stockplotr::vermilion_snapper,
  geom = "bar",
  position = "stack",
  interactive = FALSE
)