numeraire 0.2.0__py3-none-any.whl

numeraire/__init__.py

@@ -0,0 +1,118 @@
+"""numeraire — a research framework for empirical asset pricing.
+
+The reference unit against which methods are measured. The spine (``numeraire.core``)
+is method-agnostic and depended upon by everything; methods and adapters depend on it,
+never the reverse (enforced by import-linter, see pyproject ``[tool.importlinter]``).
+"""
+
+from numeraire.core import capabilities
+from numeraire.core.data import CrossSectionView, TimeSeriesView
+from numeraire.core.engine import (
+    ForecastOutput,
+    PanelWeightsOutput,
+    PricingOutput,
+    WeightsOutput,
+    config_hash,
+    pricing_in_sample,
+    walk_forward,
+    walk_forward_forecast,
+    walk_forward_panel,
+    walk_forward_pricing,
+)
+from numeraire.core.evaluators import (
+    AlphaEvaluator,
+    AverageAbsAlphaEvaluator,
+    CEQEvaluator,
+    ClarkWestEvaluator,
+    CrossSectionalR2Evaluator,
+    MeanReturnEvaluator,
+    OOSR2Evaluator,
+    SharpeEvaluator,
+    SquaredErrorDiffEvaluator,
+    StrategyReturnEvaluator,
+)
+from numeraire.core.protocols import (
+    DataView,
+    Estimator,
+    Evaluator,
+    Model,
+    Splitter,
+    SupportsForecast,
+    SupportsPricing,
+    SupportsWeights,
+)
+from numeraire.core.registry import (
+    available_evaluators,
+    get_evaluator,
+    register_evaluator,
+)
+from numeraire.core.schema import RESULT_COLUMNS, validate_result
+from numeraire.core.simulate import RebalanceSchedule, SimulationResult, simulate_weights
+from numeraire.core.sorts import SortResult, make_sorts
+from numeraire.core.splitter import WalkForwardSplitter, validation_split
+from numeraire.core.stats import (
+    adjust_tests,
+    alpha_regression,
+    certainty_equivalent,
+    clark_west,
+    grs_test,
+    newey_west_lrv,
+    performance_fee,
+    return_loss,
+    sharpe_diff_test,
+)
+
+__all__ = [
+    "RESULT_COLUMNS",
+    "AlphaEvaluator",
+    "AverageAbsAlphaEvaluator",
+    "CEQEvaluator",
+    "ClarkWestEvaluator",
+    "CrossSectionView",
+    "CrossSectionalR2Evaluator",
+    "DataView",
+    "Estimator",
+    "Evaluator",
+    "ForecastOutput",
+    "MeanReturnEvaluator",
+    "Model",
+    "OOSR2Evaluator",
+    "PanelWeightsOutput",
+    "PricingOutput",
+    "RebalanceSchedule",
+    "SharpeEvaluator",
+    "SimulationResult",
+    "SortResult",
+    "Splitter",
+    "SquaredErrorDiffEvaluator",
+    "StrategyReturnEvaluator",
+    "SupportsForecast",
+    "SupportsPricing",
+    "SupportsWeights",
+    "TimeSeriesView",
+    "WalkForwardSplitter",
+    "WeightsOutput",
+    "adjust_tests",
+    "alpha_regression",
+    "available_evaluators",
+    "capabilities",
+    "certainty_equivalent",
+    "clark_west",
+    "config_hash",
+    "get_evaluator",
+    "grs_test",
+    "make_sorts",
+    "newey_west_lrv",
+    "performance_fee",
+    "pricing_in_sample",
+    "register_evaluator",
+    "return_loss",
+    "sharpe_diff_test",
+    "simulate_weights",
+    "validate_result",
+    "validation_split",
+    "walk_forward",
+    "walk_forward_forecast",
+    "walk_forward_panel",
+    "walk_forward_pricing",
+]

numeraire/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""numeraire.adapters — thin wrappers making reference libraries conform to core protocols.
+
+Glue, not spine — each adapter imports its reference library only at module top level, so installing
+core alone never requires it. Reference-library methods (e.g. IPCA via ``ipca``) ship in extension
+packages such as ``numeraire-zoo``, which declare those heavy dependencies themselves.
+"""

numeraire/adapters/skfolio_adapter.py

@@ -0,0 +1,105 @@
+"""skfolio adapter — wrap a skfolio portfolio optimizer as a numeraire ``to_weights`` estimator.
+
+`skfolio <https://skfolio.org>`_ (BSD-3) provides mean-risk / hierarchical-risk-parity /
+risk-budgeting optimizers as scikit-learn estimators. This adapter makes one conform to the
+numeraire ``Estimator`` / ``Model`` protocol so it plugs into the walk-forward engine as a peer of
+any native method — **without** adopting skfolio's own cross-validation or walk-forward machinery
+(numeraire owns the out-of-sample loop).
+
+The contract (why this stays leak-free):
+
+- ``fit(view)`` fits the skfolio estimator on ``view.returns_frame()`` — the exact training window
+  the engine hands it — and stores the fitted ``weights_``.
+- ``to_weights(view)`` **broadcasts** those fitted weights across the view's calendar. It never
+  calls ``estimator.predict(X_test)``: skfolio's ``predict`` scores a weight vector *on the returns
+  it is given*, so feeding it the test window would pour realized test returns into the position —
+  a structural look-ahead. Weights come only from ``.weights_`` (a function of the fit window).
+
+Through ``walk_forward`` the estimator is re-fit at each origin on that origin's PIT window and the
+resulting weights are applied to the next period, so the broadcast is per-origin and point-in-time.
+The optional ``window`` caps the lookback to the most recent ``window`` rows of whatever the engine
+hands ``fit`` (e.g. a rolling estimation window under an expanding split).
+
+skfolio is an **optional** dependency (the ``[skfolio]`` extra); it is imported lazily inside
+``fit`` so this module imports with or without it installed.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from numeraire.core import capabilities
+from numeraire.core.data import TimeSeriesView
+from numeraire.core.protocols import DataView
+
+
+def _as_tsv(view: DataView) -> TimeSeriesView:
+    if not isinstance(view, TimeSeriesView):
+        raise TypeError("the skfolio adapter runs on a TimeSeriesView (asset returns block)")
+    return view
+
+
+class _SkfolioModel:
+    """A fitted skfolio portfolio: a single optimal weight vector, broadcast across a calendar."""
+
+    def __init__(self, weights: pd.Series, meta: dict[str, Any]) -> None:
+        self._weights = weights  # index = fitted asset labels
+        self.meta = meta
+
+    def capabilities(self) -> set[str]:
+        return {capabilities.TO_WEIGHTS}
+
+    def to_weights(self, view: DataView) -> pd.DataFrame:
+        tsv = _as_tsv(view)
+        assets = [str(a) for a in tsv.assets]
+        w = self._weights.reindex(assets).to_numpy(dtype=np.float64)
+        if np.isnan(w).any():
+            missing = [a for a, x in zip(assets, w, strict=True) if np.isnan(x)]
+            raise ValueError(f"fitted skfolio weights do not cover view assets {missing}")
+        vals = np.repeat(w[None, :], len(tsv.calendar), axis=0)
+        return pd.DataFrame(vals, index=tsv.calendar, columns=tsv.assets)
+
+
+class SkfolioWeights:
+    """Adapt a skfolio optimizer to numeraire ``to_weights``.
+
+    ``estimator`` is a skfolio estimator instance (e.g. ``MeanRisk()``, ``RiskBudgeting()``,
+    ``HierarchicalRiskParity()``); it is cloned per fit so each origin gets a fresh optimization.
+    When ``None``, a default ``skfolio.optimization.MeanRisk`` is used. ``window`` optionally caps
+    the estimation lookback to the most recent rows of the fit view.
+    """
+
+    def __init__(self, estimator: Any | None = None, *, window: int | None = None) -> None:
+        self.estimator = estimator
+        self.window = window
+
+    def fit(self, view: DataView) -> _SkfolioModel:
+        import skfolio
+        from sklearn.base import clone
+
+        tsv = _as_tsv(view)
+        if self.estimator is None:
+            from skfolio.optimization import MeanRisk
+
+            est = MeanRisk()
+        else:
+            est = clone(self.estimator)
+        returns = tsv.returns_frame()
+        if self.window is not None:
+            returns = returns.tail(self.window)
+        est.fit(returns)
+        weights = pd.Series(
+            np.asarray(est.weights_, dtype=np.float64).ravel(),
+            index=[str(a) for a in tsv.assets],
+        )
+        meta = {
+            "adapter": "skfolio",
+            "skfolio_version": skfolio.__version__,
+            "estimator": type(est).__name__,
+            "solver": getattr(est, "solver", None),
+            "n_train": len(returns),
+        }
+        return _SkfolioModel(weights, meta)

numeraire/baselines/__init__.py

@@ -0,0 +1,39 @@
+"""Universal benchmarks bundled in ``numeraire`` — the reference rules every method is compared to.
+
+Four estimators, all framework citizens (they pass ``numeraire.testing.check_estimator``) and all
+registered via the ``numeraire.methods`` entry-point group (dogfooding the open discovery):
+
+- :class:`EqualWeight` — 1/N ``to_weights`` (the naive benchmark).
+- :class:`MinVariance` — global minimum-variance ``to_weights`` (sample covariance + window).
+- :class:`MeanVariance` — plug-in mean-variance ``to_weights`` (``S^-1 mu``, explicit norm).
+- :class:`HistoricalMean` — prevailing-historical-mean ``to_forecast`` (Goyal-Welch benchmark).
+
+The pure weight functions (:func:`equal_weights`, :func:`minimum_variance_weights`,
+:func:`mean_variance_weights`) are the single source of truth for these formulae — method packages
+(e.g. the naive-diversification reproduction) build on them rather than re-deriving the algebra.
+
+Serious constrained optimizers are **not** re-implemented here; they arrive through the optional
+skfolio adapter (``numeraire.adapters``). These baselines are the always-available floor.
+"""
+
+from __future__ import annotations
+
+from numeraire.baselines.forecast import HistoricalMean
+from numeraire.baselines.weights import (
+    EqualWeight,
+    MeanVariance,
+    MinVariance,
+    equal_weights,
+    mean_variance_weights,
+    minimum_variance_weights,
+)
+
+__all__ = [
+    "EqualWeight",
+    "HistoricalMean",
+    "MeanVariance",
+    "MinVariance",
+    "equal_weights",
+    "mean_variance_weights",
+    "minimum_variance_weights",
+]

numeraire/baselines/forecast.py

@@ -0,0 +1,64 @@
+"""The historical-mean forecast baseline — the Goyal-Welch OOS reference.
+
+The prevailing (expanding) historical mean of the returns block is the benchmark every predictive
+regression is scored against: Goyal-Welch (2008) show it is a stubbornly hard forecast to beat out
+of sample, and the OOS R^2 in :class:`~numeraire.core.evaluators.OOSR2Evaluator` measures MSE
+improvement *relative to it*. The walk-forward forecast engine already computes exactly this
+benchmark column for free at each origin (``train.returns_frame().mean(axis=0)``); this estimator
+exposes the very same quantity as a first-class ``to_forecast`` citizen, so it can be compared,
+registered and run through the engine like any other method (its OOS R^2 against the engine
+benchmark is ~0 by construction — it *is* the benchmark).
+
+``window`` gives the rolling variant (last ``k`` observations); ``None`` (default) is the expanding
+prevailing mean, matching the engine's benchmark convention.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from numeraire.core import capabilities
+from numeraire.core.data import TimeSeriesView
+from numeraire.core.protocols import DataView
+
+
+def _as_tsv(view: DataView) -> TimeSeriesView:
+    if not isinstance(view, TimeSeriesView):
+        raise TypeError("HistoricalMean requires a TimeSeriesView (asset-returns block)")
+    return view
+
+
+class _HistoricalMeanModel:
+    """Fitted historical-mean model: forecasts the per-asset sample mean over the fit window."""
+
+    def __init__(self, window: int | None) -> None:
+        self._window = window
+
+    def capabilities(self) -> set[str]:
+        return {capabilities.TO_FORECAST}
+
+    def forecast(self, view: DataView) -> pd.Series:
+        rets = _as_tsv(view).returns_frame()
+        if self._window is not None:
+            rets = rets.tail(self._window)
+        return rets.mean()  # per-asset prevailing mean; index = view.assets
+
+
+class HistoricalMean:
+    """The prevailing-historical-mean forecaster (Goyal-Welch benchmark).
+
+    Parameters
+    ----------
+    window:
+        Trailing window (in calendar steps) for the mean; ``None`` (default) is the expanding
+        prevailing mean — the same quantity the walk-forward engine uses as its OOS R^2 benchmark.
+    """
+
+    def __init__(self, *, window: int | None = None) -> None:
+        if window is not None and window < 1:
+            raise ValueError("window must be >= 1")
+        self.window = window
+
+    def fit(self, view: DataView) -> _HistoricalMeanModel:
+        _as_tsv(view)
+        return _HistoricalMeanModel(self.window)

numeraire/baselines/weights.py

@@ -0,0 +1,218 @@
+"""Universal weight baselines: the 1/N, minimum-variance and mean-variance rules.
+
+These three are the reference points every ``to_weights`` method is measured against — the naive
+benchmark (1/N) plus the two textbook sample-plug-in optimizers. They are bundled in ``numeraire``
+itself (not a method package) because they are method-agnostic and every comparison needs them.
+
+Weight functions (the single source of truth; extensions build on these rather than re-deriving):
+
+- :func:`equal_weights` — ``w = 1/N`` (needs no estimation; the naive benchmark).
+- :func:`minimum_variance_weights` — global minimum-variance ``w = S^-1 1 / (1' S^-1 1)`` (the
+  first-order condition of ``min w'Sw`` s.t. ``1'w = 1``; always well defined for invertible ``S``).
+- :func:`mean_variance_weights` — the plug-in tangency direction ``w ∝ S^-1 mu``, with the
+  normalization made **explicit** (``"budget"`` divides by ``1' S^-1 mu`` so weights sum to one;
+  ``"none"`` leaves the raw proportional direction). The ``"budget"`` divisor passes through zero
+  when the tangency portfolio is nearly cash-neutral — the origin of sample mean-variance's famous
+  weight/turnover explosion, which is a property of the rule, not a bug here.
+
+The estimators (:class:`EqualWeight`, :class:`MinVariance`, :class:`MeanVariance`) are point-in-time
+citizens: each ``to_weights(view)`` rebalances at every date on ``view.calendar``, estimating the
+sample moments from that date's own trailing window (``window`` caps it to a rolling estimate; the
+default expands from the start). They window internally, so look-ahead is structurally impossible.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Literal
+
+import numpy as np
+import pandas as pd
+from numpy.typing import NDArray
+
+from numeraire.core import capabilities
+from numeraire.core.data import TimeSeriesView
+from numeraire.core.protocols import DataView
+
+Float = NDArray[np.float64]
+Normalization = Literal["budget", "none"]
+
+
+# --------------------------------------------------------------------------- weight functions
+
+
+def equal_weights(n: int) -> Float:
+    """The naive 1/N portfolio: ``w_i = 1/n`` (needs no moment estimation)."""
+    if n < 1:
+        raise ValueError(f"need at least one asset; got n={n}")
+    return np.ones(n, dtype=np.float64) / n
+
+
+def minimum_variance_weights(cov: Float) -> Float:
+    """Global minimum-variance weights ``S^-1 1 / (1' S^-1 1)`` — the FOC of ``min w'Sw, 1'w=1``."""
+    n = len(cov)
+    x = np.linalg.solve(cov, np.ones(n, dtype=np.float64))
+    return x / x.sum()
+
+
+def mean_variance_weights(
+    mu: Float, cov: Float, *, normalization: Normalization = "budget"
+) -> Float:
+    """Plug-in mean-variance (tangency) weights ``∝ S^-1 mu``, normalization made explicit.
+
+    ``normalization``:
+
+    - ``"budget"`` (default): divide by ``1' S^-1 mu`` so the weights sum to one — the
+      DeMiguel-Garlappi-Uppal convention. The divisor passes through zero for a near-cash-neutral
+      tangency portfolio, which is why sample mean-variance weights and turnover explode.
+    - ``"none"``: the raw proportional direction ``S^-1 mu`` (no budget rescaling).
+    """
+    x = np.linalg.solve(cov, mu)
+    if normalization == "budget":
+        return x / x.sum()
+    if normalization == "none":
+        return x
+    raise ValueError(f"normalization must be 'budget' or 'none'; got {normalization!r}")
+
+
+# --------------------------------------------------------------------------- engine citizens
+
+
+def _as_tsv(view: DataView) -> TimeSeriesView:
+    if not isinstance(view, TimeSeriesView):
+        raise TypeError("baseline weight rules run on a TimeSeriesView (asset-returns block)")
+    return view
+
+
+def _rolling_weights(
+    view: TimeSeriesView, weight_fn: Callable[[Float], Float], *, window: int | None, min_obs: int
+) -> pd.DataFrame:
+    """Rebalance at every calendar date from that date's trailing window (PIT: windows internally).
+
+    A date is skipped (warm-up) until at least ``min_obs`` past observations are available, and
+    ``weight_fn`` gets the last ``window`` rows (all history if ``window`` is ``None``); it maps a
+    ``(T x N)`` block of past returns to an ``N``-vector of weights.
+    """
+    assets = view.assets
+    rows: list[Float] = []
+    idx: list[pd.Timestamp] = []
+    for t in view.calendar:
+        hist = view.window(t).returns_frame().to_numpy(dtype=np.float64)
+        if len(hist) < min_obs:
+            continue  # warm-up
+        block = hist if window is None else hist[-window:]
+        if len(block) < min_obs:
+            continue
+        rows.append(weight_fn(block))
+        idx.append(t)
+    if not rows:
+        return pd.DataFrame(columns=assets)
+    return pd.DataFrame(np.vstack(rows), index=pd.DatetimeIndex(idx), columns=assets)
+
+
+class _WeightModel:
+    """Fitted (parameter-free, closed-form) baseline weight model over any view's calendar."""
+
+    def __init__(
+        self, weight_fn: Callable[[Float], Float], *, window: int | None, min_obs: int
+    ) -> None:
+        self._weight_fn = weight_fn
+        self._window = window
+        self._min_obs = min_obs
+
+    def capabilities(self) -> set[str]:
+        return {capabilities.TO_WEIGHTS}
+
+    def to_weights(self, view: DataView) -> pd.DataFrame:
+        return _rolling_weights(
+            _as_tsv(view), self._weight_fn, window=self._window, min_obs=self._min_obs
+        )
+
+
+class EqualWeight:
+    """The 1/N benchmark estimator: rebalances to equal weights over ``view.assets`` each period."""
+
+    def fit(self, view: DataView) -> _WeightModel:
+        _as_tsv(view)
+        return _WeightModel(lambda b: equal_weights(b.shape[1]), window=None, min_obs=1)
+
+
+def _resolve_min_obs(explicit: int | None, n_assets: int) -> int:
+    """Warm-up length: an explicit floor, else one more row than assets (invertible covariance)."""
+    return explicit if explicit is not None else n_assets + 1
+
+
+class MinVariance:
+    """Global minimum-variance estimator: sample covariance from the (optionally windowed) view.
+
+    Parameters
+    ----------
+    window:
+        Trailing window (in calendar steps) for the sample covariance; ``None`` (default) expands
+        from the start. A rolling cap mirrors the skfolio adapter's estimation window.
+    min_obs:
+        Minimum observations before the first rebalance; ``None`` (default) requires strictly more
+        rows than assets, so the sample covariance is non-singular.
+    """
+
+    def __init__(self, *, window: int | None = None, min_obs: int | None = None) -> None:
+        if window is not None and window < 2:
+            raise ValueError("window must be >= 2 (a covariance needs at least two rows)")
+        if min_obs is not None and min_obs < 2:
+            raise ValueError("min_obs must be >= 2")
+        self.window = window
+        self.min_obs = min_obs
+
+    def fit(self, view: DataView) -> _WeightModel:
+        tsv = _as_tsv(view)
+
+        def _fn(block: Float) -> Float:
+            return minimum_variance_weights(np.cov(block, rowvar=False))
+
+        return _WeightModel(
+            _fn, window=self.window, min_obs=_resolve_min_obs(self.min_obs, len(tsv.assets))
+        )
+
+
+class MeanVariance:
+    """Plug-in mean-variance estimator: sample ``mu``/``S`` → ``S^-1 mu``, normalization explicit.
+
+    Parameters
+    ----------
+    normalization:
+        ``"budget"`` (default) divides by ``1' S^-1 mu`` (weights sum to one; DGU convention);
+        ``"none"`` returns the raw proportional direction ``S^-1 mu``.
+    window, min_obs:
+        As for :class:`MinVariance` (rolling estimation window / warm-up; default warm-up is one
+        row more than the asset count so the sample covariance is invertible).
+    """
+
+    def __init__(
+        self,
+        *,
+        normalization: Normalization = "budget",
+        window: int | None = None,
+        min_obs: int | None = None,
+    ) -> None:
+        if normalization not in ("budget", "none"):
+            raise ValueError(f"normalization must be 'budget' or 'none'; got {normalization!r}")
+        if window is not None and window < 2:
+            raise ValueError("window must be >= 2 (moments need at least two rows)")
+        if min_obs is not None and min_obs < 2:
+            raise ValueError("min_obs must be >= 2")
+        self.normalization: Normalization = normalization
+        self.window = window
+        self.min_obs = min_obs
+
+    def fit(self, view: DataView) -> _WeightModel:
+        tsv = _as_tsv(view)
+        norm = self.normalization
+
+        def _fn(block: Float) -> Float:
+            mu = block.mean(axis=0)
+            cov = np.cov(block, rowvar=False)
+            return mean_variance_weights(mu, cov, normalization=norm)
+
+        return _WeightModel(
+            _fn, window=self.window, min_obs=_resolve_min_obs(self.min_obs, len(tsv.assets))
+        )