numeraire.TimeSeriesView

class numeraire.TimeSeriesView(returns: DataFrame, features: DataFrame | None = None, *, blocks: Sequence[Block] | None = None, horizon: int = 1, risk_free: Series | None = None, return_type: str = 'simple')

Bases: object

A point-in-time view: a returns (decision) calendar + one or more aligned feature blocks.

Parameters:

• returns – (date x asset) returns; its index is the decision/rebalance calendar. Excess by default; if risk_free is given they are treated as raw and converted to excess internally. A return indexed at t is realized over the period ending at t. One column = market timing. Simple returns by default — pass return_type="log" to declare log-return inputs, which are converted to simple returns once at ingestion (see return_type below).

• features – Convenience single-block input: a (date x feature) frame sharing the returns index, wrapped as one lag=0 FeatureBlock. Mutually exclusive with blocks. Omit both features and blocks for a returns-only view (market-timing / moment-based strategies that read only the returns block): feature_names is then empty and features_frame() / aligned() yield a zero-column X.

• blocks – Explicit list of FeatureBlock — each with its own calendar and availability lag. Use this to combine heterogeneous macro sources (e.g. FRED lag=1 + another lag=2 + a no-vintage source) as predictors. Mutually exclusive with features.

• horizon – Forecast horizon h in calendar steps; features at t pair with the return realized over (t, t+h]. h >= 1; h = 0 (contemporaneous) is rejected.

• risk_free – Optional raw→excess conversion (see _to_excess()). When given, risk_free is declared in the same convention as returns (return_type); a "log" rf is converted to simple alongside the returns before the excess subtraction.

• return_type – Convention of the input returns (and risk_free): "simple" (default) or "log". Log input is a declared input convention only — declared log returns are converted to simple returns once at ingestion via expm1 and the conversion is stamped into provenance. Everything downstream (targets, strategy P&L, evaluators) then operates on a single simple-return representation, so cross-sectional portfolio arithmetic (weighted sums) and multi-period compounding (prod(1 + r) - 1) are always correct.

Notes

With features, that frame must share the returns DatetimeIndex (the original behaviour). With blocks, each block keeps its own calendar and is aligned to the returns calendar by its own lag-aware FeatureBlock.asof(). With neither, the view is returns-only: no feature blocks, so every X is shaped (T x 0) and aligned yields the returns targets alone.

__init__(returns: DataFrame, features: DataFrame | None = None, *, blocks: Sequence[Block] | None = None, horizon: int = 1, risk_free: Series | None = None, return_type: str = 'simple') → None

Methods

__init__(returns[, features, blocks, ...])
aligned([horizon])	Supervised (dates, X, Y) over the calendar: X at t paired with (t, t+h].
between(start, end)	Test-fold view: data truncated to <= end, calendar restricted to (start, end].
features_asof(t)	Feature vector known as of t, concatenated lag-aware across all blocks.
features_frame()	The (date x feature) features block over the calendar (lag-aware; raw eject).
returns_frame()	The (date x asset) returns block over the calendar (raw eject).
tail(k)	Restrict the calendar to its last k observations (rolling window; data unchanged).
target_asof(t[, horizon])	Return realized over (t, t+h] per asset, or nan if not yet realized in-view.
window(end)	View restricted to information available up to end (data and calendar both <= end).

Attributes

assets	Asset (returns-column) names.
calendar	Rebalancing / observation timestamps (the prediction calendar).
feature_names	Feature (predictor-column) names, concatenated across blocks in order.
provenance	Ingestion provenance (e.g. a log→simple return conversion); empty for simple inputs.

property calendar: DatetimeIndex

Rebalancing / observation timestamps (the prediction calendar).

property provenance: dict[str, str]

Ingestion provenance (e.g. a log→simple return conversion); empty for simple inputs.

Merge into a backtest config (config={**view.provenance, ...}) to make the return convention hash-visible in every result row’s config_hash.

window(end: object) → TimeSeriesView

View restricted to information available up to end (data and calendar both <= end).

No look-ahead: returns and every feature block are truncated to dates <= end. Used for train folds — aligned() then only forms pairs whose target is realized by end.

between(start: object, end: object) → TimeSeriesView

Test-fold view: data truncated to <= end, calendar restricted to (start, end].

Predictions are formed only at calendar dates strictly after start; each uses features_asof(t) (data <= t). Realized P&L is computed by the engine from the full view, so the model never sees future returns.

property assets: list[str]

Asset (returns-column) names.

property feature_names: list[str]

Feature (predictor-column) names, concatenated across blocks in order.

tail(k: int) → TimeSeriesView

Restrict the calendar to its last k observations (rolling window; data unchanged).

returns_frame() → DataFrame

The (date x asset) returns block over the calendar (raw eject).

features_frame() → DataFrame

The (date x feature) features block over the calendar (lag-aware; raw eject).

features_asof(t: object) → NDArray[float64]

Feature vector known as of t, concatenated lag-aware across all blocks.

target_asof(t: object, horizon: int | None = None) → NDArray[float64]

Return realized over (t, t+h] per asset, or nan if not yet realized in-view.

Compounds simple returns over the h data periods strictly after t.

aligned(horizon: int | None = None) → tuple[DatetimeIndex, NDArray[float64], NDArray[float64]]

Supervised (dates, X, Y) over the calendar: X at t paired with (t, t+h].

Only pairs whose target is fully realized within this view’s data are kept — so on a window(end) view the last usable feature date t satisfies t + h <= end (the horizon purge that kills the contemporaneous leak). X rows are lag-aware and concatenated across feature blocks.