Fall Run Model Frequently Asked Questions
model_faq.RmdFrequently Asked Questions
Repository Structure
Q: Where is all the code for the model within the repository directory structure?
A: The R/ directory contains all model code. The filenames describe the type of functions within the file. For example, survival.R includes all of the survival sub-model functions for the model.
Q: Where is the code defining the lifecycle mechanics?
A: The functions within the file R/model.R defines
the lifecycle mechanics. For example, for fallRunDSM, the function
fall_run_model() in R/model.R defines the
lifecycle mechanics of fall-run Chinooks.This function calls submodels
to route, rear, grow, and apply survival to fish. These submodels are
all found in the R directory.
Q: Where are the details for model/sub-model parameters, calibration analysis, and sensitivity analysis?
A: The calibration, sensitivity analysis, and reference materials are found on the model documentation website, under the following links:
The reference tab includes the details for model parameters, sub-models, datasets, and helper functions. The Articles tab contains the details regarding calibration and sensitivity analysis.
Q: What is the code repository’s analysis folder?
A: The analysis folder contains scripts for running sensitivity analysis and scenarios. These scripts operate in parallel and are a good starting point for further analysis.
Q: What is the code repository’s calibration folder?
A: The calibration folder contains scripts for running calibration on DSM models and helper scripts for updating the cached data within the model.
Q: What is the code repository’s man folder?
A: The man folder contains the manual that generates the model/sub-model documentation.
Q: Where can I see code examples of how to run the model?
A: Each model has a website where the front page provides the model code. For more information regarding the run model, check out the run_model documentation.
Q: How are all the repositories related to each other on R2R Organization’s GitHub?
A: The models (fallRunDSM, lateFallRunDSM, winterRunDSM, and
springRunDSM) use data objects from DSMflow, DSMtemperature, and
DSMhabitat packages as model inputs. Data objects for each run are
cached from these data packages and available under the params data
object. To access stream temperature specific to fallRunDSM one would
use the following: fallRunDSM::params$avg_temp.
The package DSMscenario creates scenarios to show how Chinook salmon populations change depending on potential restoration actions. More information on scenario development can be found here.
Model Mechanics
Q: What is the overall structure of the model in R?
A: The overall structure of the model starts by defining global variables to be used as input and storage. It then steps into an annual loop (either 5 or 20 years depending on the model mode). Within this annual loop a second loop representing months is defined in which juvenile fish grow and move. Upon closing of a single month iteration, fish are either sent to the ocean or remain in rearing for use in the next month’s dynamics. Upon closing of all month iterations, returning adults are calculated and used in the next annual iteration. The model finishes running once the annual iteration is complete and outputs are calculated.
Q: What is the difference between calibrate, seed, and simulate mode
in the fall_run_model() function?
A: In seed mode the model runs for five years and returns a matrix of seeding adults to be used in the simulation mode of the model. In simulation mode the model runs for 20 years and uses adults obtained from running the model in seed mode and returns a data object with the following outputs: spawners, juvenile biomass, and proportion natural. In calibration mode the model runs for 20 years and uses known adults as input from the DSMCalibration package and returns a matrix of adults to be used in calculating a loss value for use in the calibration process.
Q: Why do some function argument names begin with ‘.’ and others ‘..’?
A: Sub-model coefficients are function arguments to facilitate sensitivity analysis. We identify these coefficients by beginning the argument names with a ‘.’ or ‘..’. Coefficient argument names that start with ‘..’ have been derived from calibration. Coefficient argument names that start with ‘.’ were derived from meta-analysis, literature, or expert opinion.
Q: What does the stochastic argument to the model do?
A: The model will run using random variation submodels when stochastic is true. While all inputs are constant, running the model with stochastic set to true will result in different outputs each time. While all inputs are constant, running the model with stochastic set to false will result in the same output each time.
Q: Where can I find the code that defines fish routing onto the floodplain, in-channel, or out-migrating?
A: The code that defines where fish are routed (floodplain, in-channel, or migrating) is defined within the monthly dynamics for loop. This for loop exists within the annual iterations and can be easily found by locating the following code (for fall-run for example):
Each model version, (fall, winter, and spring) will vary on the months used for iteration but the structure remains the same.
Q: Where are survival probabilities calculated?
A: R/survival.R
contains the definition for survival sub-models. All survival functions
start with “surv_”, followed by the specific survival sub-model name.
For example, the function signature for juvenile rearing survival is
surv_juv_rear. R/survival.R also contains two helper
functions get_rearing_survival and
get_migratory_survival these call the individual survival
submodels to increase readability in the main model file.
Model Inputs
Q: How can I find details about temperature modeling for a given watershed?
A: The DSMtemperature repository contains the details for temperature modeling for a given watershed. The documentation for this repository includes details regarding the inputs for the temperature model. Each temperature-related data set for each watershed is found in the reference section.
Q: How can I find details about habitat modeling for a given watershed?
A: The DSMhabitat repository contains the details for habitat modeling for a given watershed. The documentation for this repository contains details regarding habitat functions, habitat datasets, miscellaneous datasets, and model input data. The details for a given watershed are found under habitat datasets.
Q: How can I find details about flow modeling for a given watershed?
A: The DSMflow repository contains details for flow modeling for a given watershed. The documentation for this repository includes details regarding the model used to generate hydrologic inputs for the project. The details for each flow-related data set are found in the reference section.
Miscellaneous
Q: How do I know I have the most up to date version of the model and data packages installed? What if I want to use an older version?
A: Version control is handled through GitHub. To install the latest versions of the model and any other CVPIA package use the following code:
remotes::install_github("cvpia-osc/fallRunDSM")To install a specific version of the model, first identify the branch
associated with the release version (these use the tag v1.0, v1.1 and so
on), then modify the install_github function call as
follows
remotes::install_github("reorienting-to-recovery/fallRunDSM@v1.0")Q: I found something within the code or inputs that seems like an error, how can I notify model developers?
A: When you find n error, you can open an issue on GitHub. In the comments section of the issue please describe the problem in detail, and if possible paste code that reproduces this error. Maintainers will be notified of this issue and communicate with you on the issue tracker page.