adnuts

main: dev:

The aim of 'adnuts' (pronounced A-D NUTS like A-D MB) is to provide advanced MCMC sampling for 'ADMB' and 'TMB' models. It mimics 'Stan' in functionality and feel, specifically providing no-U-turn (NUTS) sampling with adaptive mass matrix and parallel execution.

The R package 'tmbstan' (available on CRAN) has largely replaced the TMB capabilities since original development. As such, adnuts is primarily used for ADMB models. See the following paper for an introduction to the package capabilities, and contrast with tmbstan:

Monnahan CC, Kristensen K (2018) No-U-turn sampling for fast Bayesian inference in ADMB and TMB: Introducing the adnuts and tmbstan R packages. PLoS ONE 13(5):e0197954. https://doi.org/10.1371/journal.pone.0197954

'adnuts' was designed specifically for use in fisheries stock assessments, and interested authors are referred to:

Monnahan, C.C., T.A. Branch, J.T. Thorson, I.J. Stewart, C.S. Szuwalksi (2020) Overcoming long Bayesian run times in integrated fisheries stock assessments. ICES Journal of Marine Science. https://dx.doi.org/10.1093/icesjms/fsz059

Usage

The 'sample_rwm' and 'sample_nuts' functions draw posterior samples from an ADMB model using an MCMC algorithm (random walk Metropolis or no-U-turn sampler). The returned fitted object contains samples and other information. The function 'extract_samples' can be used to get posterior samples (post warmup and thinning) into a data frame for inference, while 'launch_shinyadmb' can be used for interactive diagnostics based on 'ShinyStan'.

A brief demonstration file is the best place to help get you started, and there is also a user guide: vignette('adnuts') for more detailed information.

Installation

To use the ADMB functionality you need to build your model with version 12.0 (released December 2017) or later, otherwise this functionality is not available. See the ADMB installation instructions for more information. ADMB 12.2 is highly recommended because it provides better console output, fixes bugs, and adds improved adaptation capabilities as compared to 12.0. You can check the ADMB version of a compiled model from the command line with a command model.exe -version which prints the version among other things.

The adnuts R package version 1.1.2 can be installed from CRAN: install.packages('adnuts'). Future minor releases listed here may not be released on CRAN so the latest stable version can be installed as:

devtools::install_github('Cole-Monnahan-NOAA/adnuts')

The development version can be installed as: devtools::install_github('Cole-Monnahan-NOAA/adnuts', ref='dev')

Known issues

Windows users may experience issues if their model name is too long. In some cases the OS will rename the output files using a "short" version. You'll see files like "MODEL~1.par". The package tries to handle this but it is highly recommended to simply shorten your filename. So instead of 'model_filename_2021.tpl' use e.g. 'model_21'.

Analyses are reproducible by setting the same initial values and a seed in sample_rwm or sample_nuts (passed to ADMB as '-mcseed'). However, they may not be entirely consistent across OS platforms. The chains will start the same but may eventually diverge. This is likely due to minuscule differences in the gradient and log-posterior calculations between systems and compilers.

Disclaimer

“The United States Department of Commerce (DOC) GitHub project code is provided on an ‘as is’ basis and the user assumes responsibility for its use. DOC has relinquished control of the information and no longer has responsibility to protect the integrity, confidentiality, or availability of the information. Any claims against the Department of Commerce stemming from the use of its 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.”