numeraire.core.engine.backtest#

numeraire.core.engine.backtest(estimator: Estimator, view: Any, splitter: Any = None, *, method: str, in_sample: bool = False, **kwargs: Any) → WeightsOutput | ForecastOutput | PricingOutput | PanelWeightsOutput[source]#

Backtest estimator over view, dispatching to the right typed driver by capability.

The discoverable entry point over the typed drivers. It routes on two things:

  • which capability the fitted model advertises — capabilities() intersected with {to_weights, to_forecast, to_pricing};

  • the view type — TimeSeriesView vs CrossSectionView.

Dispatch rule (capability + view -> driver -> Output):

in_sample=True selects the single-full-sample-fit pricing path (explanatory in-sample R^2) and requires a to_pricing model. Every other path is walk-forward.

To read the capabilities the model must first be fitted, so backtest does one probe fit before delegating. That probe fits on exactly the data the selected driver’s first fit would see — the first fold’s train window (walk-forward), the warm-up prefix (forecast), or the whole view (in-sample) — never the full sample ahead of a walk-forward run. This matters for a stateful estimator: fitting the probe on the full view would let it observe post-train data before the per-fold fits, a silent look-ahead channel; mirroring the first fold keeps the probe within the same information set the driver’s first fit uses. A user splitter’s split(view) is called exactly once (its folds are replayed to the driver), so a one-shot split iterator loses no folds. The probe — like every per-fold fit the selected driver performs — runs on an isolated copy.deepcopy of the estimator, so the engine never fits the caller’s instance directly; the estimator must be deepcopy-able and must not share fit-relevant mutable state across copies (see backtest_weights()). The extra fit is intentional and cheap relative to a full walk-forward; power users who want to skip it — or who need the precise return type — can call the typed driver (backtest_weights / backtest_forecast / backtest_panel / backtest_pricing / backtest_pricing_in_sample) directly.

A model advertising more than one of the three dispatchable capabilities is ambiguous and raises TypeError — call the specific typed driver in that case. Extra keyword arguments (min_train, window, refit_every, missing_returns, config, data_vintage, run_id, n_jobs, …) are forwarded to the selected driver.