step.RdAdditional meta-functions to help manage writing stock-handling actions.
g3_step(step_f, recursing = FALSE, orig_env = environment(step_f))Input formula containing references to functions below
Only use default value
Only use default value
All action producing functions will run their output through g3_step.
This means that the functions described here will be available in any gadget3
code.
They handle translation of stock instance naming, so code can refer to e.g.
stock__num without having to translate naming to the final stock name,
and iterating over stock dimensions.
Add a comment to the code to act as a label for that step, when producing an
outline of the model. There shouldn't be more than one debug_label
call in a step.
Models compiled with trace = TRUE will print the resultant string to stdout.
Any number of character strings, or g3_stock variables. The latter will be replaced with the final name.
Identical to debug_label, but not considered a "label", just a code comment, so any number of calls can be added.
stock_assert(expression, message, message/stock-var, ...)
Assert that expression is true, if not abort with a message.
stock_reshape(dest_stock, expression)
Output expression with it's length structure reshaped to match dest_stock. The source stock is considered to be the first one found in expression
How this is achieved depends on the difference. If the source and destination match then this is a no-op. Otherwise a transformation matrix is generated and included into the model.
stock_ss(stock_var, [ dimname = override, dimname = override, ... ])
Subsets stock_var to get a length vector for the current iteration of stock_iterate(). If dimnames are supplied, then these dimensions overwritten with the suppled override, which could be a missing value, to preserve a dimension. See final example.
Length is a missing value by default, i.e. we return length groups. To avoid
this happening, set length = default to iterate over length too.
stock_ssinv(stock_var, [ dimname, dimname, ... ])
like stock_ss(), but subset only the mentioned dimnames.
stock_ss(stock, stock_name1 = expr, stock_name2 = expr, ... [ default ])
Switch based on name of stock, returning the relevant expr or default. If no default supplied, then an unknown stock is an error.
expr is implicitly wrapped with stock_with(stock, ...),
so any references to the stock variable will work. If only default is provided,
then this is identical to calling stock_with.
stock_with(stock, expr)
Replaced with expr but with all stock variables of stock renamed with their final name. This is generally needed when not iterating over a stock, but e.g. zeroing or summing the whole thing.
stock_iterate(stock, expr)
Wrap expr with the code to iterate over vector dimensions in
stock, accessed using stock_ss(stock).
Which dimensions are iterated over is decided based on the call to
stock_ss(stock). By default, stock_ss leaves length blank so will
iterate over a length vector for each dimension.
You can iterate over each value individually with the following:
stock_iterate(stock, stock_ss(stock, length = default) )
Current values for each dimension will be available as variables,
e.g. area, age, and can be used in formulae.
stock_intersect(stock, expr)
Wrap expr with the code to intersect all dimensions with the dimensions of an outer stock_iterate().
stock_interact(stock, expr, prefix = prefix)
Wrap expr with the code to interact with the dimensions of an outer stock_iterate(). Interact means to intersect over area, but try the combinatoral explosion of all other dimensions, i.e. what would make most sense when 2 stocks interact in a predator-prey relationship.
Additional variables will be prefixed with prefix.
stock_prepend(stock, param_call, name_part = NULL)
Converts a g3_param or g3_param_table call, prefixing the parameter name with the stock name, and renaming any references to stock variables. If name_part given, will only add given part(s) of the stock name.
Returns param_call with the additions made.
A formula object with references to above functions replaced.
library(magrittr)
### debug_label
stock <- g3_stock('halibut', 1:10) %>% g3s_age(1,10)
prey_stock <- g3_stock('herring', 1:3) %>% g3s_age(1,3)
g3_step(~debug_trace("Zero ", stock, "-", prey_stock, " biomass-consuming counter"))
#> ~debug_trace("Zero halibut-herring biomass-consuming counter")
#> <environment: 0x559780217d50>
### stock_assert
stock <- g3_stock('halibut', 1:10) %>% g3s_age(1,10)
g3_step(~stock_assert(stock_with(stock, all(is.finite(stock__num))), stock, "__num became NaN/Inf"))
#> ~assert_msg(~all(is.finite(halibut__num)), "halibut__num became NaN/Inf")
#> <environment: 0x559780217d50>
### stock_reshape
s <- g3_stock('s', seq(3, 21, 3))
s__num <- g3_stock_instance(s, 100)
agg <- g3_stock('agg', c(3, 10, 21), open_ended = FALSE)
g3_eval(~stock_iterate(s, stock_reshape(agg, stock_ss(s__num))))
#> [1] 233.3333 366.6667
### stock_ss
stock <- g3_stock('halibut', 1:10) %>% g3s_age(1,10) %>% g3s_livesonareas(1)
stock__num <- g3_stock_instance(stock)
g3_step(~stock_iterate(stock, { x <- x + stock_ss(stock__num) }))
#> ~g3_with(`:=`(area, halibut__area), `:=`(halibut__area_idx, g3_idx(1L)),
#> for (age in seq(halibut__minage, halibut__maxage, by = 1)) g3_with(`:=`(halibut__age_idx,
#> g3_idx(age - halibut__minage + 1L)), x <- x + halibut__num[,
#> halibut__age_idx, halibut__area_idx]))
#> <environment: 0x559780217d50>
g3_step(~stock_ss(stock__num, area = 5))
#> ~stock__num[, stock__age_idx, 5]
#> <environment: 0x559780217d50>
g3_step(~stock_ss(stock__num, age = i + 1))
#> ~stock__num[, i + 1, stock__area_idx]
#> <environment: 0x559780217d50>
g3_step(~stock_ss(stock__num, area = , age = j))
#> ~stock__num[, j, ]
#> <environment: 0x559780217d50>
### stock_ssinv
stock <- g3_stock('halibut', 1:10) %>% g3s_age(1,10) %>% g3s_livesonareas(1)
g3_step(~g3_step(~stock_ssinv(stock, 'age')))
#> ~g3_step(~stock[, stock__age_idx, ])
#> <environment: 0x559780217d50>
g3_step(~g3_step(~stock_ssinv(stock, 'area')))
#> ~g3_step(~stock[, , stock__area_idx])
#> <environment: 0x559780217d50>
### stock_switch
stock <- g3_stock('halibut', 1:10) ; fleet_stock <- g3_fleet('igfs')
g3_step(~stock_switch(stock, halibut = 2, herring = 3, -1))
#> ~2
#> <environment: 0x559780217d50>
g3_step(~stock_switch(fleet_stock, halibut = 2, herring = 3, -1))
#> ~(-1)
#> <environment: 0x559780217d50>
g3_step(~stock_switch(stock, halibut = stock__midlen, -1))
#> ~halibut__midlen
#> <environment: 0x559780217d50>
### stock_with
stock <- g3_stock('halibut', 1:10)
g3_step(~stock_with(stock, sum(stock__num)))
#> ~sum(halibut__num)
#> <environment: 0x559780217d50>
### stock_iterate
stock <- g3_stock('halibut', 1:10) %>% g3s_age(1,10)
g3_step(~stock_iterate(stock, x <- x + stock_ss(stock__num)))
#> ~for (age in seq(halibut__minage, halibut__maxage, by = 1)) g3_with(`:=`(halibut__age_idx,
#> g3_idx(age - halibut__minage + 1L)), x <- x + halibut__num[,
#> halibut__age_idx])
#> <environment: 0x559780217d50>
### stock_intersect
stock <- g3_stock('halibut', 1:10) %>% g3s_age(1,10)
prey_stock <- g3_stock('herring', 1:3) %>% g3s_age(1,3)
g3_step(~stock_iterate(stock, stock_intersect(prey_stock, {
x <- x + stock_ss(stock__num) + stock_ss(prey_stock__num)
})))
#> ~for (age in seq(halibut__minage, halibut__maxage, by = 1)) if (age >=
#> herring__minage && age <= herring__maxage) g3_with(`:=`(halibut__age_idx,
#> g3_idx(age - halibut__minage + 1L)), `:=`(herring__age_idx,
#> g3_idx(age - herring__minage + 1L)), x <- x + halibut__num[,
#> halibut__age_idx] + herring__num[, herring__age_idx])
#> <environment: 0x559780217d50>
### stock_interact
stock <- g3_stock('halibut', 1:10) %>% g3s_age(1,10)
prey_stock <- g3_stock('herring', 1:3) %>% g3s_age(1,3)
g3_step(~stock_iterate(stock, stock_interact(prey_stock, {
x <- x + stock_ss(stock__num) + stock_ss(prey_stock__num)
}, prefix = "prey" )))
#> ~for (age in seq(halibut__minage, halibut__maxage, by = 1)) g3_with(`:=`(halibut__age_idx,
#> g3_idx(age - halibut__minage + 1L)), for (prey_age in seq(herring__minage,
#> herring__maxage, by = 1)) g3_with(`:=`(herring__age_idx,
#> g3_idx(prey_age - herring__minage + 1L)), x <- x + halibut__num[,
#> halibut__age_idx] + herring__num[, herring__age_idx]))
#> <environment: 0x559780217d50>