action_spawn: Gadget3 spawning action

In lentinj/gadget3: Globally-Applicable Area Disaggregated General Ecosystem Toolbox V3

Gadget3 spawning action

Description

Add spawning to a g3 model

Usage

g3a_spawn_recruitment_fecundity(
        p0 = g3_parameterized('spawn.p0', value = 1, by_stock = by_stock),
        p1 = g3_parameterized('spawn.p1', value = 1, by_stock = by_stock),
        p2 = g3_parameterized('spawn.p2', value = 1, by_stock = by_stock),
        p3 = g3_parameterized('spawn.p3', value = 1, by_stock = by_stock),
        p4 = g3_parameterized('spawn.p4', value = 1, by_stock = by_stock),
        by_stock = TRUE )

g3a_spawn_recruitment_simplessb(
        mu = g3_parameterized('spawn.mu', by_stock = by_stock),
        by_stock = TRUE )

g3a_spawn_recruitment_ricker(
        mu = g3_parameterized('spawn.mu', by_stock = by_stock),
        lambda = g3_parameterized('spawn.lambda', by_stock = by_stock),
        by_stock = TRUE )

g3a_spawn_recruitment_bevertonholt(
        mu = g3_parameterized('spawn.mu', by_stock = by_stock),
        lambda = g3_parameterized('spawn.lambda', by_stock = by_stock),
        by_stock = TRUE )

g3a_spawn_recruitment_bevertonholt_ss3(
        # Steepness parameter
        h = g3_parameterized('spawn.h', lower = 0.1, upper = 1, value = 0.5,
            by_stock = by_stock ),
        # Recruitment deviates
        R = g3_parameterized('spawn.R', by_year = TRUE, exponentiate = TRUE,
            # Unfished equilibrium recruitment
            scale = "spawn.R0",
            by_stock = by_stock),
        # Unfished equilibrium spawning biomass (corresponding to R0)
        B0 = g3_parameterized('spawn.B0', by_stock = by_stock),
        by_stock = TRUE )

g3a_spawn_recruitment_hockeystick(
        r0 = g3_parameterized('spawn.r0', by_stock = by_stock),
        blim = g3_parameterized('spawn.blim', value = 1, by_stock = by_stock),
        by_stock = TRUE )

g3a_spawn(
        stock,
        recruitment_f,
        proportion_f = 1,
        mortality_f = 0,
        weightloss_f = 0,
        weightloss_args = list(),
        output_stocks = list(),
        output_ratios = rep(1 / length(output_stocks), times = length(output_stocks)),
        mean_f = g3a_renewal_vonb_t0(by_stock = by_stock),
        stddev_f = g3_parameterized('rec.sd', value = 10, by_stock = by_stock),
        alpha_f = g3_parameterized('walpha', by_stock = wgt_by_stock),
        beta_f = g3_parameterized('wbeta', by_stock = wgt_by_stock),
        by_stock = TRUE,
        wgt_by_stock = TRUE,
        run_step = NULL,
        run_f = ~TRUE,
        run_at = g3_action_order$spawn,
        recruit_at = g3_action_order$renewal)

Arguments

p0, p1, p2, p3, p4	Substituted into g3a_spawn_recruitment_fecundity formula, see below.
mu, lambda, h, R, B0, r0, blim	Substituted into g3a_spawn_recruitment_* formula, see below.
stock	The mature g3_stock that will spawn in this action.
recruitment_f	A list of formula generated by one of the g3a_spawn_recruitment_* functions, containing s Formula run for each subset of stock r Final formula for calculating number of recruits for spawning action
proportion_f	formula generated by one of the g3_suitability_* functions, describing the proportion of stock that will spawn at this timestep.
mortality_f	formula generated by one of the g3_suitability_* functions, describing the proportion of spawning stock that will die during spawning.
weightloss_f	formula generated by one of the g3_suitability_* functions, describing the overall weight loss during spawning. DEPRECATED: Use weightloss_args for new models.
weightloss_args	list of options to pass to g3a_weightloss, e.g. rel_loss & abs_loss. If not empty, a weightloss action will be included as part of spawning.
output_stocks	List of g3_stocks that will be spawned into.
output_ratios	Vector of proportions for how to distribute into output_stocks, summing to 1, default evenly spread.
mean_f, stddev_f, alpha_f, beta_f	formula substituted into stock structure calculations, see g3a_renewal_normalparam for details.
run_step	Which step to perform renewal in, or NULL for continuous spawning. Adds cur_step == (run_step) into default run_f.
run_f	formula specifying a condition for running this action, default always runs.
run_at	Integer order that spawning actions will be run within model, see g3_action_order.
recruit_at	Integer order that recruitment from spawning will be run within model, see g3_action_order.
by_stock, wgt_by_stock	Controls how parameters are grouped, see g3_parameterized

Details

To restrict spawning to a particular step in a year, or a particular area, use run_f. For example:

cur_step == 1

Spawning will happen on first step of every year

cur_step == 1 && cur_year >= 1990

Spawning will happen on first step of every year after 1990

cur_step == 2 && area = 1

Spawning will happen on second step of every year, in the first area

The action will define the following stock instance variables for each given stock and output_stock:

stock__spawnprop

Proportion of (stock) that are spawning in this spawning event

stock__spawningnum

Numbers of (stock) that are spawning in this spawning event

output_stock__spawnednum

Numbers of (output_stock) that will be produced in this spawning event

Value

g3a_spawn_recruitment_fecundity

A pair of formula objects:

S = l ^{p_{1}} a^{p_{2}} (p N_{al})^{p_{3}} W_{al}^{p_{4}}

R = p_{0} S

N_{al}

Number of parent stock

W_{al}

Weight of parent stock

p

Proportion of parent stock spawning, from proportion_f

p_{0..4}

Arguments provided to function

g3a_spawn_recruitment_simplessb

A pair of formula objects:

S = N_{al} p W_{al}

R = \mu S

N_{al}

Number of parent stock

W_{al}

Weight of parent stock

p

Proportion of parent stock spawning, from proportion_f

\mu

Argument provided to function

g3a_spawn_recruitment_ricker

A pair of formula objects:

S = N_{al} p W_{al}

R = \mu S e^{-\lambda S}

N_{al}

Number of parent stock

W_{al}

Weight of parent stock

p

Proportion of parent stock spawning, from proportion_f

\mu

Argument provided to function

\lambda

Argument provided to function

g3a_spawn_recruitment_bevertonholt

A pair of formula objects:

S = N_{al} p W_{al}

R = \frac{\mu S}{\lambda + S}

N_{al}

Number of parent stock

W_{al}

Weight of parent stock

p

Proportion of parent stock spawning, from proportion_f

\mu

Argument provided to function

\lambda

Argument provided to function

g3a_spawn_recruitment_bevertonholt_ss3

A modified beverton-holt implementation from SS3 returning a pair of formula objects:

S = N_{al} p W_{al}

R = \frac{ 4 h R_0 s R }{ B_0 (1 - h) + S (5 h - 1) }

N_{al}

Number of parent stock

W_{al}

Weight of parent stock

p

Proportion of parent stock spawning, from proportion_f

h

Steepness parameter, by default provided by the srr_h parameter

R_0

Unfished equilibrium recruitment, by default provided by the R0 parameter

R

Recruitment deviates, by default provided by the R parameter table

B_0

Unfished equilibrium spawning biomass (corresponding to R0), by default provided by the B0 parameter

\lambda

Argument provided to function

g3a_spawn_recruitment_hockeystick

A pair of formula objects:

S = N_{al} p W_{al}

R = R_0 \min{( S / B_{lim}, 1)}

N_{al}

Number of parent stock

W_{al}

Weight of parent stock

p

Proportion of parent stock spawning, from proportion_f

R_0

Argument r0 provided to function

B_{lim}

Argument blim provided to function

NB: This formula is differentiable, despite using min() in the definition above.

g3a_spawn

An action (i.e. list of formula objects) that will, for the given stock...

1. Use proportion_f to calculate the total parent stock that will spawn

2. Use recruitment_f to derive the total newly spawned stock

3. Apply weightloss and mortality_f to the parent stock

... then, at recruitment stage ...

1. Recruit evenly into output_stocks, using mean_f, stddev_f, alpha_f, beta_f as-per g3a_renewal_normalparam

See Also

https://gadget-framework.github.io/gadget2/userguide/chap-stock.html#sec-stockspawn, https://nmfs-ost.github.io/ss3-doc/SS330_User_Manual_release.html#beverton-holt, g3a_naturalmortality, g3_stock

Examples

ling_imm <- g3_stock(c('ling', maturity = 'imm'), seq(20, 156, 4)) |> g3s_age(0, 10)
ling_mat <- g3_stock(c('ling', maturity = 'mat'), seq(20, 156, 4)) |> g3s_age(3, 10)

actions <- list(
    g3a_time(1990, 1994, c(6, 6)),
    g3a_initialconditions_normalcv(ling_imm),
    g3a_initialconditions_normalcv(ling_mat),
    g3a_age(ling_imm),
    g3a_age(ling_mat),

    g3a_spawn(
        # Spawn from ling_mat
        ling_mat,
        # Use Ricker Recruitment Function to calculate # of recruits from total biomass
        recruitment_f = g3a_spawn_recruitment_ricker(),
        # Proportion of ling_mat spawning exponential relationship based on length
        proportion_f = g3_suitability_exponentiall50(
            alpha = g3_parameterized("spawn.prop.alpha", value = 4, scale = -1),
            l50 = g3_parameterized("spawn.prop.l50", value = 60)),
        # Proportion of ling_mat dying during spawning linear relationship to length
        mortality_f = g3_suitability_straightline(
            alpha = g3_parameterized("spawn.mort.alpha"),
            beta = g3_parameterized("spawn.mort.beta")),
        # Weight of spawning ling_imm should reduce by a fixed absolute amount (see g3a_weightloss)
        weightloss_args = list( abs_loss = g3_parameterized("spawn.weightloss", value = 0.1) ),
        # Spawn into ling_imm
        output_stocks = list(ling_imm),
        # Spawning should happen on the first step of every year
        run_f = ~cur_step==1 ),
    NULL )
model_fn <- g3_to_r(c(actions,
    g3a_report_detail(actions),
    g3a_report_history(actions, "__spawningnum$|__offspringnum$") ))

attr(model_fn, "parameter_template") |>
    # g3a_initialconditions_normalcv()
    g3_init_val("*.Linf", 50) |>
    g3_init_val("*.t0", -1.4) |>
    g3_init_val("*.walpha", 0.1) |>
    g3_init_val("*.wbeta", 1) |>
    # g3a_spawn_recruitment_ricker()
    g3_init_val("*.spawn.mu", 1e6) |>
    g3_init_val("*.spawn.lambda", 30) |>
    identity() -> params

r <- attributes(model_fn(params))
colSums(r$dstart_ling_imm__num)
colSums(r$dstart_ling_mat__wgt)

lentinj/gadget3 documentation built on June 12, 2025, 5:46 a.m.