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, ... ][, vec = (dimname|full|single) ])
Subsets stock_var for the current iteration of stock_iterate().
The vec parameter decides the start value for all dimensions
If full, no other dimensions are set.
If set to a dimname, all dimensions after that dimension are set (i.e. a dimname-vector will be returned)
If single, all dimensions are set (i.e. a single value wil be returned).
The default is length if a length dimension is present (i.e. a length vector will be returned), otherwise single.
If dimnames are supplied, then the code supplied will override the above.
This code can include default, which will be substituted for the default subset,
or missing to represent an empty position in the subset.
If a dimname is not present in stock_var, it will be ignored.
stock_ssinv(stock_var, [ dimname, dimname, ... ])
like stock_ss(), but subset only the mentioned dimnames.
stock_switch(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.
### 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: 0x5622f093b388>
### 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: 0x5622f093b388>
### 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: 0x5622f093b388>
g3_step(~stock_ss(stock__num, area = 5))
#> ~stock__num[, stock__age_idx, 5]
#> <environment: 0x5622f093b388>
# Lengthgroups for age_idx + 1
g3_step(~stock_ss(stock__num, age = default + 1))
#> ~stock__num[, stock__age_idx + 1, stock__area_idx]
#> <environment: 0x5622f093b388>
# Vector for the entirety of the "next" area
g3_step(~stock_ss(stock__num, area = default + 1, vec = area))
#> ~stock__num[, , stock__area_idx + 1]
#> <environment: 0x5622f093b388>
g3_step(~stock_ss(stock__num, area = , age = j))
#> ~stock__num[, j, ]
#> <environment: 0x5622f093b388>
### 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: 0x5622f093b388>
g3_step(~g3_step(~stock_ssinv(stock, 'area')))
#> ~g3_step(~stock[, , stock__area_idx])
#> <environment: 0x5622f093b388>
### 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: 0x5622f093b388>
g3_step(~stock_switch(fleet_stock, halibut = 2, herring = 3, -1))
#> ~(-1)
#> <environment: 0x5622f093b388>
g3_step(~stock_switch(stock, halibut = stock__midlen, -1))
#> ~halibut__midlen
#> <environment: 0x5622f093b388>
### stock_with
stock <- g3_stock('halibut', 1:10)
g3_step(~stock_with(stock, sum(stock__num)))
#> ~sum(halibut__num)
#> <environment: 0x5622f093b388>
### 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: 0x5622f093b388>
### 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: 0x5622f093b388>
### 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: 0x5622f093b388>