factrix 0.8.0__py3-none-any.whl

factrix/__init__.py

@@ -0,0 +1,122 @@
+"""factrix — Single-factor evaluation toolkit (v0.5).
+
+Three orthogonal user-facing axes — ``FactorScope``, ``Signal``,
+``Metric`` — plus an evaluate-time-derived ``Mode`` define the analysis
+cell. Construct a config via the four type-safe factories on
+``AnalysisConfig``, dispatch via ``evaluate()``, inspect via the
+returned ``FactorProfile``, and aggregate across factors with
+``multi_factor.bhy`` for FDR-corrected screening.
+
+Single-factor::
+
+    import factrix as fl
+
+    cfg = fl.AnalysisConfig.individual_continuous(metric=fl.Metric.IC)
+    profile = fl.evaluate(panel, cfg)
+    print(profile.verdict(), profile.primary_p)
+    print(profile.diagnose())
+
+Batch + BHY::
+
+    profiles = [fl.evaluate(panel, cfg) for cfg in candidate_configs]
+    survivors = fl.multi_factor.bhy(profiles, threshold=0.05)
+
+Schema reflection::
+
+    print(fl.describe_analysis_modes())
+    print(fl.suggest_config(panel))
+
+LLM agent reference: ``llms-full.txt`` covers concepts, public API, and
+typical usage patterns in a single fetch. Two access paths::
+
+    # Web — deployed at the docs site root
+    https://awwesomeman.github.io/factrix/llms-full.txt
+
+    # Local — shipped inside the wheel as package data
+    import importlib.resources
+    text = importlib.resources.files("factrix").joinpath("llms-full.txt").read_text()
+"""
+
+from factrix import datasets, multi_factor
+from factrix._analysis_config import AnalysisConfig
+from factrix._axis import (  # noqa: F401  Mode re-exported for namespace access; intentionally not in __all__
+    FactorScope,
+    Metric,
+    Mode,
+    Signal,
+)
+from factrix._codes import InfoCode, StatCode, Verdict, WarningCode
+from factrix._describe import (
+    SuggestConfigResult,
+    describe_analysis_modes,
+    list_metrics,
+    suggest_config,
+)
+from factrix._errors import (
+    ConfigError,
+    FactrixError,
+    IncompatibleAxisError,
+    InsufficientSampleError,
+    MissingConfigError,
+    ModeAxisError,
+)
+from factrix._evaluate import _evaluate as _evaluate
+from factrix._profile import FactorProfile
+from factrix._types import MetricOutput
+
+
+def evaluate(raw, config=None, /):
+    """Dispatch ``raw`` through the cell selected by ``config``.
+
+    Thin public wrapper around the private ``_evaluate`` dispatcher.
+    Intercepts the common onboarding miss — ``evaluate(panel)`` — with
+    a friendly :class:`MissingConfigError` pointing at
+    :func:`suggest_config` and the Get Started guide.
+    """
+    if config is None:
+        raise MissingConfigError(
+            "evaluate() requires an AnalysisConfig. "
+            "Call factrix.suggest_config(raw) for a recommendation, "
+            "or see the Get Started guide: "
+            "https://awwesomeman.github.io/factrix/getting-started/"
+        )
+    return _evaluate(raw, config)
+
+
+__version__ = "0.8.0"
+
+__all__ = [
+    # Configuration
+    "AnalysisConfig",
+    # Axis enums (Mode intentionally NOT exported — it is derived at
+    # evaluate-time from N and read off profile.mode, never set by user
+    # code; review fix UX-7. Still importable from factrix._axis.)
+    "FactorScope",
+    "Metric",
+    "Signal",
+    # Code enums
+    "InfoCode",
+    "StatCode",
+    "Verdict",
+    "WarningCode",
+    # Errors
+    "ConfigError",
+    "FactrixError",
+    "IncompatibleAxisError",
+    "InsufficientSampleError",
+    "MissingConfigError",
+    "ModeAxisError",
+    # Profile + dispatch
+    "FactorProfile",
+    "MetricOutput",
+    "evaluate",
+    # Introspection
+    "SuggestConfigResult",
+    "describe_analysis_modes",
+    "list_metrics",
+    "suggest_config",
+    # Multi-factor namespace
+    "multi_factor",
+    # Synthetic panels
+    "datasets",
+]

factrix/_analysis_config.py

@@ -0,0 +1,235 @@
+"""v0.5 ``AnalysisConfig`` — three-axis orthogonal factor analysis spec (§4).
+
+The user-facing surface is the four factory methods + ``from_dict`` /
+``to_dict``; ``__post_init__`` is the single source of truth for axis
+validation, reachable from every path that produces an ``AnalysisConfig``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Self
+
+from factrix._axis import FactorScope, Metric, Mode, Signal
+from factrix._errors import IncompatibleAxisError
+from factrix._registry import matches_user_axis
+
+# Nearest-legal cell suggested when an evaluate-time mode/sample check
+# fails (§4.5 A4). Keyed by ``(scope, signal, mode)``; values are
+# zero-arg factories so cycles via ``AnalysisConfig`` resolve lazily
+# (factory call sites need ``AnalysisConfig`` defined; lazy lambdas
+# defer the lookup until raise time, after class definition).
+#
+# Intentionally narrow — every other legal user triple has a registered
+# PANEL *and* TIMESERIES procedure, so ``_evaluate`` never reaches the
+# fallback path for them. Only ``(INDIVIDUAL, CONTINUOUS, *)`` lacks a
+# TIMESERIES cell (no cross-sectional dispersion at N=1 → IC and per-date
+# OLS undefined, §5.5). Adding a TIMESERIES-less cell → add one entry; do
+# not encode the suggestion at the ``raise`` site.
+_FALLBACK_MAP: dict[
+    tuple[FactorScope, Signal, Mode],
+    Callable[[], AnalysisConfig],
+] = {
+    (
+        FactorScope.INDIVIDUAL,
+        Signal.CONTINUOUS,
+        Mode.TIMESERIES,
+    ): lambda: AnalysisConfig.common_continuous(),
+}
+
+
+def _validate_axis_compat(
+    scope: FactorScope,
+    signal: Signal,
+    metric: Metric | None,
+) -> None:
+    """Raise ``IncompatibleAxisError`` if the triple is not a legal cell.
+
+    Reverse-queries the registry SSOT (§4.4 A1) — any registered
+    ``_DispatchKey`` whose ``(signal, metric)`` matches and whose scope
+    either equals ``scope`` or is the collapse sentinel admits the
+    triple. Called from ``AnalysisConfig.__post_init__`` so every
+    construction path (factory, direct, ``from_dict``) hits one gate.
+    """
+    if matches_user_axis(scope, signal, metric):
+        return
+    metric_repr = metric.value if metric is not None else None
+    # UX-8 from review: lead with the actionable factory list, leave the
+    # tuple enumeration as a parenthetical for users debugging by hand.
+    raise IncompatibleAxisError(
+        f"({scope.value}, {signal.value}, {metric_repr}) is not a legal "
+        "analysis cell. Use one of the four factory methods:\n"
+        "  AnalysisConfig.individual_continuous(metric=Metric.IC|Metric.FM)\n"
+        "  AnalysisConfig.individual_sparse()\n"
+        "  AnalysisConfig.common_continuous()\n"
+        "  AnalysisConfig.common_sparse()\n"
+        "(legal tuples: (individual, continuous, ic), "
+        "(individual, continuous, fm), (individual, sparse, None), "
+        "(common, continuous, None), (common, sparse, None).)"
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class AnalysisConfig:
+    """Three-axis spec for a single-factor analysis.
+
+    Construct via the four factory methods (the supported public API);
+    direct construction works but bypasses no validation — every path
+    runs through ``__post_init__``.
+
+    Attributes:
+        scope: Factor scope axis. ``INDIVIDUAL`` = per-asset factor;
+            ``COMMON`` = single broadcast value per date.
+        signal: Signal type axis. ``CONTINUOUS`` = real-valued;
+            ``SPARSE`` = ``{-1, 0, +1}`` trigger.
+        metric: Procedure metric axis. Only populated for
+            ``(INDIVIDUAL, CONTINUOUS, *)`` cells (``IC`` or ``FM``);
+            ``None`` elsewhere.
+        forward_periods: Forward-return horizon in **rows** of the
+            panel's time axis, not calendar time. factrix never
+            inspects ``date`` dtype or spacing; the caller owns
+            frequency and regular spacing. ``forward_periods=5``
+            therefore means 5 trading days on a daily panel, 5 weeks
+            on a weekly panel, 5 minutes on a 1-min bar panel.
+    """
+
+    scope: FactorScope
+    signal: Signal
+    metric: Metric | None
+    forward_periods: int = 5
+
+    def __post_init__(self) -> None:
+        _validate_axis_compat(self.scope, self.signal, self.metric)
+
+    @classmethod
+    def individual_continuous(
+        cls,
+        *,
+        metric: Metric = Metric.IC,
+        forward_periods: int = 5,
+    ) -> Self:
+        """Per-(date, asset) continuous factor.
+
+        Args:
+            metric: ``IC`` for rank predictive ordering; ``FM`` for
+                unit-of-exposure premium (Fama-MacBeth λ).
+            forward_periods: Forward-return horizon (rows of the time
+                axis).
+
+        Returns:
+            A validated ``AnalysisConfig`` for the
+            ``(INDIVIDUAL, CONTINUOUS, metric)`` cell.
+        """
+        return cls(
+            FactorScope.INDIVIDUAL,
+            Signal.CONTINUOUS,
+            metric,
+            forward_periods=forward_periods,
+        )
+
+    @classmethod
+    def individual_sparse(cls, *, forward_periods: int = 5) -> Self:
+        """Per-(date, asset) sparse trigger (``{-1, 0, +1}``).
+
+        PANEL canonical procedure is the CAAR cross-event t-test;
+        TIMESERIES (N=1) collapses to a dummy regression with NW HAC
+        SE.
+
+        Args:
+            forward_periods: Forward-return horizon (rows of the time
+                axis).
+
+        Returns:
+            A validated ``AnalysisConfig`` for the
+            ``(INDIVIDUAL, SPARSE, None)`` cell.
+        """
+        return cls(
+            FactorScope.INDIVIDUAL,
+            Signal.SPARSE,
+            None,
+            forward_periods=forward_periods,
+        )
+
+    @classmethod
+    def common_continuous(cls, *, forward_periods: int = 5) -> Self:
+        """Broadcast continuous factor (e.g. VIX).
+
+        Canonical procedure is the per-asset β estimate followed by a
+        cross-asset t-test on ``E[β]``.
+
+        Args:
+            forward_periods: Forward-return horizon (rows of the time
+                axis).
+
+        Returns:
+            A validated ``AnalysisConfig`` for the
+            ``(COMMON, CONTINUOUS, None)`` cell.
+        """
+        return cls(
+            FactorScope.COMMON,
+            Signal.CONTINUOUS,
+            None,
+            forward_periods=forward_periods,
+        )
+
+    @classmethod
+    def common_sparse(cls, *, forward_periods: int = 5) -> Self:
+        """Broadcast sparse trigger (FOMC, policy, index rebalance).
+
+        PANEL canonical: per-asset β on dummy + cross-asset t-test.
+        TIMESERIES (N=1): TS dummy regression + NW HAC SE.
+
+        Args:
+            forward_periods: Forward-return horizon (rows of the time
+                axis).
+
+        Returns:
+            A validated ``AnalysisConfig`` for the
+            ``(COMMON, SPARSE, None)`` cell.
+        """
+        return cls(
+            FactorScope.COMMON,
+            Signal.SPARSE,
+            None,
+            forward_periods=forward_periods,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise to a JSON-compatible dict.
+
+        Returns:
+            A dict with string-valued enums and integer
+            ``forward_periods``, suitable for JSON serialisation.
+        """
+        return {
+            "scope": self.scope.value,
+            "signal": self.signal.value,
+            "metric": self.metric.value if self.metric is not None else None,
+            "forward_periods": self.forward_periods,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Self:
+        """Reconstruct from ``to_dict``'s output.
+
+        Goes through ``__post_init__``, so an invalid triple raises
+        ``IncompatibleAxisError`` instead of silently constructing.
+
+        Args:
+            d: Mapping in the shape produced by ``to_dict``.
+
+        Returns:
+            A validated ``AnalysisConfig``.
+
+        Raises:
+            IncompatibleAxisError: If the ``(scope, signal, metric)``
+                triple is not a legal cell.
+        """
+        m = d.get("metric")
+        return cls(
+            scope=FactorScope(d["scope"]),
+            signal=Signal(d["signal"]),
+            metric=Metric(m) if m is not None else None,
+            forward_periods=d.get("forward_periods", 5),
+        )

factrix/_axis.py

@@ -0,0 +1,57 @@
+"""v0.5 analysis-axis enums (§4.1 of refactor_api.md).
+
+Three orthogonal user-facing axes describe an analysis cell:
+
+- ``FactorScope``  — does the factor vary per-asset (``INDIVIDUAL``) or
+  carry a single value broadcast to every asset (``COMMON``)?
+- ``Signal``       — continuous numeric exposure (``CONTINUOUS``) vs.
+  ``{0, R}`` event triggers (``SPARSE`` — zero on non-event entries,
+  arbitrary real magnitude otherwise; canonical example ``{-1, 0, +1}``)?
+- ``Metric``       — procedure-canonical scalar (``IC`` or ``FM``).
+  Only meaningful for ``INDIVIDUAL × CONTINUOUS``; ``None`` for the
+  remaining cells.
+
+``Mode`` is the fourth axis used by registry keys / dispatch but is not
+user-set: it is derived from ``N`` at evaluate-time and surfaced as
+``Profile.mode`` for downstream pattern-match.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class FactorScope(StrEnum):
+    """Does each asset have its own factor value, or do all share one?"""
+
+    INDIVIDUAL = "individual"
+    COMMON = "common"
+
+
+class Signal(StrEnum):
+    """Continuous numeric exposure vs. ``{0, R}`` sparse event trigger.
+
+    Sparse columns are zero on non-event entries with arbitrary real
+    magnitude otherwise (canonical example ``{-1, 0, +1}``).
+    """
+
+    CONTINUOUS = "continuous"
+    SPARSE = "sparse"
+
+
+class Metric(StrEnum):
+    """Procedure-canonical scalar for ``INDIVIDUAL × CONTINUOUS`` cells."""
+
+    IC = "ic"
+    FM = "fm"
+
+
+class Mode(StrEnum):
+    """Sample regime, derived from ``N`` at evaluate-time.
+
+    ``PANEL``      — ``N >= 2`` (multi-asset / multi-event panel).
+    ``TIMESERIES`` — ``N == 1`` (single-asset time series).
+    """
+
+    PANEL = "panel"
+    TIMESERIES = "timeseries"

factrix/_codes.py

@@ -0,0 +1,194 @@
+"""v0.5 enum codes for warnings, info notes, cell stats, and verdicts.
+
+``WarningCode`` / ``InfoCode`` / ``StatCode`` follow the ``*Code`` suffix
+invariant (§7.5).
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class WarningCode(StrEnum):
+    """Procedure-degradation flags (replaces v3 ``DegradedMode``).
+
+    Each value carries a one-line ``description`` gloss for
+    ``profile.diagnose()`` consumers (review fix UX-4) — pure metadata,
+    StrEnum value identity is unchanged.
+    """
+
+    UNRELIABLE_SE_SHORT_PERIODS = "unreliable_se_short_periods"
+    EVENT_WINDOW_OVERLAP = "event_window_overlap"
+    # Fired when ADF p > 0.1 on a CONTINUOUS factor (Stambaugh-style
+    # persistent-regressor flag, §5.2 / §7.3). Not raised for SPARSE.
+    PERSISTENT_REGRESSOR = "persistent_regressor"
+    SERIAL_CORRELATION_DETECTED = "serial_correlation_detected"
+    # Two-tier cross-asset N guards for PANEL common_continuous. Mirrors
+    # the n_periods two-tier (UNRELIABLE_SE_SHORT_PERIODS) but the axis
+    # never raises — cross-asset t-test on E[β] is well-defined for N≥2.
+    SMALL_CROSS_SECTION_N = "small_cross_section_n"
+    BORDERLINE_CROSS_SECTION_N = "borderline_cross_section_n"
+    # Fired by the (COMMON, SPARSE, PANEL) procedure when the broadcast
+    # dummy carries MIN_BROADCAST_EVENTS_HARD ≤ n_events <
+    # MIN_BROADCAST_EVENTS_WARN. Per-asset β is identifiable but
+    # the cross-event averaging is too thin for asymptotic t to be
+    # trusted. Below the HARD floor raises InsufficientSampleError instead.
+    SPARSE_COMMON_FEW_EVENTS = "sparse_common_few_events"
+    # Fired when a sparse ``factor`` column carries mixed signs but is
+    # not a clean ±1 ternary (e.g. ``{-2.5, 0, +1.3}``). The CAAR /
+    # sparse-panel statistic is the magnitude-weighted Sefcik-Thompson
+    # (1986) variant, which differs from the textbook MacKinlay (1997)
+    # signed CAAR at finite samples when negative- and positive-leg
+    # vols disagree. ``{-1, 0, +1}`` does not trigger — sign and weight
+    # semantics coincide numerically. All-non-negative columns
+    # (``{0, 1}`` / ``{0, R≥0}``) do not trigger — no flip ambiguity.
+    SPARSE_MAGNITUDE_WEIGHTED = "sparse_magnitude_weighted"
+    # Fired by ``caar`` (significance test) when the per-event-date series
+    # length sits in ``[MIN_EVENTS_HARD, MIN_EVENTS_WARN)`` — the t-stat
+    # is returned but the Brown-Warner (1985) convention treats sub-30
+    # event-date counts as power-thin for the asymptotic t-distribution.
+    # Below the HARD floor the primitive short-circuits to NaN instead.
+    FEW_EVENTS_BROWN_WARNER = "few_events_brown_warner"
+    # Fired by ``top_concentration`` when the per-date ratio series sits
+    # in ``[MIN_PORTFOLIO_PERIODS_HARD, MIN_PORTFOLIO_PERIODS_WARN)`` —
+    # the one-sided t-test on the diversification ratio is returned but
+    # ``df = n - 1 < 19`` inflates t_crit relative to the asymptotic
+    # cutoff. Below the HARD floor the primitive short-circuits to NaN.
+    BORDERLINE_PORTFOLIO_PERIODS = "borderline_portfolio_periods"
+
+    @property
+    def description(self) -> str:
+        return _WARNING_DESCRIPTIONS[self]
+
+
+_WARNING_DESCRIPTIONS: dict[WarningCode, str] = {}
+
+
+_WARNING_DESCRIPTIONS.update(
+    {
+        WarningCode.UNRELIABLE_SE_SHORT_PERIODS: "n_periods is below the WARN floor (~30); NW HAC SE may be biased. "
+        "Reused across panel time-series guards (MIN_PERIODS_WARN) and "
+        "primitive inference (MIN_FM_PERIODS_WARN); both default to 30.",
+        WarningCode.EVENT_WINDOW_OVERLAP: "Adjacent events sit within forward_periods; AR windows overlap.",
+        WarningCode.PERSISTENT_REGRESSOR: "ADF p > 0.10 on the continuous factor; β may carry Stambaugh bias.",
+        WarningCode.SERIAL_CORRELATION_DETECTED: "Ljung-Box p < 0.05 on residuals; NW lag may be under-set.",
+        WarningCode.SMALL_CROSS_SECTION_N: "PANEL cross-asset t-test with n_assets < MIN_ASSETS (10); "
+        "df=n_assets-1 too low — t_crit at n_assets=3 ≈ 4.30 "
+        "(+119% vs asymptotic 1.96).",
+        WarningCode.BORDERLINE_CROSS_SECTION_N: "PANEL cross-asset t-test with MIN_ASSETS ≤ n_assets < "
+        "MIN_ASSETS_WARN (10..29); residual t_crit inflation "
+        "5–15% — read borderline p-values cautiously.",
+        WarningCode.SPARSE_COMMON_FEW_EVENTS: "(COMMON, SPARSE, PANEL) broadcast dummy has "
+        "MIN_BROADCAST_EVENTS_HARD ≤ n_events < MIN_BROADCAST_EVENTS_WARN "
+        "(5..19); per-asset β estimable but cross-event averaging too thin "
+        "for asymptotic t.",
+        WarningCode.SPARSE_MAGNITUDE_WEIGHTED: "Sparse factor column is mixed-sign and not a "
+        "clean ±1 ternary; statistic is magnitude-weighted (Sefcik-Thompson) "
+        "rather than textbook MacKinlay signed CAAR — apply .sign() before "
+        "calling for sign-flip semantics.",
+        WarningCode.FEW_EVENTS_BROWN_WARNER: "CAAR significance test with MIN_EVENTS_HARD ≤ "
+        "n_event_dates < MIN_EVENTS_WARN (4..29); t-stat returned but "
+        "Brown-Warner (1985) convention treats sub-30 events as power-thin "
+        "for the asymptotic t-distribution — read borderline p-values cautiously.",
+        WarningCode.BORDERLINE_PORTFOLIO_PERIODS: "top_concentration with MIN_PORTFOLIO_PERIODS_HARD "
+        "≤ n_periods < MIN_PORTFOLIO_PERIODS_WARN (3..19); one-sided t-test "
+        "on the per-date diversification ratio is returned but df=n-1 inflates "
+        "t_crit relative to the asymptotic cutoff.",
+    }
+)
+
+
+def cross_section_tier(n_assets: int) -> WarningCode | None:
+    """Map an inference-stage cross-asset N to the appropriate warning code.
+
+    The argument is the **inference-stage** N — the count of assets
+    actually entering the cross-asset test, not the panel-union
+    ``FactorProfile.n_assets`` surface field. For ``(COMMON, *, None,
+    PANEL)`` cells the two differ: ``compute_ts_betas`` drops assets
+    with fewer than ``MIN_TS_OBS`` non-null observations, so the union
+    can be materially larger than the post-filter count that drives
+    ``primary_p``'s ``dof = N - 1``. Callers (``suggest_config``,
+    ``_compute_common_panel``) therefore pre-filter before calling.
+
+    Tiers are mutually exclusive — SMALL is strictly more severe than
+    BORDERLINE — so callers can membership-check the more severe code
+    without an else branch. Returns ``None`` at ``n_assets ≥
+    MIN_ASSETS_WARN`` (clean) or ``n_assets < 2`` (PANEL impossible
+    by upstream mode routing; defensive).
+    """
+    from factrix._stats.constants import MIN_ASSETS, MIN_ASSETS_WARN
+
+    if 2 <= n_assets < MIN_ASSETS:
+        return WarningCode.SMALL_CROSS_SECTION_N
+    if MIN_ASSETS <= n_assets < MIN_ASSETS_WARN:
+        return WarningCode.BORDERLINE_CROSS_SECTION_N
+    return None
+
+
+class InfoCode(StrEnum):
+    """Neutral facts surfaced to the caller — not warnings, not errors."""
+
+    SCOPE_AXIS_COLLAPSED = "scope_axis_collapsed"
+
+    @property
+    def description(self) -> str:
+        return _INFO_DESCRIPTIONS[self]
+
+
+_INFO_DESCRIPTIONS: dict[InfoCode, str] = {
+    InfoCode.SCOPE_AXIS_COLLAPSED: "N=1 collapsed scope axis; routed via _SCOPE_COLLAPSED sentinel.",
+}
+
+
+class StatCode(StrEnum):
+    """Cell-specific scalar stats keyed in ``FactorProfile.stats``.
+
+    Adding a new metric → add an enum value here + populate it in the
+    procedure. Profile schema does not grow. Stats fall in three
+    families:
+
+    - **p-values**: identifier ends in ``_p`` (``IC_P`` / ``FM_LAMBDA_P``
+      / ``TS_BETA_P`` / ``CAAR_P`` plus the diagnostic-only
+      ``FACTOR_ADF_P`` / ``LJUNG_BOX_P``). ``is_p_value`` returns
+      ``True``. These are the only codes ``multi_factor.bhy`` will
+      accept as a ``gate=`` override (BHY step-up requires probabilities
+      — feeding it t-stats yields nonsense FDR control).
+    - **t-stats** / effect-size means / lag counts / HHI: ``is_p_value``
+      returns ``False``. ``profile.verdict(gate=...)`` accepts these
+      (the comparison is generic ``value < threshold`` — interpretation
+      is the caller's call) but ``bhy(gate=...)`` rejects them.
+    """
+
+    IC_MEAN = "ic_mean"
+    IC_T_NW = "ic_t_nw"
+    IC_P = "ic_p"
+    FM_LAMBDA_MEAN = "fm_lambda_mean"
+    FM_LAMBDA_T_NW = "fm_lambda_t_nw"
+    FM_LAMBDA_P = "fm_lambda_p"
+    TS_BETA = "ts_beta"
+    TS_BETA_T_NW = "ts_beta_t_nw"
+    TS_BETA_P = "ts_beta_p"
+    CAAR_MEAN = "caar_mean"
+    CAAR_T_NW = "caar_t_nw"
+    CAAR_P = "caar_p"
+    FACTOR_ADF_P = "factor_adf_p"
+    LJUNG_BOX_P = "ljung_box_p"
+    EVENT_TEMPORAL_HHI = "event_temporal_hhi"
+    NW_LAGS_USED = "nw_lags_used"
+
+    @property
+    def is_p_value(self) -> bool:
+        """``True`` iff this stat is a probability in [0, 1].
+
+        Used by ``multi_factor.bhy`` to gatekeep the ``gate=`` override
+        — BHY step-up math requires p-values, so feeding a t-stat would
+        silently corrupt FDR control.
+        """
+        return self.value.endswith("_p")
+
+
+class Verdict(StrEnum):
+    """Procedure-canonical pass/fail outcome of ``Profile.verdict()``."""
+
+    PASS = "pass"
+    FAIL = "fail"