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.
bayesnecformula(formula, ...)An object of class bayesnecformula and
formula.
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:
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.
library(bayesnec)
bayesnecformula(y ~ crf(x, "nec3param"))
#> y ~ crf(x, "nec3param")
#> <environment: 0x5585bfa7ec98>
# or use shot alias bnf
bayesnecformula(y ~ crf(x, "nec3param")) == bnf(y ~ crf(x, "nec3param"))
#> [1] TRUE
bnf(y | trials(tr) ~ crf(sqrt(x), "nec3param"))
#> y | trials(tr) ~ crf(sqrt(x), "nec3param")
#> <environment: 0x5585bfa7ec98>
bnf(y | trials(tr) ~ crf(x, "nec3param") + ogl(group_1) + pgl(group_2))
#> y | trials(tr) ~ crf(x, "nec3param") + ogl(group_1) + pgl(group_2)
#> <environment: 0x5585bfa7ec98>
bnf(y | trials(tr) ~ crf(x, "nec3param") + (nec + top | group_1))
#> y | trials(tr) ~ crf(x, "nec3param") + (nec + top | group_1)
#> <environment: 0x5585bfa7ec98>
# \donttest{
# 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")))
#> y | trials(tr) ~ crf(scale(x, scale = TRUE), "nec3param")
#> <environment: 0x5585bfa7ec98>
# }