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 is a significant advancement in 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).


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).

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


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"))


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.

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. 2019. R: A Language and Environment for Statistical Computing. R Foundation for Statistical Computing, Vienna, Austria.

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.