Plot utilities for tidy_tam() outputs

These functions provide minimal, Plotly-based visualizations for outputs from tidy_tam() and related TAM model objects:

Usage

plot_heatmap(data, zlab = "Estimate", title = "", ...)

plot_par(data, ...)

plot_bubbles(
  data,
  res = NULL,
  y = ~age,
  ylab = "Age",
  title = NULL,
  residual_type = c("auto", "standardized", "osa"),
  ...
)

plot_resid(
  data,
  x = ~year,
  xlab = "Year",
  residual_type = c("auto", "standardized", "osa"),
  ...
)

plot_trend(
  data,
  x = ~year,
  y = ~est,
  xlab = "Year",
  ylab = "",
  title = "",
  add_intervals = TRUE,
  add_buttons = TRUE,
  ...
)

plot_obs_pred(
  data,
  ylab = "",
  title = "",
  add_buttons = TRUE,
  x = ~year,
  xlab = "Year",
  ...
)

add_plot_buttons(p)

Arguments

data

A data frame of observations or estimates.

zlab

Label for the colorbar in heatmaps.

title

Plot title.

...

Additional arguments to pass to plotly::plot_ly() such as color, colors, etc.

res

Optional one-column formula for signed bubble values, e.g. ~est for process deviations. Omitted values use OSA or standardized observation residuals. Use y = ~age_block for shared M state blocks.

y

Formula specifying y variable

ylab

Label for the y-axis.

residual_type

Initial observation residual view: "auto" (default), "standardized" or "osa". The default uses retained OSA residuals when available, otherwise standardized residuals. Model frames choose separately; overlays use OSA only when all models have them. A dropdown offers OSA and Standardized when OSAs are available. Partial gaps stay missing; unavailable OSA values are identified without computing them. A supplied res formula in plot_bubbles() bypasses these observation controls.

x

Formula specifying x variable

xlab

Label for the x-axis.

add_intervals

Logical; if TRUE, show confidence intervals when lwr and upr are present.

add_buttons

Logical; if TRUE, include buttons to toggle y-axis between Linear / Log and, if applicable, Show CI / Hide CI.

p

A Plotly object, with all desired layers already added.

Value

A Plotly object.

Details

• plot_trend(): time‐series trends with optional confidence ribbons.

• plot_heatmap(): age × year heatmaps for matrix quantities (e.g., F, M, N).

• plot_obs_pred(): observed vs predicted fits by year.

• plot_bubbles(): residuals (OSA or standardized) as bubbles by age × year.

• plot_resid(): residual diagnostics vs year, cohort, age, and expected values.

• plot_par(): parameter estimates and confidence limits, including signed effects.

• add_plot_buttons(): finish Linear / Log and CI controls after adding layers.

These functions display the supplied tables without refitting the model or recalculating uncertainty. Trend ribbons use lwr and upr confidence limits; they are not prediction intervals for future observations. Catch and survey predictions are conditional medians. Residuals come from tidy_obs_pred(). Subset to a single survey or supply a grouping aesthetic when combining surveys so distinct series are not connected. A log axis requires positive values. Both trend and observed/predicted plots accept an x formula and xlab; use x = ~ age, xlab = "Age", frame = ~ year for annual age profiles. The historical/projection separator is shown only on a year axis. Tables with fold (forecast origin) and horizon columns add forecast status to default hover text. Different origins suppress a shared separator. Explicit text or hovertemplate arguments override these hover defaults. plot_age_year() assembles both orientations with view-switching buttons. For custom overlays, call plot_trend(add_buttons = FALSE), add the layers with Plotly, then call add_plot_buttons() so CI controls include all ribbons. See tinyAM-model for definitions and units of population quantities. Optional unit columns supply default y-axis labels and hover units for natural estimates; an explicit ylab or hovertemplate takes precedence. Known inconsistent units must be converted explicitly before overlaying models. Single-coordinate trends show a point and a vertical confidence interval instead of an invisible line segment. Missing intervals split confidence ribbons into separate runs. Signed values and intervals expand the default axis below zero; nonnegative trends retain a zero baseline.

Examples

## Fit two models ----
N_dev <- fit_tam(
  cod_obs, years = 1983:2024, ages = 2:14,
  N_settings = list(process = "iid", init = "exp"),
  F_settings = list(process = "rw", mu_form = NULL),
  M_settings = list(process = "off", mu_supplied = ~ I(0.3)),
  silent = TRUE
)
N_dev <- update(N_dev,
  proj_settings = list(n_proj = 3, n_mean = 3, F_mult = 1),
  start_par = as.list(N_dev$sdrep, "Estimate")
)
M_dev <- update(
  N_dev,
  N_settings = list(process = "off", init = "exp"),
  M_settings = list(process = "ar1", mu_supplied = ~ I(0.3),
                    age_breaks = c(3, 14))
)

## Combine model objects into named list ----
fits <- list("N_dev" = N_dev, "M_dev" = M_dev)

## Stack outputs ----
tabs <- tidy_tam(model_list = fits)

## Trend plots ----
plot_trend(N_dev$pop$biomass, ylab = "Biomass")

plot_trend(tabs$pop$biomass, color = ~model, ylab = "Biomass")


N_dev$pop$N |>
  subset(age %in% 2:8) |>
  plot_trend(ylab = "N", color = ~ as.character(age))


## Age-Year Heatmap ----
plot_heatmap(N_dev$pop$F, zlab = "F")

plot_heatmap(M_dev$pop$F, zlab = "F")


## Observed vs Predicted ----
plot_obs_pred(N_dev$obs_pred$catch, frame = ~age, ylab = "Catch")

plot_obs_pred(tabs$obs_pred$index,
  color = ~model, legendgroup = ~model,
  frame = ~age, ylab = "Index"
)


## Residual Bubbles ----
plot_bubbles(N_dev$obs_pred$catch)

plot_bubbles(tabs$obs_pred$index, frame = ~model)


## Residual Scatter ----
plot_resid(N_dev$obs_pred$catch, x = ~age, xlab = "Age")

plot_resid(tabs$obs_pred$index,
  frame = ~model,
  x = ~year, xlab = "Year", showlegend = FALSE
)


## Parameter Estimates ----
plot_par(N_dev$fixed_par)

plot_par(tabs$fixed_par, color = ~model)