Make a flexdashboard for visualizing model fits

Usage

vis_tam(
  ...,
  model_list = NULL,
  interval = 0.95,
  output_file = NULL,
  open_file = TRUE,
  background = NULL,
  render_args = list(),
  model = NULL,
  process_seed = 123456L
)

# Default S3 method
vis_tam(
  ...,
  model_list = NULL,
  interval = 0.95,
  output_file = NULL,
  open_file = TRUE,
  background = NULL,
  render_args = list(),
  model = NULL,
  process_seed = 123456L
)

# S3 method for class 'tam_retro'
vis_tam(
  ...,
  model_list = NULL,
  interval = 0.95,
  output_file = NULL,
  open_file = TRUE,
  background = NULL,
  render_args = list(),
  model = NULL,
  process_seed = 123456L
)

Arguments

...: One or more TAM fits or reporting references. Supply these or model_list, not both. When supplying models through ..., their object names are used to label models (even when a single model is supplied).
model_list: A named list of fitted TAM objects or precomputed reference objects of class tam_ref. Names label models.
interval: Confidence level passed to tidy_pop() and tidy_par() for interval construction. Default 0.95.
output_file: Name of file to export using rmarkdown::render(). If NULL, a temporary HTML file is rendered. The file opens in your browser only when open_file = TRUE.
open_file: Logical. Open rendered html file?
background: Optional Markdown text shown on a Background dashboard page.
render_args: Named list of additional arguments passed to rmarkdown::render().
model: Exact model name in a tam_retro result. A single model is selected automatically; interactive sessions offer a chooser for several models. Scripts must specify a model when several are available.
process_seed: Non-negative integer seed for a reproducible local Gaussian joint sample. Default 123456L; the caller's RNG state is restored.

Value

Used for its side effects: writes an HTML dashboard and optionally opens it in the browser. Supply output_file to retain a known file path.

Details

Supply models via ... or model_list, but not both. The models must form a uniquely named list so they can be labeled in the dashboard. Additional arguments for rmarkdown::render() can be passed through render_args, which must itself be a (named) list. Dashboard R packages are installed with tinyAM. Rendering also needs Pandoc, included with RStudio or available from https://pandoc.org/installing.html. Precomputed assessment references may be mixed with tinyAM fits; they are not refittable TAM objects. Supply background to add a page describing assessment assumptions and translation choices. When supplied, Background opens first; otherwise Model structure opens first. Model structure contains Diagram and Function calls tabs. Fisheries is a dropdown with one page per declared catch fleet, followed by Aggregate fishery. Fleet pages show yield, catch and F at age, and observation residuals. Unlabeled catch models appear only on the aggregate page; they are not allocated among fleets. Without fleets, Aggregate fishery retains all single-fishery diagnostics. With fleets, it shows total yield; residuals are assessed separately within each fleet. Observation residuals initially use retained OSA residuals when available in that panel, otherwise standardized residuals. The dropdown offers OSA and Standardized when OSAs are available. Model frames choose their initial type separately. Partial OSA gaps remain missing, and labels identify the method. Retain OSA calculations with add_osa_residuals(); rendering never computes them. The Parameters menu separates Fixed and Random pages. Fixed plots group similar quantities, with initial abundance shown separately. Stock-recruit models add a relationship page with parent-year pairs, median curves at declared reference covariates and conditional recruitment predictions. Random parameters also show signed recruitment deviations. See tidy_recruitment(). The Random page separates Recruitment, N, F and M states from Process deviations and Joint-sample residuals. Optional initial abundance plots are inside N, followed by optional formula-effect tabs. plot_process_deviations() and plot_process_residuals() reproduce individual diagnostic plots from a single tidy result, selecting component = "Recruitment" or "NFM". The dashboard supplies dropdown tabs for these views; N/F/M plots have component buttons and a model slider. Shared M blocks are not treated as separate biological ages. process_seed reproduces the same Gaussian joint draw as tidy_tam(). Random plots include latent states and formula-effect trends. Age-year plots offer Annual trends (year axis, age selector) and Age profiles (age axis, year selector). Each plot starts in its specified orientation and retains each view's controls when switching. F-at-age and M-at-age include available process means and their separate confidence ribbons; Average F remains the population summary. Reproduce ordinary dashboard plots with plot_trend() and plot_obs_pred(), or use plot_age_year() for the two orientations. The small F/M mean-overlay helpers and their line styling live in inst/rmd/vis_tam.Rmd. A tam_retro dashboard compares the selected model's successful peels with its unpeeled reference. Failed or missing attempts are listed on Background. Hindcast forecasts remain visible, with origin and horizon in hover text. A common projection separator is omitted when origins differ. The result is never refitted or modified. Population patterns and Mortality patterns use plot_matrix() to explore age-year heatmaps, surfaces and contours, with shared ranges across models for each metric. Log changes values, not year or age. Hover text retains natural units, spawning definitions and projection labels. Unknown reference units and unavailable cells remain missing.

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)

if (interactive()) {
  ## Build dashboard ----
  vis_tam(fits)
}