explore

Parsing result containers for explore formulas.

Classes:

Name	Description
`Condition`	A conditioning specification in explore formula.
`ContrastExpr`	Bracket contrast expression: `Drug[A - B, C - D]`.
`ContrastItem`	A single contrast: left operand minus right operand.
`ContrastOperand`	One side of a bracket contrast item.
`ExploreFormulaError`	Error in explore formula syntax.
`ExploreFormulaSpec`	Parsed explore formula.

Classes¶

Condition¶

A conditioning specification in explore formula.

Represents a variable to condition on, optionally with specific values, a method for generating values, or a bracket contrast expression.

Created by: parse_explore_formula(), ExploreParser Consumed by: resolve_all_conditions(), dispatch_marginal_computation() Augmented by: Never

Attributes:

Name	Type	Description
`var`	`str`	Variable name to condition on.
`at_values`	`tuple \| None`	Specific values to evaluate at (e.g., (50.0,) or (“A”, “B”)).
`at_range`	`int \| None`	Number of evenly-spaced values across the variable’s range.
`at_quantile`	`int \| None`	Number of quantile values to use.
`contrast_expr`	`ContrastExpr \| None`	Bracket contrast expression on this condition variable (e.g., from `Dose[High - Low]` on the RHS). When set, the variable is treated as a grid categorical during condition resolution, and the contrast is applied as a post-processing step.

Attributes¶

at_quantile¶

at_quantile: int | None = field(default=None, validator=is_optional_positive_int)

at_range¶

at_range: int | None = field(default=None, validator=is_optional_positive_int)

at_values¶

at_values: tuple | None = field(default=None)

contrast_expr¶

contrast_expr: ContrastExpr | None = field(default=None, validator=(validators.optional(validators.instance_of(ContrastExpr))))

var¶

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

ContrastExpr¶

Bracket contrast expression: Drug[A - B, C - D].

Represents a complete bracket contrast specification parsed from explore formula syntax.

Created by: parse_explore_formula(), ExploreParser Consumed by: dispatch_bracket_contrasts(), apply_rhs_bracket_contrast() Augmented by: Never

Attributes:

Name	Type	Description
`var`	`str`	Variable name (e.g., `"Drug"`).
`items`	`tuple[ ContrastItem , ...]`	Tuple of contrast items to compute.

Attributes¶

items¶

items: tuple[ContrastItem, ...] = field(converter=tuple, validator=(validators.deep_iterable(member_validator=(validators.instance_of(ContrastItem)))))

var¶

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

ContrastItem¶

A single contrast: left operand minus right operand.

Represents one left - right comparison in a bracket contrast expression like Drug[Active - Placebo].

Created by: parse_explore_formula(), ExploreParser Consumed by: dispatch_bracket_contrasts(), apply_rhs_bracket_contrast() Augmented by: Never

Attributes:

Name	Type	Description
`left`	`ContrastOperand`	Left operand (positive side).
`right`	`ContrastOperand`	Right operand (negative side).

Attributes¶

left¶

left: ContrastOperand = field(validator=(validators.instance_of(ContrastOperand)))

right¶

right: ContrastOperand = field(validator=(validators.instance_of(ContrastOperand)))

ContrastOperand¶

One side of a bracket contrast item.

Represents a single operand in a contrast like A - B or (A + B) - C.

Created by: parse_explore_formula(), ExploreParser Consumed by: dispatch_bracket_contrasts(), apply_rhs_bracket_contrast() Augmented by: Never

Attributes:

Name	Type	Description
`levels`	`tuple[str, ...]`	Level names for this operand. Empty tuple for wildcard. Multiple levels indicate a grouped mean (e.g., `(A + B)` produces `levels=("A", "B")`).
`is_wildcard`	`bool`	True for the `*` operator, which expands to all levels not mentioned on the other side.

Attributes¶

is_wildcard¶

is_wildcard: bool = field(default=False, validator=(validators.instance_of(bool)))

levels¶

levels: tuple[str, ...] = field(factory=tuple, converter=tuple, validator=is_tuple_of_str)

ExploreFormulaError¶

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

Bases: ValueError

Error in explore formula syntax.

Provides helpful error messages with position indicators for syntax errors.

Parameters:

Name	Type	Description	Default
`message`	`str`	Error description.	required
`formula`	`str`	The formula that caused the error.	required
`position`	`int \| None`	Character position of the error (optional).	`None`

Attributes:

Name	Type	Description
`formula`
`position`

Parameters:

Name	Type	Description	Default
`message`	`str`	Error description.	required
`formula`	`str`	The formula that caused the error.	required
`position`	`int \| None`	Character position of the error.	`None`

Attributes¶

formula¶

formula = formula

position¶

position = position

ExploreFormulaSpec¶

Parsed explore formula.

Represents a parsed explore formula with focal variable, optional contrast type, and conditioning specifications.

Created by: parse_explore_formula() Consumed by: dispatch_marginal_computation(), plot_predict(), plot_explore() Augmented by: attrs.evolve() in resolve_focal_at_spec() materializes focal at-values

Attributes:

Name	Type	Description
`focal_var`	`str`	The variable to compute marginal effects for.
`contrast_type`	`str \| None`	Type of contrast (pairwise, sequential, poly, treatment, sum, helmert, custom) or None for simple EMMs. Set to `"custom"` for bracket contrast expressions.
`contrast_degree`	`int \| None`	Degree parameter for polynomial contrasts (default None means use n_levels - 1, i.e., maximum degree).
`contrast_ref`	`str \| None`	Reference level for treatment/dummy contrasts (e.g., `"Placebo"` from `treatment(Drug, ref=Placebo)`).
`contrast_level_ordering`	`tuple[str, ...] \| None`	Explicit level ordering for order-dependent contrasts (helmert, sequential, poly). Parsed from bracket list syntax, e.g. `poly(dose, [low, med, high])`.
`contrast_expr`	`ContrastExpr \| None`	Bracket contrast expression AST (e.g., from `Drug[Active - Placebo]` syntax). None for named contrast functions or simple EMMs.
`conditions`	`tuple[ Condition , ...]`	Tuple of Condition objects specifying conditioning variables.
`focal_at_values`	`tuple[float \| str, ...] \| None`	Specific values to evaluate the focal variable at (e.g., from `Days@[0, 3, 6, 9]` syntax). None means use all levels.
`focal_at_range`	`int \| None`	Number of evenly-spaced values across the focal variable’s range (e.g., from `Days@range(5)` syntax). None means not set.
`focal_at_quantile`	`int \| None`	Number of quantile values for the focal variable (e.g., from `Days@quantile(3)` syntax). None means not set.

Attributes¶

conditions¶

conditions: tuple[Condition, ...] = field(factory=tuple, converter=tuple)

contrast_degree¶

contrast_degree: int | None = field(default=None, validator=is_optional_positive_int)

contrast_expr¶

contrast_expr: ContrastExpr | None = field(default=None)

contrast_level_ordering¶

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

contrast_ref¶

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

contrast_type¶

contrast_type: str | None = field(default=None, validator=(validators.optional(is_choice_str(('pairwise', 'sequential', 'poly', 'treatment', 'sum', 'helmert', 'custom')))))

focal_at_quantile¶

focal_at_quantile: int | None = field(default=None, validator=is_optional_positive_int)

focal_at_range¶

focal_at_range: int | None = field(default=None, validator=is_optional_positive_int)

focal_at_values¶

focal_at_values: tuple[float | str, ...] | None = field(default=None)

focal_var¶

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

has_conditions¶

has_conditions: bool

Return True if conditioning variables are specified.

has_contrast¶

has_contrast: bool

Return True if any contrast is specified (named function or bracket expr).

has_contrast_expr¶

has_contrast_expr: bool

Return True if a bracket contrast expression is specified.

has_rhs_contrasts¶

has_rhs_contrasts: bool

Return True if any RHS condition has a bracket contrast expression.

Classes¶

Condition¶

Attributes¶

at_quantile¶

at_range¶

at_values¶

contrast_expr¶

var¶

ContrastExpr¶

Attributes¶

items¶

var¶

ContrastItem¶

Attributes¶

left¶

right¶

ContrastOperand¶

Attributes¶

is_wildcard¶

levels¶

ExploreFormulaError¶

Attributes¶

formula¶

position¶

ExploreFormulaSpec¶

Attributes¶

conditions¶

contrast_degree¶

contrast_expr¶

contrast_level_ordering¶

contrast_ref¶

contrast_type¶

focal_at_quantile¶

focal_at_range¶

focal_at_values¶

focal_var¶

has_conditions¶

has_contrast¶

has_contrast_expr¶

has_rhs_contrasts¶

Functions¶