meta_sim {metafolio}

Run a single metapopulation simulation.

Description

This is the master function for running metafolio simulations. It runs a single iteration of a simulation. The arguments can be manipulated with other functions in the package to use this function as part of a portfolio analysis.

Usage

meta_sim(
  n_t = 130,
  n_pop = 10,
  stray_decay_rate = 0.1,
  stray_fraction = 0.02,
  b = rep(1000, n_pop),
  spawners_0 = round(b),
  sigma_v = 0.7,
  v_rho = 0.4,
  a_width_param = c(seq(0.08, 0.04, length.out = n_pop/2), rev(seq(0.08, 0.04, length.out
    = n_pop/2))),
  optim_temp = seq(13, 19, length.out = n_pop),
  max_a = thermal_integration(n_pop),
  env_type = c("sine", "arma", "regime", "linear", "constant"),
  env_params = list(amplitude = 3.2, ang_frequency = 0.2, phase = runif(1, -pi, pi),
    mean_value = 15, slope = 0, sigma_env = 0.3),
  start_assessment = 20,
  a_lim = c(0.02, 4),
  b_lim = c(0.5, 1.5),
  silence_warnings = TRUE,
  sigma_impl = 0.1,
  assess_freq = 10,
  use_cache = FALSE,
  cache_env = FALSE,
  add_straying = TRUE,
  add_impl_error = TRUE,
  skip_saving_cache = FALSE,
  decrease_b = 0,
  debug = FALSE
)

Arguments

n_t

The number of years.

n_pop

Number of populations

stray_decay_rate

Rate that straying (exponentially) decays with distance.

stray_fraction

Fraction of fish that stray from natal streams.

b

Ricker density-dependent parameter. A vector with one numeric value per population.

spawners_0

A vector of spawner abundances at the start of the simulation. Length of the vector should equal the number of populations.

sigma_v

Stock-recruit residual standard deviation of the log-deviations.

v_rho

AR1 serial correlation of stock-recruit residuals.

a_width_param

Width of the thermal curves by population.

optim_temp

Optimal temperatures by population.

max_a

Maximum Ricker productivity parameters (a) by population. The value obtained at the optimum temperature. Note how the default argument uses the thermal_integration function.

env_type

The type of environmental time series to generate. One of "sine", "arma", "regime", "linear", or "constant". See generate_env_ts.

env_params

Parameters to pass on to generate_env_ts. You must provide the appropriate list given your chosen type of environmental signal.

start_assessment

Generation to start estimating the stock recruit relationship for escapement targets. The assessment is carried out using fit_ricker.

a_lim

A vector of length two giving the lower and upper limits for Ricker a values. If a value is estimated beyond these limits it will be set to the limit value.

b_lim

A vector of length two giving the lower and upper limits for the estimated Ricker b values *as fractions* of the previously assessed value. If a value is estimated beyond these limits it will be set to the limit value.

silence_warnings

Should the warnings be skipped if the Ricker a or b values exceed their specified bounds? meta_sim will still print other warnings regardless of this argument value.

sigma_impl

Implementation standard deviation for the implementation error beta distribution.

assess_freq

How many generations before re-assessing Ricker a and b parameters.

use_cache

Use the stochastically generated values (stock-recruit residuals and possibly environmental time series) from the previous run? See the Details section below.

cache_env

Logical: Should the environmental time series be cached? If use_cache = TRUE then this will automatically happen. But, you could set cache_env = TRUE and use_cache = FALSE to only cache the environmental time series. See the Details section below.

add_straying

Implement straying between populations?

add_impl_error

Add implementation error? Implementation error is derived using impl_error.

skip_saving_cache

Logical: if TRUE then no data will be cached for the next iteration. This will save time when running many simulations.

decrease_b

A numeric value to decrease all streams by each generation. This is intended to be used to simulate habitat loss, for example though stream flow reduction with climate change.

debug

Logical: if TRUE then meta_sim will print a number of debugging statements while it runs.

Details

To use either of the caching options, you must have run meta_sim at least once in the current session with both caching arguments set to FALSE to generate the cached values first. If you're running many iterations of meta_sim and you want to cache, then the first iteration should have both cache arguments set to FALSE, and subsequent runs can set one or both to TRUE. Internally, meta_sim caches by writing the appropriate data to an .rda file in a temporary directory.

Value

A list is returned that contains the following elements. All matrices that are returned (except the straying matrix) feature populations along the columns and generations/years along the rows.

A

A matrix of abundances.

F

A matrix of fishing mortality in numbers.

E

A matrix of realized escapement.

Eps

A matrix of (log) spawner-return residuals. These have been log-normal bias corrected so their expected value after exponentiation will be one.

A_params

A matrix of actual Ricker a parameters.

Strays_leaving

A matrix of strays leaving.

Strays_joining

A matrix of strays joining.

env_ts

A vector of the environmental time series.

stray_mat

The straying matrix. These fractions are constant across generations/years. Rows and columns are populations.

n_pop

The total possible populations as input in the simulation.

n_t

The number of generations/years the simulation was run for.

b

The original Ricker b values as specified.

Est_a

A matrix of estimated Ricker a values.

Est_b

A matrix of estimated Ricker b values.

Examples

arma_env_params <- list(mean_value = 16, ar = 0.1, sigma_env = 2, ma = 0)
base1 <- meta_sim(n_pop = 10, env_params = arma_env_params,
  env_type = "arma", assess_freq = 5)

plot_sim_ts(base1, years_to_show = 70, burn = 30)