From 1996e046d34d721f46d84eeed081739ede01e28a Mon Sep 17 00:00:00 2001 From: ericward-noaa Date: Tue, 17 Nov 2026 14:17:38 -0800 Subject: [PATCH 1/3] plot_landings(): predicted as lines with ribbons, observed as points, bar option --- R/plot_landings.R | 347 +++++++++++++++++++++------- man/conout_bam.Rd | 10 +- man/conout_rceattle.Rd | 10 +- man/conout_ss3.Rd | 10 +- man/convert_output.Rd | 18 +- man/plot_landings.Rd | 96 +++++--- tests/testthat/test-plot_landings.R | 77 +++++- 7 files changed, 423 insertions(+), 145 deletions(-) diff --git a/R/plot_landings.R b/R/plot_landings.R index 7c549387..44a97470 100644 --- a/R/plot_landings.R +++ b/R/plot_landings.R @@ -1,14 +1,31 @@ -#' Plot observed landings +#' Plot observed and predicted landings #' #' @inheritParams plot_spawning_biomass -#' @param predicted Logical. TRUE/FALSE; add the landings predicted by the -#' model as dashed lines, to show the fit to the observed landings. -#' Default: FALSE -#' @param interval Number. Coverage of intervals around the observed landings -#' based on their observation error (e.g., 0.95), drawn as a ribbon. NULL -#' draws no intervals. Default: NULL +#' @param 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. +#' @param 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`. +#' @param 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 +#' @param 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%) +#' @param ... 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"`). #' -#' @returns A plot showing cumulative landings over time. +#' @returns A plot showing the landings over time. #' #' @details The input is from an assessment model output file #' translated to a standardized output (\link[stockplotr]{convert_output}). @@ -21,17 +38,22 @@ #' `dat` has none of these, the first label containing "landings" is #' plotted, with a message. #' -#' When `predicted = TRUE`, the matching predicted landings -#' ("landings_predicted", "landings_predicted_weight", -#' "landings_predicted_numbers", or "catch_predicted") are added as dashed -#' lines in the color of each fleet, for the fleets and years with observed -#' landings. Use `facet = "fleet"` to plot each fleet in its own panel. +#' 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. #' -#' When `interval` is set, the observed landings are drawn with a ribbon at -#' that coverage. Intervals are lognormal, from a log-scale standard error or -#' a coefficient of variation, as in [plot_index()]; 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. +#' 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. #' #' @seealso [convert_output()], [filter_data()], [process_data()], [plot_timeseries()], [export_kqs()], [insert_kqs()], [create_rda()] #' @@ -45,20 +67,24 @@ #' interactive = FALSE, #' make_rda = FALSE #' ) +#' # Fit to the landings: observed (points) and predicted (lines, with 95% +#' # intervals), one panel per fleet #' plot_landings( -#' dat = stockplotr::example_data, -#' unit_label = "metric tons", +#' dat = stockplotr::vermilion_snapper, #' facet = "fleet", -#' interactive = FALSE, -#' make_rda = FALSE +#' interactive = FALSE #' ) -#' # Fit to the landings: observed (solid, with 95% intervals) and -#' # predicted (dashed), one panel per fleet +#' # Observed landings of each fleet as side-by-side bars #' plot_landings( #' dat = stockplotr::vermilion_snapper, -#' predicted = TRUE, -#' interval = 0.95, -#' facet = "fleet", +#' geom = "bar", +#' interactive = FALSE +#' ) +#' # ... or stacked, as in r4ss::SSplotCatch() +#' plot_landings( +#' dat = stockplotr::vermilion_snapper, +#' geom = "bar", +#' position = "stack", #' interactive = FALSE #' ) plot_landings <- function( @@ -72,17 +98,24 @@ plot_landings <- function( scale_amount = 1, module = NULL, interactive = TRUE, - predicted = FALSE, - interval = NULL, + predicted = TRUE, + interval = 0.95, + tolerance = 0.001, make_rda = FALSE, figures_dir = getwd(), ... ) { check_data(dat) + geom <- rlang::arg_match0(geom, c("line", "point", "area", "bar")) + if (!is.numeric(tolerance) || length(tolerance) != 1 || tolerance < 0) { + cli::cli_abort("{.arg tolerance} must be a number of 0 or more (e.g., 0.001).") + } - # The observed landings and, when `predicted`, the matching predicted landings + # The observed landings and, when `predicted`, the matching predicted + # landings. Bars, points, and areas show the observed landings only. observed_label <- landings_label_name(dat, module = module) label_name <- observed_label + predicted <- predicted && geom == "line" if (predicted) { predicted_label <- landings_predicted_label(dat, observed_label) if (is.null(predicted_label)) { @@ -97,8 +130,8 @@ plot_landings <- function( # Filter data for landings prepared_data <- filter_data( dat = dat, - label_name = landings_label_name(dat, module = module), - geom = geom, + label_name = label_name, + geom = if (geom == "area") "area" else "line", era = NULL, group = group, facet = facet, @@ -107,13 +140,13 @@ plot_landings <- function( interactive = interactive ) - # Uncertainty around the observed landings is drawn only when `interval` - # is given, at that coverage + # Intervals from the observation error of the observed and predicted + # landings; which are drawn is decided below if (is.null(interval)) { prepared_data$estimate_lower <- NA_real_ prepared_data$estimate_upper <- NA_real_ } else { - prepared_data <- index_observed_interval(prepared_data, interval, observed_label = observed_label) + prepared_data <- index_observed_interval(prepared_data, interval, observed_label = label_name) } # Process data @@ -148,6 +181,26 @@ plot_landings <- function( dplyr::filter(label == unique(label)[1]) } + if (predicted) { + predicted_data <- landings_match_observed(predicted_data, landings_data) + difference <- landings_difference(landings_data, predicted_data) + if (is.na(difference)) { + cli::cli_alert_info("No predicted landings found for the years with observed landings; plotting the observed landings only.") + predicted <- FALSE + } else if (difference <= tolerance) { + cli::cli_alert_info( + "The observed and predicted landings differ by less than {.arg tolerance} ({tolerance * 100}% of the largest observed landings); plotting the observed landings only." + ) + predicted <- FALSE + } + } + # The ribbons are drawn around the lines: the predicted landings when they + # are shown, otherwise the observed landings + if (predicted) { + landings_data$estimate_lower <- NA_real_ + landings_data$estimate_upper <- NA_real_ + } + # extract unit if unit_label is null and set lbs to F by default lbs <- FALSE if (is.null(unit_label)) { @@ -182,24 +235,26 @@ plot_landings <- function( if (group %notin% colnames(landings_data)) group <- NULL } - # inital base plot - plt <- plot_timeseries( - dat = landings_data, - y = "estimate", - geom = geom, - ylab = landings_label, - group = group, - facet = facet, - ... - ) + theme_noaa() - - one_series <- length(unique(landings_data$group_var)) == 1 && - length(unique(landings_data$model)) == 1 - if (predicted) { - plt <- landings_add_predicted(plt, landings_data, predicted_data, one_series) - } else if (one_series) { - plt <- plt + ggplot2::theme(legend.position = "none") + plt <- if (geom == "bar") { + landings_plot_bars(landings_data, group = group, facet = facet, ylab = landings_label, ...) + } else if (predicted) { + landings_plot_fit(landings_data, predicted_data, group = group, facet = facet, ylab = landings_label, ...) + } else { + one_series <- length(unique(landings_data$group_var)) == 1 && + length(unique(landings_data$model)) == 1 + p <- plot_timeseries( + dat = landings_data, + y = "estimate", + geom = geom, + ylab = landings_label, + group = group, + facet = facet, + ... + ) + if (one_series) p <- p + ggplot2::theme(legend.position = "none") + p } + plt <- plt + theme_noaa() ### Make RDA ---- if (make_rda) { @@ -281,44 +336,176 @@ landings_predicted_label <- function(dat, observed_label) { predicted } -# Add the predicted landings to the plot of observed landings as dashed -# lines, in the color of each fleet, for the fleets and years with observed -# landings -landings_add_predicted <- function(plt, observed, predicted, one_series) { - keys <- intersect(c("model", "group_var", "fleet"), names(observed)) - key <- function(d) do.call(paste, c(d[keys], sep = "\r")) +# The columns that identify a series of landings (and its panel) +landings_keys <- function(dat) { + intersect(c("model", "group_var", "fleet", "area", "season", "sex"), names(dat)) +} + +# The predicted landings for the series and years with observed landings +landings_match_observed <- function(predicted, observed) { + keys <- landings_keys(observed) + key <- function(d) do.call(paste, c(lapply(d[keys], as.character), sep = "\r")) first <- tapply(observed$year, key(observed), min) last <- tapply(observed$year, key(observed), max) predicted_key <- key(predicted) in_range <- predicted_key %in% names(first) & predicted$year >= first[predicted_key] & predicted$year <= last[predicted_key] - predicted <- predicted[in_range %in% TRUE, , drop = FALSE] + predicted[in_range %in% TRUE, , drop = FALSE] +} - # The observed landings are the solid lines - for (i in seq_along(plt$layers)) { - if (inherits(plt$layers[[i]]$geom, "GeomLine")) { - plt$layers[[i]]$mapping$linetype <- ggplot2::aes(linetype = "Observed")$linetype - } +# The range of the differences between the predicted and observed landings +# as a proportion of the largest observed landings, as in +# r4ss::SSplotCatch(); NA when no years match +landings_difference <- function(observed, predicted) { + keys <- c(landings_keys(observed), "year") + both <- dplyr::inner_join( + observed[c(keys, "estimate")], + predicted[c(keys, "estimate")], + by = keys, + suffix = c("_observed", "_predicted"), + relationship = "many-to-many" + ) + if (nrow(both) == 0) { + return(NA_real_) } - # Color the predicted landings as plot_timeseries() colors the observed ones - series <- function(d) { - if (length(unique(observed$model)) > 1) { - as.character(interaction(d$model, d$group_var)) - } else { - as.character(d$group_var) - } + difference <- both$estimate_predicted - both$estimate_observed + diff(range(difference, na.rm = TRUE)) / max(abs(both$estimate_observed), na.rm = TRUE) +} + +# The series (color) of each row: the group, or the model and group when +# there are several models +landings_series <- function(dat, models) { + if (length(models) > 1) { + factor(interaction(dat$model, dat$group_var, sep = " ")) + } else { + factor(dat$group_var) } - mapping <- ggplot2::aes(x = .data$year, y = .data$estimate, linetype = "Predicted") - if (!one_series) { - predicted$color_var <- factor(series(predicted), levels = levels(factor(series(observed)))) - mapping$colour <- ggplot2::aes(colour = .data$color_var)$colour +} + +# Axis breaks, a y-axis from zero, and panels shared by the landings plots +landings_finish_plot <- function(plt, dat, facet, xlab = "Year", ylab = NULL) { + plt <- plt + + ggplot2::labs(x = xlab, y = ylab) + + ggplot2::scale_x_continuous( + breaks = axis_breaks(dat$year), + guide = ggplot2::guide_axis(minor.ticks = TRUE) + ) + + ggplot2::scale_y_continuous(labels = scales::label_comma()) + + ggplot2::expand_limits(y = 0) + facet <- intersect(facet, colnames(dat)) + if (length(facet) > 0) { + plt <- plt + ggplot2::facet_wrap( + stats::reformulate(paste("~", paste(facet, collapse = " + "))), + labeller = function(labels) { + # Clean column names (e.g., "growth_pattern" -> "Growth Pattern") + names(labels) <- tools::toTitleCase(gsub("_", " ", names(labels))) + # Combine into "Variable: Value" format + lapply(names(labels), function(var) paste0(var, ": ", labels[[var]])) + } + ) + } + plt +} + +# The fit to the landings: the predicted landings as lines (with intervals +# as ribbons) and the observed landings as points, in the color of each +# series +landings_plot_fit <- function(observed, predicted, group = NULL, facet = NULL, ylab = NULL, ...) { + models <- unique(c(observed$model, predicted$model)) + levels <- levels(landings_series(rbind(observed, predicted), models)) + observed$series <- factor(landings_series(observed, models), levels = levels) + predicted$series <- factor(landings_series(predicted, models), levels = levels) + one_series <- length(levels) == 1 + ribbons <- predicted[!is.na(predicted$estimate_lower), , drop = FALSE] + + if (one_series) { + # One series: no fleet colors + plt <- ggplot2::ggplot() + + ggplot2::geom_ribbon( + data = ribbons, + ggplot2::aes(x = .data$year, ymin = .data$estimate_lower, ymax = .data$estimate_upper), + fill = "grey70", alpha = 0.5 + ) + + ggplot2::geom_line( + data = predicted, + ggplot2::aes(x = .data$year, y = .data$estimate, linetype = "Predicted"), + ... + ) + + ggplot2::geom_point( + data = observed, + ggplot2::aes(x = .data$year, y = .data$estimate, shape = "Observed"), + size = 2 + ) + } else { + plt <- ggplot2::ggplot() + + ggplot2::geom_ribbon( + data = ribbons, + ggplot2::aes( + x = .data$year, ymin = .data$estimate_lower, ymax = .data$estimate_upper, + fill = .data$series + ), + alpha = 0.25, show.legend = FALSE + ) + + ggplot2::geom_line( + data = predicted, + ggplot2::aes(x = .data$year, y = .data$estimate, colour = .data$series, linetype = "Predicted"), + ... + ) + + ggplot2::geom_point( + data = observed, + ggplot2::aes(x = .data$year, y = .data$estimate, colour = .data$series, shape = "Observed"), + size = 2 + ) + + ggplot2::scale_colour_discrete(drop = FALSE) + + ggplot2::scale_fill_discrete(drop = FALSE) + + ggplot2::labs( + colour = if (length(models) > 1) { + paste("Model", cap_first_letter(group)) + } else { + cap_first_letter(group) + } + ) } plt <- plt + - ggplot2::geom_line(data = predicted, mapping = mapping) + - ggplot2::scale_linetype_manual(values = c(Observed = "solid", Predicted = "dashed")) + - ggplot2::guides(linetype = ggplot2::guide_legend(title = NULL)) + ggplot2::scale_linetype_manual(name = NULL, values = c(Predicted = "solid")) + + ggplot2::scale_shape_manual(name = NULL, values = c(Observed = 16)) + + ggplot2::guides( + shape = ggplot2::guide_legend(order = 1), + linetype = ggplot2::guide_legend(order = 2), + colour = ggplot2::guide_legend(order = 3) + ) + landings_finish_plot(plt, rbind(observed[names(predicted)], predicted), facet, ylab = ylab) +} + +# The observed landings of each series as side-by-side bars for each year +# (or stacked, with `position = "stack"`), with a panel for each model +landings_plot_bars <- function(observed, group = NULL, facet = NULL, ylab = NULL, ...) { + observed$series <- factor(observed$group_var) + one_series <- length(levels(observed$series)) == 1 + args <- list(...) + if (is.null(args$position)) { + args$position <- ggplot2::position_dodge(width = 0.9, preserve = "single") + } + if (is.null(args$width)) args$width <- 0.9 + mapping <- if (one_series) { + ggplot2::aes(x = .data$year, y = .data$estimate) + } else { + ggplot2::aes(x = .data$year, y = .data$estimate, fill = .data$series) + } + plt <- ggplot2::ggplot() + + do.call(ggplot2::geom_col, c(list(data = observed, mapping = mapping), args)) + + ggplot2::labs(fill = cap_first_letter(group)) if (one_series) { - plt <- plt + ggplot2::guides(colour = "none", fill = "none") + plt <- plt + ggplot2::theme(legend.position = "none") } - plt + # Bars of several models are not comparable stacked or side by side + if (length(unique(observed$model)) > 1) { + facet <- unique(c("model", facet)) + } + # Bars start at zero + suppressMessages(landings_finish_plot(plt, observed, facet, ylab = ylab) + + ggplot2::scale_y_continuous( + labels = scales::label_comma(), + expand = ggplot2::expansion(mult = c(0, 0.05)) + )) } diff --git a/man/conout_bam.Rd b/man/conout_bam.Rd index 6cb63143..3cdb9be6 100644 --- a/man/conout_bam.Rd +++ b/man/conout_bam.Rd @@ -7,23 +7,19 @@ conout_bam(file, out_new, fleet_names = NULL) } \arguments{ -\item{file}{Path. Assessment model output file path. Currently accepts SS3 -\code{r4ss::ss_output()} or Report.sso file (being deprecated), BAM .rda file, Rceattle model object, and FIMS output -(the tibble returned by \code{FIMS::get_estimates()}, a \code{FIMSFit} object, or an .rds file with either).} - \item{out_new}{The empty standard output data frame from \code{\link[=convert_output]{convert_output()}}, which sets the columns of the output.} -\item{fleet_names}{List of Character vectors. Names of fleets in the assessment model as +\item{fleet_names}{List of named character vectors. Names of fleets in the assessment model as shortened in the output file or names of fleets to replace the native fleet names in the output. For example, if fleet names in the model are 1, 2, 3 then fleet_names = c("fleet1" = 1, "fleet2" = 2, "fleet3" = 3). Default: NULL -Should match length of \code{files}.} +Should match length of \code{files} if >1 model.} -\item{Path.}{Assessment model output file path. Currently accepts SS3 +\item{file.}{Assessment model output file path. Currently accepts SS3 Report.sso file, BAM .rda file, Rceattle model object, and FIMS model object.} } \value{ diff --git a/man/conout_rceattle.Rd b/man/conout_rceattle.Rd index 9e9e3734..7702fba6 100644 --- a/man/conout_rceattle.Rd +++ b/man/conout_rceattle.Rd @@ -7,23 +7,19 @@ conout_rceattle(file, out_new, fleet_names = NULL) } \arguments{ -\item{file}{Path. Assessment model output file path. Currently accepts SS3 -\code{r4ss::ss_output()} or Report.sso file (being deprecated), BAM .rda file, Rceattle model object, and FIMS output -(the tibble returned by \code{FIMS::get_estimates()}, a \code{FIMSFit} object, or an .rds file with either).} - \item{out_new}{The empty standard output data frame from \code{\link[=convert_output]{convert_output()}}, which sets the columns of the output.} -\item{fleet_names}{List of Character vectors. Names of fleets in the assessment model as +\item{fleet_names}{List of named character vectors. Names of fleets in the assessment model as shortened in the output file or names of fleets to replace the native fleet names in the output. For example, if fleet names in the model are 1, 2, 3 then fleet_names = c("fleet1" = 1, "fleet2" = 2, "fleet3" = 3). Default: NULL -Should match length of \code{files}.} +Should match length of \code{files} if >1 model.} -\item{Path.}{Assessment model output file path. Currently accepts SS3 +\item{file.}{Assessment model output file path. Currently accepts SS3 Report.sso file, BAM .rda file, Rceattle model object, and FIMS model object.} } \value{ diff --git a/man/conout_ss3.Rd b/man/conout_ss3.Rd index 8fdd5c43..25a79239 100644 --- a/man/conout_ss3.Rd +++ b/man/conout_ss3.Rd @@ -7,23 +7,19 @@ conout_ss3(file, out_new, fleet_names = NULL) } \arguments{ -\item{file}{Path. Assessment model output file path. Currently accepts SS3 -\code{r4ss::ss_output()} or Report.sso file (being deprecated), BAM .rda file, Rceattle model object, and FIMS output -(the tibble returned by \code{FIMS::get_estimates()}, a \code{FIMSFit} object, or an .rds file with either).} - \item{out_new}{The empty standard output data frame from \code{\link[=convert_output]{convert_output()}}, which sets the columns of the output.} -\item{fleet_names}{List of Character vectors. Names of fleets in the assessment model as +\item{fleet_names}{List of named character vectors. Names of fleets in the assessment model as shortened in the output file or names of fleets to replace the native fleet names in the output. For example, if fleet names in the model are 1, 2, 3 then fleet_names = c("fleet1" = 1, "fleet2" = 2, "fleet3" = 3). Default: NULL -Should match length of \code{files}.} +Should match length of \code{files} if >1 model.} -\item{Path.}{Assessment model output file path. Currently accepts SS3 +\item{file.}{Assessment model output file path. Currently accepts SS3 Report.sso file, BAM .rda file, Rceattle model object, and FIMS model object.} } \value{ diff --git a/man/convert_output.Rd b/man/convert_output.Rd index 30d010e4..71f61f17 100644 --- a/man/convert_output.Rd +++ b/man/convert_output.Rd @@ -4,13 +4,19 @@ \alias{convert_output} \title{Convert Output} \usage{ -convert_output(files, models = NULL, fleet_names = NULL, save_dir = NULL) +convert_output( + files, + models = NULL, + fleet_names = NULL, + save_dir = NULL, + start_year = NULL +) } \arguments{ \item{files}{List of Paths. Assessment model output file paths. Currently accepts SS3 \code{r4ss::ss_output()} or Report.sso file (being deprecated), BAM .rda file, Rceattle model object, -and FIMS output (the tibble returned by \code{FIMS::get_estimates()}, a \code{FIMSFit} object, or an -.rds file with either). If multiple elements, all valid models will be read, converted, and +and FIMS output (the tibble returned by \code{FIMS::get_estimates()}, a \code{FIMSFit} object, or an .rds +file with either). If multiple elements, all valid models will be read, converted, and appended together. \code{names(files)} will be used as the name of the model in the output.} @@ -21,16 +27,16 @@ Default: NULL Options: "ss3", "bam", "fims", "rceattle" -Should match length of \code{files}.} +Should match length of \code{files} if >1 model.} -\item{fleet_names}{List of Character vectors. Names of fleets in the assessment model as +\item{fleet_names}{List of named character vectors. Names of fleets in the assessment model as shortened in the output file or names of fleets to replace the native fleet names in the output. For example, if fleet names in the model are 1, 2, 3 then fleet_names = c("fleet1" = 1, "fleet2" = 2, "fleet3" = 3). Default: NULL -Should match length of \code{files}.} +Should match length of \code{files} if >1 model.} \item{save_dir}{Path. Full file path to save the converted output file. If saved file name is not indicated, the file will be saved as "std_output.rda" diff --git a/man/plot_landings.Rd b/man/plot_landings.Rd index 40fdf6a5..2a444005 100644 --- a/man/plot_landings.Rd +++ b/man/plot_landings.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/plot_landings.R \name{plot_landings} \alias{plot_landings} -\title{Plot observed landings} +\title{Plot observed and predicted landings} \usage{ plot_landings( dat, @@ -15,8 +15,9 @@ plot_landings( scale_amount = 1, module = NULL, interactive = TRUE, - predicted = FALSE, - interval = NULL, + predicted = TRUE, + interval = 0.95, + tolerance = 0.001, make_rda = FALSE, figures_dir = getwd(), ... @@ -37,11 +38,13 @@ unit label reflected in the data. Please refer to the argument \code{scale_amoun Default: NULL} -\item{geom}{String. Geom used for the plot. - -Default: "line". - -Options: "line", "point", or "area"} +\item{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 \code{position = "stack"} to stack them, as in +\code{r4ss::SSplotCatch()}); "point" and "area" draw the observed landings only.} \item{group}{String. Single column that groups the data. @@ -85,13 +88,21 @@ module_name in the console. @seealso \code{\link[=filter_data]{filter_data()}}} Default: \code{FALSE}} -\item{predicted}{Logical. TRUE/FALSE; add the landings predicted by the -model as dashed lines, to show the fit to the observed landings. -Default: FALSE} +\item{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 \code{tolerance}.} + +\item{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} -\item{interval}{Number. Coverage of intervals around the observed landings -based on their observation error (e.g., 0.95), drawn as a ribbon. NULL -draws no intervals. Default: NULL} +\item{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 \code{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\%)} \item{make_rda}{Logical. TRUE/FALSE; indicate whether to save the object and make an automated caption and alternative text in the form of an \code{rda} object. If TRUE, @@ -105,13 +116,15 @@ Default: \code{getwd()} The folder is created within the path if it does not exist.} -\item{...}{Arguments called from \link[ggplot2]{geom_line} or \link[ggplot2]{geom_point}} +\item{...}{Arguments passed to the geom that draws the main series +(\code{\link[ggplot2:geom_line]{ggplot2::geom_line()}} for the predicted landings, \code{\link[ggplot2:geom_col]{ggplot2::geom_col()}} +for bars, e.g., \code{position = "stack"}).} } \value{ -A plot showing cumulative landings over time. +A plot showing the landings over time. } \description{ -Plot observed landings +Plot observed and predicted landings } \details{ The input is from an assessment model output file @@ -125,17 +138,22 @@ the output also has "catch_predicted" (the first of these in \code{dat}). When \code{dat} has none of these, the first label containing "landings" is plotted, with a message. -When \code{predicted = TRUE}, the matching predicted landings -("landings_predicted", "landings_predicted_weight", -"landings_predicted_numbers", or "catch_predicted") are added as dashed -lines in the color of each fleet, for the fleets and years with observed -landings. Use \code{facet = "fleet"} to plot each fleet in its own panel. - -When \code{interval} is set, the observed landings are drawn with a ribbon at -that coverage. Intervals are lognormal, from a log-scale standard error or -a coefficient of variation, as in \code{\link[=plot_index]{plot_index()}}; 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. +When \code{predicted = TRUE} and \code{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 \code{facet = "fleet"} to plot +each fleet in its own panel. When the observed and predicted landings are +the same (within \code{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 \code{\link[=plot_index]{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( @@ -145,20 +163,24 @@ plot_landings( interactive = FALSE, make_rda = FALSE ) +# Fit to the landings: observed (points) and predicted (lines, with 95\% +# intervals), one panel per fleet plot_landings( - dat = stockplotr::example_data, - unit_label = "metric tons", + dat = stockplotr::vermilion_snapper, facet = "fleet", - interactive = FALSE, - make_rda = FALSE + interactive = FALSE ) -# Fit to the landings: observed (solid, with 95\% intervals) and -# predicted (dashed), one panel per fleet +# Observed landings of each fleet as side-by-side bars plot_landings( dat = stockplotr::vermilion_snapper, - predicted = TRUE, - interval = 0.95, - facet = "fleet", + geom = "bar", + interactive = FALSE +) +# ... or stacked, as in r4ss::SSplotCatch() +plot_landings( + dat = stockplotr::vermilion_snapper, + geom = "bar", + position = "stack", interactive = FALSE ) } diff --git a/tests/testthat/test-plot_landings.R b/tests/testthat/test-plot_landings.R index dd8c9431..36e7990c 100644 --- a/tests/testthat/test-plot_landings.R +++ b/tests/testthat/test-plot_landings.R @@ -36,7 +36,7 @@ test_that("plot_landings plots the observed landings", { # vermilion_snapper also has predicted landings in numbers and weight, whose # labels contain "landings" dat <- stockplotr::vermilion_snapper - p <- suppressMessages(plot_landings(dat, interactive = FALSE)) + p <- suppressMessages(plot_landings(dat, predicted = FALSE, interactive = FALSE)) obs <- dat[dat$label == "landings_observed" & !is.na(dat$year) & !is.na(dat$estimate), ] line <- p$layers[[which(sapply(p$layers, function(l) inherits(l$geom, "GeomLine")))]]$data expect_equal(sum(line$estimate, na.rm = TRUE), sum(obs$estimate)) @@ -55,3 +55,78 @@ test_that("plot_landings plots the observed landings", { ) expect_equal(label, "landings") }) + +# The layers of a plot drawn with a geom +landings_layers <- function(p, geom) { + Filter(function(l) inherits(l$geom, geom), p$layers) +} + +test_that("plot_landings shows the fit: observed points and predicted lines", { + dat <- stockplotr::vermilion_snapper + p <- suppressMessages(plot_landings(dat, interactive = FALSE)) + points <- landings_layers(p, "GeomPoint") + lines <- landings_layers(p, "GeomLine") + ribbons <- landings_layers(p, "GeomRibbon") + expect_length(points, 1) + expect_length(lines, 1) + expect_length(ribbons, 1) + obs <- dat[dat$label == "landings_observed" & !is.na(dat$year) & !is.na(dat$estimate), ] + expect_equal(sum(points[[1]]$data$estimate), sum(obs$estimate)) + expect_true(all(lines[[1]]$data$label == "landings_predicted")) + # The predicted landings only in the years with observed landings + expect_equal(nrow(lines[[1]]$data), nrow(obs)) + # 95% lognormal intervals from the CV of the predicted landings + r <- ribbons[[1]]$data + sigma <- sqrt(log(1 + 0.05^2)) + row <- which(r$estimate > 0)[1] + expect_equal(r$estimate_upper[row], r$estimate[row] * exp(stats::qnorm(0.975) * sigma)) + # No intervals + p <- suppressMessages(plot_landings(dat, interval = NULL, interactive = FALSE)) + expect_length(landings_layers(p, "GeomRibbon")[[1]]$data$year, 0) + # A panel per fleet + p <- suppressMessages(plot_landings(dat, facet = "fleet", interactive = FALSE)) + expect_s3_class(p$facet, "FacetWrap") + expect_s3_class(ggplot2::ggplot_build(p), "ggplot_built") + # pollock reports its landings as "catch" and "catch_predicted" + p <- suppressMessages(plot_landings(stockplotr::pollock, interactive = FALSE)) + expect_true(all(landings_layers(p, "GeomLine")[[1]]$data$label == "catch_predicted")) + expect_true(all(landings_layers(p, "GeomPoint")[[1]]$data$label == "catch")) +}) + +test_that("plot_landings shows only the observed landings when they match the predicted", { + # Stock Synthesis fits the landings almost exactly + dat <- stockplotr::example_data + expect_message( + p <- plot_landings(dat, interactive = FALSE), + "differ by less than" + ) + expect_length(landings_layers(p, "GeomPoint"), 0) + expect_true(all(landings_layers(p, "GeomLine")[[1]]$data$label == "landings_observed_weight")) + # tolerance = 0 always shows the predicted landings + p <- suppressMessages(plot_landings(dat, tolerance = 0, interactive = FALSE)) + expect_length(landings_layers(p, "GeomPoint"), 1) + expect_true(all(landings_layers(p, "GeomLine")[[1]]$data$label == "landings_predicted_weight")) + # The difference is the range of the differences relative to the largest + # observed landings, as in r4ss::SSplotCatch() + observed <- data.frame(model = "m", group_var = "a", year = 1:3, estimate = c(100, 200, 1000)) + predicted <- transform(observed, estimate = estimate + c(0, 1, -1)) + expect_equal(landings_difference(observed, predicted), 2 / 1000) + expect_true(is.na(landings_difference(observed, predicted[0, ]))) + expect_error(plot_landings(dat, tolerance = -1, interactive = FALSE), "tolerance") +}) + +test_that("plot_landings draws the observed landings as bars", { + dat <- stockplotr::vermilion_snapper + p <- suppressMessages(plot_landings(dat, geom = "bar", interactive = FALSE)) + bars <- landings_layers(p, "GeomCol") + expect_length(bars, 1) + expect_length(landings_layers(p, "GeomLine"), 0) + expect_s3_class(bars[[1]]$position, "PositionDodge") + obs <- dat[dat$label == "landings_observed" & !is.na(dat$year) & !is.na(dat$estimate), ] + expect_equal(sum(bars[[1]]$data$estimate), sum(obs$estimate)) + # Stacked, as in r4ss::SSplotCatch() + p <- suppressMessages(plot_landings(dat, geom = "bar", position = "stack", interactive = FALSE)) + b <- ggplot2::ggplot_build(p)$data[[1]] + expect_equal(max(tapply(b$ymax, b$x, max)), max(tapply(obs$estimate, obs$year, sum))) + expect_error(plot_landings(dat, geom = "pie", interactive = FALSE), "geom") +}) From 4856bf3256b6316adc2d7c7f4f65db6bb34548e0 Mon Sep 17 00:00:00 2001 From: ericward-noaa Date: Tue, 17 Nov 2026 16:51:59 -0800 Subject: [PATCH 2/3] Trim plot_landings() tests Drop checks that retest index_observed_interval() or ggplot2 internals and the argument-validation errors. --- tests/testthat/test-plot_landings.R | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/tests/testthat/test-plot_landings.R b/tests/testthat/test-plot_landings.R index 36e7990c..4bf4c8ab 100644 --- a/tests/testthat/test-plot_landings.R +++ b/tests/testthat/test-plot_landings.R @@ -70,23 +70,18 @@ test_that("plot_landings shows the fit: observed points and predicted lines", { expect_length(points, 1) expect_length(lines, 1) expect_length(ribbons, 1) + expect_gt(nrow(ribbons[[1]]$data), 0) obs <- dat[dat$label == "landings_observed" & !is.na(dat$year) & !is.na(dat$estimate), ] expect_equal(sum(points[[1]]$data$estimate), sum(obs$estimate)) expect_true(all(lines[[1]]$data$label == "landings_predicted")) # The predicted landings only in the years with observed landings expect_equal(nrow(lines[[1]]$data), nrow(obs)) - # 95% lognormal intervals from the CV of the predicted landings - r <- ribbons[[1]]$data - sigma <- sqrt(log(1 + 0.05^2)) - row <- which(r$estimate > 0)[1] - expect_equal(r$estimate_upper[row], r$estimate[row] * exp(stats::qnorm(0.975) * sigma)) # No intervals p <- suppressMessages(plot_landings(dat, interval = NULL, interactive = FALSE)) expect_length(landings_layers(p, "GeomRibbon")[[1]]$data$year, 0) # A panel per fleet p <- suppressMessages(plot_landings(dat, facet = "fleet", interactive = FALSE)) expect_s3_class(p$facet, "FacetWrap") - expect_s3_class(ggplot2::ggplot_build(p), "ggplot_built") # pollock reports its landings as "catch" and "catch_predicted" p <- suppressMessages(plot_landings(stockplotr::pollock, interactive = FALSE)) expect_true(all(landings_layers(p, "GeomLine")[[1]]$data$label == "catch_predicted")) @@ -112,7 +107,6 @@ test_that("plot_landings shows only the observed landings when they match the pr predicted <- transform(observed, estimate = estimate + c(0, 1, -1)) expect_equal(landings_difference(observed, predicted), 2 / 1000) expect_true(is.na(landings_difference(observed, predicted[0, ]))) - expect_error(plot_landings(dat, tolerance = -1, interactive = FALSE), "tolerance") }) test_that("plot_landings draws the observed landings as bars", { @@ -126,7 +120,5 @@ test_that("plot_landings draws the observed landings as bars", { expect_equal(sum(bars[[1]]$data$estimate), sum(obs$estimate)) # Stacked, as in r4ss::SSplotCatch() p <- suppressMessages(plot_landings(dat, geom = "bar", position = "stack", interactive = FALSE)) - b <- ggplot2::ggplot_build(p)$data[[1]] - expect_equal(max(tapply(b$ymax, b$x, max)), max(tapply(obs$estimate, obs$year, sum))) - expect_error(plot_landings(dat, geom = "pie", interactive = FALSE), "geom") + expect_s3_class(landings_layers(p, "GeomCol")[[1]]$position, "PositionStack") }) From 7b1e038b27c043c7b2112d3dc9d84fa71b5cc7b6 Mon Sep 17 00:00:00 2001 From: ericward-noaa Date: Wed, 18 Nov 2026 10:46:33 -0800 Subject: [PATCH 3/3] New arguments in plot_discard(), with the same defaults as plot_landings(): MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit geom: “line”, “bar” or “point”. predicted = TRUE. interval = 0.95. tolerance = 0.001. facet = "fleet" now gives one panel per fleet. - helpers out of plot_landings.R into a new file, R/utils_plot_fit.R - new test-plot_discard.R - example_data has no ribbons, because its discard uncertainty is labeled std --- R/plot_discard.R | 146 ++++++++++++++++++---- R/plot_landings.R | 182 +--------------------------- R/utils_plot_fit.R | 176 +++++++++++++++++++++++++++ man/plot_discard.Rd | 71 ++++++++++- tests/testthat/test-plot_discard.R | 49 ++++++++ tests/testthat/test-plot_landings.R | 4 +- 6 files changed, 421 insertions(+), 207 deletions(-) create mode 100644 R/utils_plot_fit.R create mode 100644 tests/testthat/test-plot_discard.R diff --git a/R/plot_discard.R b/R/plot_discard.R index a547c266..e3aab52b 100644 --- a/R/plot_discard.R +++ b/R/plot_discard.R @@ -1,8 +1,28 @@ -#' Plot discards -#' -#' Plot discards as a line graph. +#' Plot observed and predicted discards #' #' @inheritParams plot_spawning_biomass +#' @param geom String. How the discards are drawn. Default: "line". +#' Options: "line" draws the predicted discards as lines (with intervals as +#' ribbons) and the observed discards as points, or the observed discards as +#' lines when there are no predicted discards to show; "bar" draws the +#' observed discards of each fleet as side-by-side bars for each year (pass +#' `position = "stack"` to stack them); "point" draws the observed discards +#' as points. +#' @param predicted Logical. TRUE (Default) or FALSE; show the discards +#' predicted by the model as lines, with the observed discards as points, to +#' show the fit to the observed discards. The predicted discards are shown +#' only when they differ from the observed discards by more than `tolerance`. +#' @param interval Number. Coverage of the intervals drawn as ribbons around +#' the lines (e.g., 0.95), based on the observation error of the discards. +#' NULL draws no intervals. Default: 0.95 +#' @param tolerance Number. The predicted discards are shown only when the +#' range of their differences from the observed discards is more than this +#' proportion of the largest observed discards, as in [plot_landings()]. +#' Models that fit the discards almost exactly otherwise show two identical +#' series. Use 0 to always show the predicted discards. Default: 0.001 (0.1%) +#' @param ... Arguments passed to the geom that draws the main series +#' ([ggplot2::geom_line()] for the predicted discards, [ggplot2::geom_col()] +#' for bars, e.g., `position = "stack"`). #' #' @returns A ggplot showing discards over time, usually by fleet. #' @@ -11,11 +31,28 @@ #' There are options to return a `ggplot2` object or export an .rda object #' containing associated caption and alternative text for the figure. #' +#' When `dat` has observed and predicted discards ("discard_observed" and +#' "discard_predicted") and `predicted = TRUE`, the predicted discards are +#' drawn as lines in the color of each fleet, with the observed discards as +#' points, for the fleets and years with observed discards, as in +#' [plot_landings()]. Use `facet = "fleet"` to plot each fleet in its own +#' panel. When the observed and predicted discards are the same (within +#' `tolerance`), only the observed discards are drawn, as lines, with a +#' message. Otherwise, the observed discards (or the first label starting with +#' "discard") are drawn as lines. +#' +#' The intervals are lognormal, from the log-scale standard error or the +#' coefficient of variation of the discards, as in [plot_index()]. Around +#' the predicted discards, they show the range in which observations are +#' expected given the fit and the observation error; observed discards +#' outside the ribbon are poorly fit. Discards with another type of +#' uncertainty are drawn without intervals. +#' #' @note #' All plotting functions automatically recognize indexing variables and will #' use them in groupings and/or facetting. @seealso [process_data()]. #' -#' @seealso [convert_output()], [plot_timeseries()], [calculate_reference_point()], [reference_line()], [filter_data()], [process_data()], [export_kqs()], [insert_kqs()], [create_rda()] +#' @seealso [convert_output()], [plot_landings()], [plot_timeseries()], [filter_data()], [process_data()], [export_kqs()], [insert_kqs()], [create_rda()] #' #' @export #' @@ -25,8 +62,23 @@ #' unit_label = "fish", #' module = "DISCARD_OUTPUT" #' ) +#' # Fit to the discards: observed (points) and predicted (lines, with 95% +#' # intervals), one panel per fleet +#' plot_discard( +#' dat = stockplotr::vermilion_snapper, +#' facet = "fleet", +#' interactive = FALSE +#' ) +#' # Observed discards of each fleet as stacked bars +#' plot_discard( +#' dat = stockplotr::vermilion_snapper, +#' geom = "bar", +#' position = "stack", +#' interactive = FALSE +#' ) plot_discard <- function( dat, + geom = "line", group = NULL, facet = NULL, unit_label = NULL, @@ -35,10 +87,18 @@ plot_discard <- function( scale_amount = 1, interactive = TRUE, module = NULL, + predicted = TRUE, + interval = 0.95, + tolerance = 0.001, make_rda = FALSE, - figures_dir = getwd() + figures_dir = getwd(), + ... ) { check_data(dat) + geom <- rlang::arg_match0(geom, c("line", "point", "bar")) + if (!is.numeric(tolerance) || length(tolerance) != 1 || tolerance < 0) { + cli::cli_abort("{.arg tolerance} must be a number of 0 or more (e.g., 0.001).") + } # this assumes that the previous units were metric tons if (lbs && unit_label %notin% c("lbs", "pounds", "lb")) { @@ -62,7 +122,7 @@ plot_discard <- function( # extract unit if unit_label is null and set lbs to F by default lbs <- FALSE if (is.null(unit_label)) { - unit_label <- unique(prepared_data$unit) + unit_label <- unique(stats::na.omit(prepared_data$unit))[1] if (is.na(unit_label)) { cli::cli_alert_warning("No unit label found in the data. Please provide a unit label using the 'unit_label' argument.") unit_label <- "" @@ -77,43 +137,83 @@ plot_discard <- function( legend = TRUE ) - if (any(grepl("observed|predicted", unique(prepared_data$label)))) { - # select only the observed and predicted discards for plotting + # The observed (and predicted) discards, or else the first discard label + fit_labels <- "^discard_(observed|predicted)$" + has_fit <- "discard_observed" %in% prepared_data$label + if (has_fit) { prepared_data <- prepared_data |> - dplyr::filter(grepl("predicted|observed", label)) + dplyr::filter(grepl(fit_labels, .data$label)) } else if (length(unique(prepared_data$label)) > 1) { cli::cli_alert_info("Multiple discard labels found. Using the first label: {unique(prepared_data$label)[1]}") prepared_data <- prepared_data |> - dplyr::filter(label == unique(prepared_data$label)[1]) + dplyr::filter(.data$label == unique(prepared_data$label)[1]) + } + predicted <- predicted && geom == "line" && has_fit && + "discard_predicted" %in% prepared_data$label + + # Intervals from the observation error of the discards + if (is.null(interval)) { + prepared_data$estimate_lower <- NA_real_ + prepared_data$estimate_upper <- NA_real_ + } else { + prepared_data <- index_observed_interval( + prepared_data, interval, + observed_label = if (has_fit) fit_labels else "^discard" + ) } # Process the data to remove unneccessary columns and information + facet_asked <- facet p_dat <- process_data( prepared_data, group = group, facet = facet, lbs = lbs ) - discards <- p_dat[[1]] + discards <- p_dat[[1]] |> + dplyr::filter(!is.na(.data$estimate)) group <- p_dat[[2]] facet <- p_dat[[3]] + # process_data() makes the first facet the group when no group is given; + # keep it as a facet too, so `facet = "fleet"` plots a panel per fleet + if (!is.null(facet_asked) && identical(group, facet_asked[1]) && + facet_asked[1] %notin% facet && facet_asked[1] %in% colnames(discards)) { + facet <- c(facet_asked[1], facet) + } + if (!is.null(group) && group %notin% colnames(discards)) group <- NULL + + is_predicted <- discards$label == "discard_predicted" + observed <- discards[!is_predicted, , drop = FALSE] + if (predicted) { + predicted_data <- fit_match_observed(discards[is_predicted, , drop = FALSE], observed) + difference <- fit_difference(observed, predicted_data) + if (is.na(difference)) { + cli::cli_alert_info("No predicted discards found for the years with observed discards; plotting the observed discards only.") + predicted <- FALSE + } else if (difference <= tolerance) { + cli::cli_alert_info( + "The observed and predicted discards differ by less than {.arg tolerance} ({tolerance * 100}% of the largest observed discards); plotting the observed discards only." + ) + predicted <- FALSE + } + } # make the plot - if (any(grepl("observed|predicted", unique(prepared_data$label)))) { - plt <- plot_obsvpred( - dat = discards, - observed_label = "discard_observed", - predicted_label = "discard_predicted", - ylab = discard_label, - group = group, - facet = facet - ) + plt <- if (geom == "bar") { + fit_plot_bars(observed, group = group, facet = facet, ylab = discard_label, ...) + } else if (predicted) { + # The ribbons are drawn around the predicted discards + observed$estimate_lower <- NA_real_ + observed$estimate_upper <- NA_real_ + fit_plot_lines(observed, predicted_data, group = group, facet = facet, ylab = discard_label, ...) } else { - plt <- plot_timeseries( - discards, + plot_timeseries( + observed, + geom = geom, ylab = discard_label, facet = if (length(facet) > 0) facet else NULL, - group = group + group = group, + ... ) } diff --git a/R/plot_landings.R b/R/plot_landings.R index 44a97470..798b52f3 100644 --- a/R/plot_landings.R +++ b/R/plot_landings.R @@ -182,8 +182,8 @@ plot_landings <- function( } if (predicted) { - predicted_data <- landings_match_observed(predicted_data, landings_data) - difference <- landings_difference(landings_data, predicted_data) + predicted_data <- fit_match_observed(predicted_data, landings_data) + difference <- fit_difference(landings_data, predicted_data) if (is.na(difference)) { cli::cli_alert_info("No predicted landings found for the years with observed landings; plotting the observed landings only.") predicted <- FALSE @@ -236,9 +236,9 @@ plot_landings <- function( } plt <- if (geom == "bar") { - landings_plot_bars(landings_data, group = group, facet = facet, ylab = landings_label, ...) + fit_plot_bars(landings_data, group = group, facet = facet, ylab = landings_label, ...) } else if (predicted) { - landings_plot_fit(landings_data, predicted_data, group = group, facet = facet, ylab = landings_label, ...) + fit_plot_lines(landings_data, predicted_data, group = group, facet = facet, ylab = landings_label, ...) } else { one_series <- length(unique(landings_data$group_var)) == 1 && length(unique(landings_data$model)) == 1 @@ -335,177 +335,3 @@ landings_predicted_label <- function(dat, observed_label) { } predicted } - -# The columns that identify a series of landings (and its panel) -landings_keys <- function(dat) { - intersect(c("model", "group_var", "fleet", "area", "season", "sex"), names(dat)) -} - -# The predicted landings for the series and years with observed landings -landings_match_observed <- function(predicted, observed) { - keys <- landings_keys(observed) - key <- function(d) do.call(paste, c(lapply(d[keys], as.character), sep = "\r")) - first <- tapply(observed$year, key(observed), min) - last <- tapply(observed$year, key(observed), max) - predicted_key <- key(predicted) - in_range <- predicted_key %in% names(first) & - predicted$year >= first[predicted_key] & predicted$year <= last[predicted_key] - predicted[in_range %in% TRUE, , drop = FALSE] -} - -# The range of the differences between the predicted and observed landings -# as a proportion of the largest observed landings, as in -# r4ss::SSplotCatch(); NA when no years match -landings_difference <- function(observed, predicted) { - keys <- c(landings_keys(observed), "year") - both <- dplyr::inner_join( - observed[c(keys, "estimate")], - predicted[c(keys, "estimate")], - by = keys, - suffix = c("_observed", "_predicted"), - relationship = "many-to-many" - ) - if (nrow(both) == 0) { - return(NA_real_) - } - difference <- both$estimate_predicted - both$estimate_observed - diff(range(difference, na.rm = TRUE)) / max(abs(both$estimate_observed), na.rm = TRUE) -} - -# The series (color) of each row: the group, or the model and group when -# there are several models -landings_series <- function(dat, models) { - if (length(models) > 1) { - factor(interaction(dat$model, dat$group_var, sep = " ")) - } else { - factor(dat$group_var) - } -} - -# Axis breaks, a y-axis from zero, and panels shared by the landings plots -landings_finish_plot <- function(plt, dat, facet, xlab = "Year", ylab = NULL) { - plt <- plt + - ggplot2::labs(x = xlab, y = ylab) + - ggplot2::scale_x_continuous( - breaks = axis_breaks(dat$year), - guide = ggplot2::guide_axis(minor.ticks = TRUE) - ) + - ggplot2::scale_y_continuous(labels = scales::label_comma()) + - ggplot2::expand_limits(y = 0) - facet <- intersect(facet, colnames(dat)) - if (length(facet) > 0) { - plt <- plt + ggplot2::facet_wrap( - stats::reformulate(paste("~", paste(facet, collapse = " + "))), - labeller = function(labels) { - # Clean column names (e.g., "growth_pattern" -> "Growth Pattern") - names(labels) <- tools::toTitleCase(gsub("_", " ", names(labels))) - # Combine into "Variable: Value" format - lapply(names(labels), function(var) paste0(var, ": ", labels[[var]])) - } - ) - } - plt -} - -# The fit to the landings: the predicted landings as lines (with intervals -# as ribbons) and the observed landings as points, in the color of each -# series -landings_plot_fit <- function(observed, predicted, group = NULL, facet = NULL, ylab = NULL, ...) { - models <- unique(c(observed$model, predicted$model)) - levels <- levels(landings_series(rbind(observed, predicted), models)) - observed$series <- factor(landings_series(observed, models), levels = levels) - predicted$series <- factor(landings_series(predicted, models), levels = levels) - one_series <- length(levels) == 1 - ribbons <- predicted[!is.na(predicted$estimate_lower), , drop = FALSE] - - if (one_series) { - # One series: no fleet colors - plt <- ggplot2::ggplot() + - ggplot2::geom_ribbon( - data = ribbons, - ggplot2::aes(x = .data$year, ymin = .data$estimate_lower, ymax = .data$estimate_upper), - fill = "grey70", alpha = 0.5 - ) + - ggplot2::geom_line( - data = predicted, - ggplot2::aes(x = .data$year, y = .data$estimate, linetype = "Predicted"), - ... - ) + - ggplot2::geom_point( - data = observed, - ggplot2::aes(x = .data$year, y = .data$estimate, shape = "Observed"), - size = 2 - ) - } else { - plt <- ggplot2::ggplot() + - ggplot2::geom_ribbon( - data = ribbons, - ggplot2::aes( - x = .data$year, ymin = .data$estimate_lower, ymax = .data$estimate_upper, - fill = .data$series - ), - alpha = 0.25, show.legend = FALSE - ) + - ggplot2::geom_line( - data = predicted, - ggplot2::aes(x = .data$year, y = .data$estimate, colour = .data$series, linetype = "Predicted"), - ... - ) + - ggplot2::geom_point( - data = observed, - ggplot2::aes(x = .data$year, y = .data$estimate, colour = .data$series, shape = "Observed"), - size = 2 - ) + - ggplot2::scale_colour_discrete(drop = FALSE) + - ggplot2::scale_fill_discrete(drop = FALSE) + - ggplot2::labs( - colour = if (length(models) > 1) { - paste("Model", cap_first_letter(group)) - } else { - cap_first_letter(group) - } - ) - } - plt <- plt + - ggplot2::scale_linetype_manual(name = NULL, values = c(Predicted = "solid")) + - ggplot2::scale_shape_manual(name = NULL, values = c(Observed = 16)) + - ggplot2::guides( - shape = ggplot2::guide_legend(order = 1), - linetype = ggplot2::guide_legend(order = 2), - colour = ggplot2::guide_legend(order = 3) - ) - landings_finish_plot(plt, rbind(observed[names(predicted)], predicted), facet, ylab = ylab) -} - -# The observed landings of each series as side-by-side bars for each year -# (or stacked, with `position = "stack"`), with a panel for each model -landings_plot_bars <- function(observed, group = NULL, facet = NULL, ylab = NULL, ...) { - observed$series <- factor(observed$group_var) - one_series <- length(levels(observed$series)) == 1 - args <- list(...) - if (is.null(args$position)) { - args$position <- ggplot2::position_dodge(width = 0.9, preserve = "single") - } - if (is.null(args$width)) args$width <- 0.9 - mapping <- if (one_series) { - ggplot2::aes(x = .data$year, y = .data$estimate) - } else { - ggplot2::aes(x = .data$year, y = .data$estimate, fill = .data$series) - } - plt <- ggplot2::ggplot() + - do.call(ggplot2::geom_col, c(list(data = observed, mapping = mapping), args)) + - ggplot2::labs(fill = cap_first_letter(group)) - if (one_series) { - plt <- plt + ggplot2::theme(legend.position = "none") - } - # Bars of several models are not comparable stacked or side by side - if (length(unique(observed$model)) > 1) { - facet <- unique(c("model", facet)) - } - # Bars start at zero - suppressMessages(landings_finish_plot(plt, observed, facet, ylab = ylab) + - ggplot2::scale_y_continuous( - labels = scales::label_comma(), - expand = ggplot2::expansion(mult = c(0, 0.05)) - )) -} diff --git a/R/utils_plot_fit.R b/R/utils_plot_fit.R new file mode 100644 index 00000000..3bb555c4 --- /dev/null +++ b/R/utils_plot_fit.R @@ -0,0 +1,176 @@ +# Helpers shared by plots of observed and predicted values over time +# (plot_landings(), plot_discard()): predicted values as lines with +# intervals as ribbons, observed values as points or bars + +# The columns that identify a series (and its panel) +fit_keys <- function(dat) { + intersect(c("model", "group_var", "fleet", "area", "season", "sex"), names(dat)) +} + +# The predicted values for the series and years with observed values +fit_match_observed <- function(predicted, observed) { + keys <- fit_keys(observed) + key <- function(d) do.call(paste, c(lapply(d[keys], as.character), sep = "\r")) + first <- tapply(observed$year, key(observed), min) + last <- tapply(observed$year, key(observed), max) + predicted_key <- key(predicted) + in_range <- predicted_key %in% names(first) & + predicted$year >= first[predicted_key] & predicted$year <= last[predicted_key] + predicted[in_range %in% TRUE, , drop = FALSE] +} + +# The range of the differences between the predicted and observed values as +# a proportion of the largest observed value, as in +# r4ss::SSplotCatch(); NA when no years match +fit_difference <- function(observed, predicted) { + keys <- c(fit_keys(observed), "year") + both <- dplyr::inner_join( + observed[c(keys, "estimate")], + predicted[c(keys, "estimate")], + by = keys, + suffix = c("_observed", "_predicted"), + relationship = "many-to-many" + ) + if (nrow(both) == 0) { + return(NA_real_) + } + difference <- both$estimate_predicted - both$estimate_observed + diff(range(difference, na.rm = TRUE)) / max(abs(both$estimate_observed), na.rm = TRUE) +} + +# The series (color) of each row: the group, or the model and group when +# there are several models +fit_series <- function(dat, models) { + if (length(models) > 1) { + factor(interaction(dat$model, dat$group_var, sep = " ")) + } else { + factor(dat$group_var) + } +} + +# Axis breaks, a y-axis from zero, and panels shared by the fit plots +fit_finish_plot <- function(plt, dat, facet, xlab = "Year", ylab = NULL) { + plt <- plt + + ggplot2::labs(x = xlab, y = ylab) + + ggplot2::scale_x_continuous( + breaks = axis_breaks(dat$year), + guide = ggplot2::guide_axis(minor.ticks = TRUE) + ) + + ggplot2::scale_y_continuous(labels = scales::label_comma()) + + ggplot2::expand_limits(y = 0) + facet <- intersect(facet, colnames(dat)) + if (length(facet) > 0) { + plt <- plt + ggplot2::facet_wrap( + stats::reformulate(paste("~", paste(facet, collapse = " + "))), + labeller = function(labels) { + # Clean column names (e.g., "growth_pattern" -> "Growth Pattern") + names(labels) <- tools::toTitleCase(gsub("_", " ", names(labels))) + # Combine into "Variable: Value" format + lapply(names(labels), function(var) paste0(var, ": ", labels[[var]])) + } + ) + } + plt +} + +# The fit to observed data: the predicted values as lines (with intervals as +# ribbons) and the observed values as points, in the color of each series +fit_plot_lines <- function(observed, predicted, group = NULL, facet = NULL, ylab = NULL, ...) { + models <- unique(c(observed$model, predicted$model)) + levels <- levels(fit_series(rbind(observed, predicted), models)) + observed$series <- factor(fit_series(observed, models), levels = levels) + predicted$series <- factor(fit_series(predicted, models), levels = levels) + one_series <- length(levels) == 1 + ribbons <- predicted[!is.na(predicted$estimate_lower), , drop = FALSE] + + if (one_series) { + # One series: no fleet colors + plt <- ggplot2::ggplot() + + ggplot2::geom_ribbon( + data = ribbons, + ggplot2::aes(x = .data$year, ymin = .data$estimate_lower, ymax = .data$estimate_upper), + fill = "grey70", alpha = 0.5 + ) + + ggplot2::geom_line( + data = predicted, + ggplot2::aes(x = .data$year, y = .data$estimate, linetype = "Predicted"), + ... + ) + + ggplot2::geom_point( + data = observed, + ggplot2::aes(x = .data$year, y = .data$estimate, shape = "Observed"), + size = 2 + ) + } else { + plt <- ggplot2::ggplot() + + ggplot2::geom_ribbon( + data = ribbons, + ggplot2::aes( + x = .data$year, ymin = .data$estimate_lower, ymax = .data$estimate_upper, + fill = .data$series + ), + alpha = 0.25, show.legend = FALSE + ) + + ggplot2::geom_line( + data = predicted, + ggplot2::aes(x = .data$year, y = .data$estimate, colour = .data$series, linetype = "Predicted"), + ... + ) + + ggplot2::geom_point( + data = observed, + ggplot2::aes(x = .data$year, y = .data$estimate, colour = .data$series, shape = "Observed"), + size = 2 + ) + + ggplot2::scale_colour_discrete(drop = FALSE) + + ggplot2::scale_fill_discrete(drop = FALSE) + + ggplot2::labs( + colour = if (length(models) > 1) { + paste("Model", cap_first_letter(group)) + } else { + cap_first_letter(group) + } + ) + } + plt <- plt + + ggplot2::scale_linetype_manual(name = NULL, values = c(Predicted = "solid")) + + ggplot2::scale_shape_manual(name = NULL, values = c(Observed = 16)) + + ggplot2::guides( + shape = ggplot2::guide_legend(order = 1), + linetype = ggplot2::guide_legend(order = 2), + colour = ggplot2::guide_legend(order = 3) + ) + fit_finish_plot(plt, rbind(observed[names(predicted)], predicted), facet, ylab = ylab) +} + +# The observed values of each series as side-by-side bars for each year +# (or stacked, with `position = "stack"`), with a panel for each model +fit_plot_bars <- function(observed, group = NULL, facet = NULL, ylab = NULL, ...) { + observed$series <- factor(observed$group_var) + one_series <- length(levels(observed$series)) == 1 + args <- list(...) + if (is.null(args$position)) { + args$position <- ggplot2::position_dodge(width = 0.9, preserve = "single") + } + if (is.null(args$width)) args$width <- 0.9 + mapping <- if (one_series) { + ggplot2::aes(x = .data$year, y = .data$estimate) + } else { + ggplot2::aes(x = .data$year, y = .data$estimate, fill = .data$series) + } + plt <- ggplot2::ggplot() + + do.call(ggplot2::geom_col, c(list(data = observed, mapping = mapping), args)) + + ggplot2::labs(fill = cap_first_letter(group)) + if (one_series) { + plt <- plt + ggplot2::theme(legend.position = "none") + } + # Bars of several models are not comparable stacked or side by side + if (length(unique(observed$model)) > 1) { + facet <- unique(c("model", facet)) + } + # Bars start at zero + suppressMessages(fit_finish_plot(plt, observed, facet, ylab = ylab) + + ggplot2::scale_y_continuous( + labels = scales::label_comma(), + expand = ggplot2::expansion(mult = c(0, 0.05)) + )) +} diff --git a/man/plot_discard.Rd b/man/plot_discard.Rd index 61f21df0..7160d03f 100644 --- a/man/plot_discard.Rd +++ b/man/plot_discard.Rd @@ -2,10 +2,11 @@ % Please edit documentation in R/plot_discard.R \name{plot_discard} \alias{plot_discard} -\title{Plot discards} +\title{Plot observed and predicted discards} \usage{ plot_discard( dat, + geom = "line", group = NULL, facet = NULL, unit_label = NULL, @@ -14,8 +15,12 @@ plot_discard( scale_amount = 1, interactive = TRUE, module = NULL, + predicted = TRUE, + interval = 0.95, + tolerance = 0.001, make_rda = FALSE, - figures_dir = getwd() + figures_dir = getwd(), + ... ) } \arguments{ @@ -25,6 +30,14 @@ returned from \link[stockplotr]{convert_output}. If inputting a list of tibbles, the first tibble's reference point defined in \code{ref_line} is used to plot a reference line or calculate relative spawning biomass.} +\item{geom}{String. How the discards are drawn. Default: "line". +Options: "line" draws the predicted discards as lines (with intervals as +ribbons) and the observed discards as points, or the observed discards as +lines when there are no predicted discards to show; "bar" draws the +observed discards of each fleet as side-by-side bars for each year (pass +\code{position = "stack"} to stack them); "point" draws the observed discards +as points.} + \item{group}{String. Single column that groups the data. Set group = "none" to summarize data over all indexing values. @@ -75,6 +88,21 @@ Default: NULL If the interactive and >1 module_name is found, user will select the module_name in the console. @seealso \code{\link[=filter_data]{filter_data()}}} +\item{predicted}{Logical. TRUE (Default) or FALSE; show the discards +predicted by the model as lines, with the observed discards as points, to +show the fit to the observed discards. The predicted discards are shown +only when they differ from the observed discards by more than \code{tolerance}.} + +\item{interval}{Number. Coverage of the intervals drawn as ribbons around +the lines (e.g., 0.95), based on the observation error of the discards. +NULL draws no intervals. Default: 0.95} + +\item{tolerance}{Number. The predicted discards are shown only when the +range of their differences from the observed discards is more than this +proportion of the largest observed discards, as in \code{\link[=plot_landings]{plot_landings()}}. +Models that fit the discards almost exactly otherwise show two identical +series. Use 0 to always show the predicted discards. Default: 0.001 (0.1\%)} + \item{make_rda}{Logical. TRUE/FALSE; indicate whether to save the object and make an automated caption and alternative text in the form of an \code{rda} object. If TRUE, the rda will be exported to the folder indicated in the argument "figures_dir". @@ -86,18 +114,39 @@ Default: \code{FALSE}.} Default: \code{getwd()} The folder is created within the path if it does not exist.} + +\item{...}{Arguments passed to the geom that draws the main series +(\code{\link[ggplot2:geom_line]{ggplot2::geom_line()}} for the predicted discards, \code{\link[ggplot2:geom_col]{ggplot2::geom_col()}} +for bars, e.g., \code{position = "stack"}).} } \value{ A ggplot showing discards over time, usually by fleet. } \description{ -Plot discards as a line graph. +Plot observed and predicted discards } \details{ The input is from an assessment model output file translated to a standardized output (\link[stockplotr]{convert_output}). There are options to return a \code{ggplot2} object or export an .rda object containing associated caption and alternative text for the figure. + +When \code{dat} has observed and predicted discards ("discard_observed" and +"discard_predicted") and \code{predicted = TRUE}, the predicted discards are +drawn as lines in the color of each fleet, with the observed discards as +points, for the fleets and years with observed discards, as in +\code{\link[=plot_landings]{plot_landings()}}. Use \code{facet = "fleet"} to plot each fleet in its own +panel. When the observed and predicted discards are the same (within +\code{tolerance}), only the observed discards are drawn, as lines, with a +message. Otherwise, the observed discards (or the first label starting with +"discard") are drawn as lines. + +The intervals are lognormal, from the log-scale standard error or the +coefficient of variation of the discards, as in \code{\link[=plot_index]{plot_index()}}. Around +the predicted discards, they show the range in which observations are +expected given the fit and the observation error; observed discards +outside the ribbon are poorly fit. Discards with another type of +uncertainty are drawn without intervals. } \note{ All plotting functions automatically recognize indexing variables and will @@ -109,7 +158,21 @@ plot_discard( unit_label = "fish", module = "DISCARD_OUTPUT" ) +# Fit to the discards: observed (points) and predicted (lines, with 95\% +# intervals), one panel per fleet +plot_discard( + dat = stockplotr::vermilion_snapper, + facet = "fleet", + interactive = FALSE +) +# Observed discards of each fleet as stacked bars +plot_discard( + dat = stockplotr::vermilion_snapper, + geom = "bar", + position = "stack", + interactive = FALSE +) } \seealso{ -\code{\link[=convert_output]{convert_output()}}, \code{\link[=plot_timeseries]{plot_timeseries()}}, \code{\link[=calculate_reference_point]{calculate_reference_point()}}, \code{\link[=reference_line]{reference_line()}}, \code{\link[=filter_data]{filter_data()}}, \code{\link[=process_data]{process_data()}}, \code{\link[=export_kqs]{export_kqs()}}, \code{\link[=insert_kqs]{insert_kqs()}}, \code{\link[=create_rda]{create_rda()}} +\code{\link[=convert_output]{convert_output()}}, \code{\link[=plot_landings]{plot_landings()}}, \code{\link[=plot_timeseries]{plot_timeseries()}}, \code{\link[=filter_data]{filter_data()}}, \code{\link[=process_data]{process_data()}}, \code{\link[=export_kqs]{export_kqs()}}, \code{\link[=insert_kqs]{insert_kqs()}}, \code{\link[=create_rda]{create_rda()}} } diff --git a/tests/testthat/test-plot_discard.R b/tests/testthat/test-plot_discard.R new file mode 100644 index 00000000..e5a5dd77 --- /dev/null +++ b/tests/testthat/test-plot_discard.R @@ -0,0 +1,49 @@ +# The layers of a plot drawn with a geom +discard_layers <- function(p, geom) { + Filter(function(l) inherits(l$geom, geom), p$layers) +} + +test_that("plot_discard plots the fit to the observed discards", { + p <- suppressMessages(plot_discard( + stockplotr::example_data, + module = "DISCARD_OUTPUT", + interactive = FALSE + )) + expect_s3_class(p, "gg") + # Observed discards as points and predicted discards as lines, for the + # same fleets and years + points <- discard_layers(p, "GeomPoint")[[1]]$data + line <- discard_layers(p, "GeomLine")[[1]]$data + expect_true(all(points$label == "discard_observed")) + expect_true(all(line$label == "discard_predicted")) + expect_equal(nrow(points), nrow(line)) + # "std" is not a known type of observation error: no intervals + expect_equal(nrow(discard_layers(p, "GeomRibbon")[[1]]$data), 0) +}) + +test_that("plot_discard options change the plot", { + dat <- stockplotr::vermilion_snapper + p <- suppressMessages(plot_discard(dat, interactive = FALSE)) + expect_length(discard_layers(p, "GeomPoint"), 1) + ribbon <- discard_layers(p, "GeomRibbon")[[1]]$data + expect_true(all(ribbon$estimate_lower < ribbon$estimate)) + + # The predicted discards of vermilion_snapper are within 0.2% of the + # observed discards: only the observed discards, as lines + expect_message( + p <- plot_discard(dat, tolerance = 0.01, interactive = FALSE), + "differ by less than" + ) + expect_length(discard_layers(p, "GeomPoint"), 0) + + p <- suppressMessages(plot_discard(dat, interval = NULL, interactive = FALSE)) + expect_equal(nrow(discard_layers(p, "GeomRibbon")[[1]]$data), 0) + + p <- suppressMessages(plot_discard(dat, facet = "fleet", interactive = FALSE)) + expect_s3_class(p$facet, "FacetWrap") + + p <- suppressMessages(plot_discard(dat, geom = "bar", interactive = FALSE)) + expect_length(discard_layers(p, "GeomCol"), 1) + + expect_error(plot_discard(dat, tolerance = -1, interactive = FALSE), "tolerance") +}) diff --git a/tests/testthat/test-plot_landings.R b/tests/testthat/test-plot_landings.R index 4bf4c8ab..0764c267 100644 --- a/tests/testthat/test-plot_landings.R +++ b/tests/testthat/test-plot_landings.R @@ -105,8 +105,8 @@ test_that("plot_landings shows only the observed landings when they match the pr # observed landings, as in r4ss::SSplotCatch() observed <- data.frame(model = "m", group_var = "a", year = 1:3, estimate = c(100, 200, 1000)) predicted <- transform(observed, estimate = estimate + c(0, 1, -1)) - expect_equal(landings_difference(observed, predicted), 2 / 1000) - expect_true(is.na(landings_difference(observed, predicted[0, ]))) + expect_equal(fit_difference(observed, predicted), 2 / 1000) + expect_true(is.na(fit_difference(observed, predicted[0, ]))) }) test_that("plot_landings draws the observed landings as bars", {