Sync backtests
Run local backtests, sync them to AlphaLens, and understand the Strategy Center data model.
Backtests are local Python runs. AlphaLens receives the finished result and renders it as a Strategy Center source.
Run from the CLI
ALPHALENS_API_KEY=alens_... alphalens run --strategy my_strategy:MyStrategyThe strategy import path is module:ClassName. Run from the directory where the module is importable.
Common overrides:
alphalens run \
--strategy my_strategy:MyStrategy \
--start 2021-01-01 \
--end 2025-12-31 \
--resolution 1day \
--cash 250000 \
--benchmark SPY \
--param leverage=1.5Useful output flags:
| Flag | Purpose |
|---|---|
--report report.html | Write a local HTML report |
--save-equity equity.csv | Save local equity series |
--save-trades trades.csv | Save local trades |
--save-orders orders.csv | Save local orders |
--no-progress | Suppress monthly progress logs |
--no-track | Skip local run registry tracking |
Run from Python
from alphalens_core import AlphaLensClient
from my_strategy import MyStrategy
al = AlphaLensClient(api_key="alens_...")
result = al.backtest(MyStrategy)
print(result.stats)If api_key is omitted, AlphaLensClient reads ALPHALENS_API_KEY.
What the engine does
When you run a backtest, alphalens-core:
- Loads the strategy class.
- Fetches the requested universe and benchmark data.
- Seeds warmup history.
- Calls
initialize. - Replays bars through schedules and
on_data. - Simulates fills using next-bar execution.
- Computes metrics, returns, trades, orders, and position values.
- Syncs the normalized result to AlphaLens when cloud auth is configured.
What appears in Strategy Center
Synced backtests become backtest:<run_id> sources.
Strategy Center uses the synced data for:
- Strategy and run lists.
- Equity and daily performance.
- Benchmark comparison.
- Drawdown and underwater curves.
- Rolling Sharpe.
- Trades and orders.
- Position allocation over time.
- KPI values such as return, Sharpe, Calmar, PSR, Omega, win rate, and P&L.
Standard Portfolio output
Backtests are normalized into the same dashboard contract as broker accounts.
| Field | Why it matters |
|---|---|
| NAV points | Performance, benchmark comparison, drawdown, rolling Sharpe |
| Positions | Holdings table and allocation chart |
| Trades and orders | Win/loss, trade analytics, audit trail |
| Metrics | KPI strip and run comparison |
| Warnings | Missing data, stale source, or reconciliation issues |
This is why Strategy Center looks like the portfolio dashboard instead of a separate research-only report.
Parameter sweeps
Add sweep_grid to the class for repeatable research:
class MyStrategy(Algorithm):
sweep_grid = {
"lookback": [63, 126, 189],
"top_n": [1, 2, 3],
}Then run batch or walk-forward workflows from the CLI. Promote only the runs that pass your research criteria into paper deployment.