Skip to content

formula DSL

Formula DSL types.

This module contains lightweight Python types used by the public formula helpers (bf(), set_rescor(), etc.) to represent brms formula expressions in a structured way.

The main entry point for end users is the set of helpers exposed via brmspy.brms. Those helpers return FormulaConstruct instances which can be combined with + to build multivariate or compound models.

Notes
  • These objects are data containers; the execution (turning them into actual R formula objects) happens in the worker process.
  • ProxyListSexpVector values inside the tree represent R-side objects (for example brms family objects) and are only meaningful while the worker process that created them is alive.

Examples:

Compose formula parts using the public helpers:

from brmspy.brms import bf, set_rescor

f = bf("y ~ x") + bf("z ~ 1") + set_rescor(True)
print(f)

Classes

FormulaPart dataclass

A single formula helper invocation.

Instances of this type represent a call like bf("y ~ x") or set_rescor(True) without executing anything. They are primarily used as nodes inside a FormulaConstruct.

Parameters:

Name Type Description Default
_fun Literal[...]

Whitelisted formula helper name.

 required
_args Sequence[Primitive]

Positional arguments for the helper.

 required
_kwargs Mapping[str, Primitive]

Keyword arguments for the helper.

 required
Notes

This is a low-level type. Most users should construct these via the public helper functions in brmspy.brms.

Functions

__post_init__()

Validate _fun, _args, and _kwargs types after construction.

__str__()

Render a readable fun(arg1, ..., kw=...) representation.

FormulaConstruct dataclass

A composite formula expression built from parts.

FormulaConstruct stores a tree of nodes (FormulaPart and/or R objects) representing expressions combined with +. It is primarily created by calling the public formula helpers exposed by brmspy.brms.

Notes

The + operator supports grouping:

  • a + b + c becomes a single summand (one “group”)
  • (a + b) + (a + b) becomes two summands (two “groups”)

Use iter_summands() to iterate over these groups in a deterministic way.

Functions

__add__(other)

Combine two formula expressions with +.

Parameters:

Name Type Description Default
other Other

Value to add. Strings are treated as bf(<string>).

 required

Returns:

Type Description
FormulaConstruct

New combined expression.
__radd__(other)

Support "y ~ x" + bf("z ~ 1") by coercing the left operand.

iter_summands()

Iterate over arithmetic groups (summands).

Returns:

Type Description
Iterator[tuple[FormulaPart | ProxyListSexpVector, ...]]

Each yielded tuple represents one summand/group.

Examples:

from brmspy.brms import bf, gaussian, set_rescor

f = bf("y ~ x") + gaussian() + set_rescor(True)
for summand in f.iter_summands():
    print(summand)
__iter__()

Alias for iter_summands().

iterate()

Iterate over all leaf nodes in left-to-right order.

This flattens the expression tree, unlike iter_summands(), which respects grouping.

Returns:

Type Description
Iterator[FormulaPart | ProxyListSexpVector]