formula

Formula parsing, design matrix construction, and newdata evaluation.

Call chain:

model(formula, data) -> parse_formula() -> build_bundle_from_data() -> build_design_matrices()
model.predict(newdata=) -> evaluate_newdata() (applies learned encoding to new observations)

Classes:

Functions:

Modules:

Classes¶

DesignResult¶

Output of build_design_matrices(). Separates arrays from metadata.

Attributes:

Attributes¶

X¶

X: NDArray[np.float64]

X_labels¶

X_labels: tuple[str, ...]

n_obs¶

n_obs: int

Number of observations.

y¶

y: NDArray[np.float64] | None = None

y_label¶

y_label: str | None = None

FormulaError¶

FormulaError(message: str, formula: str | None = None, position: int | None = None) -> None

Bases: ValueError

Exception raised for formula parsing errors.

Provides helpful error messages with pointer to error position.

Parameters:

Attributes:

Attributes¶

formula¶

formula = formula

position¶

position = position

TermResult¶

Result of evaluating one formula term.

Attributes:

Attributes¶

columns¶

columns: NDArray[np.float64]

labels¶

labels: list[str]

state_updates¶

state_updates: dict

Functions¶

build_design_matrices¶

build_design_matrices(spec: FormulaSpec, data: pl.DataFrame) -> tuple[DesignResult, FormulaSpec]

Build X and y matrices from a parsed formula spec.

Evaluates terms, learns encoding (contrasts, transforms), and returns both the design matrices AND an updated FormulaSpec with learned state.

The returned FormulaSpec has contrast_matrices, contrast_types, and transform_state populated (they may be empty in the input spec from parse_formula if this is the first build).

Parameters:

Returns:

build_random_effects_from_spec¶

build_random_effects_from_spec(spec: FormulaSpec, data: pl.DataFrame) -> RandomEffectsInfo | None

Build random effects design matrix from FormulaSpec.

Parameters:

Returns:

expand_double_verts¶

expand_double_verts(formula: str) -> tuple[str, dict]

Expand || syntax into separate uncorrelated random effects terms.

This matches lme4’s expandDoubleVerts() function. The || syntax creates independent (uncorrelated) random effects by expanding to separate terms.

Parameters:

Returns:

Examples:

>>> expand_double_verts("y ~ x + (Days || Subject)")
('y ~ x + (1 | Subject) + (0 + Days | Subject)', {...})

>>> expand_double_verts("y ~ x + (1 + x + y || group)")
('y ~ x + (1 | group) + (0 + x | group) + (0 + y | group)', {...})

Note: The transformation rules are:

• (x || g) -> (1 | g) + (0 + x | g)

• (1 + x || g) -> (1 | g) + (0 + x | g)

• (1 + x + y || g) -> (1 | g) + (0 + x | g) + (0 + y | g)

• (0 + x || g) -> (0 + x | g) [no intercept term added]

expand_nested_syntax¶

expand_nested_syntax(formula: str) -> tuple[str, dict]

Expand nested / syntax into separate crossed random effects terms.

This matches lme4’s behavior where nested syntax (a/b) is syntactic sugar for separate terms: (1|a/b) expands to (1|a) + (1|a:b).

The : in the grouping factor creates an interaction grouping where each unique combination of levels becomes a separate group.

Parameters:

Returns:

Examples:

>>> expand_nested_syntax("y ~ x + (1|school/class)")
('y ~ x + (1|school) + (1|school:class)', {...})

>>> expand_nested_syntax("y ~ x + (1|a/b/c)")
('y ~ x + (1|a) + (1|a:b) + (1|a:b:c)', {...})

>>> expand_nested_syntax("y ~ x + (Days|Subject/Session)")
('y ~ x + (Days|Subject) + (Days|Subject:Session)', {...})

Note: The transformation rules are:

• (1|a/b) -> (1|a) + (1|a:b)

• (1|a/b/c) -> (1|a) + (1|a:b) + (1|a:b:c)

• (x|a/b) -> (x|a) + (x|a:b)

• (1 + x|a/b) -> (1 + x|a) + (1 + x|a:b)

parse_formula¶

parse_formula(formula: str, data: pl.DataFrame, *, factors: dict[str, list[str]] | None = None, custom_contrasts: dict[str, NDArray] | None = None) -> FormulaSpec

Parse formula and detect categoricals from data.

This does parsing + categorical detection but NOT matrix construction. Reuses parser/ for tokenization and AST construction.

Parameters:

Returns:

Modules¶

bundle¶

Data bundle construction from formula and DataFrame.

Orchestrates formula parsing, design matrix construction, missing value handling, weight validation, rank deficiency detection, and random effects metadata to produce a DataBundle. Extracted from model/core.py.

Functions:

Classes¶

Functions¶

build_bundle_from_data¶

build_bundle_from_data(*, spec: ModelSpec, formula: str, data: pl.DataFrame, custom_contrasts: dict[str, np.ndarray] | None, weights_col: str | None, offset_col: str | None = None, missing: str) -> tuple[DataBundle, FormulaSpec]

Build a DataBundle and learned FormulaSpec from a model spec and data.

Handles the full pipeline: formula parsing, design matrix construction, missing value handling, weight validation, offset extraction, rank deficiency detection, family-specific response validation, and random effects metadata.

Parameters:

Returns:

filter_valid_rows¶

filter_valid_rows(data: pl.DataFrame | None, valid_mask: np.ndarray | None) -> pl.DataFrame | None

Filter a DataFrame to only valid (non-NA) rows using a boolean mask.

Returns the data unchanged if no filtering is needed (data is None, mask is None, or all rows are valid).

Parameters:

Returns:

contrast_registry¶

Contrast function registry for explore formulas.

Centralizes the vocabulary of contrast function names, aliases, and parameter requirements. Used by the explore parser and contrast dispatch logic to ensure consistent naming.

Functions:

Attributes:

Attributes¶

CONTRAST_ALIASES¶

CONTRAST_ALIASES: dict[str, str] = {'pairwise': 'pairwise', 'sequential': 'sequential', 'poly': 'poly', 'treatment': 'treatment', 'dummy': 'treatment', 'sum': 'sum', 'deviation': 'sum', 'helmert': 'helmert'}

DEGREE_FUNCTIONS¶

DEGREE_FUNCTIONS: frozenset[str] = frozenset({'poly'})

MODEL_CONTRAST_FUNCTIONS¶

MODEL_CONTRAST_FUNCTIONS: frozenset[str] = frozenset({k for k, v in (CONTRAST_ALIASES.items()) if v != 'pairwise'})

OMIT_FUNCTIONS¶

OMIT_FUNCTIONS: frozenset[str] = frozenset({'sum', 'deviation'})

ORDER_DEPENDENT¶

ORDER_DEPENDENT: frozenset[str] = frozenset({'sequential', 'poly', 'helmert'})

REF_FUNCTIONS¶

REF_FUNCTIONS: frozenset[str] = frozenset({'treatment', 'dummy'})

VALID_CONTRAST_FUNCTIONS¶

VALID_CONTRAST_FUNCTIONS: frozenset[str] = frozenset(CONTRAST_ALIASES.keys())

Functions¶

resolve_contrast_name¶

resolve_contrast_name(name: str) -> str

Resolve a contrast function name to its canonical form.

Parameters:

Returns:

contrast_specs¶

Contrast specification resolution for design matrix coding.

Resolves user-facing contrast specs (strings, tuples, ndarrays) into concrete contrast matrices. This is pure validation + dispatch logic extracted from the model class.

resolve_contrast_specs: Validate and resolve contrast specifications resolve_contrast_specs: Validate and resolve contrast specifications

Functions:

Attributes¶

Functions¶

resolve_contrast_specs¶

resolve_contrast_specs(data: pl.DataFrame, contrasts: dict[str, object]) -> dict[str, NDArray[np.float64]]

Resolve user-facing contrast specs into concrete contrast matrices.

Takes the raw contrast specifications provided by the user (strings, tuples, ndarrays) and validates them against the data, returning a dict mapping column names to contrast matrices.

Parameters:

Returns:

validate_constructor_contrasts¶

validate_constructor_contrasts(contrasts: dict, data: pl.DataFrame | None) -> None

Validate the contrasts= kwarg passed to the model constructor.

Each value must be an ndarray of shape (n_levels, n_levels - 1) where n_levels is the number of unique values in the column.

Parameters:

design¶

Design matrix construction from FormulaSpec.

Classes:

Functions:

Attributes¶

Classes¶

DesignResult¶

Output of build_design_matrices(). Separates arrays from metadata.

Attributes:

Attributes¶

X¶

X: NDArray[np.float64]

X_labels¶

X_labels: tuple[str, ...]

n_obs¶

n_obs: int

Number of observations.

y¶

y: NDArray[np.float64] | None = None

y_label¶

y_label: str | None = None

Functions¶

build_design_matrices¶

build_design_matrices(spec: FormulaSpec, data: pl.DataFrame) -> tuple[DesignResult, FormulaSpec]

Build X and y matrices from a parsed formula spec.

Evaluates terms, learns encoding (contrasts, transforms), and returns both the design matrices AND an updated FormulaSpec with learned state.

The returned FormulaSpec has contrast_matrices, contrast_types, and transform_state populated (they may be empty in the input spec from parse_formula if this is the first build).

Parameters:

Returns:

encoding¶

Categorical variable encoding using Polars Enum.

Functions:

Classes¶

Functions¶

detect_categoricals¶

detect_categoricals(ast: Binary | Call | Variable | object, data: pl.DataFrame) -> dict[str, list[str]]

Detect categorical variables from a formula AST.

Walks the AST to find:

1. Explicit categorical markers: factor(x), T(x), S(x)

2. String columns referenced in the formula

For explicit markers, extracts level information if provided. For implicit string columns, infers levels from data.

Parameters:

Returns:

Examples:

>>> from parser import Scanner, Parser
>>> import polars as pl
>>> tokens = Scanner('y ~ factor(group) + age').scan()
>>> ast = Parser(tokens).parse()
>>> df = pl.DataFrame({'y': [1, 2], 'group': ['A', 'B'], 'age': [30, 40]})
>>> detect_categoricals(ast, df)
{'group': ['A', 'B']}

detect_levels¶

detect_levels(series: pl.Series) -> list[str]

Infer level ordering from a non-categorical series.

For string columns that haven’t been converted to Enum yet, infers levels by getting unique values and sorting them.

For numeric columns used with factor(), formats integer values without decimal points (e.g., 6.0 becomes “6”).

Parameters:

Returns:

Examples:

>>> import polars as pl
>>> s = pl.Series('x', ['B', 'A', 'C', 'A'])
>>> detect_levels(s)
['A', 'B', 'C']
>>> s = pl.Series('x', [6.0, 4.0, 8.0, 4.0])
>>> detect_levels(s)
['4', '6', '8']

encode_categorical¶

encode_categorical(series: pl.Series, contrast: NDArray[np.float64]) -> NDArray[np.float64]

Encode a categorical series using a contrast matrix.

Takes a Polars series (must be Enum or Categorical type) and applies contrast encoding by indexing into the contrast matrix with the integer codes.

Parameters:

Returns:

Examples:

>>> import polars as pl
>>> from coding import treatment_coding
>>> series = pl.Series('x', ['B', 'A', 'C']).cast(pl.Enum(['A', 'B', 'C']))
>>> contrast = treatment_coding(['A', 'B', 'C'])
>>> encode_categorical(series, contrast)
array([[1., 0.],
       [0., 0.],
       [0., 1.]])

ensure_enum¶

ensure_enum(data: pl.DataFrame, factors: dict[str, list[str]]) -> pl.DataFrame

Convert columns to Enum type with specified level ordering.

This function converts string/categorical columns to Polars Enum type, ensuring consistent level ordering. If a column is already an Enum with matching levels, it is left unchanged.

For numeric columns, applies the same formatting as detect_levels() to ensure consistency (e.g., 6.0 -> “6”).

Parameters:

Returns:

Examples:

>>> import polars as pl
>>> df = pl.DataFrame({'group': ['B', 'A', 'C', 'A', 'B']})
>>> df = ensure_enum(df, {'group': ['A', 'B', 'C']})
>>> df['group'].dtype
Enum(categories=['A', 'B', 'C'])

get_levels¶

get_levels(series: pl.Series) -> list[str]

Get the level ordering from an Enum or Categorical series.

Parameters:

Returns:

Examples:

>>> import polars as pl
>>> s = pl.Series('x', ['B', 'A']).cast(pl.Enum(['A', 'B', 'C']))
>>> get_levels(s)
['A', 'B', 'C']

evaluate¶

Term evaluation — AST nodes to design matrix columns.

Classes:

Functions:

Attributes¶

Classes¶

TermResult¶

Result of evaluating one formula term.

Attributes:

Attributes¶

columns¶

columns: NDArray[np.float64]

labels¶

labels: list[str]

state_updates¶

state_updates: dict

Functions¶

evaluate_call¶

evaluate_call(call: Call, data: pl.DataFrame, factors: dict[str, list[str]], contrast_matrices: dict[str, NDArray], transform_state: dict[str, dict], transforms: dict[str, object], custom_contrasts: dict[str, NDArray], intercept_absorbed: bool) -> tuple[TermResult, bool]

Evaluate a function call term.

Handles: contrast functions, transform, center/norm/zscore/scale, log/log10/sqrt.

Parameters:

Returns:

evaluate_categorical¶

evaluate_categorical(name: str, series: pl.Series, factors: dict[str, list[str]], contrast_matrices: dict[str, NDArray], custom_contrasts: dict[str, NDArray], intercept_absorbed: bool, *, spans_intercept: bool | None = None, contrast_type: str | None = None) -> TermResult

Evaluate a categorical variable with contrast encoding.

Parameters:

Returns:

evaluate_interaction¶

evaluate_interaction(term: Binary, data: pl.DataFrame, factors: dict[str, list[str]], contrast_matrices: dict[str, NDArray], transform_state: dict[str, dict], transforms: dict[str, object], custom_contrasts: dict[str, NDArray], intercept_absorbed: bool, *, is_toplevel: bool = True) -> tuple[TermResult, bool]

Evaluate an interaction term (a:b).

Parameters:

Returns:

evaluate_star¶

evaluate_star(term: Binary, data: pl.DataFrame, factors: dict[str, list[str]], contrast_matrices: dict[str, NDArray], transform_state: dict[str, dict], transforms: dict[str, object], custom_contrasts: dict[str, NDArray], intercept_absorbed: bool) -> tuple[TermResult, bool]

Evaluate a * term (main effects + interaction): a * b = a + b + a:b.

Parameters:

Returns:

evaluate_term¶

evaluate_term(term: object, data: pl.DataFrame, factors: dict[str, list[str]], contrast_matrices: dict[str, NDArray], transform_state: dict[str, dict], transforms: dict[str, object], custom_contrasts: dict[str, NDArray], intercept_absorbed: bool) -> tuple[TermResult, bool]

Evaluate a single formula term against data.

Dispatches to evaluate_variable, evaluate_call, evaluate_interaction, etc. based on AST node type.

Parameters:

Returns:

evaluate_variable¶

evaluate_variable(name: str, data: pl.DataFrame, factors: dict[str, list[str]], contrast_matrices: dict[str, NDArray], custom_contrasts: dict[str, NDArray], intercept_absorbed: bool) -> TermResult

Evaluate a simple variable reference.

Parameters:

Returns:

evaluate_contrast¶

Contrast function evaluation for formula-syntax categorical encoding.

Handles formula expressions like treatment(x, ref=B), sum(x, omit=A), helmert(x, [low, med, high]), poly(x, [lo, hi], degree=2).

Each contrast function maps to a builder from design.coding and a label generator. The function name in the formula IS the encoding scheme.

Functions:

Attributes¶

Classes¶

Functions¶

evaluate_contrast_call¶

evaluate_contrast_call(call: Call, func_name: str, data: pl.DataFrame, factors: dict[str, list[str]], contrast_matrices: dict[str, NDArray], custom_contrasts: dict[str, NDArray], intercept_absorbed: bool, *, spans_intercept: bool | None = None) -> tuple['TermResult', bool]

Evaluate a contrast encoding function call.

Dispatches to the appropriate contrast matrix builder based on the function name (treatment, sum, helmert, sequential, poly).

Parameters:

Returns:

evaluate_newdata¶

Newdata evaluation — apply learned encoding to new observations.

Functions:

Attributes¶

Classes¶

Functions¶

evaluate_newdata¶

evaluate_newdata(spec: FormulaSpec, data: pl.DataFrame, *, on_unseen_level: str = 'error') -> NDArray[np.float64]

Apply learned encoding from FormulaSpec to new data.

Pure function: reads factor levels, contrast matrices, and transform state from spec. No mutation.

Parameters:

Returns:

evaluate_transforms¶

Transform evaluation — stateful, math, and polynomial transforms.

Extracted from evaluate.py to keep file sizes manageable and provide a clean home for nested transform evaluation logic.

Functions:

Classes¶

Functions¶

evaluate_math_transform¶

evaluate_math_transform(func_name: str, arg: object, data: pl.DataFrame, factors: dict[str, list[str]], contrast_matrices: dict[str, NDArray], transform_state: dict[str, dict], transforms: dict[str, object], custom_contrasts: dict[str, NDArray]) -> TermResult

Evaluate a math transform like log(), sqrt().

Supports nested calls: log(rank(x)) evaluates rank(x) first, then applies log to the result.

Parameters:

Returns:

evaluate_stateful_transform¶

evaluate_stateful_transform(func_name: str, arg: object, data: pl.DataFrame, factors: dict[str, list[str]], contrast_matrices: dict[str, NDArray], transform_state: dict[str, dict], transforms: dict[str, object], custom_contrasts: dict[str, NDArray]) -> TermResult

Evaluate a stateful transform like center(), scale(), rank().

Supports nested calls: zscore(rank(x)) evaluates rank(x) first, then applies zscore to the result.

Parameters:

Returns:

resolve_transform_arg¶

resolve_transform_arg(arg: object, data: pl.DataFrame, factors: dict[str, list[str]], contrast_matrices: dict[str, NDArray], transform_state: dict[str, dict], transforms: dict[str, object], custom_contrasts: dict[str, NDArray]) -> tuple[NDArray[np.float64], str, dict]

Resolve a transform argument to raw data, handling nested calls.

If the argument is a simple variable, fetches it from the DataFrame. If the argument is a nested Call (e.g. rank(x) inside zscore(rank(x))), recursively evaluates the inner call first.

Parameters:

Returns:

helpers¶

Shared AST utilities for formula operations.

Functions:

Classes¶

Functions¶

contains_pipe¶

contains_pipe(node: object) -> bool

Check if an AST node contains a PIPE operator (random effect).

Parameters:

Returns:

extract_name¶

extract_name(node: object) -> str | None

Extract variable name or literal value from AST node.

Handles interaction terms (a:b) by recursively extracting names from both sides and joining with ‘:’.

Parameters:

Returns:

variable_not_found_error¶

variable_not_found_error(name: str, data_columns: list[str]) -> ValueError

Create informative error for missing variable.

Parameters:

Returns:

parse¶

R-style formula string parsing into FormulaSpec containers.

Classes:

Functions:

Attributes¶

Classes¶

FormulaError¶

FormulaError(message: str, formula: str | None = None, position: int | None = None) -> None

Bases: ValueError

Exception raised for formula parsing errors.

Provides helpful error messages with pointer to error position.

Parameters:

Attributes:

Attributes¶

formula¶

formula = formula

position¶

position = position

FormulaStructure¶

Data-free formula structure extracted from an AST.

Contains the same structural information as a full parse_formula() call but without requiring data for categorical detection. Used by build_model_spec_from_formula() to replace regex-based extraction.

Attributes:

Attributes¶

fixed_term_names¶

fixed_term_names: tuple[str, ...]

has_intercept¶

has_intercept: bool

has_random_effects¶

has_random_effects: bool

random_terms_raw¶

random_terms_raw: tuple[str, ...]

response_transform¶

response_transform: tuple[str, ...] | None

response_var¶

response_var: str | None

Functions¶

expand_double_verts¶

expand_double_verts(formula: str) -> tuple[str, dict]

Expand || syntax into separate uncorrelated random effects terms.

This matches lme4’s expandDoubleVerts() function. The || syntax creates independent (uncorrelated) random effects by expanding to separate terms.

Parameters:

Returns:

Examples:

>>> expand_double_verts("y ~ x + (Days || Subject)")
('y ~ x + (1 | Subject) + (0 + Days | Subject)', {...})

>>> expand_double_verts("y ~ x + (1 + x + y || group)")
('y ~ x + (1 | group) + (0 + x | group) + (0 + y | group)', {...})

Note: The transformation rules are:

• (x || g) -> (1 | g) + (0 + x | g)

• (1 + x || g) -> (1 | g) + (0 + x | g)

• (1 + x + y || g) -> (1 | g) + (0 + x | g) + (0 + y | g)

• (0 + x || g) -> (0 + x | g) [no intercept term added]

expand_nested_syntax¶

expand_nested_syntax(formula: str) -> tuple[str, dict]

Expand nested / syntax into separate crossed random effects terms.

This matches lme4’s behavior where nested syntax (a/b) is syntactic sugar for separate terms: (1|a/b) expands to (1|a) + (1|a:b).

The : in the grouping factor creates an interaction grouping where each unique combination of levels becomes a separate group.

Parameters:

Returns:

Examples:

>>> expand_nested_syntax("y ~ x + (1|school/class)")
('y ~ x + (1|school) + (1|school:class)', {...})

>>> expand_nested_syntax("y ~ x + (1|a/b/c)")
('y ~ x + (1|a) + (1|a:b) + (1|a:b:c)', {...})

>>> expand_nested_syntax("y ~ x + (Days|Subject/Session)")
('y ~ x + (Days|Subject) + (Days|Subject:Session)', {...})

Note: The transformation rules are:

• (1|a/b) -> (1|a) + (1|a:b)

• (1|a/b/c) -> (1|a) + (1|a:b) + (1|a:b:c)

• (x|a/b) -> (x|a) + (x|a:b)

• (1 + x|a/b) -> (1 + x|a) + (1 + x|a:b)

extract_formula_structure¶

extract_formula_structure(formula: str) -> FormulaStructure

Extract formula structure from a formula string without data.

Parses the formula into an AST and walks it to extract response variable, fixed-effect term names, intercept presence, and random-effect term strings. Does not require data (no categorical detection).

Parameters:

Returns:

parse_formula¶

parse_formula(formula: str, data: pl.DataFrame, *, factors: dict[str, list[str]] | None = None, custom_contrasts: dict[str, NDArray] | None = None) -> FormulaSpec

Parse formula and detect categoricals from data.

This does parsing + categorical detection but NOT matrix construction. Reuses parser/ for tokenization and AST construction.

Parameters:

Returns:

parser¶

Recursive descent parser for statistical formula strings.

Modules:

Classes:

Classes¶

Assign¶

Assign(name: 'Variable', value: object) -> None

Expression for assignments (e.g., x=value in function calls).

Attributes:

Attributes¶

name¶

name = name

value¶

value = value

Binary¶

Binary(left: object, operator: Token, right: object) -> None

Expression for binary operations (e.g., x + y, x ~ y).

Attributes:

Attributes¶

left¶

left = left

operator¶

operator = operator

right¶

right = right

Call¶

Call(callee: object, args: list) -> None

Expression for function calls (e.g., factor(x), center(y)).

Attributes:

Attributes¶

args¶

args = args

callee¶

callee = callee

Grouping¶

Grouping(expression: object) -> None

Expression for parenthesized groups.

Attributes:

Attributes¶

expression¶

expression = expression

ListExpr¶

ListExpr(elements: list[object]) -> None

Expression for bracket list literals (e.g., [low, med, high]).

Used for level ordering in contrast functions like helmert(x, [low, med, high]).

Attributes:

Attributes¶

elements¶

elements = elements

Literal¶

Literal(value: object, lexeme: str | None = None) -> None

Expression for literal values (numbers, strings, etc.).

Attributes:

Attributes¶

lexeme¶

lexeme = lexeme

value¶

value = value

ParseError¶

Bases: Exception

Error raised during formula parsing.

Parser¶

Parser(tokens: list[Token], formula: str = '') -> None

Parse a sequence of Tokens and return an abstract syntax tree.

Parameters:

Functions:

Attributes:

Attributes¶

current¶

current = 0

formula¶

formula = formula

tokens¶

tokens = tokens

Functions¶

addition¶

addition() -> object

advance¶

advance() -> Token | None

assignment¶

assignment() -> object

at_end¶

at_end() -> bool

call¶

call() -> object

check¶

check(types: str | list[str]) -> bool

Check if current token matches any of the given types.

comparison¶

comparison() -> object

consume¶

consume(kind: str, message: str) -> Token

Consume the next Token, raising ParseError if it doesn’t match.

Parameters:

Returns:

expression¶

expression() -> object

finish_call¶

finish_call(expr: object) -> Call

format_error_context¶

format_error_context(position: int, message: str) -> str

Format a parse error with visual pointer to the error location.

Parameters:

Returns:

interaction¶

interaction() -> object

match¶

match(types: str | list[str]) -> bool

Match and consume token if it matches any of the given types.

multiple_interaction¶

multiple_interaction() -> object

multiplication¶

multiplication() -> object

parse¶

parse() -> object

Parse a sequence of Tokens.

Returns:

peek¶

peek() -> Token

Return the Token we are about to consume.

previous¶

previous() -> Token

Return the last Token we consumed.

primary¶

primary() -> object

random_effect¶

random_effect() -> object

tilde¶

tilde() -> object

unary¶

unary() -> object

QuotedName¶

QuotedName(expression: Token) -> None

Expression for back-quoted names (e.g., weird column name!).

Attributes:

Attributes¶

expression¶

expression = expression

ScanError¶

Bases: Exception

Error raised during formula scanning.

Scanner¶

Scanner(code: str) -> None

Scan formula string and return Tokens.

Parameters:

Functions:

Attributes:

Attributes¶

code¶

code = code

current¶

current = 0

start¶

start = 0

tokens¶

tokens: list[Token] = []

Functions¶

add_token¶

add_token(kind: str, literal: object = None) -> None

advance¶

advance() -> str

at_end¶

at_end() -> bool

backquote¶

backquote() -> None

char¶

char() -> None

floatnum¶

floatnum() -> None

identifier¶

identifier() -> None

match¶

match(expected: str) -> bool

number¶

number() -> None

peek¶

peek() -> str

peek_next¶

peek_next() -> str

scan¶

scan(add_intercept: bool = True) -> list[Token]

Scan formula string.

Parameters:

Returns:

scan_token¶

scan_token() -> None

Token¶

Token(kind: str, lexeme: str, literal: object = None, position: int = 0) -> None

Representation of a single Token.

Attributes:

Attributes¶

kind¶

kind = kind

lexeme¶

lexeme = lexeme

literal¶

literal = literal

position¶

position = position

Unary¶

Unary(operator: Token, right: object) -> None

Expression for unary operations (e.g., -x, +x).

Attributes:

Attributes¶

operator¶

operator = operator

right¶

right = right

Variable¶

Variable(name: Token, level: 'Literal | None' = None) -> None

Expression for variable references.

Attributes:

Attributes¶

level¶

level = level

name¶

name = name

Modules¶

expr¶

AST expression node types for formula parsing.

Vendored from formulae library (https://github.com/bambinos/formulae).

Classes:

Classes¶

Assign¶

Assign(name: 'Variable', value: object) -> None

Expression for assignments (e.g., x=value in function calls).

Attributes:

Attributes¶

name¶

name = name

value¶

value = value

Binary¶

Binary(left: object, operator: Token, right: object) -> None

Expression for binary operations (e.g., x + y, x ~ y).

Attributes:

Attributes¶

left¶

left = left

operator¶

operator = operator

right¶

right = right

Call¶

Call(callee: object, args: list) -> None

Expression for function calls (e.g., factor(x), center(y)).

Attributes:

Attributes¶

args¶

args = args

callee¶

callee = callee

Grouping¶

Grouping(expression: object) -> None

Expression for parenthesized groups.

Attributes:

Attributes¶

expression¶

expression = expression

ListExpr¶

ListExpr(elements: list[object]) -> None

Expression for bracket list literals (e.g., [low, med, high]).

Used for level ordering in contrast functions like helmert(x, [low, med, high]).

Attributes:

Attributes¶

elements¶

elements = elements

Literal¶

Literal(value: object, lexeme: str | None = None) -> None

Expression for literal values (numbers, strings, etc.).

Attributes:

Attributes¶

lexeme¶

lexeme = lexeme

value¶

value = value

QuotedName¶

QuotedName(expression: Token) -> None

Expression for back-quoted names (e.g., weird column name!).

Attributes:

Attributes¶

expression¶

expression = expression

Unary¶

Unary(operator: Token, right: object) -> None

Expression for unary operations (e.g., -x, +x).

Attributes:

Attributes¶

operator¶

operator = operator

right¶

right = right

Variable¶

Variable(name: Token, level: 'Literal | None' = None) -> None

Expression for variable references.

Attributes:

Attributes¶

level¶

level = level

name¶

name = name

parser¶

Recursive descent parser for formula strings.

Vendored from formulae library (https://github.com/bambinos/formulae).

Classes:

Functions:

Classes¶

ParseError¶

Bases: Exception

Error raised during formula parsing.

Parser¶

Parser(tokens: list[Token], formula: str = '') -> None

Parse a sequence of Tokens and return an abstract syntax tree.

Parameters:

Functions:

Attributes:

Attributes¶

current¶

current = 0

formula¶

formula = formula

tokens¶

tokens = tokens

Functions¶

addition¶

addition() -> object

advance¶

advance() -> Token | None

assignment¶

assignment() -> object

at_end¶

at_end() -> bool

call¶

call() -> object

check¶

check(types: str | list[str]) -> bool

Check if current token matches any of the given types.

comparison¶

comparison() -> object

consume¶

consume(kind: str, message: str) -> Token

Consume the next Token, raising ParseError if it doesn’t match.

Parameters:

Returns:

expression¶

expression() -> object

finish_call¶

finish_call(expr: object) -> Call

format_error_context¶

format_error_context(position: int, message: str) -> str

Format a parse error with visual pointer to the error location.

Parameters:

Returns:

interaction¶

interaction() -> object

match¶

match(types: str | list[str]) -> bool

Match and consume token if it matches any of the given types.

multiple_interaction¶

multiple_interaction() -> object

multiplication¶

multiplication() -> object

parse¶

parse() -> object

Parse a sequence of Tokens.

Returns:

peek¶

peek() -> Token

Return the Token we are about to consume.

previous¶

previous() -> Token

Return the last Token we consumed.

primary¶

primary() -> object

random_effect¶

random_effect() -> object

tilde¶

tilde() -> object

unary¶

unary() -> object

Functions¶

listify¶

listify(obj: str | list[str] | None) -> list[str]

Wrap non-list objects in a list.

scanner¶

Formula string scanner/tokenizer.

Vendored from formulae library (https://github.com/bambinos/formulae).

Classes:

Functions:

Classes¶

ScanError¶

Bases: Exception

Error raised during formula scanning.

Scanner¶

Scanner(code: str) -> None

Scan formula string and return Tokens.

Parameters:

Functions:

Attributes:

Attributes¶

code¶

code = code

current¶

current = 0

start¶

start = 0

tokens¶

tokens: list[Token] = []

Functions¶

add_token¶

add_token(kind: str, literal: object = None) -> None

advance¶

advance() -> str

at_end¶

at_end() -> bool

backquote¶

backquote() -> None

char¶

char() -> None

floatnum¶

floatnum() -> None

identifier¶

identifier() -> None

match¶

match(expected: str) -> bool

number¶

number() -> None

peek¶

peek() -> str

peek_next¶

peek_next() -> str

scan¶

scan(add_intercept: bool = True) -> list[Token]

Scan formula string.

Parameters:

Returns:

scan_token¶

scan_token() -> None

Functions¶

format_error_context¶

format_error_context(formula: str, position: int, message: str) -> str

Format a scan error with visual pointer to the error location.

Parameters:

Returns:

token¶

Token class for formula parsing.

Vendored from formulae library (https://github.com/bambinos/formulae).

Classes:

Classes¶

Token¶

Token(kind: str, lexeme: str, literal: object = None, position: int = 0) -> None

Representation of a single Token.

Attributes:

Attributes¶

kind¶

kind = kind

lexeme¶

lexeme = lexeme

literal¶

literal = literal

position¶

position = position

random_effects¶

Random effects Z matrix construction from FormulaSpec.

Functions:

Classes¶

Functions¶

build_random_effects_from_spec¶

build_random_effects_from_spec(spec: FormulaSpec, data: pl.DataFrame) -> RandomEffectsInfo | None

Build random effects design matrix from FormulaSpec.

Parameters:

Returns: