Metadata-Version: 2.5
Name: pippen
Version: 0.0.0
Summary: Reliability-adjusted NBA player impact estimates with calibrated uncertainty
Project-URL: Homepage, https://github.com/AlphaNerdFx/pippen
Project-URL: Documentation, https://alphanerdfx.github.io/pippen/
Project-URL: Repository, https://github.com/AlphaNerdFx/pippen
Project-URL: Issues, https://github.com/AlphaNerdFx/pippen/issues
Project-URL: Changelog, https://github.com/AlphaNerdFx/pippen/blob/main/CHANGELOG.md
Author: The PIPPEN Authors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: analytics,basketball,nba,plus-minus,rapm,sports-analytics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: duckdb>=1.0
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: pandera>=0.20
Requires-Dist: platformdirs>=4.0
Requires-Dist: pyarrow>=14.0
Requires-Dist: requests>=2.31
Requires-Dist: rich>=13.0
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.11
Requires-Dist: tenacity>=8.2
Requires-Dist: typer>=0.12
Provides-Extra: api
Requires-Dist: fastapi>=0.115; extra == 'api'
Requires-Dist: pydantic>=2.8; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'api'
Provides-Extra: dashboard
Requires-Dist: plotly>=5.23; extra == 'dashboard'
Requires-Dist: streamlit>=1.38; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pandas-stubs; extra == 'dev'
Requires-Dist: pre-commit>=3.8; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-gen-files>=0.5; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
Provides-Extra: fit
Requires-Dist: jax>=0.4.28; extra == 'fit'
Requires-Dist: lightgbm>=4.3; extra == 'fit'
Requires-Dist: mlflow>=2.16; extra == 'fit'
Requires-Dist: numpyro>=0.15; extra == 'fit'
Requires-Dist: optuna>=4.0; extra == 'fit'
Requires-Dist: shap>=0.45; extra == 'fit'
Provides-Extra: rigour
Requires-Dist: mutmut>=3.2; extra == 'rigour'
Requires-Dist: pytest-benchmark>=5.0; extra == 'rigour'
Requires-Dist: pytest-randomly>=3.15; extra == 'rigour'
Provides-Extra: sources
Requires-Dist: nba-api>=1.10; extra == 'sources'
Requires-Dist: pbpstats>=1.3; extra == 'sources'
Description-Content-Type: text/markdown

# PIPPEN

**Player Impact from Pooled Priors and Estimated Noise.**

Reliability-adjusted NBA player impact estimates, with calibrated uncertainty.

[![CI](https://github.com/AlphaNerdFx/pippen/actions/workflows/ci.yml/badge.svg)](https://github.com/AlphaNerdFx/pippen/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org)

> **Status: pre-release.** The data layer and the metric are under active
> construction. Nothing here is stable yet, and no results have been published.

---

## What this is

Public NBA impact metrics disagree with each other, and none of them tells you how
much to trust any single number. This project treats the existing metrics as
**noisy measurements of one quantity that nobody observes directly**: a player's
true contribution to point differential.

That reframing turns player evaluation into a measurement-error problem, which
statistics has known how to solve for a century. The pipeline:

1. Compute **RAPM** (Regularized Adjusted Plus-Minus) from possession-level
   play-by-play, so the project owns its own ground truth rather than borrowing
   a paywalled one.
2. **Measure** how reliable each input metric actually is, by splitting each
   player's season into odd and even games and correlating the halves.
3. **Fuse** the metrics by inverse-variance weighting, so noisier measurements
   count for less.
4. Report the result as a value **and an interval**, because a rookie with 200
   minutes and a starter with 2,400 minutes should not be quoted with the same
   confidence.

Scottie Pippen is the point of the name. He is the canonical player whose box
score understated what he did, and whose value showed up in what happened to the
team when he played. That gap is the thing this project measures.

## What this is not

- **Not a betting tool.** No odds, no spreads, no bankroll advice.
- **Not a replacement for DARKO or EPM.** Those are excellent and this project
  measures itself against them rather than claiming to beat them.
- **Not a redistribution of anyone's paid data.** See [Data and licensing](#data-and-licensing).
- **Not validated yet.** The headline claim below is a hypothesis under test, not
  a result.

## The claim under test

> Does PIPPEN predict next-season team net rating better than any single input
> metric does, out of sample?

If the answer is no, the fusion added nothing, and this README will say so.
Stating a falsifiable claim before running the experiment is the point.

---

## Installation

```bash
pip install pippen
```

Development install, using [uv](https://docs.astral.sh/uv/):

```bash
git clone https://github.com/AlphaNerdFx/pippen
cd pippen
uv sync --extra dev
uv run pippen --help
```

Optional extras: `sources` (data downloaders), `fit` (model fitting), `api`,
`dashboard`, `docs`.

## Quickstart

```bash
pippen paths                              # where data will be cached
pippen fetch  --seasons 2015-2024         # download play-by-play and box scores
pippen rapm   --seasons 2015-2024 --window 3
pippen train
pippen evaluate                           # runs the claim under test
```

---

## Data and licensing

The code is **Apache-2.0**. Published data artifacts are **CC BY 4.0**.

The rule this project follows without exception:

> **If a value was not computed from a source that permits redistribution, it does
> not go into a release.**

| Input | Source | Position |
|---|---|---|
| RAPM (own) | Computed from possession data | Ours. Published. |
| Four Factors, Net Rating, box-score rates | [hoopR-nba-data](https://github.com/sportsdataverse/hoopR-nba-data), CC BY 4.0 | Published, with attribution. |
| Tracking features | `nba_api` | Derived features only. Raw responses are never redistributed. |
| BPM, VORP, Win Shares | Basketball-Reference | **Local validation only.** Never in a release artifact. |
| EPM, DARKO | Dunks & Threes, darko.app | **Not used.** Paywalled or unlicensed. Compared by rank correlation only. |

NBA data carries usage restrictions. This project is for personal and research
use. Commercial use of the underlying league data requires licensing from the
rights holders, which this project does not grant and cannot grant.

### Attribution

Bulk historical play-by-play comes from **hoopR-nba-data** by the
SportsDataverse authors, used under CC BY 4.0. Possession and lineup
reconstruction uses **[pbpstats](https://github.com/dblackrun/pbpstats)** by
Darryl Blackport, MIT licensed.

---

## Documentation

Full documentation, including the method write-up and its limitations, lives at
<https://alphanerdfx.github.io/pippen/>.

- [Method](docs/methodology/) — how reliability is measured and how fusion works
- [Architecture](docs/architecture/) — pipeline stages and data layout
- [Research notes](docs/research/) — the background survey this project grew from

## Contributing

Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), and note
that this project ships a [Code of Conduct](CODE_OF_CONDUCT.md).

## License

Apache License 2.0. See [LICENSE](LICENSE).
