alphalens-core 0.3.11

AlphaLens — an event-driven backtesting & walk-forward engine for systematic strategies

alphalens-core

An event-driven backtesting & walk-forward engine for systematic trading strategies.

Write a strategy as a Python class, run a single forward pass over an in-memory OHLCV feed, and get back an equity curve, a trade log, and a rich set of performance statistics — plus walk-forward analysis, parameter sweeps, and an HTML dashboard. alphalens-core is the open engine behind AlphaLens.

Install

pip install alphalens-core              # core engine (pandas + numpy only)
pip install "alphalens-core[viz]"       # + matplotlib / quantstats dashboard & reports
pip install "alphalens-core[polygon]"   # + Polygon market-data fetching
pip install "alphalens-core[live]"      # + Alpaca execution and Polygon history
pip install "alphalens-core[fast]"      # + pyarrow parquet cache

Quickstart

from alphalens_core import Algorithm, Backtester

class GoldenCross(Algorithm):
    start = "2020-01-01"
    end = "2024-12-31"
    universe = ["SPY"]

    def initialize(self):
        self.set_warmup(50)

    def on_data(self, slice):
        hist = self.history("SPY", 50)["close"]
        if len(hist) < 50:
            return
        self.set_holdings("SPY", 1.0 if hist.tail(10).mean() > hist.mean() else 0.0)

result = Backtester().run(GoldenCross)
print(result.stats)     # Sharpe, Sortino, CAGR, max drawdown, win rate, …
result.dashboard        # inline HTML report in Jupyter, or opens in your browser

Live data needs a POLYGON_API_KEY (a .env / .env.local file is loaded automatically). To run fully offline, inject your own DataFeed.

Live / Alpaca Paper Trading

The live runner uses the same Algorithm class and history API as the backtester. The simplest path is the built-in Alpaca + Polygon runner:

export POLYGON_API_KEY=...
export ALPACA_API_KEY=...
export ALPACA_SECRET_KEY=...

alphalens live --strategy my_strategy:MyStrategy

alphalens live defaults to Alpaca paper trading. Pass --live only when you intend to route orders to the live Alpaca account. The command reads class.universe and class.resolution by default; override them with --universe SPY,QQQ or --resolution 5minute.

For custom broker/data transports, LiveSession.from_cache seeds a bounded rolling history, then each completed Slice is appended before on_data runs:

from alphalens_core import AlpacaBrokerage, LiveSession, NO_BAR
from my_data import next_completed_slice
from my_strategy import MyStrategy

broker = AlpacaBrokerage(paper=True)
session = LiveSession.from_cache(
    MyStrategy,
    brokerage=broker,
    next_bar_fn=next_completed_slice,  # Slice, NO_BAR while idle, None to stop
    history_bars=500,
    state_path=".alphalens/live/my_strategy.json",
)
session.run()

from_cache uses UniverseCache and Polygon by default; inject an existing cache to use another DataSource. The runner:

• exposes seeded and appended bars through history(), history_array(), and history_arrays();
• keeps history bounded and suppresses duplicate timestamps;
• rejects out-of-order bars and unreconciled broker orders;
• synchronizes Alpaca cash/positions and FIFO lots at startup;
• respects strategy resolution and warmup settings;
• checkpoints the last processed bar to avoid replay after restart.

Market-data transport is intentionally separate from execution. A callback must emit completed, consolidated slices for the strategy universe. See PolygonCompletedBarPoller for the built-in Polygon polling implementation. Live membership changes are not yet supported: the session fails explicitly for dynamic universes until removal orders can be reconciled with broker fills.

Features

• Event-driven lifecycle — initialize, on_data, on_order_event, on_securities_changed, on_end_of_day, on_warmup_finished.
• Realistic fills — next-bar execution with pluggable slippage / fee / fill models, and a one-bar look-ahead guard so decisions on bar t can't peek at bar t's close.
• Walk-forward analysis with per-fold parameter search.
• Parameter sweeps + PBO (probability of backtest overfitting).
• Live execution through Alpaca paper/live brokerage with buffered rolling history and restart-safe bar processing.
• Reporting — result.stats, an HTML result.dashboard, and quantstats reports.

CLI

alphalens run --strategy mymod:MyStrategy
alphalens live --strategy mymod:MyStrategy
alphalens wfa --strategy mymod:MyStrategy --train 504 --test 63 --step 63
alphalens cache --info

License

Apache-2.0 © AlphaLens LLC