Bayesian estimation in the Fisheries Integrated Modeling System (FIMS)

class: center, middle, inverse, title-slide

.title[
# Bayesian estimation in the<br>Fisheries Integrated Modeling<br>System (FIMS)
]
.subtitle[
## FIMS CIE Review
]
.author[
### Andrea Havron, NOAA Fisheries OST<br><a href="mailto:andrea.havron@noaa.gov" class="email">andrea.havron@noaa.gov</a><br>
]
.date[
### 2026/04/21
]

---

layout: true

.footnote[U.S. Department of Commerce | National Oceanic and Atmospheric Administration | National Marine Fisheries Service]

---
# Outline

- Why Bayesian estimation for FIMS

- FIMS as a standard TMB model

- SparseNUTS workflow for posterior sampling

- Why C++ classes make priors easy and extensible

- Practical examples and take-home points

---
# Why Bayesian Estimation in FIMS?

<div class="bayes-grid">
  <div class="bayes-card">
    <div class="bayes-title">Allows for probabilistic statements</div>
    <div class="bayes-detail">E.g., the estimated probability that female spawning biomass at the start of 2024 is below the reference point of 40% of unfished biomass is 1.3%, and the probability that the relative fishing intensity exceeded 1 in 2023 is 0.4%. The joint probability of both these occurring is 0.2%.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Designed with MCMC in mind from the onset</div>
    <div class="bayes-detail">MCMC sampling is a great diagnostic for models estimated using maximum likelihood and its capability has been included in FIMS since the beginning rather than starting the process after it is too late.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Bayesian sampling is now incredibly fast</div>
    <div class="bayes-detail">{SparseNUTS} and other algorithms that can account for correlation and sparsity while sampling have made Bayesian estimation on non-linear models feasible on standard computers.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Same model, deeper inference</div>
    <div class="bayes-detail">In FIMS, we do not rewrite the model; we sample the same TMB objective that powers frequentist estimation.</div>
  </div>
</div>

---
# FIMS can be a TMB Model

<div class="accent-box">
FIMS produces a TMB objective function under the hood. Once we have that objective, Bayesian sampling with {SparseNUTS} follows the same path used for any other TMB model.
</div>

<div class="bayes-grid">
  <div class="bayes-card">
    <div class="bayes-title">Model definition</div>
    <div class="bayes-detail">FIMS C++ classes build likelihood components and priors into one joint negative log posterior.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">TMB interface</div>
    <div class="bayes-detail">The model is exposed as an objective with gradients from automatic differentiation.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Optimizer path</div>
    <div class="bayes-detail">Use nlminb for MLE and Hessian-based summaries.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Sampler path</div>
    <div class="bayes-detail">Use SparseNUTS::sample_snuts() on that same objective for posterior draws.</div>
  </div>
</div>

---
# One Objective, Two Estimation Modes

``` r
# Build objective from FIMS/TMB ingredients
success <- FIMS::CreateTMBModel()
parameters <- list(p = get_fixed(), re = get_random())
obj <- TMB::MakeADFun(
  data = list(),
  parameters,
  random = "re",
  DLL = "FIMS",
  silent = TRUE
)

# Frequentist path
fit <- stats::nlminb(start = obj$par, objective = obj$fn, gradient = obj$gr)

# Bayesian path (same objective)
posterior <- SparseNUTS::sample_snuts(
  obj = obj,
  iter_warmup = 1000,
  iter_sampling = 1000,
  chains = 4
)
```

<div class="accent-box">
{SparseNUTS} samples the same AD-enabled target function. FIMS users get Bayesian inference without reimplementing the model in another framework.
</div>

---
# SparseNUTS Workflow in Practice

<div class="workflow-step"><b>Step 1:</b> Configure the model in FIMS and confirm optimization converges.</div>
<div class="workflow-step"><b>Step 2:</b> Pass the TMB objective to SparseNUTS with an informed warmup and chain count.</div>
<div class="workflow-step"><b>Step 3:</b> Check diagnostics: R-hat, effective sample size, divergences, and trace plots.</div>
<div class="workflow-step"><b>Step 4:</b> Summarize posterior distributions for management quantities and derived measures.</div>

<div class="accent-box">
SparseNUTS is especially attractive for TMB models with sparse random-effects structure, where efficient gradient-based MCMC is critical.
</div>

---
# Pacific hake case study

``` r
SparseNUTS:::pairs.tmbfit(fit, pars = 1:6, order = "slow")
```

---
# Priors Anywhere: Why FIMS C++ Design Helps

<div class="bayes-grid">
  <div class="bayes-card">
    <div class="bayes-title">Class-based parameter objects</div>
    <div class="bayes-detail">Parameters are represented as structured C++ objects with names, transforms, and links to model components.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Consistent objective assembly</div>
    <div class="bayes-detail">Priors enter the same joint objective as likelihood terms, minimizing bookkeeping and duplication.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Extensibility</div>
    <div class="bayes-detail">Adding a new parameter or model component naturally allows for allowing priors because all parameters use the same class.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">If a distribution exists you can use it</div>
    <div class="bayes-detail">Once a distribution is coded in FIMS it can be used to fit data or place a prior on a parameter. Other frameworks often restrict what types of priors are allowed on certain parameters. Multiple distributions can be used across time for a single parameter if desired and priors can be shared across parameters.</div>
  </div>
</div>

---
# 🚧 Transformations: Flexibility vs. Safety

Decision Points:

<div class ="bayes-column">
  <div class="bayes-card">
    <div class="bayes-title">Safety First: Constrained Priors</div>
    <div class="bayes-detail">Users can only define Normal priors for parameters in log-space. This does not require a Jacobian. Models can easily transition from MLE output to MCMC input. This puts a hard limit on prior flexibility. </div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Middle Ground: Natural Parameter Priors</div>
    <div class="bayes-detail">Allow users to put priors on natural parameters and pass min/max parameter constraints into {StanNUTS}, this will trigger Stan's automatic Jacobian detection. MLE models optimize better when parameters are in log-space, so moving between the two would be more challenging.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Maximum Flexibility: Automatic Jacobian Adjustments</div>
    <div class="bayes-detail">This would keep input parameters in log or logit-space but users could place priors on any transformation. An automatic Jacobian transformation would determine any adjustment needed given the input and prior transformations. Models could swicth between MLE and MCMC, although there would be a flag needed to determine whether or not the Jacobian adjustment was turned on.</div>
  </div>
</div>

---
# Flexible Parameter Priors
<br>
<div class="bayes-grid">
  <div class="bayes-card">
    <div class="bayes-title">Parameter class field</div>
    <div class="bayes-detail">The transformation field takes the the name of the transformation applied to the parameter.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Internal ApplyBackTransformation function</div>
    <div class="bayes-detail">Applies the appropriate back transformation given the transformation field.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Flexible prior specification</div>
    <div class="bayes-detail">Priors can be placed on the natural parameter or any transformation of it, such as the log or logit.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Challenges</div>
    <div class="bayes-detail">Given this flexibility, how do we make sure uses do not use the wrong transformation for MLE models.</div>
  </div>
</div>

<br><br>
🚧 Currently implemented in the surplus production development branch

---
# Automatic Jacobian Transformation
<br>
<div class="bayes-column">
  <div class="bayes-card">
    <div class="bayes-title">Tracking input parameter and prior transformations</div>
    <div class="bayes-detail">A systems needs to be developed to distinguish between the input parameter's tranformation (what the MCMC sampler sees) and the transformation of the prior.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Internal AddLogJacobian function</div>
    <div class="bayes-detail">Given the transformations of the input and the prior from the transformation field, this internal function determines the log Jacobian adjustment using TMB's Jacobian() and log_determinant() functions.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Challenge</div>
    <div class="bayes-detail">How to differentiate between MCMC and MLE estimation runs?</div>
  </div>
</div>

<br>
🚧 Currently being developed in the surplus production development branch

---
# Future for Multivariate priors
<br>
**Existing Infrastructure**
<div class="bayes-column">
  <div class="bayes-card">
    <div class="bayes-title">Shared Parameter Architecture</div>
    <div class="bayes-detail">Our C++ class structure allows us to easily extend simple distributions into complex, multivariate ones.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Cross-Module Linking</div>
    <div class="bayes-detail">Using a global pointer system, we can "bridge" parameters from different parts of the model to create a single, multivariate prior.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Location Independence</div>
    <div class="bayes-detail">Parameters can be linked and estimated together regardless of which module they originally belong to.</div>
  </div>
</div>

---
# Future for Multivariate priors
<br>
**Next Steps for Development**
<div class="bayes-column">
  <div class="bayes-card">
    <div class="bayes-title">Advanced Distributions</div>
    <div class="bayes-detail">Implement multivariate distributions like GMRF (Gaussian Markov Random Fields) and 2D-AR1 models.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Covariance Automation</div>
    <div class="bayes-detail">Develop functions to automatically assemble the covariance matrices required for these distributions.</div>
  </div>
  <div class="bayes-card">
    <div class="bayes-title">Component Building</div>
    <div class="bayes-detail">Enhance the pointer system to allow users to build multivariate priors piece-by-piece from individual model components.</div>
  </div>
</div>

---
# Summary

- One TMB object for both MLE optimization and Bayesian MCMC

- {SparseNUTS} package for fast, gradient-based MCMC in high-dimensional models

- Modular and flexible prior specification across all parameters

- Plan for flexible priors via automatic Jacobian transformations

- Future development on multivariate priors