The Woods Hole Assessment Model (WHAM) is a general state-space age-structured stock assessment framework designed to include environmental effects on population processes. The state-space framework is attractive because it can estimate observation and process error, as well as naturally propagate random effect parameters in stock projections. WHAM can be configured to estimate a range of assessment models (see Ex 1 and Ex 6):

  • statistical catch-at-age (SCAA) model with recruitments as fixed effects,
  • SCAA with recruitments as random effects
  • “full state-space model”, abundance at all ages are random effects

WHAM advances fisheries assessment because it can estimate constrained random deviations, i.e. random effects, on parameters such as:

  • recruitment / numbers-at-age (Ex 2 and Ex 6),
  • selectivity (Ex 4),
  • natural mortality (Ex 5), and
  • environmental effects on the above (Ex 2 and Ex 5)

A nice property of treating population and environmental processes as random effects is that their uncertainty is naturally propagated in projections/forecasts (Ex 3).

Overview of WHAM presentation (Jan 8 2021):


WHAM generalizes and extends R and TMB code from Miller et al. (2016), Miller and Hyun 2018, and Miller et al. 2018. WHAM has many similarities to ASAP (code, Legault and Restrepo 1998), including the input data file structure. Many of the plotting functions for input data, results, and diagnostics are modified from ASAP code written by Chris Legault and Liz Brooks (ASAPplots).

A paper describing WHAM has been published, which includes the model equations, simulation tests, and demos of random effects options for numbers-at-age, M, selectivity, and environment-recruitment:

Stock et al. (2021) describes the 2D (year x age) AR(1) correlation structure that can be used on numbers-at-age, M, and selectivity in WHAM (as in Berg and Nielsen 2016, Cadigan 2016, and Xu et al. 2019).

WHAM is written in R and TMB, and would not be possible without these superb open-source tools. For more information, see:


For the latest stable, tested release:

devtools::install_github("timjmiller/wham", dependencies=TRUE)

For the development version with recent bug fixes and features (potentially untested):

devtools::install_github("timjmiller/wham", dependencies=TRUE, ref="devel")


We suggest walking through the vignettes to familiarize yourself with WHAM:

Clean, runnable .R scripts for each vignette are also available in the example_scripts folder of the wham package install:

wham.dir <- find.package("wham")
file.path(wham.dir, "example_scripts")

You can then run the entire first example script with:

source(file.path(wham.dir, "example_scripts", "ex1_SNEMA_yellowtail_flounder.R"))

You can run ALL examples with (takes 1 hour):

wham.dir <- find.package("wham")
source(file.path(wham.dir, "example_scripts", "run_all_examples.R"))

Install details

Installation from GitHub does not include the vignettes by default because they can be accessed online anytime at If you want to build the vignettes locally, they look best if you build using R Studio:

devtools::install_github("timjmiller/wham", dependencies=TRUE, build_vignettes = TRUE, build_opts = c("--no-resave-data", "--no-manual"))

View installed vignettes:

If you’re having problems with dependencies not installing, you can try:

devtools::install_github("kaskr/adcomp/TMB", dependencies=TRUE)
to.install <- c("plotrix","ellipse","Hmisc","gplots","fields","RColorBrewer","colorspace","mnormt","Deriv","tidyr","dplyr","ggplot2","viridis")
new.packages <- to.install[!(to.install %in% installed.packages()[,"Package"])]
if(length(new.packages)) install.packages(new.packages)


Kristensen, K., Nielsen, A., Berg, C. W., Skaug, H., and Bell, B. M. 2016. TMB: Automatic differentiation and Laplace approximation. Journal of Statistical Software 70(5): 1–21. doi: 10.18637/jss.v070.i05.

Legault, C. M. and Restrepo, V. R. 1998. A flexible forward age-structured assessment program. ICCAT. Col. Vol. Sci. Pap. 49: 246-253. link

Miller, T. J., Hare, J. A., and Alade, L. A. 2016. A state-space approach to incorporating environmental effects on recruitment in an age-structured assessment model with an application to Southern New England yellowtail flounder. Canadian Journal of Fisheries and Aquatic Sciences 73(8): 1261-1270. doi: 10.1139/cjfas-2015-0339

Miller, T. J. and Hyun, S-Y. 2018. Evaluating evidence for alternative natural mortality and process error assumptions using a state-space, age-structured assessment model. Canadian Journal of Fisheries and Aquatic Sciences 75(5): 691-703. doi: 10.1139/cjfas-2017-0035

Miller, T. J., O’Brien, L., and Fratantoni, P. S. 2018. Temporal and environmental variation in growth and maturity and effects on management reference points of Georges Bank Atlantic cod. Canadian Journal of Fisheries and Aquatic Sciences 75(12): 2159-2171. doi: 10.1139/cjfas-2017-0124

R Core Team. 2020. R: A Language and Environment for Statistical Computing. R Foundation for Statistical Computing, Vienna, Austria.

Stock, B. C., and Miller, T. J. 2021. The Woods Hole Assessment Model (WHAM): A general state-space assessment framework that incorporates time- and age-varying processes via random effects and links to environmental covariates. Fisheries Research, 240: 105967. doi: 10.1016/j.fishres.2021.105967

Stock, B. C., Xu, H., Miller, T. J., Thorson, J. T., and Nye, J. A. 2021. Implementing two-dimensional autocorrelation in either survival or natural mortality improves a state-space assessment model for Southern New England-Mid Atlantic yellowtail flounder. Fisheries Research, 237: 105873. doi: 10.1016/j.fishres.2021.105873

NOAA Disclaimer

This repository is a scientific product and is not official communication of the National Oceanic and Atmospheric Administration, or the United States Department of Commerce. All NOAA GitHub project code is provided on an ‘as is’ basis and the user assumes responsibility for its use. Any claims against the Department of Commerce or Department of Commerce bureaus stemming from the use of this GitHub project will be governed by all applicable Federal law. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by the Department of Commerce. The Department of Commerce seal and logo, or the seal and logo of a DOC bureau, shall not be used in any manner to imply endorsement of any commercial product or activity by DOC or the United States Government.

NOAA Fisheries

U.S. Department of Commerce | National Oceanographic and Atmospheric Administration | NOAA Fisheries