# eapctf: Empirical Asset Pricing Toolkit

**eapctf** is a Python package for empirical asset pricing research. It covers the full
pipeline from factor construction to SDF estimation, ML-based return prediction, and
portfolio optimization. The package also provides first-class support for the
[Common Task Framework (CTF)](https://jkpfactors.com) introduced in Hoberg, Jensen,
Kelly and Pedersen (2025), enabling local replication of CTF server evaluation.

## Modules

| Module | Purpose | Reference |
|--------|---------|-----------|
| `eapctf.ctf` | CTF local pipeline: run, validate, evaluate, submit | HJKP (2025) |
| `eapctf.sorting` | Univariate and bivariate portfolio sorts, FF3/FF5/HXZ4/SY4 factors | FF (1993, 2015) |
| `eapctf.crosssection` | Fama-MacBeth regressions, multiple-testing correction | FM (1973) |
| `eapctf.timeseries` | Time-series alpha, GRS test, spanning test | GRS (1989) |
| `eapctf.sdf` | GMM-based SDF estimation, HJ distance and bounds | Hansen (1982) |
| `eapctf.predict` | Expanding-window OOS prediction with 10+ estimators | GKX (2020) |
| `eapctf.portfolio` | MVO, HRP, Black-Litterman, parametric policy | Markowitz (1952) |
| `eapctf.utils` | Panel utilities, rank normalization, JKP_153 constant set | — |

## Installation

```bash
# with uv (recommended)
uv add eapctf

# with pip
pip install eapctf
```

See the [Installation](getting-started/installation.md) page for optional extras and
system requirements.

## CTF Support

`eapctf.ctf` provides a local replication pipeline for the CTF competition at
[jkpfactors.com](https://jkpfactors.com). Key functions:

- `run_local()` — execute a CTF model script against local data
- `compute_metrics()` — evaluate with the same 10% vol-targeting methodology as the CTF server
- `validate()` — run all 23 compliance checks before submission
- `pipeline()` — end-to-end orchestration from model script to optional submission

The package ships with two reference benchmarks — 1/N equal-weight and IPCA — and
[verified replication results](ctf/replication-results.md) confirming that local
evaluation closely reproduces CTF leaderboard scores.

## License

MIT. See [repository](https://github.com/chanwool/eapctf) for full text.
