bagel-factor 0.1.3

Single-factor evaluation/testing toolkit (pandas-first).

bagel-factor

A small, pandas-first toolkit for single-factor evaluation/testing.

Scope (by design)

This package focuses on:

• canonical point-in-time data helpers ((date, asset) panel)
• preprocessing transforms (clip / z-score / rank)
• single-factor evaluation (IC/ICIR, quantile returns, long-short, coverage, turnover)

It intentionally does not implement multi-factor modeling or portfolio backtesting.

Install

Requires Python >=3.12

pip install bagel-factor

Install (dev / from source)

This repo is managed with uv.

uv sync

Quickstart

1) Prepare a canonical panel

Most APIs expect a canonical panel:

• pd.DataFrame
• indexed by pd.MultiIndex with names ("date", "asset")

import pandas as pd
from bagelfactor.data import ensure_panel_index

raw = pd.DataFrame(
    {
        "date": ["2020-01-01", "2020-01-01"],
        "asset": ["A", "B"],
        "close": [10.0, 20.0],
        "alpha": [1.0, 2.0],
    }
)

panel = ensure_panel_index(raw)

2) (Optional) preprocess the factor

from bagelfactor.preprocess import Clip, Pipeline, Rank, ZScore

preprocess = Pipeline([
    Clip("alpha", lower=0.0, upper=2.0),
    ZScore("alpha"),
    Rank("alpha"),
])

3) Run single-factor evaluation

horizons supports multiple forward-return windows (tuple of positive integers).

from bagelfactor.single_factor import SingleFactorJob

res = SingleFactorJob.run(
    panel,
    factor="alpha",
    price="close",
    horizons=(1, 5, 20),
    n_quantiles=5,
    preprocess=preprocess,
)

ic_1d = res.ic[1]
qret_5d = res.quantile_returns[5]
long_short_20d = res.long_short[20]

4) Visualize results

from bagelfactor.visualization import plot_result_summary

fig = plot_result_summary(res, horizon=5)
fig.show()

5) Statistical tests

from bagelfactor.stats import ols_alpha_tstat, ttest_1samp

ic_test = ttest_1samp(res.ic[5], popmean=0.0)
ls_alpha = ols_alpha_tstat(res.long_short[5])

print(ic_test)
print(ls_alpha)

Full example with expected outputs: see docs/example.md.

Benchmarks

• IC (information coefficient): vectorized implementation yields ~4-5x speedup on synthetic panels (examples/benchmark_ic.py) with numeric agreement to baseline.
• Coverage: vectorized implementation yields ~20-30x speedup; results are numerically identical to the baseline implementation.

Reproduce: uv run python examples/benchmark_ic.py (benchmarks included in repository).

Documentation

Table of contents

• Getting started

  • Factor evaluation guide
  • End-to-end example

• Modules

  • bagelfactor.data

    • data/index
    • data/panel
    • data/loaders
    • data/loaders internal
    • data/align
    • data/calendar
    • data/factors
    • data/universe

  • bagelfactor.metrics

    • metrics/ic
    • metrics/quantiles
    • metrics/turnover
    • metrics/coverage

  • bagelfactor.preprocess

    • preprocess/pipeline
    • preprocess/transforms

  • bagelfactor.single_factor

    • single_factor/job
    • single_factor/result

  • bagelfactor.visualization

    • visualization/single_factor

  • bagelfactor.stats

    • stats/tests
    • stats/regression

  • bagelfactor.reporting

    • reporting/export

• Design docs

  • v0 proposals

License

MIT (see LICENSE).