action_predate: Gadget3 predation actions

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

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_project(
    quota_f = NULL,
    landings_f = NULL,
    quota_prop = g3_parameterized("quota.prop", by_predator = TRUE, value = 1),
    cons_step = g3_parameterized("cons.step", by_predator = TRUE, by_step = TRUE,
        value = quote( step_lengths / 12.0 )),
    unit = c("biomass", "biomass-year", "harvest-rate", "harvest-rate-year",
             "individuals", "individuals-year") )

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, landings_f	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).
quota_f	A per-year quota for use during projection time periods, or for the whole model if landings_f is NULL. Generally, this will be produced by g3_quota.
quota_prop	A quota can apply to multiple fleets, in which case use this parameter to assign the proportion of quota available to the current fleet. Note that ideally all quota_prop values sum to 1, but this doesn't have to be the case (e.g. over/under-utilisation of quotas).
cons_step	The proportion of the per-year quota that is used in each step. As with quota_prop ideally all values sum to 1.
unit	The unit that quota_f / landings_f is provided in. "biomass", "effort", "individuals" are equivalent to totalfleet / linearfleet & numberfleet respectively.
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_project

The formula used depends on the unit parameter. "biomass", "effort", "individuals" are equivalent to totalfleet / linearfleet & numberfleet respectively. However, E will switch from landings to quota once the model is projecting.

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')

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