alpholio

Cross-sectional portfolio backtesting. The toolkit consumes alpha and handles bucketing, weighting, metrics and charts.

📖 Documentation (Chinese) ｜ 简体中文 README

Four modules, one direction of data flow. Each module owns a single public entry point, so any stage can be swapped without touching the others.

InputProcessor ──InputBundle──▶ PortfolioEngine ──EngineResult──▶ Analyzer ──AnalysisResult──▶ Visualizer ──▶ PNG / CSV

The toolkit consumes alpha only — it never generates signals. Price-based factors such as MOM / STR / WSTR are ordinary inputs; see the daily MOM example for one worked end to end.

Install

pip install alpholio

Working from a clone instead:

pip install -e .                      # compatible ranges
pip install -e ".[docs]"              # adds the documentation site toolchain

To reproduce the exact verified combination (Python 3.12.2):

conda env create -f environment.yml
conda activate alpholio
pip install -e .

Quick start

Factor and price tables go in as DataFrames — no need to write them to disk first:

import alpholio as alp

bt = alp.backtest(signals=alpha_df, prices=price_df, horizon=5)

bt.summary()                   # metrics per (signal_model, bucket, weight)
bt.plot("long_short")          # long-short equity curve, returns a matplotlib Figure
bt.plot("deciles")             # per-quantile gradient chart
bt.save("outputs/")            # PNG charts and CSV metrics to disk

bt.returns                     # per-period portfolio returns, long format
bt.curves                      # equity and cumulative log-return curves

horizon is the measurement window of each period's realised return and is required. Column mapping is inferred when the source names already match the contract (date / id / alpha); the rebalance interval defaults to horizon; and value weighting is added automatically when the price table carries a cap column.

Monthly panels only need a frequency: horizon and the rebalance interval then count calendar months, and metrics annualise at 12 periods per year.

bt = alp.backtest(signals=alpha_df, prices=panel_df, horizon=1, frequency="monthly")

File paths work interchangeably with in-memory tables:

bt = alp.backtest(signals="alpha.feather", prices="prices.feather", horizon=5)
bt = alp.backtest(signals={"MOM": mom_df, "REV": rev_df}, prices=price_df, horizon=5)

Batch runs and reproducible archives

The JSON config directory remains a first-class entry point, suited to batch execution on a server and to shipping alongside a paper:

alpholio run --config-dir configs/

result = alp.run_pipeline("configs/")

Both paths share the same validation and computation and agree value for value. Parameters settled in a notebook export back out into a config directory:

bt.to_config("paper/configs/", data_dir="paper/data/")

Documentation

The full documentation is written in Chinese. Direct links:

Benchmarks

No market index data is bundled. Benchmark series are supplied by the user through input.references, enter the result table under bucket REF, and appear on charts once "REF" is listed in a chart's buckets.

Equal-weighted portfolios should be paired with an equal-weighted index and cap-weighted with a cap-weighted index — only like-for-like comparisons mean anything. A single references entry is replicated across every weighting scheme, so pairing one index per scheme takes two entries plus two chart configs constraining weights and signals. See Multiple signals.

Building the docs locally

pip install -e ".[docs]"
mkdocs serve

License

MIT