Normalizes a formula or a list of formulas containing random-effect terms into a single formula and parsed BayesTools random-effect terms.
random_effects_formula(random, envir = parent.frame(), group_covariance = NULL)a formula or non-empty list of formulas.
environment used for the returned formula.
optional known group covariance. Use one
random_group_covariance() object or numeric matrix for a single random
block, or a named list of objects/matrices for multiple random blocks.
Names should match resolved random-effect block names, or grouping labels
when the grouping label is unambiguous.
A BayesTools_random_effects object with formula, terms,
components, and group_covariance fields.
List names define top-level random-effect components used by allocation and
summary metadata. In lists with two or more entries, missing names are
replaced by "component 1", "component 2", and so on, then sanitized
for JAGS node names. An unnamed one-entry list is treated like its bare
formula and receives no user-facing component prefix; an explicitly named
entry retains its name. Unnamed
random-effect terms inside a list entry are auto-named from the component
label. Explicit name = arguments define the final random-effect block name
and are the names targeted by prior_random() block overrides.
The fitted parameter_map() links concrete parameter_coordinates() to
public quantities declared by parameter_catalog(). Their canonical form is
(formula) owner: quantity(arguments), with owner: omitted for exactly one
random block and retained when multiple blocks require disambiguation.
Parentheses contain coefficient or parameter names and square brackets
contain factor or index levels. Public correlations use cor; compact scalar
rho and LKJ construction coordinates remain internal.
Random-effect terms have two distinct left-side grammars:
id(), diag(), and us() / un() use a coefficient formula. The
1, 0, and -1 terms control the random intercept; continuous slopes,
factor slopes, and interactions are supported. Plain (expr | group)
defaults to us(), and expr || group to diag().
cs() / hcs(), ar1() / ar() / har(), and car() use a
structure-owned index specification. They do not accept
random_block(contrasts = ...). cs(), hcs(), ar1(), and har()
reject explicit intercept controls; car() has no intercept, so it rejects
an explicit 1 and accepts the redundant 0 and - 1.
Random-coefficient factor coding comes from the block's resolved contrast
metadata. It reuses an already established fixed-factor contrast by default;
random_block(contrasts = ...) is the explicit per-block override. Removing
the random intercept does not by itself request one coefficient per factor
level.
The discrete index structures cs(), hcs(), ar1(), and har() accept
factor, character, numeric/integer, or logical columns. Existing factor
levels are preserved; otherwise sorted unique values define levels and
AR(1) order. CS/HCS can combine several columns with +; AR1/HAR require
exactly one. CAR requires one finite numeric/integer column, or an ordered
factor with numeric labels, and uses actual coordinate distances.
AR1/HAR warns when character or unordered-factor numeric labels resolve to
a non-increasing numeric order, such as 1, 10, 2. The order is retained;
use numeric values for numeric ordering, or an ordered factor with explicit
levels to confirm another intended order.
The random() / re() wrappers also accept hom = FALSE with
covariance = "cs" or "ar1" as aliases for "hcs" or "har",
respectively. An explicit random_covariance(structure = ...) prior must
match that resolved heterogeneous structure. Direct cs() / ar1() tags
retain their homogeneous meaning; use hcs() / har() for heterogeneous
SDs.
Random-effect predictors must be literal data-column names combined with
standard formula operators. Inline transformations and arbitrary calls are
rejected; create transformed predictors as explicit columns first. Grouping
terms support variables, : interactions, and / nesting. Grouping
interactions follow base-R/lme4 lexicographic tuple order, and the fitted
tuple-to-index map is stored for replay.
Categorical predictor and grouping levels must not contain BayesTools'
reserved internal tokens, such as __xXx__. Predictor names must not
contain the substring intercept, which is reserved for the intercept.
Only the random-effect terms of the input are returned. Other parts of the
right-hand side, such as offset() or the 0 + / - 1 intercept controls
of the fixed part (~ 0 + (1 | g) returns the term us(1 | g)), are
dropped; the fixed part belongs to the model formula passed to
JAGS_formula().