Skip to content

MetricSpec & Registration

factrix uses declarative specification and a centralized registry to topologically sort and execute evaluations. You can document first-party or third-party metric behaviors and dependencies using these tools.

MetricSpec

factrix.MetricSpec dataclass 

MetricSpec(name: str, cell: Cell, aggregation: Aggregation, input_shape: InputShape = PANEL, output_shape: OutputShape = SCALAR, role: SpecRole = METRIC, requires: dict[str, Callable] = dict(), batchable: bool = False, sample_threshold: SampleThreshold = SampleThreshold(), requires_continuous_magnitude: bool = False, slice_boundary_sensitive: bool = False)

Per-callable typed spec built and registered by the @metric decorator.

One :class:MetricSpec per public callable in the declaring factrix/metrics/*.py module.

Fields:

  • name: function name in the declaring module.
  • cell: applicable (scope, density, structure) cell; None along any axis denotes * wildcard.
  • aggregation: how the cross-section and time-series reductions compose. Load-bearing for the DAG executor / FDR. Distinct from the concept family (ic / decay / quantile), which is the declaring module's stem and is derived from file location (the file = family invariant), never stored on the spec.
  • input_shape: shape of data the callable directly receives (PANEL / SERIES / SCALAR).
  • output_shape: shape of the returned value. METRIC specs must have SCALAR (enforced by __post_init__).
  • role: METRIC for user-facing result-producing callables (default); PIPELINE for stage-1 helpers excluded from list_metrics / inspection.metrics.* / result dict keys but pulled by the DAG via requires.
  • requires: {consumer_param_name: producer_callable}. Key is a parameter on the declaring callable; value is another @metric callable whose per-factor output the DAG executor injects at that parameter. Empty dict means no upstream dependency.
  • batchable: True when the callable accepts factor_cols= and returns dict[factor_name, output] so the DAG executor calls it once across the whole batch.
  • sample_threshold: :class:SampleThreshold declaring the panel-shape thresholds below which the metric is statistically unusable / degraded. Defaults to SampleThreshold() (all None — no pre-flight gate); :func:inspect_data applies the cell-match check and any declared thresholds.
  • requires_continuous_magnitude: True when the metric needs a continuous-magnitude factor (|factor| must vary across events); :func:inspect_data blocks it on a discrete ±k signal, matching the metric's run-time not_applicable_discrete_signal short-circuit. Defaults to False.
  • slice_boundary_sensitive: True when evaluating independently on date-axis slices changes the computation by truncating ordered history, resetting a sampling phase, or refitting a time-series model. This is a capability of the estimator, not an inference from aggregation.

@metric_spec Decorator

factrix.metric_spec 

metric_spec(spec: MetricSpec) -> Callable[[Callable[..., Any]], Callable[..., Any]]

Stamp __metric_spec__ onto a metric callable.

Pure metadata stamp — does not register. Pair with an explicit :func:register call to make the spec visible to :func:list_metrics / :func:spec_by_name / DAG dispatch::

@metric_spec(MetricSpec(name="custom_ic", cell=..., ...))
def custom_ic(panel, ...): ...

factrix.metrics.register(custom_ic)

Accepts the full :class:MetricSpec object rather than spreading kwargs so the decorator surface stays evergreen across MetricSpec field changes (e.g. the structural rework in the panel-dataclass-unification follow-up).

Metric Registration

factrix.metrics.register 

register(fn: Callable[..., Any]) -> None

Register a third-party metric class or callable.

title: SpecRole

SpecRole

factrix uses roles to differentiate between public, user-facing metrics and internal pipeline stages.

factrix._axis.SpecRole

Bases: Enum

Whether a spec is a user-facing metric or an internal pipeline step.

METRIC — public result-producing callable; surfaced by :func:factrix.list_metrics and included in :attr:EvaluationResult.metrics dict keys. PIPELINE — stage-1 intermediate-frame producer (e.g. compute_ic); pulled by the DAG executor via :attr:MetricSpec.requires but not listed as a runnable metric.