sacoRiverModel: Saco River Model

In danStich/shadia: American shad dam passage performance standard model for R

Saco River Model

Description

Dam passage performance standard model for Saco River, Maine, USA

Usage

sacoRiverModel(
  nRuns = 1,
  species = "shad",
  nYears = 40,
  n_adults = 10000,
  timing = c(1, 1, 1, 1, 1, 1),
  upstream = list(cataract = 1, spring = 1, skelton = 1, barmills = 1, westBuxton = 1,
    bonnyEagle = 1),
  downstream = list(cataract = 1, spring = 1, barmills = 1, skelton = 1, westBuxton = 1,
    bonnyEagle = 1),
  downstream_juv = list(cataract = 1, spring = 1, barmills = 1, skelton = 1, westBuxton =
    1, bonnyEagle = 1),
  inRiverF = 0,
  commercialF = 0,
  bycatchF = 0,
  indirect = 1,
  latent = 1,
  watershed = FALSE,
  k_method = "cumulative",
  sensitivity = FALSE,
  spatially_explicit_output = FALSE,
  output_years = NULL,
  output_p_repeat = FALSE
)

Arguments

nRuns	The number of times that the model will be run.
species	Species for which the model will be run. Current options include American 'shad' and 'blueback' herring.
nYears	The number of years for which each run will last. The default is 40 years to match default FERC license duration.
n_adults	Number of starting adults in population.
timing	The amount of time required for upstream passage by individual fish (in days), where the default (1) indicates a 24-h dam passage performance standard and the value is specified as a proportion of 1 day.
upstream	A named list of upstream dam passage efficiencies at each dam in the Saco River. Users may specify a single value of upstream passage at each dam, or a vector of upstream passage efficiencies at each dam. Note that passage efficiences passed as vectors are randomly sampled during each model run (not each year). Therefore, multiple model runs are necessary if more than one passage efficiency is supplied for any dam.
downstream	A named list of downstream dam passage efficiencies at each dam. Users may specify a single value of downstream passage at each dam, or a vector of downstream passage efficiencies at each dam. Note that passage efficiences passed as vectors are randomly sampled during each model run (not each year). Therefore, multiple model runs are necessary if more than one passage efficiency is supplied for any dam.
downstream_juv	A named list of downstream juvenile dam passage efficiencies at each dam.
inRiverF	Annual, recreational harvest in river. Parameterized as an annual rate [0, 1].
commercialF	Commercial fishery mortality in marine environment incurred through targeted fisheries. Parameterized as an annual rate [0, 1].
bycatchF	Marine bycatch mortality of species in non-target fisheries. Parameterized as an annual rate [0, 1].
indirect	Indirect mortality incurred during freshwater migration as a result of dam-related impacts (e.g., injury, predation, etc.).
latent	Latent mortality incurred during estuary passage as a result of dam-related impacts (e.g., injury, delay, etc.).
watershed	A logical indicating whether or not to use the same dam passage efficiencies at all dams for upstream and downstream. If watershed = TRUE, then the first element in lists 'upstream', 'downstream', and 'downstream_juv' are recycled for all subsequent dams.
k_method	Method used to impose carrying capacity. The default, 'cumulative', assumes that carrying capacity is based on all available habitat through the most upstream occupied production units in a given migration route. The alternative, 'discrete' assumes that carrying capacity is applied within discrete production units based on the numbers, and was the method used in Stich et al. (2019).
sensitivity	Whether to return a dataframe for sensitivity analysis. The default is set to FALSE for faster run time and smaller memory load in parallel processing.
spatially_explicit_output	Whether to return population size in each production unit.
output_years	Whether to return all years (default = 'NULL') or only final year of each simulation ('"last"').
output_p_repeat	A logical indicating whether to return pRepeat by age (in years) with the output. The default value is 'FALSE' to limit output size in physical memory.

Value

Returns a dataframe when sensitivity = FALSE (default). Returns a list of two named dataframes when sensitivity = TRUE. The first dataframe (res) contains user-defined inputs and available model outputs depending on optional arguments. The second dataframe (sens) contains input variables for sensitivity analysis if desired. If run in parallel, returns a list of lists of dataframes.

The following named columns may be returned in res:

• year Year of simulation

• species Species used for simulation

• timing_cataract...timing_bonnyEagle Passage timing input by user

• cataract_us...bonnyEagle_us User-specified upstream passage efficiencies

• cataract_ds...bonnyEagle_ds User-specified downstream passage efficiencies

• cataract_dsj...bonnyEagle_dsj User-specified juvenile downstream passage efficiencies

• F.inRiver User-specified recreational fishing mortality

• F.commercial User-specified recreational fishing mortality

• F.bycatch User-specified recreational fishing mortality

• indirect User-specified indirect mortality dams

• latent User-specified latent mortality

• pRepeat_Age1...pRepeat_AgeN Age-specific probability of repeat spawning

• N_I...N_VII Production unit-specific population size after in-river fishery mortality

• populationSize Number of spawners returning to the river

The following named columns are returned in sens:

• S.downstream Downstream survival per kilometer

• S.marine Marine survival as an annual rate

• popStart Starting population size

• p.female Probability of being female

• S.prespawnM Prespawn survival rate for males

• S.postspawnM Postspawn survival rate for males

• S.prespawnF Postspawn survival rate for males

• S.postspawnF Postspawn survival rate for males

• S.juvenile Hatch to out-migrant survival rate

• b.Arr Mean arrival date for males

• r.Arr Mean arrival date for females

• ATUspawn1 Accumulated thermal units at initiation of spawn

• ATUspawn2 Accumulated thermal units at termination of spawn

• Dspawn1 Initial spawning date

• Dspawn2 Terminal spawning date

• linF L-infinity parameter from the von Bertalanffy growth function for females

• kF K parameter from the von Bertalanffy growth function for females

• t0F t0 parameter from the von Bertalanffy growth function for females

• linM L-infinity parameter from the von Bertalanffy growth function for males

• kM K parameter from the von Bertalanffy growth function for males

• t0M t0 parameter from the von Bertalanffy growth function for males

• b.length Mean length of males

• r.length Mean length of females

• spawnInt Mean spawning interval

• batchSize Mean batch size

• resTime Mean residence time

• s.Optim Mean optimal ground speed

• d.Max Mean maximum daily movement rate

• tortuosity Path tortuosity parameter

• motivation Seasonal change in fish "motivation" for upstream movement

• daily.move Mean realized daily movement rate

• habStoch Habitat stochasticity

Production units delineated by main-stem dams

• Saco River

  • PU I Downstream of Cataract Project

  • PU II Cataract Project to Springs and Bradbury

  • PU III Springs and Bradbury Dam to Skelton

  • PU IV Skelton Dam to Bar Mills

  • PU V Bar Mills Dam to West Buxton

  • PU VI West Buxton Dam to Bonny Eagle

  • PU VII Bonny Eagle Dam to Hiram Falls

Schematic of production units

Production units delineated by dams in the watershed. Circles are log proportional to carrying capacity in each unit.

Warning about serial execution and memory limits

Currently, internal functions rely on list2env to return lists to a temporary environment created in the sacoRiverModel function. Consequently, lists that are exported must be limited in size. Therefore, users currently need to limit the number of runs per call (nRuns argument) to less than 10 or R will hit memory limits quickly. In reality, serial execution is prohibitively slow unless implemented using manual parallel processing (e.g., bash scripting).

In order to achieve a desired number of runs for a given set of inputs, the recommended approach is to use parallel execution as demonstrated using snowfall in the example below.

Examples

# Parallel execution on a local cluster
## Not run: 

# Load R packages
library(snowfall)
library(rlecuyer)
library(shadia)
library(tidyverse)

# Initialize parallel socket cluster
sfInit(parallel = TRUE, cpus = 7, type = "SOCK")

# Define a model run as a function
model <- function(x) {

  # Run the model
  sim <- sacoRiverModel()

  # Output
  return(sim)
}

# Export  libraries or data to workers
sfLibrary(shadia)

# Distribute calculation to workers
niterations <- 30

# Use sfLapply() to distribute simulations to workers
# and run the model with these settings in parallel
result <- sfLapply(1:niterations, model)

# Stop snowfall
Sys.time() - start

# Extract user inputs and population metrics
resdf <- do.call(rbind, result)

# . Abundance at mouth ----
library(tidyverse)
plotter <- resdf %>%
  group_by(year) %>%
  summarize(
    pop = mean(populationSize),
    lci = CI(populationSize)[1],
    uci = CI(populationSize)[2],
    .groups = "keep"
  )

ggplot(plotter, aes(x = year, y = pop)) +
  geom_line(lwd = 1) +
  geom_ribbon(aes(x = year, ymin = lci, ymax = uci, color = NULL)) +
  xlab("Year") +
  ylab("Millions of spawners") +
  scale_y_continuous(
    breaks = seq(0, 10e7, .5e6),
    labels = format(seq(0, 100, 0.5), digits = 2)
  )


## End(Not run)

danStich/shadia documentation built on Aug. 28, 2024, 9:42 p.m.