bayesnecformula {bayesnec}

Set up a model formula for use in bayesnec

Description

Set up a model formula for use in the bayesnec package, allowing linear and non-linear (potentially multi-level) concentration-response models to be defined.

Usage

bayesnecformula(formula, ...)

Arguments

formula

Either a character string defining an R formula or an actual formula object. See details.

...

Unused.

Details

See methods(class = "bayesnecformula") for an overview of available methods.

General formula syntax

The formula argument accepts formulas of the following syntax:

response | aterms ~ crf(x, model) + glterms

The population-level term: crf

bayesnec uses a special internal term called crf, which sets the concentration-response equation to be evaluated based on some x predictor. The equation itself is defined by the argument "model": a character vector containing a specific model, a concatenation of specific models, or a single string defining a particular group of models (or group of equations, see models). Internally this argument is substituted by an actual brmsformula, which is then passed onto brm for model fitting.

Group-level terms: glterms

The user has three options to define group-level effects in a bayesnecformula: 1) a general "offset" group-level effect defined by the term ogl (as in e.g. ogl(group_variable)). This adds an additional population-level parameter ogl to the model defined by crf, analogously to an intercept-only group-level effect in a classic linear model. 2) A group-level effect applied to all parameters in a model at once. This is done by the special term pgl, (as in e.g. pgl(group_variable)), which comes in handy so the user does not need to know the internal syntax and name of each parameter in the model. 3) A more classic approach where the user can specify which specific parameters — NB: that requires prior knowledge on the model structure and parameter names — to vary according to a grouping variable (as in e.g. (bot | group_variable)). bayesnecformula will ignore this term should the parameter not exist in the specified model or model suite. For example, the parameter bot exists in model "nec4param" but not in "nec3param", so if the user specifies model = "nec" in crf, the term (bot | group_variable) will be dropped in models where that parameter does not exist.

Further brms terms (largely untested)

Currently bayesnecformula is quite agnostic about additional terms that are valid for a brmsformula. These are aterms and pterms (see ?brmsformula). The only capability that bayesnecformula does not allow is the addition of pterms outside of the term crf. Although pterms can be passed to predictor x within crf, we strongly discourage their use because those functionalities have not been tested yet. If this is extremely important to your work, please raise an issue on bayesnec GitHub, and we will consider further testing and development. Currently, the only two aterms that have validated behaviour are:

1. trials(), which is essential in binomially-distributed data, e.g. y | trials(trials_variable), and 2) weights, e.g. y | weights(weights_variable), following brms formula syntax. Please note that brms does not implement design weights as in other standard base functions. From their help page, brms "takes the weights literally, which means that an observation with weight 2 receives 2 times more weight than an observation with weight 1. It also means that using a weight of 2 is equivalent to adding the corresponding observation twice to the data frame". Other aterms might be added, though we cannot attest to their functionality within bayesnec, i.e. checks will be done outside via brm.

NB: aterms other than trials() and weights() are currently omitted from model.frame output. If you need other aterms as part of that output please raise an issue on our GitHub page.

Validation of formula Please note that the function only checks for the input nature of the formula argument and adds a new class. This function does not perform any validation on the model nor checks on its adequacy to work with other functions in the package. For that please refer to the function check_formula which requires the dataset associated with the formula.

Value

An object of class bayesnecformula and formula.

See Also

check_formula, model.frame, models, show_params, make_brmsformula

Examples

library(bayesnec)

bayesnecformula(y ~ crf(x, "nec3param"))
# or use shot alias bnf
bayesnecformula(y ~ crf(x, "nec3param")) == bnf(y ~ crf(x, "nec3param"))
bnf(y | trials(tr) ~ crf(sqrt(x), "nec3param"))
bnf(y | trials(tr) ~ crf(x, "nec3param") + ogl(group_1) + pgl(group_2))
bnf(y | trials(tr) ~ crf(x, "nec3param") + (nec + top | group_1))


# complex transformations are not advisable because
# they are passed directly to Stan via brms
# and are likely to fail -- transform your variable beforehand!
try(bnf(y | trials(tr) ~ crf(scale(x, scale = TRUE), "nec3param")))