formula

Formula specification container for learned encoding state.

Classes:

Name	Description
`FormulaSpec`	Learned formula encoding — everything needed to replay on new data.

Classes¶

FormulaSpec¶

Learned formula encoding — everything needed to replay on new data.

This container captures the full state of formula parsing and evaluation:

Parsed AST terms from the formula string
Categorical factor levels and contrast matrices learned from training data
Stateful transform parameters (mean, std, etc.) learned from training data

Created by: parse_formula() Consumed by: build_design_matrices(), evaluate_newdata(), build_bundle_from_data() Augmented by: attrs.evolve() after build_design_matrices() adds learned contrasts/transforms

Attributes:

Name	Type	Description
`formula`	`str`	Original formula string.
`response_var`	`str \| None`	LHS variable name, or None for RHS-only formulas.
`response_transform`	`tuple[str, ...] \| None`	Transform chain applied to response, innermost first. E.g. (“rank”, “zscore”) means zscore(rank(y)). None if no transform.
`has_intercept`	`bool`	Whether the intercept is included.
`rhs_terms`	`tuple`	Parsed AST nodes for fixed-effect RHS terms.
`re_terms`	`tuple`	Random effect AST nodes (Binary with PIPE operator).
`factors`	`dict[str, tuple[str, ...]]`	Factor name to ordered level list mapping.
`contrast_matrices`	`dict[str, NDArray]`	Factor name to contrast matrix mapping.
`contrast_types`	`dict[str, str]`	Factor name to contrast type string mapping.
`transform_state`	`dict[str, dict]`	Transform key to state dict mapping.
`transforms`	`dict[str, object]`	Transform key to fitted StatefulTransform instance mapping.
`custom_contrasts`	`dict[str, NDArray]`	User-provided contrast matrices.
`uncorr_metadata`	`dict`	Metadata from
`nested_metadata`	`dict`	Metadata from / expansion.

Attributes¶

contrast_matrices¶

contrast_matrices: dict[str, NDArray] = field(factory=dict, converter=to_frozen_dict)

contrast_types¶

contrast_types: dict[str, str] = field(factory=dict, converter=to_frozen_dict)

custom_contrasts¶

custom_contrasts: dict[str, NDArray] = field(factory=dict, converter=to_frozen_dict)

factors¶

factors: dict[str, tuple[str, ...]] = field(factory=dict, converter=to_factor_dict)

formula¶

formula: str = field(validator=(validators.instance_of(str)))

has_intercept¶

has_intercept: bool = field(default=True, validator=(validators.instance_of(bool)))

has_random_effects¶

has_random_effects: bool

Whether formula contains random effect terms.

nested_metadata¶

nested_metadata: dict = field(factory=dict, converter=to_frozen_dict)

re_terms¶

re_terms: tuple = field(factory=tuple, converter=to_tuple)

response_transform¶

response_transform: tuple[str, ...] | None = field(default=None, validator=is_optional_tuple_of_str)

response_var¶

response_var: str | None = field(default=None, validator=is_optional_str)

rhs_terms¶

rhs_terms: tuple = field(factory=tuple, converter=to_tuple)

transform_state¶

transform_state: dict[str, dict] = field(factory=dict, converter=to_frozen_dict)

transforms¶

transforms: dict[str, object] = field(factory=dict, converter=to_frozen_dict)

uncorr_metadata¶

uncorr_metadata: dict = field(factory=dict, converter=to_frozen_dict)