Result types

results

What each command computed, as data rather than as text.

Every command in this repo used to end in a wall of print. That made three things impossible at once: calling a command from Python and getting its numbers, testing what a command reports without capturing stdout, and documenting the output without copying a terminal transcript into markdown.

The split is: nullres.api computes and returns one of these; nullres.report turns one of these into the text a terminal shows. Nothing here computes and nothing here formats. A field is either something a command measured or something it needs in order to explain what it measured.

These types ARE the public API. Adding a field is a compatible change; removing or renaming one is not.

RunResult dataclass

RunResult(cfg: RunConfig, metrics: dict[str, dict], n_trials: int, trials_caveat: str = '', killed_warning: str = '', ablated: str | None = None, features_before: int = 0, features_after: int = 0, record: RunRecord | None = None)

nullres run — every configured strategy, measured out of sample.

benchmark property

benchmark: dict

Buy & hold's metrics — the bar everything else has to clear.

survivors property

survivors: list[str]

Strategies whose deflated Sharpe is still above zero.

Deflated, not raw: a positive Sharpe that does not survive the trial count is a strategy that looked, not a strategy that found.

AuditResult dataclass

AuditResult(cfg: RunConfig, checks: list[Check])

nullres audit — the five mechanical leak checks.

skipped property

skipped: list[Check]

Checks that could not apply. Not passes — nothing was ruled out.

BudgetResult dataclass

BudgetResult(cfg: RunConfig, sigma: float, logret: ndarray, hours_per_bar: float, min_hold: int)

nullres budget — the arithmetic that decides most questions.

SweepResult dataclass

SweepResult(cfg: RunConfig, strategy: str, entries: list[float], holds: list[int], cells: DataFrame, record: RunRecord | None = None)

nullres sweep — out-of-sample Sharpe across entry x hold.

grid property

grid: DataFrame

Sharpe as an entry x hold matrix.

RobustnessResult dataclass

RobustnessResult(cfg: RunConfig, strategy: str, params: dict[str, Any], grid: DataFrame, grid_keys: list[str], grid_kind: str, flip_rate: float, flip_pairs: int, stability: DataFrame, transfer: DataFrame, benchmark_sharpe: float, verdict: str, notes: list[str], symbols: list[str], transfer_start: str | None = None, killed_warning: str = '', record: RunRecord | None = None)

nullres robust — three independent attempts to falsify a strategy.

AblationResult dataclass

AblationResult(cfg: RunConfig, group: str, n_rows: int, features_with: int, features_without: int, auc_with: ndarray, auc_without: ndarray, t_stat: float, p_value: float, record: RunRecord | None = None)

nullres ablate — does a feature group improve DISCRIMINATION?

Measured on AUC across folds, not Sharpe. With ~80 trades an equity curve is decided by which handful of positions landed; AUC uses every labelled bar, so it can tell "the model knows more" from "the model got luckier".

delta property

delta: ndarray

Per-fold AUC difference, with the group minus without it.

PanelVerification dataclass

PanelVerification(mean_auc: float, shuffled_auc: float, survivors_auc: float | None, per_symbol: DataFrame, delisted_share: float, contribution: Series, tail_curve: DataFrame, tail_census: dict, concentration: dict | None = None, min_obs: int = 200, nominal_weight: float | None = None)

The controls that decide whether cross-sectional skill is real.

Expensive — the first two refit the whole walk-forward — so this is only populated when verify=True.

detects_death property

detects_death: bool

True when dropping delisted names collapses the AUC.

A model that only knows which coins are dying has found something real and untradable: by the time a coin is dying its borrow has vanished.

XsecResult dataclass

XsecResult(cfg: RunConfig, panel: Panel, proba: Series, fold_reports: list[dict], requested_symbols: list[str], survivorship: Check, oos_times: DatetimeIndex, oos_mask: Series, books: dict[str, dict], ks: tuple[int, ...], positions: dict[int, DataFrame] = dict(), stability: DataFrame | None = None, stability_k: int | None = None, cost_sensitivity: DataFrame | None = None, n_trials: int = 1, trials_caveat: str = '', universe_month: str | None = None, verification: PanelVerification | None = None, record: RunRecord | None = None)

nullres xsec — cross-sectional long/short on a panel.

heaviest_book property

heaviest_book: tuple[str, dict]

The book carrying the most gross notional.

A dollar-neutral book hides its leverage: net is 0 and exposure reads 100% whether it carries 1x or 5x.

FeatureImportanceResult dataclass

FeatureImportanceResult(cfg: RunConfig, importances: Series, derivative_names: set[str])

nullres features — permutation importance on the last fold's test window.

FetchResult dataclass

FetchResult(cfg: RunConfig, bars: DataFrame, funding: DataFrame | None = None, metrics: DataFrame | None = None)

nullres fetch — what is now in the cache.

LedgerView dataclass

LedgerView(runs: list[RunRecord], n_total: int, n_configs: int, n_trials: int, killed: int, survived: int, inconclusive: int, unrecorded_variants: int, verdict_filter: str | None = None, limit: int = 25)

nullres log — the evidence ledger, summarised.