gadget3 (version 0.14-0)

step: G3 stock_* transformation functions

Description

Additional meta-functions to help manage writing stock-handling actions.

Usage

g3_step(step_f, recursing = FALSE, orig_env = environment(step_f))

Value

g3_step

A formula object with references to above functions replaced.

Arguments

step_f

Input formula containing references to functions below

recursing

Only use default value

orig_env

Only use default value

debug_label

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.

Arguments

Any number of character strings, or g3_stock variables. The latter will be replaced with the final name.

debug_trace

Identical to debug_label, but not considered a "label", just a code comment, so any number of calls can be added.

stock_assert

stock_assert(expression, message, message/stock-var, ...)

Assert that expression is true, if not abort with a message.

stock_reshape

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_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_ssinv(stock_var, [ dimname, dimname, ... ])

like stock_ss(), but subset only the mentioned dimnames.

stock_switch

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_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_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_intersect(stock, expr)

Wrap expr with the code to intersect all dimensions with the dimensions of an outer stock_iterate().

stock_interact

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_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.

stock_hasdim

stock_hasdim(stock, dim_name)

Returns TRUE iff dim_name is present in stock.

This is mostly useful to replace code depending on whether a dimension has been used. When used as part of an if statement, the if statement and the unused branch will be optimised away.

Details

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.

Examples

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

### 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"))

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

### 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_step(~stock_ss(stock__num, area = 5))
# Lengthgroups for age_idx + 1
g3_step(~stock_ss(stock__num, age = default + 1))
# Vector for the entirety of the "next" area
g3_step(~stock_ss(stock__num, area = default + 1, vec = area))
g3_step(~stock_ss(stock__num, area = , age = j))

### 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(~g3_step(~stock_ssinv(stock, 'area')))

### stock_switch
stock <- g3_stock('halibut', 1:10) ; fleet_stock <- g3_fleet('igfs')
g3_step(~stock_switch(stock, halibut = 2, herring = 3, -1))
g3_step(~stock_switch(fleet_stock, halibut = 2, herring = 3, -1))
g3_step(~stock_switch(stock, halibut = stock__midlen, -1))

### stock_with
stock <- g3_stock('halibut', 1:10)
g3_step(~stock_with(stock, sum(stock__num)))

### stock_iterate
stock <- g3_stock('halibut', 1:10) %>% g3s_age(1,10)
g3_step(~stock_iterate(stock, x <- x + stock_ss(stock__num)))

### 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)
})))

### 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" )))