gettingstarted.Rmd

```{r, child="_styles.Rmd"}
```

<h2 id="multi"><b>Getting started with `shadia`</b></h2>

The purpose of this page is to get users set up to run American shad dam passage performance standards models. New users should follow instructions for installation and read notes related to use on this page before moving on to <a href="models.html">model overviews</a> and <a href="examples.html">examples</a>.

<h3 id="multi"><b>Installation</b></h3>

This package can be installed with the [`devtools`](https://www.rstudio.com/products/rpackages/devtools/) package in R using the repository url: `devtools::install_github("danStich/shadia")`.

To install `shadia`, you will need to have `devtools` installed ahead of time in R, but that requires some special tools. To install on **Windows**, you will need to download and install the appropriate version of [Rtools](https://cran.r-project.org/bin/windows/Rtools/). To install on **Mac**, you will need to have the [XCode command-line tools](http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/) installed. And, if running from **Linux**, you will need to install the developer version of R (`r-base-dev`) if you have not already.
 
<h3 id="multi"><b>Use</b></h3>

The purpose of this package is to distribute code used to run the American shad dam passage performance standard model. Currently, the model is implemented for the **Connecticut**, **Kennebec**, **Merrimack**, **Mohawk and Hudson**, **Penobscot**, **Saco**, and **Susquehanna** rivers, USA, and we add new rivers as need arises. The main package functions include `connecticutRiverModel()`, `kennebecRiverModel()`, `merrimackRiverModel()`, `mohawkHudsonRiverModel()`, `penobscotRiverModel()`, `sacoRiverModel()`, and `susquehannaRiverModel()`. 

These models can be run without any arguments to estimate population abundance in specific reaches or in whole rivers under 'no dam' passage scenarios. Alternatively, the user can specify upstream and downstream fish passage at dams to simulate populations under different hydropower management scenarios. Timing of upstream passage, fishery, and bycatch mortality can also be defined as deterministic management scenarios or stochastic inputs for all rivers. Outputs include population abundance of spawners in the watersheds, within specific production units of each river, and the proportion of repeat spawners in each age class.

The models each take several (10-30) seconds to run for one iteration on most standard workstations. For that reason, we strongly recommend using a parallel approach where multiple model runs are needed.

<h3 id="multi"><b>Parallel execution</b></h3>

Management decisions should not be based on a single model run. The models rely on stochastic inputs for parameterization, as detailed in [Stich et al. (2019)](http://www.nrcresearchpress.com/doi/10.1139/cjfas-2018-0008#.W2SVohRKgeI). As such, any two model runs might result in substantially different predictions, even under the same management scenario. Thus, mutliple runs of a given scenario are needed to provide a minimal characterization of stochasticity, and an understanding of variability in the response(s) of interest. In these cases, we strongly recommend running the model using the `snowfall` package as demonstrated in the help file for each model, which can be accessed by typing `?...RiverModel` (where '`...`' is the name of each river in lowercase) in the console and pressing `< Enter >`, or on the [examples page of this website](examples.html).

</br>