pymixef.formula module

Safe R-like formula parsing and deterministic design-matrix compilation.

The parser implements fixed effects, * interactions, : explicit interactions, / nesting, correlated | and independent || random blocks. Predictor expressions are interpreted by a small AST evaluator; Python eval and arbitrary attribute access are never used.

class pymixef.formula.DesignMatrices(response, fixed, fixed_names, random_blocks, row_ids, audit, spec, factor_levels=<factory>, contrast_coding=<factory>)[source]

Bases: object

Backend-neutral compiled response, fixed, and random designs.

Parameters:

  • response (NDArray[float64])

  • fixed (NDArray[float64])

  • fixed_names (tuple[str, ...])

  • random_blocks (tuple[RandomDesignBlock, ...])

  • row_ids (tuple[str, ...])

  • audit (DataAudit)

  • spec (FormulaSpec)

  • factor_levels (Mapping[str, tuple[Any, ...]])

  • contrast_coding (Mapping[str, str])

response: NDArray[float64]
fixed: NDArray[float64]
fixed_names: tuple[str, ...]
random_blocks: tuple[RandomDesignBlock, ...]
row_ids: tuple[str, ...]
audit: DataAudit
spec: FormulaSpec
factor_levels: Mapping[str, tuple[Any, ...]]
contrast_coding: Mapping[str, str]
property y: NDArray[float64]
property X: NDArray[float64]
to_backend_data()[source]

Return the shared payload consumed by numerical engines.

Return type:

dict[str, Any]

explanation()[source]

Build structured dry-run diagnostics without fitting.

Return type:

FormulaExplanation

explain()[source]

Return a human-readable dry-run report.

Return type:

str

class pymixef.formula.FormulaExplanation(formula, response, n_rows, fixed_shape, fixed_names, fixed_rank, aliased_fixed, random_blocks, excluded_rows, factor_levels, contrast_coding)[source]

Bases: object

Dry-run dimensions, equations, coding, and rank diagnostics.

Parameters:

  • formula (str)

  • response (str)

  • n_rows (int)

  • fixed_shape (tuple[int, int])

  • fixed_names (tuple[str, ...])

  • fixed_rank (int)

  • aliased_fixed (tuple[str, ...])

  • random_blocks (tuple[Mapping[str, Any], ...])

  • excluded_rows (int)

  • factor_levels (Mapping[str, tuple[Any, ...]])

  • contrast_coding (Mapping[str, str])

formula: str
response: str
n_rows: int
fixed_shape: tuple[int, int]
fixed_names: tuple[str, ...]
fixed_rank: int
aliased_fixed: tuple[str, ...]
random_blocks: tuple[Mapping[str, Any], ...]
excluded_rows: int
factor_levels: Mapping[str, tuple[Any, ...]]
contrast_coding: Mapping[str, str]
to_dict()[source]
Return type:

dict[str, Any]

class pymixef.formula.FormulaSpec(response, fixed_terms, random_terms=(), intercept=True, source=None)[source]

Bases: object

Parsed, data-independent formula semantics.

Parameters:

  • response (str)

  • fixed_terms (tuple[str, ...])

  • random_terms (tuple[RandomTerm, ...])

  • intercept (bool)

  • source (str | None)

response: str
fixed_terms: tuple[str, ...]
random_terms: tuple[RandomTerm, ...]
intercept: bool
source: str | None
property formula: str | None
to_dict()[source]
Return type:

dict[str, Any]

to_ir(*, family='gaussian')[source]

Compile data-independent semantics into the shared model IR.

Parameters:

family (str)

Return type:

ModelIR

explain()[source]

Return a deterministic, data-independent mathematical summary.

Return type:

str

class pymixef.formula.RandomDesignBlock(matrix, group_labels, group_codes, group_levels, term_names, correlated, name, expanded=False)[source]

Bases: object

Compiled row-level random design and deterministic group factorization.

Parameters:

  • matrix (NDArray[float64])

  • group_labels (tuple[Any, ...])

  • group_codes (NDArray[int64])

  • group_levels (tuple[Any, ...])

  • term_names (tuple[str, ...])

  • correlated (bool)

  • name (str)

  • expanded (bool)

matrix: NDArray[float64]
group_labels: tuple[Any, ...]
group_codes: NDArray[int64]
group_levels: tuple[Any, ...]
term_names: tuple[str, ...]
correlated: bool
name: str
expanded: bool
property Z: NDArray[float64]
property groups: tuple[Any, ...]
property group: tuple[Any, ...]
to_dict()[source]
Return type:

dict[str, Any]

class pymixef.formula.RandomTerm(terms, group, correlated=True, intercept=True, source=None)[source]

Bases: object

One resolved random-effects block.

Parameters:

  • terms (tuple[str, ...])

  • group (str)

  • correlated (bool)

  • intercept (bool)

  • source (str | None)

terms: tuple[str, ...]
group: str
correlated: bool
intercept: bool
source: str | None
property operator: str
property term_names: tuple[str, ...]
to_dict()[source]
Return type:

dict[str, Any]

pymixef.formula.compile_formula(formula, data, *, missing='drop')[source]

Compile a formula and data into deterministic numeric matrices.

Parameters:
Return type:

DesignMatrices

pymixef.formula.dry_run(formula, data, *, missing='drop')

Compile a formula and data into deterministic numeric matrices.

Parameters:
Return type:

DesignMatrices

pymixef.formula.explain_formula(formula, data=None, *, missing='drop')[source]

Explain parsed semantics, and matrix dimensions when data are supplied.

Parameters:

  • formula (str | FormulaSpec)

  • data (Any | None)

  • missing (str)

Return type:

str

pymixef.formula.model_matrix(formula, data, *, missing='drop')[source]

Return only the fixed-effect design and names.

Parameters:
Return type:

tuple[NDArray[float64], tuple[str, …]]

pymixef.formula.parse_formula(formula)[source]

Parse an R-like mixed-effects formula without touching data.

Parameters:

formula (str)

Return type:

FormulaSpec

On this page
Show Source