penobscotRiverModel: Penobscot River Model

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

Penobscot River Model

Description

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

Usage

penobscotRiverModel(
  nRuns = 1,
  species = "shad",
  nYears = 40,
  n_adults = 10000,
  pStillwaterUp = rbeta(1, 15, 120),
  pStillwaterD = rbeta(1, 15, 120),
  pPiscUp = rbeta(1, 25, 75),
  timing = c(1, 1, 1, 1, 1, 1, 1),
  upstream = list(milford = 1, howland = 1, westEnfield = 1, brownsMill = 1, moosehead =
    1, guilford = 1, weldon = 1),
  downstream = list(stillwater = 1, orono = 1, milford = 1, howland = 1, westEnfield = 1,
    brownsMill = 1, moosehead = 1, guilford = 1, weldon = 1),
  downstream_juv = list(stillwater = 1, orono = 1, milford = 1, howland = 1, westEnfield
    = 1, brownsMill = 1, moosehead = 1, guilford = 1, weldon = 1),
  pinHarvest = 0,
  inRiverF = 0,
  commercialF = 0,
  bycatchF = 0,
  indirect = 1,
  latent = 1,
  watershed = FALSE,
  climate = "current",
  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.
pStillwaterUp	Probability of using the Stillwater Branch for upstream migration. The default is based on proportional distribution of discharge around Marsh Island.
pStillwaterD	Probability of using the Stillwater Branch for downstream migration. The default is based on proportional distribution of discharge around Marsh Island.
pPiscUp	Probability of using the Piscataquis River during upstream migration. The default is based on proportional distribution of habitat in the Piscataquis and mainstem Penobscot rivers.
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 Penobscot River. Stillwater and Orono dams are not included in the list of values because all fish reaching Orono Dam are "trucked" upstream. 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 in the Penobscot River (including Orono and Stillwater dams). 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 dam passage efficiencies at each dam in the Kennebec River for juveniles.
pinHarvest	In-river, sustenance harvest by Penobscot Indian Nation (PIN) upstream of Weldon Dam. Parameterized as an annual rate [0, 1].
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

• climate Climate scenario used for simulation

• pStillUp Probability of fish using the Stillwater Branch for upstream migration

• pBypassD Probability of fish using the Stillwater Branch for downstream migration

• pPiscUp Probability of fish using the Piscataquis River for upstream migration and spawning

• timing_milford...timing_guilford Passage timing input by user

• milford_us...guilford_us User-specified upstream passage efficiencies

• milford_ds...guilford_ds User-specified downstream passage efficiencies

• milford_dsj...guilford_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_pu1A2A...N_pu4B 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

Production units delineated by dams in the watershed. Circles are log proportional to carrying capacity in each unit. Black dots indicate no suitable habitat in a unit.

Warning about serial execution and memory limits

Currently, internal functions rely on list2env to return lists to a temporary environment created in the penobscotRiverModel 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 <- penobscotRiverModel()

  # Output
  return(sim)
}

# Export  libraries or data to workers
sfLibrary(shadia)

# Distribute calculation to workers
niterations <- 200

# 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.