androscogginRiverModel: Androscoggin River Model

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

Androscoggin River Model

Description

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

Usage

androscogginRiverModel(
  nRuns = 1,
  species = "shad",
  nYears = 40,
  n_adults = 10000,
  timing = rep(1, 12),
  p_sabattus = 0.05,
  upstream = list(brunswick = 1, pejepscot = 1, worumbo = 1, lbarker = 1, ubarker = 1,
    littlefield = 1, hackett = 1, marcal = 1, welchville = 1, paris = 1, farwell = 1,
    fortier = 1),
  downstream = list(brunswick = 1, pejepscot = 1, worumbo = 1, lbarker = 1, ubarker =
    1, littlefield = 1, hackett = 1, marcal = 1, welchville = 1, paris = 1, farwell = 1,
    fortier = 1),
  downstream_juv = list(brunswick = 1, pejepscot = 1, worumbo = 1, lbarker = 1, ubarker
    = 1, littlefield = 1, hackett = 1, marcal = 1, welchville = 1, paris = 1, farwell =
    1, fortier = 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.
p_sabattus	Probability of using the Sabattus River for migration. Default is based on proportional distribution of habitat in each route.
upstream	A named list of upstream dam passage efficiencies at each dam in the Androscoggin River and its largest tributary, the Sabattus 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. As a rough rule of thumb we advise a minimum of 100 runs per combination of management parameters (upstream timing and passage, and downstream survival through dams).
downstream	A named list of downstream dam passage efficiencies at each dam in the Androscoggin river.
downstream_juv	A named list of downstream dam passage efficiencies at each dam in the Androscoggin River for juveniles.
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

• p_sabattus Probability of fish using the Sabattus River during upstream migration and spawning

• timing_brunswick...timing_paris Passage timing input by user

• brunswick_us...fortier_us User-specified upstream passage efficiencies

• brunswick_ds...fortier_ds User-specified downstream passage efficiencies

• brunswick_dsj...fortier_dsj User-specified juvenile downstream passage efficiencies

• F.inRiver User-specified recreational fishing mortality

• F.commercial User-specified recreational fishing mortality

• F.recreational User-specified recreational fishing mortality

• indirectM User-specified indirect mortality dams

• indirectM User-specified latent mortality

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

• N_IA...N_IB 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

Schematic of production units coming soon

NA

Warning about serial execution and memory limits

Currently, internal functions rely on list2env() to return lists to a temporary environment created in the androscogginRiverModel() 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 the snowfall package in the example below.

Examples

# Parallel execution on a local cluster
# \dontrun{

# 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) {
  times <- c(1, 3, 7, 20)
  timex <- sample(times, 1)

  upstream <- sample(c(.7, .8, 0.9, 1), 1)
  downstream <- 1
  downstream_juv <- 0.95

  # Run the model
  sim <- androscogginRiverModel(
    nRuns = 1,
    species = "shad",
    nYears = 20,
    n_adults = 10000,
    timing = rep(1, 13),
    p_sabattus = 0.05,
    upstream = list(
      brunswick = upstream,
      pejepscot = 1,
      worumbo = 1,
      lbarker = 1,
      ubarker = 1,
      littlefield = 1,
      hackett = 1,
      marcal = 1,
      welchville = 1, 
      paris = 1,
      farwell = 1,
      fortier = 1),
    downstream = list(
      brunswick = downstream,
      pejepscot = 1,
      worumbo = 1,
      lbarker = 1,
      ubarker = 1,
      littlefield = 1,
      hackett = 1,
      marcal = 1,
      welchville = 1, 
      paris = 1,
      farwell = 1,
      fortier = 1),
    downstream_juv = list(
      brunswick = downstream_juv,
      pejepscot = 1,
      worumbo = 1,
      lbarker = 1,
      ubarker = 1,
      littlefield = 1,
      hackett = 1,
      marcal = 1,
      welchville = 1, 
      paris = 1,
      farwell = 1,
      fortier = 1),
    inRiverF = 0,
    commercialF = 0,
    bycatchF = 0,
    indirect = 1,
    latent = 1,
    watershed = TRUE,
    k_method = "cumulative",
    sensitivity = FALSE
  )

  # 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, timing_brunswick, brunswick_us) %>%
  summarize(
    pop = mean(populationSize),
    lci = CI(populationSize)[1],
    uci = CI(populationSize)[2],
    .groups = "keep"
  )

ggplot(
  plotter,
  aes(
    x = year, y = pop,
    fill = factor(brunswick_us),
    color = factor(brunswick_us)
  )
) +
  geom_line(lwd = 1) +
  geom_ribbon(
    aes(x = year, ymin = lci, ymax = uci, color = NULL),
    alpha = 0.15
  ) +
  xlab("Year") +
  ylab("Millions of spawners") +
  labs(
    fill = "Upstream passage",
    color = "Upstream passage"
  ) +
  scale_y_continuous(
    breaks = seq(0, 10e7, .5e6),
    labels = format(seq(0, 100, 0.5), digits = 2)
  ) +
  theme_bw() +
  theme(
    axis.title.x = element_text(vjust = -1),
    axis.title.y = element_text(vjust = 3),
    legend.position = "top"
  ) +
  facet_wrap(~timing_brunswick)

# }

danStich/shadia documentation built on Nov. 2, 2023, 6:43 a.m.