action_predate: Gadget3 predation actions

In 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_effortfleet(catchability_fs, E)

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

g3a_predate_fleet(fleet_stock, prey_stocks, suitabilities, catchability_f,
    overconsumption_f = quote(
        logspace_add_vec(stock__consratio * -1e3, 0.95 * -1e3) / -1e3 ),
    run_f = ~TRUE, run_at = g3_action_order$predate)

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

Arguments

fleet_stock	g3_stock that describes the harvesting fleet.
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 formula 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.
overconsumption_f	Overconsumption rule, a formula that should cap all values in stock__consratio to <= 95
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_fleet will, given a g3_fleet "predator" and g3_stock prey, 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:

prey_stock__suit_fleet_stock

Suitability of (prey_stock) for (fleet_stock), in a prey array. i.e. the result of calculating the formula in suitabilities for the current state of the prey

prey_stock__predby_predstock

Biomass of (prey_stock) caught by (fleet_stock), in a prey array

fleet_stock__catch

Biomass of all prey caught by (fleet stock), in a fleet array

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

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

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

\frac{E N_{sl} W_{sl}}{\displaystyle \sum_{\it stocks} \sum_{\it lengths} N_{sl} W_{sl}}

E

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

N

Number of stock in length cell

W

Mean weight of stock in length cell

g3a_predate_catchability_numberfleet

A formula that defines a fleet's desired catch by total number of stock landed (not the biomass):

\frac{E N_{sl}}{\displaystyle \sum_{\it stocks} \sum_{\it lengths} N_{sl}}

E

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

N

Number of stock in length cell

g3a_predate_catchability_linearfleet

A formula object that defines a linear relationship between desired catch and available biomass:

E \Delta t N_{sl} W_{sl}

E

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

\Delta t

length of current timestep in months

N

Number of stock in length cell

W

Mean weight of stock in length cell

g3a_predate_catchability_effortfleet

This is a multi-species extension to linearfleet, allowing differently-parameterized catchability per-stock. Returns a formula object that defines:

c_{s} E \Delta t N_{sl} W_{sl}

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 timestep in months

N

Number of stock in length cell

W

Mean weight of stock in length cell

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:

q E \Delta t N_{sl} W_{sl}

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.

E

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

\Delta t

length of current timestep

N

Number of stock in length cell

W

Mean weight of stock in length cell

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

g3a_predate_fleet

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

1. Zero fleet and prey catch counters

2. For each prey, collect maximum desired by fleet for all prey, into a prey_stock__predby_predstock variable

3. After all fleet consumption is done, scale consumption using catchability_f, sum into prey_stock__totalpredate

4. After all consumption is done, temporarily convert prey_stock__predby_predstock to a proprotion of prey_stock__totalpredate

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

6. Recalculate prey_stock__predby_predstock, fleet_stock__catch, 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 documentation built on July 3, 2024, 9:07 a.m.