action_predate {gadget3} | R Documentation |
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 |
|
prey_stocks |
List of |
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 |
catchability_f |
A formula generated by one of the |
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 |
sum_stocks |
Either a list of g3_stock objects to sum when choosing a value from quote_table,
or |
recalc_f |
A formula denoting when to recalculate the current quota. For example |
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 |
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 columnsN
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 quotaN
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...
Zero fleet and prey catch counters
For each prey, collect maximum desired by fleet for all prey, into a prey_stock__predby_predstock variable
After all fleet consumption is done, scale consumption using catchability_f, sum into prey_stock__totalpredate
After all consumption is done, temporarily convert prey_stock__predby_predstock to a proprotion of prey_stock__totalpredate
Calculate prey_stock__consratio (ratio of consumed to available), capping using overconsumption_f. Update prey_stock__num
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')