formula

Formula helpers and DSL.

This module provides a small Pythonic DSL for composing brms formulas. The public functions (bf, lf, nlf, acformula, set_rescor, set_mecor, set_nl) build a FormulaConstruct that can be passed to brmspy.brms.brm() or combined using the + operator.

Notes

• The returned objects are lightweight formula specifications; the actual R brms formula object is built in the worker when fitting / generating Stan code.
• This module is part of the public API documented under docs/api/brms_functions/formula.md.

Classes

Functions

bf(*formulas, **formula_args)

Build a brms model formula.

This is the primary entrypoint for specifying the mean model and can be combined with other formula parts (e.g. lf, nlf, acformula) using +.

Parameters:

Name	Type	Description	Default
*formulas	str	One or more brms formula strings (e.g. "y ~ x + (1|group)"). Multiple formulas are commonly used for multivariate models.	()
**formula_args		Keyword arguments forwarded to R brms::brmsformula() (for example decomp="QR", center=True, sparse=True, nl=True, loop=True).	{}

Returns:

Type	Description
FormulaConstruct	A composable formula specification.

See Also

brms::brmsformula : R documentation

Examples:

Basic formula:

from brmspy.brms import bf

f = bf("y ~ x1 + x2 + (1|group)")

QR decomposition (often helps with collinearity):

from brmspy.brms import bf

f = bf("reaction ~ days + (days|subject)", decomp="QR")

Multivariate formula + residual correlation:

from brmspy.brms import bf, set_rescor

f = bf("mvbind(y1, y2) ~ x") + set_rescor(True)

lf(*formulas, flist=None, dpar=None, resp=None, center=None, cmc=None, sparse=None, decomp=None)

Add linear formulas for distributional / non-linear parameters.

This wraps R brms::lf() and is typically used to model distributional parameters such as sigma (heteroskedasticity) or to specify predictors for non-linear parameters.

Parameters:

Name	Type	Description	Default
*formulas	str | FormulaConstruct | FormulaPart | ProxyListSexpVector	One or more formulas such as "sigma ~ x".	()
flist		Optional list of formulas (advanced; mirrors brms).	None
dpar	str or None	Distributional parameter name (e.g. "sigma", "phi").	None
resp	str or None	Response name for multivariate models.	None
center	bool | None	Forwarded to R brms::lf().	None
cmc	bool | None	Forwarded to R brms::lf().	None
sparse	bool | None	Forwarded to R brms::lf().	None
decomp	bool | None	Forwarded to R brms::lf().	None

Returns:

Type	Description
FormulaConstruct	A composable formula specification that can be combined using +.

See Also

brms::lf : R documentation

Examples:

Model mean + sigma:

from brmspy.brms import bf, lf

f = bf("y ~ x") + lf("sigma ~ x", dpar="sigma")

nlf(*formulas, flist=None, dpar=None, resp=None, loop=None)

Add non-linear formulas.

Wraps R brms::nlf(). This is used together with set_nl() and parameter definitions in lf() to specify non-linear models.

Parameters:

Name	Type	Description	Default
*formulas	str | FormulaConstruct | FormulaPart | ProxyListSexpVector	One or more non-linear formulas (e.g. "y ~ a * exp(b * x)").	()
flist		Optional list of formulas (advanced; mirrors brms).	None
dpar	str or None	Distributional parameter name (optional).	None
resp	str or None	Response name for multivariate models.	None
loop	bool or None	Forwarded to R brms::nlf(loop=...).	None

Returns:

Type	Description
FormulaConstruct	A composable formula specification.

See Also

brms::nlf : R documentation

Examples:

from brmspy.brms import bf, nlf, set_nl

f = bf("y ~ 1") + nlf("y ~ a * exp(b * x)") + set_nl()

acformula(autocor, resp=None)

Add an autocorrelation structure.

Wraps R brms::acformula().

Parameters:

Name	Type	Description	Default
autocor	str	One-sided autocorrelation formula (e.g. "~ arma(p = 1, q = 1)").	required
resp	str or None	Response name for multivariate models.	None

Returns:

Type	Description
FormulaConstruct	A composable formula specification.

See Also

brms::acformula : R documentation

Examples:

from brmspy.brms import bf, acformula

f = bf("y ~ x") + acformula("~ arma(p = 1, q = 1)")

set_rescor(rescor=True)

Control residual correlations in multivariate models.

Wraps R brms::set_rescor().

Parameters:

Name	Type	Description	Default
rescor	bool	Whether to model residual correlations.	True

Returns:

Type	Description
FormulaConstruct	A composable formula specification.

See Also

brms::set_rescor : R documentation

Examples:

from brmspy.brms import bf, set_rescor

f = bf("y1 ~ x") + bf("y2 ~ z") + set_rescor(True)

set_mecor(mecor=True)

Control correlations between latent me() terms.

Wraps R brms::set_mecor().

Parameters:

Name	Type	Description	Default
mecor	bool	Whether to model correlations between latent variables introduced by me().	True

Returns:

Type	Description
FormulaConstruct	A composable formula specification.

See Also

brms::set_mecor : R documentation

Examples:

from brmspy.brms import bf, set_mecor

f = bf("y ~ me(x, sdx)") + set_mecor(True)

set_nl(dpar=None, resp=None)

Mark a model (or part of it) as non-linear.

Wraps R brms::set_nl().

Parameters:

Name	Type	Description	Default
dpar	str or None	Distributional parameter name (if only part of the model is non-linear).	None
resp	str or None	Response name for multivariate models.	None

Returns:

Type	Description
FormulaConstruct	A composable formula specification.

See Also

brms::set_nl : R documentation

Examples:

from brmspy.brms import bf, lf, set_nl

f = bf("y ~ a * inv_logit(x * b)") + lf("a + b ~ z") + set_nl()