numeraire.core.schema

The standard tidy, long-format result schema.

Every evaluator emits rows in this schema; downstream plotting (plotnine / R) consumes it, so the plotting choice stays decoupled. Stability is promised on this schema (semver).

numeraire.core.schema.RESULT_COLUMNS: tuple[str, ...] = ('run_id', 'method', 'date', 'metric', 'value', 'universe', 'capability', 'protocol', 'config_hash', 'data_vintage')

Minimum columns every result table must carry (in any order).

protocol labels the evaluation discipline the row was produced under: "walk_forward" (the framework’s out-of-sample walk-forward path, which every weights/forecast evaluator emits) or "in_sample" (a single full-sample fit, the paper cross-sectional-pricing tradition). It makes an explanatory in-sample number unconfusable with an out-of-sample one.

numeraire.core.schema.ATTRITION_COLUMNS: tuple[str, ...] = ('n_obs', 'n_dropped')

Optional, schema-additive attrition columns.

Evaluators that compare a model against a benchmark or a realized target (out-of-sample R^2, squared-error difference, Clark-West, the cross-sectional pricing metrics) attach n_obs — the size of the joint finite sample the metric was computed on — and n_dropped — the count of candidate observations excluded by that joint mask. They make selective missingness auditable on the row itself. They are optional: rows from evaluators without a benchmark comparison omit them, and validate_result() never requires them (only that every non-null cell is a finite, non-negative, integer-valued count).

numeraire.core.schema.validate_result(df: DataFrame) → None

Raise ValueError if df violates the result schema.

Enforces that every column in RESULT_COLUMNS is present; extra columns are allowed. When the optional ATTRITION_COLUMNS are present, every non-null cell must be a finite, non-negative, integer-valued numeric (a count); non-numeric cells are rejected rather than coerced away. The columns themselves are never required.