Package 'gadget3'

Gadget3 language utilities

Description

Produce objects with special meaning to gadget3

Usage

g3_native(r, cpp, depends = c())
g3_global_formula(f = quote(noop), init_val = NULL)

Arguments

r	An R function to decorate with a 'C++' equivalent
cpp	Either: A character string containing the 'C++' equivalent as a Lambda function A character string containing 'C++' function template definition, calling the function __fn__ A list of type-casts to use when calling an equivalently named native function
depends	A list of string names of dependent functions. The content of this and the initial [] for any Lambda function should match.
f	An optional formula to modify the content of a globablly-defined variable
init_val	An optiona formula to set the initial value of a globally-defined variable

Details

These functions are generally for gadget3 development, but made available so actions can be produced outside the package.

Value

g3_native

Returns a function that can be used in formulas for both R and TMB-based models.

g3_global_formula

Returns a formula that will be defined globally, and this can preserve state across timesteps.

Examples

# The definition of g3_env$ratio_add_vec looks like:
eg_ratio_add_vec <- g3_native(r = function(orig_vec, orig_amount,
                                        new_vec, new_amount) {
    ((orig_vec * orig_amount + new_vec * new_amount)
      /
    avoid_zero_vec(orig_amount + new_amount))
}, cpp = '[](vector<Type> orig_vec, vector<Type> orig_amount,
                            vector<Type> new_vec, vector<Type> new_amount)
                            -> vector<Type> {
    return (orig_vec * orig_amount + new_vec * new_amount)
             /
           avoid_zero_vec(orig_amount + new_amount);
}', depends = c('avoid_zero_vec'))
# eg_ratio_add_vec() can then be used in formulas, both in R & TMB.

# Define a random walk action, using g3_global_formula to keep track of
# previous value. NB: my_randomwalk_prevrec must be unique in a model
random_walk_action <- g3_formula(quote({
    if (cur_time > 0) nll <- nll + dnorm(x, stock__prevrec, 1, 1)
    my_randomwalk_prevrec <- x
}), x = 'TODO', my_randomwalk_prevrec = g3_global_formula(init_val = 0.0))

---

Gadget3 global environment

Description

Functions available to any gadget3 model

Details

g3_env is the top-level environment that any gadget3 model uses, populated with utility functions.

NB: Several functions have _vec variants. Due to TMB limitations these should be used when you have a vector not scalar input.

ADREPORT

TMB's ADREPORT function. See sdreport documentation

as_integer

C++ compatible equivalent to as.integer

as.numeric

R as.numeric or TMB asDouble

assert_msg

C++/R function that ensures expression is true, or stops model.

assert_msg(x > 0, "x must be positive")

avoid_zero

Adds small value to input to ensure output is never zero avoid_zero_vec is identical to avoid_zero, and is only present for backward compatibility.

bounded / bounded_vec

Ensures x is within limits b & a.

If x positive, return a. If x negative, b. If x -10..10, smoothly transition from b to a

bounded_vec(x, 200, 100)

g3_matrix_vec

Apply matrix transformation tf to vector vec, return resultant vector.

g3_matrix_vec(tf, vec)

lgamma_vec

Vector equivalent of lgamma

logspace_add

TMB's logspace_add, essentially a differentiable version of pmax.

normalize_vec

Divide vector a by it's sum, i.e. so it now sums to 1. If vector is all-zero, return an all-zero vector instead.

nvl

Return first non-null argument. NB: No C++ implementation.

print_array

Utility to pretty-print array ar

ratio_add_vec

Sum orig_vec & new_vec according to ratio of orig_amount & new_amount

nonconform_add / nonconform_mult / nonconform_div / nonconform_div_avz

Scalar sum/multiply/divide 2 non-conforming arrays, by treating the latter as a vector and repeating as many times as required. Results will be structured identically to the first array.

nonconform_div_avz(x, y) is equivalent to nonconform_div(x, avoid_zero_vec(y))

REPORT

TMB's REPORT function.

REprintf

Equivalent of RCpp REprintf

Rprintf

Equivalent of RCpp Rprintf

Examples

## avoid_zero
g3_eval(quote( c( avoid_zero(0), avoid_zero(10) ) ))
g3_eval(quote( avoid_zero(0:5) ))

## bounded / bounded_vec
curve(g3_eval(quote( bounded(x, 200, 100) ), x = x), -100, 100)

## logspace_add
curve(g3_eval(quote( logspace_add(x, 10) ), x = x), 0, 40)

## normalize_vec
g3_eval(quote( normalize_vec(c( 4, 4, 8, 2 )) ))

## nonconform_mult
g3_eval(quote( nonconform_mult(
    array(seq(0, 4*5*6), dim = c(4,5,6)),
    c(1e1, 1e2, 1e3, 1e4)) ))

## nonconform_div_avz
g3_eval(quote( nonconform_div_avz(
    array(seq(0, 4*5*6), dim = c(4,5,6)),
    c(1e1, 1e2, 0, 1e4)) ))
g3_eval(quote( nonconform_div(
    array(seq(0, 4*5*6), dim = c(4,5,6)),
    avoid_zero(c(1e1, 1e2, 0, 1e4))) ))

---

Gadget3 age action

Description

Add ageing actions to a g3 model

Usage

g3a_age(
        stock,
        output_stocks = list(),
        output_ratios = rep(1/length(output_stocks),
        times = length(output_stocks)),
        run_f = ~cur_step_final,
        run_at = g3_action_order$age,
        transition_at = g3_action_order$age)

Arguments

stock	g3_stock to age.
output_stocks	List of g3_stocks that oldest specimens in stock should move into.
output_ratios	Vector of proportions for how to distribute into output_stocks, default evenly spread.
run_f	formula specifying a condition for running this action, default is end of model year.
run_at	Integer order that actions will be run within model, see g3_action_order.
transition_at	Integer order that transition actions will be run within model, see g3_action_order.

Value

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

1. Move the final age group into temporary storage, stock__transitioning_num / stock__transitioning_wgt

2. Move the contents of all other age groups into the age group above

3. Move the contents of the temporary storage into output_stocks

If stock has only one age, and output_stocks has been specified, then the contentes will be moved, if output_stocks is empty, then the action will do nothing.

See Also

https://gadget-framework.github.io/gadget2/userguide/chap-stock.html#sec:stockmature, g3_stock

Examples

ling_imm <- g3_stock('ling_imm', seq(20, 156, 4)) %>% g3s_age(3, 10)
ling_mat <- g3_stock('ling_mat', seq(20, 156, 4)) %>% g3s_age(5, 15)

# Ageing for immature ling
age_action <- g3a_age(ling_imm,
    output_stocks = list(ling_mat))

---

Gadget3 growth action

Description

Add growth/maturity actions to a g3 model

Usage

g3a_grow_lengthvbsimple(
        linf_f = g3_parameterized('Linf', by_stock = by_stock),
        kappa_f = g3_parameterized('K', by_stock = by_stock),
        by_stock = TRUE)

g3a_grow_weightsimple(
        alpha_f = g3_parameterized('walpha', by_stock = by_stock),
        beta_f = g3_parameterized('wbeta', by_stock = by_stock),
        by_stock = TRUE)

g3a_grow_impl_bbinom(
        delta_len_f = g3a_grow_lengthvbsimple(by_stock = by_stock),
        delta_wgt_f = g3a_grow_weightsimple(by_stock = by_stock),
        beta_f = g3_parameterized('bbin', by_stock = by_stock),
        maxlengthgroupgrowth,
        by_stock = TRUE)

g3a_grow_length_multspec(
        p0 = g3_parameterized('multispec.p0', value = 1, by_stock = by_stock),
        p1 = g3_parameterized('multispec.p1', value = 1, by_stock = by_stock),
        p2 = g3_parameterized('multispec.p2', value = 1, by_stock = by_stock),
        p3 = g3_parameterized('multispec.p3', value = 0, by_stock = by_stock),
        temperature = 0,
        by_stock = TRUE)

g3a_grow_weight_multspec(
        p4 = g3_parameterized('multispec.p4', value = 1, by_stock = by_stock),
        p5 = g3_parameterized('multispec.p5', value = 1, by_stock = by_stock),
        p6 = g3_parameterized('multispec.p6', value = 0, by_stock = by_stock),
        p7 = g3_parameterized('multispec.p7', value = 1, by_stock = by_stock),
        p8 = g3_parameterized('multispec.p8', value = 0, by_stock = by_stock),
        temperature = 0,
        by_stock = TRUE)

g3a_grow_length_weightjones(
        p0 = g3_parameterized('weightjones.p0', value = 0, by_stock = by_stock),
        p1 = g3_parameterized('weightjones.p1', value = 0, by_stock = by_stock),
        p2 = g3_parameterized('weightjones.p2', value = 1, by_stock = by_stock),
        p3 = g3_parameterized('weightjones.p3', value = 0, by_stock = by_stock),
        p4 = g3_parameterized('weightjones.p4', value = 1, by_stock = by_stock),
        p5 = g3_parameterized('weightjones.p5', value = 100, by_stock = by_stock),
        p6 = g3_parameterized('weightjones.p6', value = 1, by_stock = by_stock),
        p7 = g3_parameterized('weightjones.p7', value = 1, by_stock = by_stock),
        reference_weight = 0,
        temperature = 0,
        by_stock = TRUE)

g3a_grow_weight_weightjones(
        q0 = g3_parameterized('weightjones.q0', value = 1, by_stock = by_stock),
        q1 = g3_parameterized('weightjones.q1', value = 1, by_stock = by_stock),
        q2 = g3_parameterized('weightjones.q2', value = 1, by_stock = by_stock),
        q3 = g3_parameterized('weightjones.q3', value = 1, by_stock = by_stock),
        q4 = g3_parameterized('weightjones.q4', value = 1, by_stock = by_stock),
        q5 = g3_parameterized('weightjones.q5', value = 0, by_stock = by_stock),
        max_consumption = g3a_predate_maxconsumption(temperature = temperature),
        temperature = 0,
        by_stock = TRUE)

g3a_growmature(stock, impl_f, maturity_f = ~0, output_stocks = list(), 
    output_ratios = rep(1/length(output_stocks), times = length(output_stocks)), 
    transition_f = ~cur_step_final, run_f = ~TRUE,
    run_at = g3_action_order$grow,
    transition_at = g3_action_order$mature)

Arguments

linf_f	A formula to substitute for $L_\infty$.
kappa_f	A formula to substitute for $\kappa$.
alpha_f	A formula to substitute for $\alpha$.
beta_f	A formula to substitute for $\beta$.
p0, p1, p2, p3, p4, p5, p6, p7, p8, q0, q1, q2, q3, q4, q5	A formula to substitute for the equivalent value.
max_consumption	Maximum predator consumption, see g3a_predate_maxconsumption.
temperature	A formula providing values for the current temperature, likely implemented with g3_timeareadata.
maxlengthgroupgrowth	An integer with the maximum length groups an individual can jump in one step.
reference_weight	Reference weight. see formula for g3a_grow_length_weightjones.
stock	g3_stock to grow.
delta_len_f	A formula defining a non-negative vector for mean increase in length for stock for each lengthgroup, as defined by g3a_grow_lengthvbsimple.
delta_wgt_f	A formula defining the corresponding weight increase as a matrix of lengthgroup to lengthgroup delta for stock, as defined by g3a_grow_weightsimple.
by_stock	Change the default parameterisation (e.g. to be by 'species'), see g3_parameterized.
impl_f	A pair of formula objects, as defined by g3a_grow_impl_bbinom. Both define a matrix of length groups i to length group deltas j (0..maxlengthgroupgrowth), the values in the first indicate the proportion of individuals moving from i to i + j, the values in the second indicate the corresponding weight increase of individuals moving from i to i + j.
maturity_f	A maturity formula, as defined by g3a_mature_constant.
output_stocks	List of g3_stocks that maturing stock should move into.
output_ratios	Vector of proportions for how to distribute into output_stocks, summing to 1, default evenly spread.
transition_f	formula specifying a contition for running maturation steps as well as growth, default final step of year.
run_f	formula specifying a condition for running this action, default always runs.
run_at	Integer order that actions will be run within model, see g3_action_order.
transition_at	Integer order that transition actions will be run within model, see g3_action_order.

Details

A model can have any number of g3a_growmature actions, so long as the calling arguments are different. For instance, run_f = ~age == 5 and run_f = ~age == 7.

impl_f's dependent variables are analysed to see what will affect growth. If nothing but cur_step_size will affect growth, then growth will only be recalculated when the step size changes.

Value

g3a_grow_lengthvbsimple

Returns a formula for use as delta_len_f:

${{\Delta}L}_i = ( L_\infty - L_i )(1 - e^{-\kappa {\Delta t}})$

$\Delta t$

Length of current step as a proportion of the year, e.g. 0.25. See cur_step_size in g3a_time

g3a_grow_weightsimple

Returns a formula for use as delta_wgt_f:

${{\Delta}W}_{i,j} = \alpha ( (L_i + {{\Delta}L}_j)^\beta - {L_i}^\beta )$

${\Delta}L$

Vector of all possible length group increases i.e 0..maxlengthgroupgrowth

g3a_grow_length_multspec

Returns a formula for use as delta_len_f:

${{\Delta}L}_i = {\Delta t} p_0 L_i^{p_1} \psi_i (p_2 T + p_3)$

$p_x$

Supplied parameters

$\Delta t$

Length of current step as a proportion of the year, e.g. 0.25. See cur_step_size in g3a_time

$L_i$

Current length

$\psi_i$

Feeding level of stock. See g3a_predate_catchability_predator

$T$

Temperature of current region

g3a_grow_weight_multspec

Returns a formula for use as delta_wgt_f:

${{\Delta}W}_{i,j} = {\Delta t} p_4 {W_i}^{p_5} (\psi_i - p_6) (p_7 T + p_8)$

$p_x$

Supplied parameters

$\Delta t$

Length of current step as a proportion of the year, e.g. 0.25. See cur_step_size in g3a_time

$W_i$

Current mean weight

$\psi_i$

Feeding level of stock. See g3a_predate_catchability_predator

$T$

Temperature of current region

Note that the equation is not dependent on the change in length, the value will be the same for each $j$.

g3a_grow_length_weightjones

Returns a formula for use as delta_len_f:

$r = \frac{ W_i - (p_0 + \psi_i (p_1 + p_2 \psi_i)) W_{ref} }{ W_i }$

${{\Delta}L}_i = {minmax}(p_3 + p_4 r, 0, p_5) \frac{ {{\Delta}W}_{i,j} }{ p_6 p_7 {L_i}^{(p_7 - 1)} }$

$W_i$

Current mean weight

$p_x$

Supplied parameters

$\psi_i$

Feeding level of stock. See g3a_predate_catchability_predator

$W_{ref}$

Reference weight, from the reference_weight parameter

${{\Delta}W}_{i,j}$

Change in weight, i.e. the output from the delta_wgt_f formula, probably g3a_grow_weight_weightjones.

g3a_grow_weight_weightjones

Returns a formula for use as delta_wgt_f:

${{\Delta}W}_{i,j} = {\Delta t} ( \frac{ M \psi_i }{ q_0 {W_i}^{q_1} } - q_2 {W_i}^{q_3} e^{(q_4 T + q_5)} )$

$q_x$

Supplied parameters

$\Delta t$

Length of current step as a proportion of the year, e.g. 0.25. See cur_step_size in g3a_time

$M$

Maximum theoretical consumption, as defined by g3a_predate_maxconsumption

$\psi_i$

Feeding level of stock. See g3a_predate_catchability_predator

$W_i$

Current mean weight

$T$

Temperature of current region

Note that the equation is not dependent on the change in length, the value will be the same for each $j$.

g3a_grow_impl_bbinom

formula object converting mean growths using beta-binomia distribution. See https://gadget-framework.github.io/gadget2/userguide/chap-stock.html#beta-binomial

g3a_growmature

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

1. Move any maturing individuals into temporary storage, stock__transitioning_num / stock__transitioning_wgt

2. Calculate increase in length/weight using growth_f and impl_f

3. Move the contents of the temporary storage into output_stocks

See Also

https://gadget-framework.github.io/gadget2/userguide/chap-stock.html#sec:stockgrowth, g3_stock

Examples

ling_imm <- g3_stock(c(species = 'ling', 'imm'), seq(20, 156, 4))
ling_mat <- g3_stock(c(species = 'ling', 'mat'), seq(20, 156, 4))

# Growth / maturity for immature ling
growth_action <- g3a_growmature(ling_imm,
    impl_f = g3a_grow_impl_bbinom(
        # Parameters will be ling.Linf, ling.K
        g3a_grow_lengthvbsimple(by_stock = 'species'),
        # Parameters will be ling_imm.walpha, ling_imm.wbeta
        g3a_grow_weightsimple(),
        maxlengthgroupgrowth = 15),
    maturity_f = g3a_mature_constant(
        alpha = g3_parameterized('ling.mat1', scale = 0.001),
        l50 = g3_parameterized('ling.mat2')),
        output_stocks = list(ling_mat))

# Multspec growth - define a data frame with temperature
temperature <- g3_timeareadata(
    'temp',
    data.frame(year = 2000, step=c(1,2), temp=c(10, 14)),
    value_field = "temp" )

ms_growth_actions <- list(
  g3a_growmature(ling_imm, g3a_grow_impl_bbinom(
    g3a_grow_length_multspec(temperature = temperature),
    g3a_grow_weight_multspec(temperature = temperature),
    maxlengthgroupgrowth = 8 )),
  NULL)

---

Gadget3 maturity action

Description

Add maturity actions to a g3 model

Usage

g3a_mature_continuous(
        alpha = g3_parameterized('mat.alpha', by_stock = by_stock),
        l50 = g3_parameterized('mat.l50', by_stock = by_stock),
        beta = 0,
        a50 = 0,
        bounded = TRUE,
        by_stock = TRUE)

g3a_mature_constant(alpha = NULL, l50 = NA, beta = NULL, a50 = NA, gamma = NULL, 
    k50 = NA)

g3a_mature(stock, maturity_f, output_stocks, output_ratios = rep(1/length(output_stocks), 
    times = length(output_stocks)), run_f = ~TRUE,
    run_at = g3_action_order$grow,
    transition_at = g3_action_order$mature)

Arguments

alpha	A formula to substitute for $\alpha$.
l50	A formula to substitute for $l_{50}$. Must be defined if alpha is defined.
beta	A formula to substitute for $\beta$.
a50	A formula to substitute for $a_{50}$. Must be defined if beta is defined.
gamma	A formula to substitute for $\gamma$.
k50	A formula to substitute for $k_{50}$. Must be defined if gamma is defined.
bounded	Should the maturity ratio be bounded to 0..1? Set TRUE if maturity is producing negative numbers of individuals.
by_stock	Change the default parameterisation (e.g. to be by 'species'), see g3_parameterized.
stock	g3_stock to mature.
maturity_f	A maturity formula, as defined by g3a_mature_constant.
output_stocks	List of g3_stocks that maturing stock should move into.
output_ratios	Vector of proportions for how to distribute into output_stocks, summing to 1, default evenly spread.
run_f	formula specifying a condition for running this action, default always runs.
run_at	Integer order that actions will be run within model, see g3_action_order.
transition_at	Integer order that transition actions will be run within model, see g3_action_order.

Details

Generally you would use g3a_growmature, which does both growth and maturity at the same time.

A model can have any number of g3a_mature actions, so long as the calling arguments are different. For instance, run_f = ~age == 5 and run_f = ~age == 7.

Value

g3a_mature_continuous

A formula object representing

$m_0 * (\alpha \Delta{L} + \beta {\Delta t})^\top$

$m_0$

The g3a_mature_constant formula, as defined below, using parameters supplied to g3a_mature_continuous

$\Delta{L}$

Vector of all possible changes in length, as per current growth matrix (see g3a_grow_impl_bbinom)

$\Delta t$

Length of current step as a proportion of the year, e.g. 0.25. See cur_step_size in g3a_time

g3a_mature_constant

A formula object with the following equation

$\frac{1}{ 1 + e^{-\alpha(l - l_{50}) -\beta(a - a_{50}) -\gamma(k - k_{50})}}$

$l$

length of stock

$l_{50}$

length of stock when 50% are mature

$a$

age of stock

$a_{50}$

age of stock when 50% are mature

$k$

weight of stock

$k_{50}$

weight of stock when 50% are mature

g3a_mature

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

1. Move any maturing individuals into temporary storage, stock__transitioning_num / stock__transitioning_wgt

2. Move the contents of the temporary storage into output_stocks

See Also

https://gadget-framework.github.io/gadget2/userguide/chap-stock.html#sec:stockmature, g3a_growmature, g3_stock

Examples

ling_imm <- g3_stock('ling_imm', seq(20, 156, 4))
ling_mat <- g3_stock('ling_mat', seq(20, 156, 4))

# Maturity for immature ling
maturity_action <- g3a_mature(ling_imm,
    maturity_f = g3a_mature_continuous(),
    output_stocks = list(ling_mat))

---

Gadget3 migration action

Description

Add migration to a g3 model

Usage

g3a_migrate_normalize(row_total = 1)

g3a_migrate(stock, migrate_f, normalize_f = g3a_migrate_normalize(),
            run_f = TRUE,
            run_at = g3_action_order$migrate)

Arguments

row_total	When calculating the proportion of individuals that will stay in place, use this total for what rows are expected to sum to.
stock	The g3_stock that will migrate in this action.
migrate_f	A formula describing the migration in terms of (source) area and dest_area.
normalize_f	Function to normalize a vector of possible destinations, to make sure fish aren't added or destroyed.
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.

Details

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

cur_step == 1

Migration will happen on first step of every year

cur_step == 1 && cur_year >= 1990

Migration will happen on first step of every year after 1990

cur_step == 2 && area = 1

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

Multiple migration actions can be added, for a separate spring and autumn migration, for instance.

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

stock__migratematrix

$a \times a$ array, containing proportion of (stock) moved from one area to another. If NaN, no movement has occurred

Value

g3a_migrate_normalize

A formula transforming stock__migratematrix[,stock__area_idx] (i.e. all possible destinations from a given area) by:

1. Squaring so values are all positive

2. Altering the proportion of static individuals so a row sums to row_total

3. Dividing by row_total so a row sums to 1

g3a_migrate

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

1. Fill in stock__migratematrix using migrate_f and normalize_f

2. Apply movement to stock

See Also

g3_stock

Examples

areas <- list(a=1, b=2, c=3, d=4)

# NB: stock doesn't live in b, so won't figure in stock_acd__migratematrix
stock_acd <- (g3_stock('stock_acd', seq(10, 40, 10))
    %>% g3s_livesonareas(areas[c('a', 'c', 'd')]))

movement_action <- list(
    g3a_migrate(
        stock_acd,
        # In spring, individuals in area 'a' will migrate to 'd'.
        ~if (area == area_a && dest_area == area_d) 0.8 else 0,
        run_f = ~cur_step == 2),
    g3a_migrate(
        stock_acd,
        # In autumn, individuals in all areas will migrate to 'a'
        ~if (dest_area == area_a) 0.8 else 0,
        run_f = ~cur_step == 4),
    list())

---

Gadget3 natural mortality action

Description

Add natural mortality to a g3 model

Usage

g3a_naturalmortality_exp(
        param_f = g3_parameterized('M', by_stock = by_stock, by_age = TRUE),
        by_stock = TRUE,
        action_step_size_f = ~cur_step_size)

g3a_naturalmortality(
        stock,
        mortality_f = g3a_naturalmortality_exp(),
        run_f = TRUE,
        run_at = g3_action_order$naturalmortality)

Arguments

param_f	A formula to substitute for $m$.
action_step_size_f	How much model time passes in between runs of action? defaults to ~cur_step_size, i.e. every step. Use action_step_size_f = 1 if action only runs yearly.
by_stock	Change the default parameterisation (e.g. to be by 'species'), see g3_parameterized.
stock	g3_stock mortality applies to.
mortality_f	A mortality formula, as defined by g3a_naturalmortality_exp.
run_f	formula specifying a condition for running this action, default always runs.
run_at	Integer order that actions will be run within model, see g3_action_order.

Details

A model can have any number of g3a_naturalmortality actions, so long as the calling arguments are different. For instance, run_f = ~age == 5 and run_f = ~age == 7.

Value

g3a_naturalmortality_exp

A formula object with the following equation

$e^{-m \Delta t}$

$\Delta t$

Length of current step as a proportion of the year, e.g. 0.25. See cur_step_size in g3a_time

g3a_naturalmortality

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

1. Remove a proportion of each stock group as calculated by the mortality formula mortality_f

See Also

https://gadget-framework.github.io/gadget2/userguide/chap-stock.html#sec:stocknatmort, g3a_growmature, g3_stock

Examples

ling_imm <- g3_stock('ling_imm', seq(20, 156, 4)) %>% g3s_age(3, 10)

# Natural mortality for immature ling
naturalmortality_action <- g3a_naturalmortality(ling_imm)

# NB: M is used in both g3a_naturalmortality and g3a_renewal_initabund, to
# customise, you need to make sure the definitions are in sync, for example:

M <- g3_parameterized('M', by_stock = TRUE, by_age = FALSE)
actions <- list(
    g3a_naturalmortality(ling_imm,
        g3a_naturalmortality_exp(M)),
    g3a_initialconditions_normalparam(ling_imm,
        factor_f = g3a_renewal_initabund(M = M)),
    NULL)

---

Standard gadget3 order of actions

Description

Constant defining standard order of actions

Usage

g3_action_order

Details

All gadget3 actions have a run_at parameter. This decides the point in the model that the action will happen relative to others.

The defaults for these are set via g3_action_order.

Value

A named integer list

See Also

https://gadget-framework.github.io/gadget2/userguide/chap-order.html

Examples

# The default action order
unlist(g3_action_order)

# View single value
g3_action_order$age

---

Gadget3 predation actions

Description

Add predation to a g3 model

Usage

g3a_predate_catchability_totalfleet(E)

g3a_predate_catchability_numberfleet(E)

g3a_predate_catchability_linearfleet(E)

g3a_predate_catchability_effortfleet(catchability_fs, E)

g3a_predate_catchability_quotafleet(quota_table, E,
                                    sum_stocks = list(),
                                    recalc_f = NULL)

g3a_predate_maxconsumption(
        m0 = g3_parameterized('consumption.m0', value = 1,
            by_predator = TRUE, optimise = FALSE),
        m1 = g3_parameterized('consumption.m1', value = 0,
            by_predator = TRUE, optimise = FALSE),
        m2 = g3_parameterized('consumption.m2', value = 0,
            by_predator = TRUE, optimise = FALSE),
        m3 = g3_parameterized('consumption.m3', value = 0,
            by_predator = TRUE, optimise = FALSE),
        temperature = 0 )

g3a_predate_catchability_predator(
        prey_preferences = 1,
        energycontent = g3_parameterized('energycontent', value = 1,
            by_stock = by_stock, optimise = FALSE),
        half_feeding_f = g3_parameterized('halffeeding',
            by_predator = by_predator, optimise = FALSE),
        max_consumption = g3a_predate_maxconsumption(temperature = temperature),
        temperature = 0,
        by_predator = TRUE,
        by_stock = TRUE )

g3a_predate(
        predstock,
        prey_stocks,
        suitabilities,
        catchability_f,
        overconsumption_f = quote( dif_pmin(stock__consratio, 0.95, 1e3) ),
        run_f = ~TRUE,
        run_at = g3_action_order$predate )

# NB: Deprecated interface, use g3a_predate()
g3a_predate_fleet(fleet_stock, prey_stocks, suitabilities, catchability_f,
    overconsumption_f = quote( dif_pmin(stock__consratio, 0.95, 1e3) ),
    run_f = ~TRUE, run_at = g3_action_order$predate)

# NB: Deprecated interface, use g3a_predate() with g3a_predate_catchability_totalfleet
g3a_predate_totalfleet(fleet_stock, prey_stocks, suitabilities, amount_f,
    overconsumption_f = quote( dif_pmin(stock__consratio, 0.95, 1e3) ),
    run_f = ~TRUE, run_at = g3_action_order$predate)

Arguments

predstock, fleet_stock	g3_stock that describes the harvesting predators/fleet, or a list of g3_stock objects, in which case g3a_predate will be run for each in turn.
prey_stocks	List of g3_stocks that maturing stock should move into.
suitabilities	Either a list of stock names to formula objects, with an optional unnamed default option, or a formula object (which is always used). Each formula should define suitability of a stock, for example by using g3_suitability_exponentiall50.
catchability_f	A list of formulas generated by one of the g3a_predate_catchability_* functions, which define the total biomass a fleet is able to catch.
E	A formula defining total catch a fleet can harvest at the current time/area (totalfleet/numberfleet), or a scaling factor used to define the stock caught (linearfleet/effortfleet/quotafleet).
catchability_fs	Either a list of stock names to formula objects, with an optional unnamed default option, or a formula object (which is always used).
quota_table	A data.frame with 'biomass' and 'quota' columns, 'biomass' a numeric column, an upper bound for total biomass amount, the final value always being Inf. 'quota' being a list of formulas, defining the quota for each, e.g. with g3_parameterized.
sum_stocks	Either a list of g3_stock objects to sum when choosing a value from quote_table, or NULL, in which case choose the quota based on the current prey.
recalc_f	A formula denoting when to recalculate the current quota. For example ~cur_step == 1 will ensure the quota is only recalculated at the beginning of the year.
amount_f	Equivalent to E passed to g3a_predate_catchability_totalfleet.
prey_preferences	Either 1, indicating a Type II functional response, or >1 for a Type III functional response. Either a list of stock names to numbers, with an optional unnamed default option, or a single number to be used for all stocks.
energycontent	A formula object for the energy content of the current prey, in in kilojoules per kilogram.
half_feeding_f	The biomass of prey required to allow the predator to consume prey at half the maximum consumption level.
max_consumption	A formula for maximum consumption of the predator, in kilojoules per month. Generally generated by g3a_predate_maxconsumption
m0, m1, m2, m3	Parameters for maximum possible consumption formula, see below.
temperature	A formula object for the current temperature, probably generated by g3_timeareadata.
overconsumption_f	Overconsumption rule, a formula that should cap all values in stock__consratio to <= 95
by_stock	Change the default parameterisation (e.g. to be by 'species'), see g3_parameterized.
by_predator	Change the default parameterisation (e.g. to be by 'species'), see g3_parameterized.
run_f	formula specifying a condition for running this action, default always runs.
run_at	Integer order that actions will be run within model, see g3_action_order.

Details

g3a_predate will, given a g3_fleet "predator" and a set of g3_stock preys, add predation into a model. The behaviour is driven by 2 parameters:

suitabilities

Defines a predator's preference within a prey stock, normally one of the suitability functions, e.g. g3_suitability_exponentiall50

catchability_f

Defines a predator's overall requirements, set with one of the catchability functions, e.g. g3a_predate_catchability_totalfleet

For the definition of each catchability function, see the values section below.

Details for custom actions

The actions will define the following stock instance variables for each given fleet_stock and prey_stock:

(predstock)__totalsuit

Total suitable prey for (predstock), i.e. $\sum_{\it preys}^p \sum_{\it lengths}^l F_{pl}$

prey_stock__suit_fleet_stock

Suitability of (prey_stock) for (fleet_stock), i.e. $F_{pl}$

(predstock)_(prey_stock)__cons

Biomass of (prey_stock) caught by (predstock), by predator & prey dimensions

prey_stock__totalpredate

Biomass of total consumed (prey_stock), in a prey array

prey_stock__consratio

Ratio of prey_stock__totalpredate / (current biomass), capped by overconsumption_f

In addition, g3a_predate_fleet will generate prey_stock__predby_predstock, Biomass of (prey_stock) caught by (fleet_stock), in a prey array, for compatibility with older models. It is otherwise identical to g3a_predate.

A model can have any number of g3a_predate_* actions, so long as the calling arguments are different. For instance, run_f = ~age == 5 and run_f = ~age == 7.

Value

g3a_predate_catchability_totalfleet

formula objects that define a fleet's desired catch by total biomass (e.g. landings data):

$F_{pl} = S N_{pl} W_{pl}$

$C_{pl} = \frac{E F_{pl}}{\displaystyle \sum_{\it preys}^p \sum_{\it lengths}^l F_{pl}}$

$S$

Suitability form suitabilities argument

$E$

E argument, biomass caught by fleet. Generally a g3_timeareadata table containing landings data, with year/step/area/weight columns

$N_{pl}$

Number of prey in length cell for prey $p$, length $l$

$W_{pl}$

Mean weight of prey in length cell for prey $p$, length $l$

g3a_predate_catchability_numberfleet

formula objects that define a fleet's desired catch by total number of stock landed (individuals, not biomass):

$F_{pl} = S N_{pl}$

$C_{pl} = \frac{E F_{pl} W_{pl}}{\displaystyle \sum_{\it preys}^p \sum_{\it lengths}^l F_{pl}}$

$S$

Suitability form suitabilities argument

$E$

E argument, numbers caught by fleet. Generally a g3_timeareadata table containing landings data, or a constant quota

$N_{pl}$

Number of prey in length cell for prey $p$, length $l$

$W_{pl}$

Mean weight of prey in length cell for prey $p$, length $l$

g3a_predate_catchability_linearfleet

formula objects that define a linear relationship between desired catch and available biomass:

$F_{pl} = S N_{pl} W_{pl}$

$C_{pl} = E \Delta t F_{pl}$

$S$

Suitability form suitabilities argument

$E$

E argument, scaling factor for the stock that is to be caught, per month

$\Delta t$

Length of current step as a proportion of the year, e.g. 0.25. See cur_step_size in g3a_time

$N_{pl}$

Number of prey in length cell for prey $p$, length $l$

$W_{pl}$

Mean weight of prey in length cell for prey $p$, length $l$

g3a_predate_catchability_effortfleet

This is a multi-species extension to linearfleet, allowing differently-parameterized catchability per-stock:

$F_{pl} = S N_{pl} W_{pl}$

$C_{pl} = c_{s} E \Delta t F_{pl}$

$S$

Suitability form suitabilities argument

$c_{s}$

catchability_fs argument for the current stock

$E$

E argument, scaling factor for the stock that is to be caught, per month

$\Delta t$

Length of current step as a proportion of the year, e.g. 0.25. See cur_step_size in g3a_time

$N_{pl}$

Number of prey in length cell for prey $p$, length $l$

$W_{pl}$

Mean weight of prey in length cell for prey $p$, length $l$

g3a_predate_catchability_quotafleet

A formula onject that defines catch based on the available biomass of the stock multiplied by a scaling factor set according to a simple harvest control rule:

$F_{pl} = S N_{pl} W_{pl}$

$C_{pl} = q E \Delta t F_{pl}$

$q$

quota selected from quota_table, corresponding to the total biomass of sum_stocks. For example, given data.frame(biomass = c(10000, Inf), quota = I(list(g3_parameterized('quota.low'), g3_parameterized('quota.high')))), 'quota.low' will be chosen when total biomass is less than 10000, otherwise 'quota.high' will be used.

$S$

Suitability form suitabilities argument

$E$

E argument, scaling factor for the stock that is to be caught, per month

$\Delta t$

Length of current step as a proportion of the year, e.g. 0.25. See cur_step_size in g3a_time

$N_{pl}$

Number of prey in length cell for prey $p$, length $l$

$W_{pl}$

Mean weight of prey in length cell for prey $p$, length $l$

...if recalc_f is set, this will only be recaculated when true. Any other step will use the previous value.

g3a_predate_maxconsumption

formula objects that define a predator's maximum consumption:

$M_{L} = m_0 \Delta t e^{(m_1T-m_2T^3)} L^{m_3}$

$m_x$

mx parameter, for $M_L$, maximum possible consumption for the predator on the current timestep

$\Delta t$

Length of current step as a proportion of the year, e.g. 0.25. See cur_step_size in g3a_time

$T$

temperature parameter, formula representing current temperature

g3a_predate_catchability_predator

formula objects that define the predator/prey relationship:

$F_{pl} = (S E_{p} N_{pl} W_{pl})^{d_p}$

$C_{pl} = \frac{ N_{L} M_{L} \psi_L F_{pl} }{ E_{p} \displaystyle \sum_{\it preys}^p \sum_{\it lengths}^l F_{pl} }$

$\psi_{L} = \frac{ \displaystyle \sum_{\it preys}^p \sum_{\it lengths}^l F_{pl} }{ H \Delta t + \displaystyle \sum_{\it preys}^p \sum_{\it lengths}^l F_{pl} }$

$S$

Suitability form suitabilities argument

$\Delta t$

Length of current step as a proportion of the year, e.g. 0.25. See cur_step_size in g3a_time

$N_{pl}$

Number of prey in length cell for prey $p$, length $l$

$W_{pl}$

Mean weight of prey in length cell for prey $p$, length $l$

$M_L$

Maximum possible consumption for the predator on the current timestep, in in kilojoules per month. See g3a_predate_maxconsumption

$L$

Length of the current predator

$E_p$

energycontent parameter, the energy content of prey

$H$

half_feeding_f parameter, the biomass of prey required to allow the predator to consume prey at half the maximum consumption level

$T$

temperature parameter, formula representing current temperature

g3a_predate

An action (i.e. list of formula objects) that will...

1. For each prey, collect all suitable stock into a predstock_prey_stock__suit variable, using the catchability_f $F_pl$ formula. The units here will depend on the catchability_f method used.

2. After all predator consumption is done, scale consumption using the catchability_f $C_pl$ formula into predstock_prey_stock__cons, summed into prey_stock__totalpredate

3. Calculate prey_stock__consratio (ratio of consumed to available), capping using overconsumption_f. Update prey_stock__num

4. Recalculate predstock_prey_stock__cons, predstock_prey_stock__suit, post-overconsumption

See Also

https://gadget-framework.github.io/gadget2/userguide/chap-stock.html#sec:stockpredator, g3_stock

Examples

areas <- c(a = 1, b = 2)
ling_imm <- g3_stock(c(species = 'ling', 'imm'), seq(20, 156, 4)) %>% g3s_age(3, 10)
ling_mat <- g3_stock(c(species = 'ling', 'mat'), seq(20, 156, 4)) %>% g3s_age(5, 15)
lln <- g3_fleet('lln') %>% g3s_livesonareas(areas[c('a', 'b')])

# Invent a lln_landings table
lln_landings <- expand.grid(
    year = 1999:2000,
    step = c(1, 2),
    area = areas[c('a', 'b')])
lln_landings$total_weight <- floor(runif(nrow(lln_landings), min=100, max=999))

# g3a_predate_catchability_totalfleet(): Set catch accordings to landings data
predate_action <- g3a_predate_fleet(
    lln,
    list(ling_imm, ling_mat),
    suitabilities = g3_suitability_exponentiall50(by_stock = 'species'),
    catchability_f = g3a_predate_catchability_totalfleet(
        g3_timeareadata('lln_landings', lln_landings, "total_weight") ))

# g3a_predate_catchability_numberfleet(): Fixed quota of 1000 fish
predate_action <- g3a_predate_fleet(
    lln,
    list(ling_imm, ling_mat),
    suitabilities = g3_suitability_exponentiall50(by_stock = 'species'),
    catchability_f = g3a_predate_catchability_numberfleet(
        g3_parameterized(
            'quota',
            value = 1000,
            by_predator = TRUE,
            scale = 0.5,
            optimise = FALSE) ))
attr(suppressWarnings(g3_to_r(list(predate_action))), 'parameter_template')

---

Gadget3 renewal actions

Description

Add renewal / initialconditions to a g3 model

Usage

g3a_renewal_vonb_recl(
        Linf = g3_parameterized('Linf', value = 1, by_stock = by_stock),
        K = g3_parameterized('K', value = 1, by_stock = by_stock),
        recl = g3_parameterized('recl', by_stock = by_stock),
        recage = g3_parameterized('recage', by_stock = FALSE, optimise = FALSE),
        by_stock = TRUE)

g3a_renewal_vonb_t0(
        Linf = g3_parameterized('Linf', value = 1, by_stock = by_stock),
        K = g3_parameterized('K', value = 1, by_stock = by_stock),
        t0 = g3_parameterized('t0', by_stock = by_stock),
        by_stock = TRUE)

g3a_renewal_initabund(
    scalar = g3_parameterized('init.scalar', value = 1, by_stock = by_stock),
    init = g3_parameterized('init', value = 1, by_stock = by_stock, by_age = TRUE),
    M = g3_parameterized('M', by_stock = by_stock, by_age = TRUE),
    init_F = g3_parameterized('init.F', by_stock = by_stock_f),
    recage = g3_parameterized('recage', by_stock = FALSE, optimise = FALSE),
    proportion_f = ~1,
    by_stock = TRUE,
    by_stock_f = FALSE)

############################# g3a_initialconditions

g3a_initialconditions(stock, num_f, wgt_f, run_f = ~cur_time == 0L,
        run_at = g3_action_order$initial)

g3a_initialconditions_normalparam(
        stock,
        factor_f = g3a_renewal_initabund(by_stock = by_stock),
        mean_f = g3a_renewal_vonb_t0(by_stock = by_stock),
        stddev_f = g3_parameterized('init.sd', value = 10,
            by_stock = by_stock, by_age = by_age),
        alpha_f = g3_parameterized('walpha', by_stock = wgt_by_stock),
        beta_f = g3_parameterized('wbeta', by_stock = wgt_by_stock),
        age_offset = quote( cur_step_size ),
        by_stock = TRUE,
        by_age = FALSE,
        wgt_by_stock = TRUE,
        run_f = ~cur_time == 0L,
        run_at = g3_action_order$initial)

g3a_initialconditions_normalcv(
        stock,
        factor_f = g3a_renewal_initabund(by_stock = by_stock),
        mean_f = g3a_renewal_vonb_t0(by_stock = by_stock),
        cv_f = g3_parameterized('lencv', by_stock = by_stock, value = 0.1,
            optimise = FALSE),
        alpha_f = g3_parameterized('walpha', by_stock = wgt_by_stock),
        beta_f = g3_parameterized('wbeta', by_stock = wgt_by_stock),
        age_offset = quote( cur_step_size ),
        by_stock = TRUE,
        by_age = FALSE,
        wgt_by_stock = TRUE,
        run_f = ~cur_time == 0L,
        run_at = g3_action_order$initial)

############################# g3a_renewal

g3a_renewal(stock, num_f, wgt_f, run_f = ~TRUE,
        run_at = g3_action_order$renewal)

g3a_renewal_normalparam(
        stock,
        factor_f = g3_parameterized('rec',
            by_stock = by_stock,
            by_year = TRUE,
            scale = g3_parameterized(
                name = 'rec.scalar',
                by_stock = by_stock),
            ifmissing = NaN),
        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_age = quote(stock__minage),
        run_projection = FALSE,
        run_step = 1,
        run_f = NULL,
        run_at = g3_action_order$renewal)

g3a_renewal_normalcv(
        stock,
        factor_f = g3_parameterized('rec',
            by_stock = by_stock,
            by_year = TRUE,
            scale = g3_parameterized(
                name = 'rec.scalar',
                by_stock = by_stock),
            ifmissing = NaN),
        mean_f = g3a_renewal_vonb_t0(by_stock = by_stock),
        cv_f = g3_parameterized('lencv', by_stock = by_stock, value = 0.1,
            optimise = FALSE),
        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_age = quote(stock__minage),
        run_projection = FALSE,
        run_step = 1,
        run_f = NULL,
        run_at = g3_action_order$renewal)

############################# g3a_otherfood

g3a_otherfood(
        stock,
        num_f = g3_parameterized('of_abund', by_year = TRUE, by_stock = by_stock,
            scale = g3_parameterized('of_abund.step', by_step = TRUE,
                by_stock = by_stock) ),
        wgt_f = g3_parameterized('of_meanwgt', by_stock = by_stock),
        by_stock = TRUE,
        force_lengthvector = !any(grepl("__midlen$", all.vars(num_f))),
        run_f = quote( cur_time <= total_steps ),
        run_at = g3_action_order$initial)

g3a_otherfood_normalparam(
        stock,
        factor_f = g3_parameterized(
            'of_abund', by_year = TRUE, by_stock = by_stock,
            scale = g3_parameterized(
                'of_abund.step', value = 1, by_step = TRUE, by_stock = by_stock),
            ifmissing = "of_abund.proj" ),
        mean_f = g3a_renewal_vonb_t0(by_stock = by_stock),
        stddev_f = g3_parameterized('init.sd', value = 10,
            by_stock = by_stock, by_age = by_age),
        alpha_f = g3_parameterized('walpha', by_stock = wgt_by_stock),
        beta_f = g3_parameterized('wbeta', by_stock = wgt_by_stock),
        by_stock = TRUE,
        by_age = FALSE,
        wgt_by_stock = TRUE,
        run_f = quote( cur_time <= total_steps ),
        run_at = g3_action_order$initial)

g3a_otherfood_normalcv(
        stock,
        factor_f = g3_parameterized(
            'of_abund', by_year = TRUE, by_stock = by_stock,
            scale = g3_parameterized(
                'of_abund.step', value = 1, by_step = TRUE, by_stock = by_stock),
            ifmissing = "of_abund.proj" ),
        mean_f = g3a_renewal_vonb_t0(by_stock = by_stock),
        cv_f = g3_parameterized('lencv', by_stock = by_stock, value = 0.1,
            optimise = FALSE),
        alpha_f = g3_parameterized('walpha', by_stock = wgt_by_stock),
        beta_f = g3_parameterized('wbeta', by_stock = wgt_by_stock),
        by_stock = TRUE,
        by_age = FALSE,
        wgt_by_stock = TRUE,
        run_f = quote( cur_time <= total_steps ),
        run_at = g3_action_order$initial)

Arguments

stock	The g3_stock to apply to
num_f	formula that produces a lengthgroup vector of number of individuals for the current age/area/... length group.
wgt_f	formula that produces a lenghgroup vector of mean weight for the current age/area/... length group.
run_at	Integer order that actions will be run within model, see g3_action_order.
factor_f, mean_f, stddev_f, alpha_f, beta_f	formula substituted into normalparam calcuations, see below.
cv_f	formula substituted into normalcv calcuations, basically stddev_f = mean_f * cv_f, see below.
age_offset	Replace age with age - age_offset in mean_f. Used to simulate initialconditions at time "-1".
force_lengthvector	Should we assume that num_f is a constant, and needs repeating enough times to turn into a length vector?
run_age	Age to run renewals for, used as age == (run_age) into default run_f
run_projection	Boolean. Run renewal in projection years? If false adds !cur_year_projection into default run_f
run_step	Which step to perform renewal in, or NULL for continuous renewal. Adds cur_step == (run_step) into default run_f
run_f	formula specifying a condition for running this action, For initialconditions defaults to first timestep. For renewal, the default is a combination of run_age, run_step & run_projection. For otherfood, the default is to always run, apart from when the model is ending.
Linf, K, t0, recl	formula substituted into vonb calcuations, see below.
recage	formula substituted into initial abundance and vonb calcuations, see below.
proportion_f, scalar, init, M, init_F	formula substituted into initial abundance calcuations, see below.
by_stock, wgt_by_stock, by_stock_f, by_age	Controls how parameters are grouped, see g3_parameterized

Details

All of the following actions will renew stock in a model. The differences are when and what they apply to by default:

g3a_initialconditions_*

Will run at the start of the model, building an inital state of all ages

g3a_renewal_*

Will run at every step but only for the minimal age, adding new recruits as an alternative to g3a_spawn()

g3a_otherfood_*

Will run at every step, replacing the previous state, creating a non-dynamic stock for predators to consume

Specifying the quantities and mean-weights in each case works identically.

A model can have any number of g3a_renewal_* actions, so long as the calling arguments are different. For instance, run_f = ~age == 5 and run_f = ~age == 7.

The g3a_renewal_* actions will define the following stock instance variables for stock:

stock__renewalnum

Extra individuals added to the stock

stock__renewalwgt

Mean weight of added individuals

Value

g3a_renewal_vonb_recl

A formula object representing

$L_{\infty} * {1 - e^{-1 * \kappa * (a - (a_{0} + \frac{\log(1 - L_{0}/L_{\infty})}{\kappa} ))}}$

$L_{0}$

Substituted for recl

$L_{\infty}$

Substituted for Linf

$\kappa$

Substituted for K

$a_{0}$

Substituted for recage

NB: g3a_initialconditions_normalparam will replace $a$ with $a - \Delta{t}$, see age_offset

g3a_renewal_vonb_t0

A formula object representing

$L_{\infty} * (1 - e^{-1 * \kappa * (a - t_{0}) })$

$L_{\infty}$

Substituted for Linf

$\kappa$

Substituted for K

$t_{0}$

Substituted for t0

NB: g3a_initialconditions_normalparam will replace $a$ with $a - \Delta{t}$, see age_offset

g3a_renewal_vonb

An alias for g3a_renewal_vonb_recl()

g3a_renewal_initabund

A formula object representing

$scalar * init * e^{-1 * (M + F_{0}) * (a - a_{0}) } * proportion$

scalar

Substituted for scalar

init

Substituted for init

$M$

Substituted for M

$F_{0}$

Substituted for init_F

$a_{0}$

Substituted for recage

proportion

Substituted for proportion

g3a_initialconditions / g3a_renewal / g3a_otherfood

An action (i.e. list of formula objects) that will, for the given stock, iterate over each area/age/etc. combination, and generate a lengthgroup vector of new individuals and weights using num_f and wgt_f.

renewal will add fish to the existing stock, whereas initialconditions & otherfood will replace any previous values.

g3a_initialconditions_normalparam / g3a_renewal_normalparam / g3a_otherfood_normalparam

As g3a_initialconditions / g3a_renewal, but the following formulae are used to calculate num/wgt:

$n = {dnorm}(L, \mu, \sigma)$

$N = F 10000 \frac{n}{\sum n}$

$W = \alpha L^{\beta}$

$L$

Midlength of length groups for current area/age/...

$F$

Substituted for factor_f

$\mu$

Substituted for mean_f

$\sigma$

Substituted for stddev_f

$\alpha$

Substituted for alpha_f

$\beta$

Substituted for beta_f

g3a_initialconditions_normalcv / g3a_renewal_normalcv / g3a_otherfood_normalcv

As g3a_initialconditions / g3a_renewal, but the following formulae are used to calculate num/wgt:

$n = e^{-(\frac{L - \mu}{\mu * {CV}})^2 / 2}$

$N = F 10000 \frac{n}{\sum n}$

$W = \alpha L^{\beta}$

$L$

Midlength of length groups for current area/age/...

$F$

Substituted for factor_f

$\mu$

Substituted for mean_f

$CV$

Substituted for cv_f

$\alpha$

Substituted for alpha_f

$\beta$

Substituted for beta_f

See Also

https://gadget-framework.github.io/gadget2/userguide/chap-stock.html#sec:stockinitial, https://gadget-framework.github.io/gadget2/userguide/chap-stock.html#sec:stockrenew, https://gadget-framework.github.io/gadget2/userguide/chap-other.html#chap-other, g3_stock

Examples

ling_imm <- g3_stock('ling_imm', seq(20, 156, 4)) %>% g3s_age(3, 10)

initialconditions_action <- g3a_initialconditions_normalparam(
    ling_imm,
    by_age = TRUE)  # per-age init.sd parameters
renewal_action <- g3a_renewal_normalparam(
    ling_imm,
    run_step = 2)  # Renewal happens in spring

# To get a single ling_imm.lencv parameter instead of init.sd
initialconditions_action <- g3a_initialconditions_normalcv(
    ling_imm)
renewal_action <- g3a_renewal_normalcv(
    ling_imm,
    run_step = 2)  # Renewal happens in spring

## Plots
par(mar = c(4,2,2,1), cex.main = 1)
curve(g3_eval(g3a_renewal_vonb_t0(Linf = 20, K = 0.8, t0 = 0), age = x),
    0, 10, col = 2, xlab = "age", main = "g3a_renewal_vonb_t0(Linf = 20, K = 0.8..1.4, t0 = 0)")
curve(g3_eval(g3a_renewal_vonb_t0(Linf = 20, K = 1.0, t0 = 0), age = x),
    0, 10, col = 1, add = TRUE)
curve(g3_eval(g3a_renewal_vonb_t0(Linf = 20, K = 1.2, t0 = 0), age = x),
    0, 10, col = 3, add = TRUE)
curve(g3_eval(g3a_renewal_vonb_t0(Linf = 20, K = 1.4, t0 = 0), age = x),
    0, 10, col = 4, add = TRUE)

## Otherfood
# "Otherfood" stocks are defined in a similar manner to any other stock
# Note that _normalparam & _normalcv need both length & age dimensions
other_wgt <- g3_stock('other_wgt', 0)
other_cv <- g3_stock('other_cv', seq(50, 100, by = 10)) %>% g3s_age(5,10)

otherfood_actions <- list(
    # Will get other_wgt.of_abund.1998.1, other_wgt.of_meanwgt parameters
    g3a_otherfood(other_wgt),
    # Use standard vonB parameters (Linf/K/t0) to define abundance
    g3a_otherfood_normalcv(other_cv) )

---

Gadget3 report actions

Description

Add report to a g3 model

Usage

g3a_report_stock(report_stock, input_stock, report_f,
    include_adreport = FALSE,
    run_f = TRUE,
    run_at = g3_action_order$report)

g3a_report_history(
        actions,
        var_re = "__num$|__wgt$",
        out_prefix = "hist_",
        run_f = TRUE,
        run_at = g3_action_order$report)

g3a_report_detail(actions,
    run_f = quote( g3_param('report_detail', optimise = FALSE, value = 1L,
        source = "g3a_report_detail") == 1 ),
    abundance_run_at = g3_action_order$report_early,
    run_at = g3_action_order$report)

Arguments

report_stock	The g3_stock to aggregate into
input_stock	The g3_stock that will be aggregated
report_f	formula specifying what to collect, for instance g3_formula( stock_ss(input_stock__num) ) or g3_formula( stock_ss(input_stock__wgt) ).
actions	List of actions that model will consist of.
var_re	Regular expression specifying variables to log history for.
out_prefix	Prefix to add to history report output, e.g. hist_ling_imm__num.
include_adreport	Should the aggregated value get ADREPORT'ed?
abundance_run_at	Integer order that abundance will be collected within the model. Note that by default it's collected at the start, not the end
run_f	formula specifying a condition for running this action, default always runs.
run_at	Integer order that actions will be run within model, see g3_action_order.

Details

The g3a_report_detail defines a selection of default reports from your model, using g3a_report_history:

*_surveyindices_*__params

The slope/intercept as used by g3l_distribution_surveyindices_log

step_lengths

*_weight

The weighting of likelihood components

nll_*

Breakdown of nll for each likelihood component

dstart_*__num

Abundance in numbers, at start of each model step

dstart_*__wgt

Mean weight of individuals, at start of each model step

detail_*__renewalnum

Numbers produced by renewal at each model step

detail_*__spawnednum

Numbers produced by spawning at each model step

detail_*_*__cons

Total biomass of prey consumed by predator, at each model step

detail_*_*__suit

Total suitable biomass of prey for predator, at each model step

The reports produced by g3a_report_history will vary based on the provided inputs. A model can have any number of g3a_report_* actions, so long as the calling arguments are different. For instance, run_f = ~age == 5 and run_f = ~age == 7.

Value

g3a_report_stock

An action (i.e. list of formula objects) that will...

1. Iterate over input_stock, collecting data into report_stock

2. Add the contents of report_stock__instance_name to the model report

g3a_report_history

An action (i.e. list of formula objects) that will store the current state of each variable found matching var_re.

g3a_report_detail

Uses g3a_report_history to generate detailed reports suitable for use in g3_fit.

See Also

g3_stock

Examples

ling_imm <- g3_stock('ling_imm', seq(20, 156, 4)) %>% g3s_age(3, 10)

# Report that aggregates ages together
agg_report <- g3_stock('agg_report', c(1)) %>%
    g3s_agegroup(list(young = 1:3, old = 4:5)) %>%
    g3s_time(year = 2000:2002)
# Generate dissaggregated report by cloning the source stock, adding time
raw_report <- g3s_clone(ling_imm, 'raw_report') %>%
    g3s_time(year = 2000:2002)

actions <- list(
    g3a_age(ling_imm),
    g3a_report_stock(agg_report, ling_imm, g3_formula( stock_ss(ling_imm__num) ),
        include_adreport = TRUE),
    g3a_report_stock(raw_report, ling_imm, g3_formula( stock_ss(ling_imm__num) )))
# "raw_report__num" and "agg_report__num" will be available in the model report
# In addition, agg_report__num will be included in TMB::sdreport() output

# Report history of all "__num" and "__wgt" variables
actions <- c(actions, list(g3a_report_history(actions)))

# Report history of just "ling_imm__num"
actions <- c(actions, list(g3a_report_history(actions, "^ling_imm__num$")))

# Add a detail report suitable for g3_fit
actions <- c(actions, list(g3a_report_detail(actions)))

---

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

μ

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

μ

Argument provided to function

λ

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

μ

Argument provided to function

λ

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

λ

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)

---