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(),
...
)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.
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
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.
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
Character vector. Column name or names used for faceting.
Default: NULL
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
String. Era of data.
Default: "time"
Options: "early", "time", "fore" (forecast), or NULL (all data)
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
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()
Logical. TRUE/FALSE; indicate whether the environment is interactive.
Default: FALSE
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.
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
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%)
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.
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").
A plot showing the landings over time.
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.
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
)