fishStan

fishStan: Hierarchical Bayesian models for fisheries - Published in JOSS (2022)

https://code.usgs.gov/umesc/quant-ecology/fishstan

Scientific Fields

Repository

Version 2+ of the fishStan package.

https://code.usgs.gov/umesc/quant-ecology/fishstan/blob/master/

# fishStan

#### Authors:          Richard A. Erickson, Daniel S. Stich, Jillian L. Hebert
#### Point of contact: Richard A. Erickson (rerickson@usgs.gov)
#### Repository Type:  Formal _R_ language package
#### Year of Origin:   2020 (original publication)
#### Year of Version:  2020
#### Version:          2.0.0 
#### Digital Object Identifier (DOI): https://doi.org/10.5066/P9TT3ILO
#### USGS Information Product Data System (IPDS) no.: IP-123048 (internal agency tracking)

***

_Suggested Citation:_

Erickson, RA. Stich, DS, Hebert, JL. 2020. fishStan: Hierarchical Bayesian models for
fisheries. U.S. Geological Survey software release. Reston, Va.
https://doi.org/10.5066/P9TT3ILO.

_Authors' [ORCID](https://orcid.org) nos.:_

- Richard A. Erickson, [0000-0003-4649-482X](https://orcid.org/0000-0003-4649-482X);
- Daniel S. Stich, [0000-0002-8946-1115](https://orcid.org/0000-0002-8946-1115);
- Jillian L. Hebert, [0000-0003-4893-8287](https://orcid.org/0000-0003-4893-8287);


***
***

`fishStan` is an `R` package (R Core Team 2020) providing a collection
of hierarchical Bayesian models written in the Stan language as called
through RStan (Stan Development Team 2020). 
The package is a USGS software software release. 

The purpose of the package is to document these models for use in USGS
projects and allow easy discrimination. 
The package assumes the user is familiar with R and hierarchical
models.
Furthermore, `fishStan` assumes the user has advanced level-knowledge
of these areas. 
The package is easier to use than compiling RStan models on ones own,
but requires more technical skill than using functions such as `lm()`
or `glm()`. 
`fishStan` users would also befit from understanding how `RStan`
works because it relies upon that package and users may use `RStan` tools for model diagnostics (and would benefit from doing so!) such as `rstan::traceplot()` to understand if their model converged. 

Currently, the project includes multiple models including

- Growth models
  - A hierarchical von Bertalanffy growth model,
  - A hierarchical von Bertalanffy growth model without t0,
  - A hierarchical Gompertz growth model
  - A hierarchical **L**ogistic **IN**dividual **G**rowth (LING) model
  - A hierarchical Galluci and Quinn growth model
- A hierarchical linear regression
- A hierarchical logistic regression model that includes both binomial
  and Bernoulli input options
- A catch curve model
  
All hierarchical models are based upon the _Multivariate
Priors for Hierarchical Models_ example from the [Stan User Manual,
Section 1.13][stan_user_1.13].
  
The R package contains vignettes providing an overview of the
package and how to use the models.
To access these, type `browseVignettes("fishStan")` in `R`. 

The package resides on the link shown in the _Suggested
Citation_. 
Please consult this README along with other files
(`CONTRIBUTING.md`, `DISCLAIMER.md`, `LICENSE.md`).

# User background

We expect users of `fishStan` to be familiar with Bayesian statistics.
A understanding of the subject area will also help the users to apply the models to their area (e.g., fisheries biology).
Furthermore, the user will want use tools to ensure their models have converged such as [`traceplot()`](https://mc-stan.org/rstan/reference/stanfit-method-traceplot.html) or looking at the model diagnostics.
Likewise, tools such as 
[`shinystan`](https://mc-stan.org/users/interfaces/shinystan) or [`loo`](https://mc-stan.org/users/interfaces/loo) may also be used with model results.


# Package Installation

Many users will want to install this packages using their locally
installed versions of R. 
However, we also include directions for installing this package
using Docker.
This package takes about 7 minutes to build on a Surface Pro 7 with an
Intel(R) Core(TM) i7-1065G7 CPU @ 1.30GHz  

## Using local R

Installing this package requires compilers because it uses RStan. 
On Windows, this requires RTools to be installed. 
On macOS, this requires XCode or other compilers to be installed.
The RStan homepage (https://mc-stan.org/rstan/, accessed 30 June 2020)
has directions for installing RStan. 
Windows users may find the RStan's Wiki
(https://github.com/stan-dev/rstan/wiki/Installing-RStan-from-source-on-Windows,
accessed 30 June 2020) to be helpful because RStan can be tricky to
install on Windows. 

Once RStan is installed, the fishStan package should be able to be installed
using the `remotes` package. 
The following code installs the remotes package if needed and then
installs this version 2.0 of this package. 

```{r}
if (!require("remotes")) install.packages("remotes")
remotes::install_gitlab('umesc/quant-ecology/fishstan@v2.1', host='code.usgs.gov')
```

You may also want to build the vignettes with the option
`build_vignettes = TRUE` in `remotes::install_gitlab()`.

## Build using local command line

Some users have reported problems with permissions and
`install_gitlab()` not working correctly.
If this is the case, you may want need to download this repository
either as a zip file or with the `git clone` command.
Then `cd` to the parent directory for the downloaded 
(and decompressed if needed) repository and type`R CMD INSTALL fishStan`.
This should build the package for you. 
However, this still requires access to a `C++` compiler
(e.g., RTools on Windows or XCode on macOS).

## Using Docker

For people familiar with Docker, this code will create a Docker image
where you may build this package. 
**Note the code does not install the packages due to complications
caused by trying to use `rstantools` from inside a dockerfile. 
Instead, you may use the running Docker container to install the package.**
To do so, save the following script to a `Dockerfile`:

```{bash}
FROM rocker/verse

## Adapted from https://hub.docker.com/r/asachet/rocker-stan/dockerfile
## To strip down the rocker version
## and also write the install_rstan.R file inside of docker instead of
## copying it locally
RUN apt-get update \
	&& apt-get install -y --no-install-recommends \
	clang


## From https://github.com/stan-dev/rstan/wiki/Installing-RStan-on-Linux
RUN echo \
	'dotR <- file.path(Sys.getenv("HOME"), ".R")\n\
	if (!file.exists(dotR)) dir.create(dotR)\n\
	M <- file.path(dotR, "Makevars")\n\
	if (!file.exists(M)) file.create(M)\n\
	cat("\nCXX14FLAGS=-O3 -march=native -mtune=native -fPIC",\n\
	"CXX14=g++",\n\
	file = M, sep = "\n", append = TRUE)'\
	| cat >> install_rstan.R

RUN ["r", "install_rstan.R"]


# Install rstan
RUN install2.r --error --deps TRUE \
    rstan \
    && rm -rf /tmp/downloaded_packages/ /tmp/*.rds

# Installing the rest 
RUN install2.r -s --error \
	bayesplot \
	brms \
	coda \
	loo \
	projpred \
	rstanarm \
	rstantools \ 
	shinystan \
	tidybayes \
	ggthemes

RUN R -e "update.packages(repos = 'http://cran.us.r-project.org')"
```

Next, change (`cd`) into the directory containing the Dockerfile,
then build the image using the following command:

```{bash}
docker build --rm --force-rm -t rerickson/rstan .
```

On Windows, the Docker container may then by run by typing 

```{bash}
docker run -d -p 8787:8787 -e PASSWORD=nowUse -v ${PWD}:/home/rstudio:z -w /home/rstudio/ rerickson/rstan
```

On *nix systems, the Docker container may be run by typing

```{bash}
docker run -d -p 8787:8787 -e PASSWORD=nowUse -v $(pwd):/home/rstudio:z -w /home/rstudio/ rerickson/rstan
```

Open a browser window and navigate to `localhost::8787`. Log in with username = 'rstudio', password = 'nowUse'
(or modify the password in the `docker run` command to a value of your choosing).

Once you have Docker running, install the package using the previous
sections' directions. 


# Repository Files

This repository contains the code for an R package using RStan.
This repository contains the standard R repository files 
(see the official R Documentation [_Writing R Extensions_][r_ext]
accessed 30 June 2020 or Wickhman 2015 for an descriptions of these
files) as well as RStan package files. 
The `rstantools` package (Gabry et al. 2020) describes these files. 
In addition to the R Package source files, this repository contains
the following files:

- `README.md` is this file.
- `LICENSE.md` is the Official USGS License. 
- `code.json` is the code metadata.
- `CONTRIBUTING.md` describes how to contribute to this project.
- `DISCLAIMER.md` is the standard USGS disclaimer.
- `.gitignore` is a file telling git which files to not track.
- `.Rbuildignore` is a file telling R what files to exclude.

# Note

When running the von Bertalanffy growth model, the following exception may be generated in at least one but maybe two chains:

Chain : Exception: Exception: normal_rng: Location parameter is -inf, but must be finite!  (in '/functions/growth_projection_von_b.stan' at line 53; included from 'model_h_growth' at line 3) (in 'model_h_growth' at line 91)

The exception (which disappears after commenting out the generated quantities section of the von Bertalanffy growth stan model) can be ignored as long as none of the variables defined in the generated quantities section (including site_projections, hyper_projection, m_mortality, m_mortality_bar, growth_coef, and growth_coef_hyper) are used or interpreted. Especially do not use or interpret any site projection values as the exception is generated from within the function that calculates site projection values. See issue #2 for more information about the exception.

# Acknowledgments

Dave Glover and Jahn Kallis provided guidance for the initial
development of this package. 
This research was funded by the USGS Invasive Species Program and
Great Lakes Restoration Initiative. 

# References

Gabry J, Goodrich B, M Lysy 2020. rstantools: Tools
for Developing R Packages Interfacing with
'Stan'. https://mc-stan.org/rstantools/,
https://discourse.mc-stan.org/.

R Core Team (2020). R: A language and environment for statistical
computing. R Foundation for Statistical Computing, Vienna,
Austria. URL https://www.R-project.org/

Stan Development Team (2020). RStan: the R interface to Stan. R package version 2.19.3. http://mc-stan.org/.

[r_ext]: https://cran.r-project.org/doc/manuals/r-release/R-exts.html
[stan_user_1.13]: https://mc-stan.org/docs/2_22/stan-users-guide/multivariate-hierarchical-priors-section.html

Owner

JOSS Publication

fishStan: Hierarchical Bayesian models for fisheries

Published

March 21, 2022

DOI

10.21105/joss.03444

Volume 7, Issue 71, Page 3444

Authors

Richard A. Erickson
U.S. Geological Survey, Upper Midwest Environmental Sciences Center, La Crosse, WI, United States of America

Daniel S. Stich
State University of New York at Oneonta, Oneonta, NY, United States of America

Jillian L. Hebert
U.S. Geological Survey, Upper Midwest Environmental Sciences Center, La Crosse, WI, United States of America

Editor

Marcos Vital

Tags

population ecology hierarchical Bayesian models fisheries assessment

View PDF Review Thread Software Archive

Committers

Last synced: 10 months ago

Issues and Pull Requests

Last synced: 10 months ago