bayesnecformula {bayesnec} | R Documentation |
bayesnec
Set up a model formula for use in the
bayesnec
package allowing to
define linear and non-linear (potentially multilevel) concentration-response
models.
bayesnecformula(formula, ...)
formula |
Either a |
... |
Unused. |
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 what an intercept-only group-level effect
would be 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 the user because those functionalities have not
been tested yet. If this is extremely important to your research, please
raise an issue on GitHub and we will consider.
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 function. 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.
An object of class bayesnecformula
and
formula
.
check_formula
,
model.frame
,
models
,
show_params
,
make_brmsformula
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")))