stathead 0.1.0__py3-none-any.whl

stathead/__init__.py

@@ -0,0 +1,43 @@
+"""StatHead — Python client for the fantasy football model.
+
+Loaders return pandas DataFrames sourced from the upstream repo at
+https://github.com/dachhack/stathead. First call downloads + caches the
+underlying JSON/CSV; subsequent calls read from the cache.
+
+Quick start:
+
+    import stathead as sh
+
+    rookies = sh.load_career_predictions_2026()
+    backtest = sh.load_career_backtest()
+    adp = sh.load_adp_historical()
+    ktc = sh.load_ktc()
+
+Pin to a specific commit for reproducibility:
+
+    sh.pin_version("a6720e5")  # or any git ref/tag/SHA
+"""
+from ._fetch import clear_cache, pin_version, set_ref
+from .adp import load_adp_ffc, load_adp_historical
+from .features import load_feature_matrix, load_manual_overrides
+from .ktc import load_ktc, load_ktc_history
+from .predictions import load_career_backtest, load_career_predictions_2026
+from .prospects import load_prospect_grades
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "clear_cache",
+    "pin_version",
+    "set_ref",
+    "load_adp_ffc",
+    "load_adp_historical",
+    "load_career_backtest",
+    "load_career_predictions_2026",
+    "load_feature_matrix",
+    "load_ktc",
+    "load_ktc_history",
+    "load_manual_overrides",
+    "load_prospect_grades",
+]

stathead/_fetch.py

@@ -0,0 +1,89 @@
+"""Fetch + on-disk cache for files hosted in the stathead repo.
+
+All loaders go through :func:`fetch_json` / :func:`fetch_csv_gz`, which
+resolve the URL against the currently-pinned git ref and cache the raw
+bytes under ``~/.cache/stathead/<ref>/<path>``.
+
+Override the ref via :func:`pin_version` (per-session) or the
+``STATHEAD_REF`` env var (per-shell).
+"""
+from __future__ import annotations
+
+import gzip
+import json
+import os
+import shutil
+from pathlib import Path
+from typing import Any
+from urllib.request import Request, urlopen
+
+_BASE_URL = "https://raw.githubusercontent.com/dachhack/stathead"
+_DEFAULT_REF = "main"
+_ref: str = os.environ.get("STATHEAD_REF", _DEFAULT_REF)
+
+
+def pin_version(ref: str) -> None:
+    """Pin all future loaders to a specific git ref (commit SHA, tag, or
+    branch name). Passing ``"main"`` resets to latest."""
+    set_ref(ref)
+
+
+def set_ref(ref: str) -> None:
+    """Alias of :func:`pin_version` with a clearer name."""
+    global _ref
+    _ref = ref
+
+
+def current_ref() -> str:
+    """Return the git ref currently used for fetches."""
+    return _ref
+
+
+def _cache_root() -> Path:
+    try:
+        from platformdirs import user_cache_dir  # type: ignore
+
+        return Path(user_cache_dir("stathead"))
+    except ImportError:
+        root = os.environ.get("XDG_CACHE_HOME")
+        if root:
+            return Path(root) / "stathead"
+        return Path.home() / ".cache" / "stathead"
+
+
+def _cache_path(path: str) -> Path:
+    return _cache_root() / _ref / path
+
+
+def clear_cache(ref: str | None = None) -> None:
+    """Remove cached files for the given ref (default: current ref).
+    Pass ``"*"`` to nuke the entire cache."""
+    if ref == "*":
+        root = _cache_root()
+    else:
+        root = _cache_root() / (ref or _ref)
+    if root.exists():
+        shutil.rmtree(root)
+
+
+def _fetch(path: str) -> bytes:
+    cache = _cache_path(path)
+    if cache.exists():
+        return cache.read_bytes()
+    url = f"{_BASE_URL}/{_ref}/{path}"
+    req = Request(url, headers={"User-Agent": "stathead-py"})
+    with urlopen(req, timeout=60) as resp:  # noqa: S310 — trusted domain
+        data = resp.read()
+    cache.parent.mkdir(parents=True, exist_ok=True)
+    cache.write_bytes(data)
+    return data
+
+
+def fetch_json(path: str) -> Any:
+    """Fetch a JSON file from the repo and parse it."""
+    return json.loads(_fetch(path).decode("utf-8"))
+
+
+def fetch_csv_gz(path: str) -> bytes:
+    """Fetch a .csv.gz file and return the decompressed CSV bytes."""
+    return gzip.decompress(_fetch(path))

stathead/adp.py

@@ -0,0 +1,67 @@
+"""ADP loaders — historical (all seasons, model training data) + FFC raw."""
+from __future__ import annotations
+
+import pandas as pd
+
+from ._fetch import fetch_json
+
+
+def load_adp_historical() -> pd.DataFrame:
+    """Historical ADP used in model training, fully populated 2010-2025.
+
+    Sourced from the feature-store profile + players shards (already
+    normalized across sources — this is the ADP the model actually trains
+    on, not a single vendor's raw response).
+
+    Columns: ``season``, ``name``, ``name_norm``, ``position``, ``adp``,
+    ``adpRound``, ``nflDraftPick``, ``nflDraftRound``, ``age``,
+    ``yearsInLeague``.
+
+    Use this for any cross-year ADP analysis — it has no gaps.
+    """
+    profile = fetch_json("public/data/feature-store/profile.json")
+    players = fetch_json("public/data/feature-store/players.json")
+    rows: list[dict] = []
+    for key, rec in profile.items():
+        if "::" not in key:
+            continue
+        name_norm, season_str = key.rsplit("::", 1)
+        try:
+            season = int(season_str)
+        except ValueError:
+            continue
+        info = players.get(key) or {}
+        rows.append({
+            "season": season,
+            "name": info.get("displayName", name_norm),
+            "name_norm": name_norm,
+            "position": info.get("position"),
+            "adp": rec.get("adp"),
+            "adpRound": rec.get("adpRound"),
+            "nflDraftPick": rec.get("nflDraftPick"),
+            "nflDraftRound": rec.get("nflDraftRound"),
+            "age": rec.get("age"),
+            "yearsInLeague": rec.get("yearsInLeague"),
+        })
+    return pd.DataFrame(rows).sort_values(["season", "adp"], na_position="last").reset_index(drop=True)
+
+
+def load_adp_ffc(season: int | None = None) -> pd.DataFrame:
+    """FantasyFootballCalculator PPR ADP — raw API responses.
+
+    Coverage depends on what has been fetched into the repo (currently 2025).
+    Pass a ``season`` to filter, or leave ``None`` to load everything available.
+
+    Columns: ``season``, ``name``, ``position``, ``team``, ``adp``, ``high``,
+    ``low``, ``stdev``, ``timesDrafted``, ``bye``.
+    """
+    seasons = [season] if season else [2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025, 2026]
+    rows: list[dict] = []
+    for s in seasons:
+        try:
+            d = fetch_json(f"public/data/ffc_adp_ppr_{s}.json")
+        except Exception:
+            continue
+        for p in d.get("players") or []:
+            rows.append({"season": s, **p})
+    return pd.DataFrame(rows)

stathead/features.py

@@ -0,0 +1,27 @@
+"""Raw feature matrix + manual feature overrides used by the pipeline."""
+from __future__ import annotations
+
+from typing import Any
+
+from ._fetch import fetch_json
+
+
+def load_feature_matrix() -> dict[str, Any]:
+    """Return the full ``feature-matrix.json`` as a dict.
+
+    The file contains many sub-structures (``careerPredictions2026``,
+    ``predRows``, ``vorNorm``, schema-per-position, etc.). Most users want
+    :func:`~stathead.load_career_predictions_2026` instead — this is an
+    escape hatch for advanced introspection.
+    """
+    return fetch_json("public/data/feature-matrix.json")
+
+
+def load_manual_overrides() -> dict[str, Any]:
+    """Manual CFBD usage overrides keyed by ``"Name|POS"``.
+
+    Contains per-season carries / receptions / team totals for players
+    missing from CFBD's player-usage file (Odell Beckham Jr., Duke Johnson,
+    Todd Gurley, etc.). See ``scripts/backfill_cfbd_variants.py``.
+    """
+    return fetch_json("public/data/manual-cfbd-overrides.json")

stathead/ktc.py

@@ -0,0 +1,66 @@
+"""KeepTradeCut dynasty values — current snapshot + daily history."""
+from __future__ import annotations
+
+import pandas as pd
+
+from ._fetch import fetch_json
+
+
+def load_ktc() -> pd.DataFrame:
+    """Current KTC dynasty values, one row per player.
+
+    The 1QB rankings file carries both the ``value`` (1QB) and
+    ``superflexValue`` in the same record, so a single fetch gives both
+    formats.
+
+    Columns: ``playerID``, ``name``, ``position``, ``positionRank``, ``team``,
+    ``age``, ``value_1qb``, ``value_superflex``, ``isRookie``.
+    """
+    raw = fetch_json("public/data/ktc_rankings_1qb.json")
+    rows = [{
+        "playerID": r["playerID"],
+        "name": r["playerName"],
+        "position": r["position"],
+        "positionRank": r.get("positionRank"),
+        "team": r.get("team"),
+        "age": r.get("age"),
+        "value_1qb": r.get("value"),
+        "value_superflex": r.get("superflexValue"),
+        "isRookie": r.get("isRookie", False),
+    } for r in raw]
+    return pd.DataFrame(rows)
+
+
+def load_ktc_history() -> pd.DataFrame:
+    """Daily KTC value history — one row per (playerID, date).
+
+    1QB and Superflex values are emitted side-by-side to make trend /
+    momentum queries easy. ~100k rows (200+ days × 500 players).
+
+    Columns: ``playerID``, ``name``, ``position``, ``team``, ``date``,
+    ``value_1qb``, ``value_superflex``.
+    """
+    current = fetch_json("public/data/ktc_rankings_1qb.json")
+    info_by_id = {r["playerID"]: {
+        "name": r["playerName"], "position": r["position"], "team": r.get("team"),
+    } for r in current}
+
+    history = fetch_json("public/data/ktc_history.json")
+    rows: list[dict] = []
+    for h in history:
+        info = info_by_id.get(h["playerID"], {})
+        sf_map = {p["d"]: p["v"] for p in (h.get("superflex") or {}).get("valueHistory") or []}
+        for p in (h.get("oneQB") or {}).get("valueHistory") or []:
+            rows.append({
+                "playerID": h["playerID"],
+                "name": info.get("name"),
+                "position": info.get("position"),
+                "team": info.get("team"),
+                "date": p["d"],
+                "value_1qb": p["v"],
+                "value_superflex": sf_map.get(p["d"]),
+            })
+    df = pd.DataFrame(rows)
+    if not df.empty:
+        df["date"] = pd.to_datetime(df["date"])
+    return df

stathead/predictions.py

@@ -0,0 +1,46 @@
+"""Rookie career model predictions — 2026 class + historical backtest."""
+from __future__ import annotations
+
+import pandas as pd
+
+from ._fetch import fetch_json
+
+
+def _flatten(row: dict) -> dict:
+    """Lift ``features`` sub-dict into top-level columns."""
+    features = row.pop("features", None) or {}
+    return {**row, **features}
+
+
+def load_career_predictions_2026() -> pd.DataFrame:
+    """2026 draft-class career predictions, one row per scored prospect.
+
+    Columns (non-exhaustive): ``name``, ``position``, ``adp``, ``team``,
+    ``predictedCareerPPG``, ``percentile``, ``modelTier``, ``boomProb``,
+    ``bustProb``, ``boomZ``, ``bustZ``, plus every feature in the model
+    (``collegeDominatorRating``, ``collegeUsageOverall``, ``rspDotDraft``,
+    ``pdfRankOverallMean``, ``recruitRating``, ``relativeAthleticScore``, …).
+    """
+    fm = fetch_json("public/data/feature-matrix.json")
+    rows = [_flatten(dict(p)) for p in fm.get("careerPredictions2026") or []]
+    return pd.DataFrame(rows)
+
+
+def load_career_backtest() -> pd.DataFrame:
+    """Historical rookie backtest rows (2010-2025) with predictedPPG + actualPPG.
+
+    Used to evaluate the career model (both the precomputed tier system and
+    the GBM + Ridge ensemble). One row per drafted prospect across QB/RB/WR/TE.
+
+    Columns: ``name``, ``position``, ``draftSeason``, ``predictedPPG``,
+    ``actualPPG``, ``percentile``, ``modelTier``, ``combinedScore``,
+    plus every feature used in training.
+    """
+    cache = fetch_json("public/data/model-cache-career-v72.json")
+    out: list[dict] = []
+    for pos, model in (cache.get("rookieCareerModels") or {}).items():
+        for r in model.get("backtestRows") or []:
+            row = dict(r)
+            row.setdefault("position", pos)
+            out.append(_flatten(row))
+    return pd.DataFrame(out)

stathead/prospects.py

@@ -0,0 +1,18 @@
+"""2026 draft prospect scouting grades (NFL.com / PFN composite)."""
+from __future__ import annotations
+
+import pandas as pd
+
+from ._fetch import fetch_json
+
+
+def load_prospect_grades(year: int = 2026) -> pd.DataFrame:
+    """NFL draft prospect scouting grades for the given class.
+
+    Currently only ``year=2026`` is distributed with the repo.
+
+    Columns: ``name``, ``pos``, ``school``, ``grade``, ``projRound``,
+    ``projPick``, ``tier``.
+    """
+    data = fetch_json(f"src/data/prospect-grades-{year}.json")
+    return pd.DataFrame(data)

stathead-0.1.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: stathead
+Version: 0.1.0
+Summary: Python client for the StatHead fantasy football model — rookie career predictions, historical ADP, dynasty values, and flattened feature matrices.
+Project-URL: Homepage, https://github.com/dachhack/stathead
+Project-URL: Source, https://github.com/dachhack/stathead
+Project-URL: Issues, https://github.com/dachhack/stathead/issues
+Author: StatHead
+License: MIT
+Keywords: adp,dynasty,fantasy-football,ktc,nfl,rookie-prospects
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Requires-Dist: pandas>=1.5
+Provides-Extra: dev
+Requires-Dist: duckdb>=0.10; extra == 'dev'
+Requires-Dist: polars>=0.20; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=0.10; extra == 'duckdb'
+Provides-Extra: polars
+Requires-Dist: polars>=0.20; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# stathead
+
+Python client for the [StatHead](https://github.com/dachhack/stathead) fantasy football model. Returns pandas DataFrames of rookie career predictions, historical ADP, KeepTradeCut dynasty values, and the flattened feature matrix used to train the models.
+
+## Install
+
+```bash
+pip install stathead
+```
+
+Optional extras:
+
+```bash
+pip install "stathead[polars]"   # for .to_polars() helpers
+pip install "stathead[duckdb]"   # for local SQL querying
+```
+
+## Quick start
+
+```python
+import stathead as sh
+
+# 2026 rookie class predictions (77 players × ~80 columns)
+rookies = sh.load_career_predictions_2026()
+rookies.nlargest(10, "percentile")[["name", "position", "predictedCareerPPG", "modelTier"]]
+
+# Historical backtest — predicted vs actual for every drafted rookie 2010-2025
+backtest = sh.load_career_backtest()
+wr = backtest[backtest.position == "WR"]
+wr.groupby("modelTier")[["actualPPG", "predictedPPG"]].mean()
+
+# Historical ADP, every season fully populated
+adp = sh.load_adp_historical()
+adp[(adp.season == 2023) & (adp.adp <= 24)]
+
+# Dynasty values
+ktc = sh.load_ktc()
+ktc.nlargest(25, "value_1qb")
+
+# Daily KTC history (for momentum / trend analysis)
+hist = sh.load_ktc_history()
+hist.pivot_table(index="date", columns="name", values="value_1qb")
+```
+
+## Pinning to a specific version
+
+Loaders resolve against the upstream GitHub repo. Pin to a commit SHA, tag,
+or branch for reproducibility:
+
+```python
+sh.pin_version("a6720e5")   # or a tagged release
+```
+
+Clear the local cache if you want to re-fetch:
+
+```python
+sh.clear_cache()
+```
+
+## Data freshness
+
+Data files are cached under `~/.cache/stathead/<ref>/` after the first
+download. Subsequent runs read from disk — no network roundtrip. Delete the
+cache directory or call `clear_cache()` to force a refresh.
+
+## Available loaders
+
+| Function | Returns | Shape |
+|---|---|---|
+| `load_career_predictions_2026()` | 2026 rookie predictions | ~77 × ~80 cols |
+| `load_career_backtest()` | Historical rookies with pred + actual PPG | ~1087 × ~100 cols |
+| `load_adp_historical()` | Model-training ADP 2010-2025 | 4507 × 10 |
+| `load_adp_ffc(season=None)` | FFC PPR raw ADP (per season as fetched) | variable |
+| `load_ktc()` | Current KTC dynasty values | ~500 × 9 |
+| `load_ktc_history()` | Daily KTC history | ~100k × 7 |
+| `load_prospect_grades(year=2026)` | Draft scouting grades | ~200 × 7 |
+| `load_feature_matrix()` | Raw `feature-matrix.json` (dict) | — |
+| `load_manual_overrides()` | Manual CFBD usage overrides (dict) | — |
+
+## Licensing & attribution
+
+Package code is MIT-licensed. The data this package retrieves is derived
+from the StatHead project's own modeling pipeline; upstream sources
+(nflverse, FFC, KeepTradeCut, CFBD, etc.) retain their own terms — see
+each source's license before redistributing. If you're building on these
+predictions, a link back to the StatHead repo is appreciated but not
+required.
+
+## Contributing
+
+The package is small and focused — see
+[`python/src/stathead/`](./src/stathead/) for the loader modules. Issues
+and PRs welcome at the [main repo](https://github.com/dachhack/stathead).

stathead-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+stathead/__init__.py,sha256=X2NGm7sIIBHtkpvwQwOZBVMxJsSmX8z9J2x-GRTjBgg,1238
+stathead/_fetch.py,sha256=XzCxKIRuZGUou3XQYdnPNhTBTP5hTZ71gLc6qKRnKLU,2539
+stathead/adp.py,sha256=YFR9lRyRYBZ8E2_F8Wfn4ny8p184rLK6k5Am2dLR2gE,2533
+stathead/features.py,sha256=Egsg9DcTHaHdGSEwbLZseP2VuMsA6U4A5PoQ2NFhnpM,996
+stathead/ktc.py,sha256=2h99n3gd-YZIpiZrruFAmei-jw_dj_S5Li9kFcno34s,2355
+stathead/predictions.py,sha256=M-ZbM5R2p0h53cJI2HyAYqSoFFf2FpyEzLxR_wD9EfA,1835
+stathead/prospects.py,sha256=YptPFlUq9mNrfYuTml730IN4zJTH_2Yx_pQez-w1sws,546
+stathead-0.1.0.dist-info/METADATA,sha256=ubGM2TQ7cXm84fmDIuR-zDkbS3ABT5O00J5g3T9V5Wc,4307
+stathead-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+stathead-0.1.0.dist-info/RECORD,,

stathead-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any