bossanova 0.1.0.dev14__tar.gz → 0.1.0.dev15__tar.gz

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bossanova
-Version: 0.1.0.dev14
+Version: 0.1.0.dev15
 Summary: Bridging statistical cultures with some jazz
 Author: Eshin Jolly
 License-Expression: MIT

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev15}/bossanova/__init__.py

@@ -15,7 +15,9 @@ except (ImportError, AttributeError):
 
 # Configuration
 from bossanova.internal.maths.config import (  # noqa: E402
+    get_display_digits,
     get_singular_tolerance,
+    set_display_digits,
     set_singular_tolerance,
 )
 
@@ -42,11 +44,13 @@ __all__ = [
     "compare",
     "expressions",
     "get_backend",
+    "get_display_digits",
     "get_singular_tolerance",
     "load_dataset",
     "lrt",
     "model",
     "set_backend",
+    "set_display_digits",
     "set_singular_tolerance",
     "show_datasets",
     "viz",

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev15}/bossanova/internal/containers/builders/state.py

@@ -222,7 +222,8 @@ def build_mee_state(
         L_matrix: Design matrix for delta method inference (optional).
             Shape (n_estimates, n_coef). For EMMs this is X_ref.
         contrast_method: Original contrast type for multiplicity adjustment
-            ("pairwise", "revpairwise", "sequential", "poly", or None).
+            ("pairwise", "sequential", "poly", "treatment", "sum",
+            "helmert", or None).
         n_contrast_levels: Number of EMM levels before contrasting (family size).
         link: Link function name for response-scale CI back-transformation.
         L_matrix_link: Link-scale L_matrix for CI back-transformation.

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev15}/bossanova/internal/containers/structs/explore.py

@@ -4,29 +4,93 @@ from attrs import field, frozen, validators
 
 __all__ = [
     "Condition",
+    "ContrastExpr",
+    "ContrastItem",
+    "ContrastOperand",
     "ExploreFormula",
     "ExploreFormulaError",
 ]
 
 
+# =====================================================================
+# Bracket contrast expression containers
+# =====================================================================
+
+
+@frozen
+class ContrastOperand:
+    """One side of a bracket contrast item.
+
+    Represents a single operand in a contrast like ``A - B`` or
+    ``(A + B) - C``.
+
+    Attributes:
+        levels: 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: True for the ``*`` operator, which expands to all
+            levels not mentioned on the other side.
+    """
+
+    levels: tuple[str, ...] = field(factory=tuple, converter=tuple)
+    is_wildcard: bool = field(default=False, validator=validators.instance_of(bool))
+
+
+@frozen
+class ContrastItem:
+    """A single contrast: left operand minus right operand.
+
+    Represents one ``left - right`` comparison in a bracket contrast
+    expression like ``Drug[Active - Placebo]``.
+
+    Attributes:
+        left: Left operand (positive side).
+        right: Right operand (negative side).
+    """
+
+    left: ContrastOperand = field(validator=validators.instance_of(ContrastOperand))
+    right: ContrastOperand = field(validator=validators.instance_of(ContrastOperand))
+
+
+@frozen
+class ContrastExpr:
+    """Bracket contrast expression: ``Drug[A - B, C - D]``.
+
+    Represents a complete bracket contrast specification parsed from
+    explore formula syntax.
+
+    Attributes:
+        var: Variable name (e.g., ``"Drug"``).
+        items: Tuple of contrast items to compute.
+    """
+
+    var: str = field(validator=validators.instance_of(str))
+    items: tuple[ContrastItem, ...] = field(converter=tuple)
+
+
 @frozen
 class Condition:
     """A conditioning specification in explore formula.
 
-    Represents a variable to condition on, optionally with specific values
-    or a method for generating values.
+    Represents a variable to condition on, optionally with specific values,
+    a method for generating values, or a bracket contrast expression.
 
     Attributes:
         var: Variable name to condition on.
         at_values: Specific values to evaluate at (e.g., (50.0,) or ("A", "B")).
         at_range: Number of evenly-spaced values across the variable's range.
         at_quantile: Number of quantile values to use.
+        contrast_expr: 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.
     """
 
     var: str = field(validator=validators.instance_of(str))
     at_values: tuple | None = field(default=None)
     at_range: int | None = field(default=None)
     at_quantile: int | None = field(default=None)
+    contrast_expr: ContrastExpr | None = field(default=None)
 
 
 @frozen
@@ -38,10 +102,16 @@ class ExploreFormula:
 
     Attributes:
         focal_var: The variable to compute marginal effects for.
-        contrast_type: Type of contrast (pairwise, revpairwise, sequential, poly)
-            or None for simple EMMs.
+        contrast_type: Type of contrast (pairwise, sequential, poly, treatment,
+            sum, helmert, custom) or None for simple EMMs. Set to ``"custom"``
+            for bracket contrast expressions.
         contrast_degree: Degree parameter for polynomial contrasts (default None
             means use n_levels - 1, i.e., maximum degree).
+        contrast_ref: Reference level for treatment/dummy contrasts
+            (e.g., ``"Placebo"`` from ``treatment(Drug, ref=Placebo)``).
+        contrast_expr: Bracket contrast expression AST (e.g., from
+            ``Drug[Active - Placebo]`` syntax). None for named contrast
+            functions or simple EMMs.
         conditions: Tuple of Condition objects specifying conditioning variables.
         focal_at_values: Specific values to evaluate the focal variable at
             (e.g., from ``Days@[0, 3, 6, 9]`` syntax). None means use all levels.
@@ -54,6 +124,8 @@ class ExploreFormula:
     focal_var: str = field(validator=validators.instance_of(str))
     contrast_type: str | None = field(default=None)
     contrast_degree: int | None = field(default=None)
+    contrast_ref: str | None = field(default=None)
+    contrast_expr: ContrastExpr | None = field(default=None)
     conditions: tuple[Condition, ...] = field(factory=tuple, converter=tuple)
     focal_at_values: tuple[float | str, ...] | None = field(default=None)
     focal_at_range: int | None = field(default=None)
@@ -82,14 +154,24 @@ class ExploreFormula:
 
     @property
     def has_contrast(self) -> bool:
-        """Return True if a contrast function is specified."""
-        return self.contrast_type is not None
+        """Return True if any contrast is specified (named function or bracket expr)."""
+        return self.contrast_type is not None or self.contrast_expr is not None
+
+    @property
+    def has_contrast_expr(self) -> bool:
+        """Return True if a bracket contrast expression is specified."""
+        return self.contrast_expr is not None
 
     @property
     def has_conditions(self) -> bool:
         """Return True if conditioning variables are specified."""
         return len(self.conditions) > 0
 
+    @property
+    def has_rhs_contrasts(self) -> bool:
+        """Return True if any RHS condition has a bracket contrast expression."""
+        return any(c.contrast_expr is not None for c in self.conditions)
+
 
 class ExploreFormulaError(ValueError):
     """Error in explore formula syntax.

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev15}/bossanova/internal/containers/structs/state.py

@@ -219,13 +219,18 @@ class MeeState:
         explore_formula: The explore formula string that generated this result.
         focal_var: The primary variable being explored.
         type: Type of marginal effect ("means", "slopes", "contrasts").
+        weights: Averaging philosophy used: ``"equal"`` (balanced reference grid,
+            emmeans-style) or ``"observed"`` (g-computation over observed data).
         L_matrix: Design matrix for delta method inference. Shape (n_estimates, n_coef).
             For EMMs, this is X_ref; for slopes, a coefficient selector row.
         contrast_method: Original contrast type for multiplicity adjustment
-            ("pairwise", "revpairwise", "sequential", "poly", or None).
+            ("pairwise", "sequential", "poly", "treatment", "sum",
+            "helmert", or None).
         n_contrast_levels: Number of EMM levels before contrasting (family size for Tukey).
-        link: Link function name for response-scale back-transformation (set when units="data").
-        L_matrix_link: Link-scale L_matrix for CI back-transformation (set when units="data").
+        link: Link function name for response-scale back-transformation (set when units="data"
+            and weights="equal").
+        L_matrix_link: Link-scale L_matrix for CI back-transformation (set when units="data"
+            and weights="equal").
         inference_method: Inference method used (``"asymp"``, ``"boot"``,
             ``"perm"``, or ``None``). Controls which columns appear in
             the ``.effects`` DataFrame.
@@ -253,6 +258,7 @@ class MeeState:
     focal_var: str = field(validator=validators.instance_of(str))
     type: str = field(validator=validators.in_(("means", "slopes", "contrasts")))
     units: str = field(default="link", validator=validators.in_(("link", "data")))
+    weights: str = field(default="equal", validator=validators.in_(("equal", "observed")))
 
     # Design matrix for delta method inference (optional)
     # Shape: (n_estimates, n_coef). For EMMs, this is X_ref; for slopes, a selector row.
@@ -264,7 +270,17 @@ class MeeState:
     contrast_method: str | None = field(
         default=None,
         validator=validators.optional(
-            validators.in_(("pairwise", "revpairwise", "sequential", "poly"))
+            validators.in_(
+                (
+                    "pairwise",
+                    "sequential",
+                    "poly",
+                    "treatment",
+                    "sum",
+                    "helmert",
+                    "custom",
+                )
+            )
         ),
     )
     n_contrast_levels: int | None = field(default=None)

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev15}/bossanova/internal/maths/__init__.py

@@ -28,6 +28,7 @@ from bossanova.internal.maths.batching import (
     get_available_memory_gb,
 )
 from bossanova.internal.maths.config import is_singular
+from bossanova.internal.maths.rounding import round_float_columns, round_sigfigs
 from bossanova.internal.maths.inference import (
     Chi2TestResult,
     FTestResult,
@@ -240,6 +241,8 @@ __all__ = [
     "poly_numeric",
     "poly_numeric_labels",
     "qr_solve",
+    "round_float_columns",
+    "round_sigfigs",
     "sequential_contrast",
     "sequential_labels",
     "sum_contrast",

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev15}/bossanova/internal/maths/config.py

@@ -12,15 +12,71 @@ if TYPE_CHECKING:
     import numpy as np
 
 __all__ = [
+    "get_display_digits",
     "get_singular_tolerance",
     "is_singular",
+    "set_display_digits",
     "set_singular_tolerance",
 ]
 
+# Default significant figures for DataFrame display output.
+# Matches R's summary() convention of 4 significant digits.
+_DISPLAY_DIGITS: int = 4
+
 # Default singular tolerance matches lme4's default (utilities.R:924-928)
 _SINGULAR_TOLERANCE: float = 1e-4
 
 
+def get_display_digits() -> int:
+    """Get the number of significant figures for DataFrame display output.
+
+    Controls how many significant figures are shown in user-facing
+    DataFrames returned by model properties (``.params``, ``.effects``,
+    ``.diagnostics``, etc.) and ``compare()``.  Matches R's ``signif()``
+    convention.
+
+    Returns:
+        Current display digits setting (default 4).
+
+    Examples:
+        ```python
+        from bossanova import get_display_digits
+        get_display_digits()
+        # 4
+        ```
+    """
+    return _DISPLAY_DIGITS
+
+
+def set_display_digits(digits: int) -> None:
+    """Set the number of significant figures for DataFrame display output.
+
+    Controls how many significant figures are shown in user-facing
+    DataFrames returned by model properties (``.params``, ``.effects``,
+    ``.diagnostics``, etc.) and ``compare()``.  Matches R's ``signif()``
+    convention.
+
+    The ``summary()`` method has its own ``digits`` parameter and is
+    unaffected by this setting.
+
+    Args:
+        digits: Number of significant figures.  Must be >= 1.
+
+    Raises:
+        ValueError: If digits is less than 1.
+
+    Examples:
+        ```python
+        from bossanova import set_display_digits
+        set_display_digits(6)  # Show 6 significant figures
+        ```
+    """
+    global _DISPLAY_DIGITS
+    if digits < 1:
+        raise ValueError(f"digits must be >= 1, got {digits}")
+    _DISPLAY_DIGITS = digits
+
+
 def get_singular_tolerance() -> float:
     """Get the current singular tolerance for mixed models.
 

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev15}/bossanova/internal/maths/inference/contrasts.py

@@ -7,9 +7,11 @@ import numpy as np
 __all__ = [
     "build_all_pairwise_contrast",
     "build_contrast_matrix",
+    "build_helmert_contrast",
     "build_pairwise_contrast",
     "build_sequential_contrast",
     "build_sum_to_zero_contrast",
+    "build_treatment_contrast",
     "compose_contrast",
     "get_contrast_labels",
 ]
@@ -224,6 +226,98 @@ def build_sum_to_zero_contrast(n_levels: int) -> np.ndarray:
     return C
 
 
+def build_treatment_contrast(n_levels: int, ref_idx: int = 0) -> np.ndarray:
+    """Build treatment (Dunnett-style) contrasts against a reference level.
+
+    Creates n_levels - 1 contrasts, each comparing one non-reference level
+    to the specified reference level.
+
+    Args:
+        n_levels: Number of EMM levels (factor levels).
+        ref_idx: Index of the reference level (0-based).
+
+    Returns:
+        Contrast matrix of shape (n_levels - 1, n_levels).
+        Row i compares non-reference level i to the reference.
+
+    Raises:
+        ValueError: If n_levels < 1 or ref_idx out of range.
+
+    Examples:
+        >>> C = build_treatment_contrast(3, ref_idx=0)
+        >>> C
+        array([[-1.,  1.,  0.],
+               [-1.,  0.,  1.]])
+
+        >>> C = build_treatment_contrast(3, ref_idx=2)
+        >>> C
+        array([[ 1.,  0., -1.],
+               [ 0.,  1., -1.]])
+    """
+    if n_levels < 1:
+        raise ValueError(f"n_levels must be >= 1, got {n_levels}")
+    if ref_idx < 0 or ref_idx >= n_levels:
+        raise ValueError(f"ref_idx must be in [0, {n_levels - 1}], got {ref_idx}")
+
+    if n_levels == 1:
+        return np.zeros((0, 1))
+
+    C = np.zeros((n_levels - 1, n_levels))
+    row = 0
+    for i in range(n_levels):
+        if i == ref_idx:
+            continue
+        C[row, ref_idx] = -1
+        C[row, i] = 1
+        row += 1
+
+    return C
+
+
+def build_helmert_contrast(n_levels: int) -> np.ndarray:
+    """Build Helmert contrasts (each level vs mean of previous levels).
+
+    Creates n_levels - 1 contrasts where level k is compared to
+    the mean of levels 0, 1, ..., k-1. Useful for ordered factors
+    where you want to test if each successive level differs from
+    the average of all prior levels.
+
+    Args:
+        n_levels: Number of EMM levels (factor levels).
+
+    Returns:
+        Contrast matrix of shape (n_levels - 1, n_levels).
+
+    Raises:
+        ValueError: If n_levels < 1.
+
+    Examples:
+        >>> C = build_helmert_contrast(3)
+        >>> C
+        array([[-1. ,  1. ,  0. ],
+               [-0.5, -0.5,  1. ]])
+
+        >>> C = build_helmert_contrast(4)
+        >>> C
+        array([[-1.        ,  1.        ,  0.        ,  0.        ],
+               [-0.5       , -0.5       ,  1.        ,  0.        ],
+               [-0.33333333, -0.33333333, -0.33333333,  1.        ]])
+    """
+    if n_levels < 1:
+        raise ValueError(f"n_levels must be >= 1, got {n_levels}")
+
+    if n_levels == 1:
+        return np.zeros((0, 1))
+
+    C = np.zeros((n_levels - 1, n_levels))
+    for k in range(1, n_levels):
+        # Level k vs mean of levels 0..k-1
+        C[k - 1, :k] = -1.0 / k
+        C[k - 1, k] = 1.0
+
+    return C
+
+
 def build_contrast_matrix(
     contrast_type: str | dict,
     levels: list,
@@ -237,9 +331,10 @@ def build_contrast_matrix(
     Args:
         contrast_type: Type of contrast:
             - "pairwise": All pairwise comparisons (k(k-1)/2 contrasts)
-            - "revpairwise": Reversed pairwise comparisons
             - "trt.vs.ctrl" or "treatment": Compare each level to first level
             - "sequential": Successive differences (level[i+1] - level[i])
+            - "sum": Each level vs grand mean (deviation coding)
+            - "helmert": Each level vs mean of previous levels
             - dict: Custom contrasts with names as keys and weights as values
         levels: List of factor levels.
         normalize: If True, normalize custom contrasts to sum to 1/-1.
@@ -281,10 +376,6 @@ def build_contrast_matrix(
         # All pairwise comparisons: B-A, C-A, C-B, ...
         return build_all_pairwise_contrast(n_levels)
 
-    elif contrast_type == "revpairwise":
-        # Reversed pairwise: A-B, A-C, B-C, ...
-        return -build_all_pairwise_contrast(n_levels)
-
     elif contrast_type in ("trt.vs.ctrl", "treatment"):
         # Each level vs first level
         return build_pairwise_contrast(n_levels)
@@ -293,14 +384,23 @@ def build_contrast_matrix(
         # Successive differences: B-A, C-B, D-C, ...
         return build_sequential_contrast(n_levels)
 
+    elif contrast_type == "sum":
+        # Each level vs grand mean (deviation coding)
+        return build_sum_to_zero_contrast(n_levels)
+
+    elif contrast_type == "helmert":
+        # Each level vs mean of previous levels
+        return build_helmert_contrast(n_levels)
+
     else:
         raise ValueError(
             f"Unknown contrast type: {contrast_type!r}\n\n"
             "Supported types:\n"
             "  - 'pairwise': All pairwise comparisons\n"
-            "  - 'revpairwise': Reversed pairwise\n"
             "  - 'sequential': Successive differences (level[i+1] - level[i])\n"
-            "  - 'trt.vs.ctrl': Each level vs first level\n"
+            "  - 'trt.vs.ctrl' / 'treatment': Each level vs first level\n"
+            "  - 'sum': Each level vs grand mean\n"
+            "  - 'helmert': Each level vs mean of previous levels\n"
             "  - dict: Custom contrasts {name: weights}"
         )
 

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev15}/bossanova/internal/maths/inference/multiplicity.py

@@ -3,8 +3,9 @@
 Provides critical value computation for multiplicity-adjusted CIs,
 matching R's emmeans defaults:
 
-- Tukey HSD for pairwise/revpairwise contrasts (studentized range).
-- Multivariate-t (MVT) for sequential contrasts (Genz-Bretz CDF + root-finding).
+- Tukey HSD for pairwise contrasts (studentized range).
+- Multivariate-t (MVT) for sequential, treatment, sum, helmert contrasts
+  (Genz-Bretz CDF + root-finding).
 - No adjustment for polynomial contrasts.
 
 Internal exports:

bossanova-0.1.0.dev15/bossanova/internal/maths/rounding.py

@@ -0,0 +1,89 @@
+"""Significant-figures rounding for display output.
+
+Provides vectorized rounding to N significant figures, matching R's
+``signif()`` behavior. Used at the user-facing API boundary to produce
+clean DataFrame output without altering internal computation precision.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import polars as pl
+
+__all__ = [
+    "round_float_columns",
+    "round_sigfigs",
+]
+
+
+def round_sigfigs(x: np.ndarray, n: int = 4) -> np.ndarray:
+    """Round array values to *n* significant figures.
+
+    Matches R's ``signif()`` behavior: the *n* most significant digits
+    are preserved regardless of magnitude.
+
+    Args:
+        x: Input array (float64). May contain NaN or inf values.
+        n: Number of significant figures. Must be >= 1.
+
+    Returns:
+        Array of the same shape with values rounded to *n* significant
+        figures. NaN and inf values are passed through unchanged.
+
+    Examples:
+        >>> round_sigfigs(np.array([0.00012345, 3.14159, 12345.68]), n=4)
+        array([1.235e-04, 3.142e+00, 1.235e+04])
+    """
+    x = np.asarray(x, dtype=np.float64)
+    result = x.copy()
+
+    # Only round finite, non-zero values
+    mask = np.isfinite(x) & (x != 0)
+    if not mask.any():
+        return result
+
+    vals = x[mask]
+    magnitude = np.floor(np.log10(np.abs(vals)))
+    shift = 10.0 ** (magnitude - n + 1)
+    result[mask] = np.round(vals / shift) * shift
+
+    return result
+
+
+def round_float_columns(df: pl.DataFrame, digits: int = 4) -> pl.DataFrame:
+    """Round all Float64 columns to *digits* significant figures.
+
+    Non-float columns (String, Int32, Int64, etc.) are passed through
+    unchanged. Null values within float columns are preserved.
+
+    Args:
+        df: Input DataFrame.
+        digits: Number of significant figures. Must be >= 1.
+
+    Returns:
+        New DataFrame with Float64 columns rounded.
+    """
+    float_cols = [c for c in df.columns if df[c].dtype == pl.Float64]
+    if not float_cols:
+        return df
+
+    replacements = []
+    for col_name in float_cols:
+        series = df[col_name]
+        if series.null_count() == len(series):
+            # All nulls — nothing to round
+            replacements.append(series)
+            continue
+
+        arr = series.to_numpy(allow_copy=True)
+        rounded = round_sigfigs(arr, n=digits)
+
+        # Preserve nulls from the original series
+        new_series = pl.Series(col_name, rounded)
+        if series.null_count() > 0:
+            null_mask = series.is_null()
+            new_series = new_series.set(null_mask, None)
+
+        replacements.append(new_series)
+
+    return df.with_columns(replacements)

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev15}/bossanova/internal/operations/common/__init__.py

@@ -1,5 +1,13 @@
 """Common utilities shared across operations modules."""
 
+from bossanova.internal.operations.common.contrast_registry import (
+    CONTRAST_ALIASES,
+    DEGREE_FUNCTIONS,
+    ORDER_DEPENDENT,
+    REF_FUNCTIONS,
+    VALID_CONTRAST_FUNCTIONS,
+    resolve_contrast_name,
+)
 from bossanova.internal.operations.common.data_utils import filter_valid_rows
 from bossanova.internal.operations.common.factors import (
     get_factor_levels,
@@ -11,9 +19,15 @@ from bossanova.internal.operations.common.formula_utils import (
 )
 
 __all__ = [
+    "CONTRAST_ALIASES",
+    "DEGREE_FUNCTIONS",
+    "ORDER_DEPENDENT",
+    "REF_FUNCTIONS",
+    "VALID_CONTRAST_FUNCTIONS",
     "build_ablated_formula",
     "filter_valid_rows",
     "get_factor_levels",
     "infer_factor_levels_from_data",
     "remove_predictor_from_formula",
+    "resolve_contrast_name",
 ]

bossanova-0.1.0.dev15/bossanova/internal/operations/common/contrast_registry.py

@@ -0,0 +1,61 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "CONTRAST_ALIASES",
+    "DEGREE_FUNCTIONS",
+    "ORDER_DEPENDENT",
+    "REF_FUNCTIONS",
+    "VALID_CONTRAST_FUNCTIONS",
+    "resolve_contrast_name",
+]
+
+# Canonical names and their aliases.
+# Keys = alias, Values = canonical name.
+CONTRAST_ALIASES: dict[str, str] = {
+    "pairwise": "pairwise",
+    "sequential": "sequential",
+    "poly": "poly",
+    "treatment": "treatment",
+    "dummy": "treatment",
+    "sum": "sum",
+    "deviation": "sum",
+    "helmert": "helmert",
+}
+
+# All valid contrast function names (canonical + aliases)
+VALID_CONTRAST_FUNCTIONS: frozenset[str] = frozenset(CONTRAST_ALIASES.keys())
+
+# Functions that accept a ``degree`` parameter
+DEGREE_FUNCTIONS: frozenset[str] = frozenset({"poly"})
+
+# Functions that require a ``ref`` parameter
+REF_FUNCTIONS: frozenset[str] = frozenset({"treatment", "dummy"})
+
+# Order-dependent functions (level ordering matters)
+ORDER_DEPENDENT: frozenset[str] = frozenset({"sequential", "poly", "helmert"})
+
+
+def resolve_contrast_name(name: str) -> str:
+    """Resolve a contrast function name to its canonical form.
+
+    Args:
+        name: Contrast function name (may be an alias).
+
+    Returns:
+        Canonical contrast name.
+
+    Raises:
+        ValueError: If name is not a recognized contrast function.
+    """
+    canonical = CONTRAST_ALIASES.get(name)
+    if canonical is None:
+        valid = ", ".join(sorted(VALID_CONTRAST_FUNCTIONS))
+        raise ValueError(f"Unknown contrast function '{name}'. Valid options: {valid}")
+    return canonical