Backtest¶

See the Backtesting guide for the walk-forward methodology and worked examples.

Engine¶

engine ¶

A vectorized walk-forward backtester.

The backtester is optimizer-agnostic: it takes any callable optimizer(returns_window) -> PortfolioResult and rebalances on a fixed schedule, applying linear transaction costs on turnover. It returns a :class:BacktestResult holding the strategy return series, weight history, and a metrics summary — ready for the plotting utilities.

BacktestResult `dataclass` ¶

BacktestResult(
    name: str,
    returns: Series,
    weights: DataFrame,
    turnover: Series,
    metrics: dict[str, float] = dict(),
)

Output of a backtest run.

backtest ¶

backtest(
    returns: DataFrame,
    optimizer: Optimizer,
    *,
    name: str | None = None,
    lookback: int = 252,
    rebalance_every: int = 21,
    transaction_cost: float = 0.001,
    periods_per_year: int = 252,
    risk_free: float = 0.0,
) -> BacktestResult

Walk-forward backtest of a single optimizer.

Parameters:

Name	Type	Description	Default
`returns`	`DataFrame`	Asset return panel (rows = periods, columns = assets).	required
`optimizer`	`Optimizer`	Callable mapping a trailing return window to a :class:`PortfolioResult`.	required
`lookback`	`int`	Number of trailing periods handed to the optimizer at each rebalance.	`252`
`rebalance_every`	`int`	Rebalance frequency in periods (21 ≈ monthly for daily data).	`21`
`transaction_cost`	`float`	Proportional cost per unit of turnover (one-way), e.g. `0.0010` = 10bps.	`0.001`

Returns:

Type	Description
`BacktestResult`	Net-of-cost strategy returns, weight history, turnover, and metrics.

Source code in src/jaxfolio/backtest/engine.py

def backtest(
    returns: pd.DataFrame,
    optimizer: Optimizer,
    *,
    name: str | None = None,
    lookback: int = 252,
    rebalance_every: int = 21,
    transaction_cost: float = 0.0010,
    periods_per_year: int = 252,
    risk_free: float = 0.0,
) -> BacktestResult:
    """Walk-forward backtest of a single optimizer.

    Parameters
    ----------
    returns:
        Asset return panel (rows = periods, columns = assets).
    optimizer:
        Callable mapping a trailing return window to a :class:`PortfolioResult`.
    lookback:
        Number of trailing periods handed to the optimizer at each rebalance.
    rebalance_every:
        Rebalance frequency in periods (21 ≈ monthly for daily data).
    transaction_cost:
        Proportional cost per unit of turnover (one-way), e.g. ``0.0010`` = 10bps.

    Returns
    -------
    BacktestResult
        Net-of-cost strategy returns, weight history, turnover, and metrics.
    """
    assets = list(returns.columns)
    n = len(assets)
    dates = returns.index
    ret_vals = returns.to_numpy()

    weights = np.zeros(n)
    weight_hist: dict[pd.Timestamp, np.ndarray] = {}
    turnover_hist: dict[pd.Timestamp, float] = {}
    strat_returns = np.zeros(len(returns))

    for t in range(lookback, len(returns)):
        # Rebalance at the cadence; otherwise let weights drift with returns.
        if (t - lookback) % rebalance_every == 0:
            window = returns.iloc[t - lookback : t]
            result = optimizer(window)
            target = _align_weights(result, assets)
            cost = transaction_cost * np.abs(target - weights).sum()
            turnover_hist[dates[t]] = float(np.abs(target - weights).sum())
            weights = target
        else:
            cost = 0.0

        period_ret = ret_vals[t]
        gross = float(np.dot(weights, period_ret))
        strat_returns[t] = gross - cost
        weight_hist[dates[t]] = weights.copy()

        # Drift weights with realized returns (buy-and-hold between rebalances).
        grown = weights * (1.0 + period_ret)
        total = grown.sum()
        if total > 0:
            weights = grown / total

    ret_series = pd.Series(strat_returns, index=dates, name=name or "strategy")
    ret_series = ret_series.iloc[lookback:]
    w_df = pd.DataFrame.from_dict(weight_hist, orient="index", columns=assets)
    to_series = pd.Series(turnover_hist, name="turnover")

    summary = M.summary(ret_series, risk_free=risk_free, periods_per_year=periods_per_year)
    summary["avg_turnover"] = float(to_series.mean()) if len(to_series) else 0.0
    return BacktestResult(
        name=name or "strategy",
        returns=ret_series,
        weights=w_df,
        turnover=to_series,
        metrics=summary,
    )

compare ¶

compare(
    returns: DataFrame,
    optimizers: dict[str, Optimizer],
    **kwargs,
) -> dict[str, BacktestResult]

Backtest several optimizers on the same data and return a name->result map.

Source code in src/jaxfolio/backtest/engine.py

def compare(
    returns: pd.DataFrame,
    optimizers: dict[str, Optimizer],
    **kwargs,
) -> dict[str, BacktestResult]:
    """Backtest several optimizers on the same data and return a name->result map."""
    return {name: backtest(returns, opt, name=name, **kwargs) for name, opt in optimizers.items()}

metrics_table ¶

metrics_table(
    results: dict[str, BacktestResult],
) -> DataFrame

Assemble a tidy metrics comparison table across backtest results.

Source code in src/jaxfolio/backtest/engine.py

def metrics_table(results: dict[str, BacktestResult]) -> pd.DataFrame:
    """Assemble a tidy metrics comparison table across backtest results."""
    rows = {name: res.metrics for name, res in results.items()}
    return pd.DataFrame(rows).T

Metrics¶

metrics ¶

Performance and risk metrics for return series.

All functions accept a 1-D array-like of periodic returns and return plain floats. Annualization uses periods_per_year (252 for daily by default).