stathead 0.3.1__tar.gz → 0.3.3__tar.gz

{stathead-0.3.1 → stathead-0.3.3}/.gitignore

@@ -41,6 +41,7 @@ public/data/clay-team-projections-*.json
 !public/data/ktc-forecasts-*.json
 !public/data/redraft-projections.json
 !public/data/projection-base-*.json
+!public/data/weekly-projections-*.json
 !public/data/model-eval-*.json
 !public/data/team-metrics-*.json
 !public/data/coach-tendencies.json
@@ -106,6 +107,12 @@ __pycache__/
 .venv/
 pdfs/
 
+# Footballguys SFB cheatsheet (paid product) — LOCAL-ONLY, never committed.
+# Regenerate from a PDF you own:
+#   pdftotext -layout <cheatsheet.pdf> - | npx tsx scripts/parse-sfb-cheatsheet.ts > public/data/sfb16-cheatsheet.json
+# (already covered by the public/data/* ignore; listed here for discoverability)
+public/data/sfb16-cheatsheet.json
+
 # Proprietary inputs (Clay PDFs + parsed dataset) — never committed.
 /private/
 # Local-only Clay projection set consumed at runtime by the "Consensus" preset.

{stathead-0.3.1 → stathead-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stathead
-Version: 0.3.1
+Version: 0.3.3
 Summary: Python client for the StatHead fantasy football model — rookie career predictions, historical ADP, and flattened feature matrices.
 Project-URL: Homepage, https://github.com/dachhack/stathead
 Project-URL: Source, https://github.com/dachhack/stathead
@@ -154,6 +154,7 @@ available here as a pandas DataFrame.
 | Function | Returns | Shape |
 |---|---|---|
 | `load_redraft_projections()` | Seasonal redraft PPG (PPR) + receptions/game | ~250 × 7 |
+| `load_weekly_projections()` | Per-week matchup-adjusted projections incl. kickers + team DST, one row per player-game (opp, home, matchup mult, PPR pts, gsis/sleeper ids; `df.attrs['def_vs_pos']`) | ~509 × 17 rows/player |
 | `load_ppg_projections()` | Model-predicted PPG for established players | ~250 × 4 |
 | `load_adp_value_model()` | VOR vs ADP, hit probability, confidence interval | ~153 × 10 |
 | `load_volume_projections()` | Team pass/rush/target volumes with low/high bands | ~153 × ~14 |

{stathead-0.3.1 → stathead-0.3.3}/README.md

@@ -126,6 +126,7 @@ available here as a pandas DataFrame.
 | Function | Returns | Shape |
 |---|---|---|
 | `load_redraft_projections()` | Seasonal redraft PPG (PPR) + receptions/game | ~250 × 7 |
+| `load_weekly_projections()` | Per-week matchup-adjusted projections incl. kickers + team DST, one row per player-game (opp, home, matchup mult, PPR pts, gsis/sleeper ids; `df.attrs['def_vs_pos']`) | ~509 × 17 rows/player |
 | `load_ppg_projections()` | Model-predicted PPG for established players | ~250 × 4 |
 | `load_adp_value_model()` | VOR vs ADP, hit probability, confidence interval | ~153 × 10 |
 | `load_volume_projections()` | Team pass/rush/target volumes with low/high bands | ~153 × ~14 |

{stathead-0.3.1 → stathead-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stathead"
-version = "0.3.1"
+version = "0.3.3"
 description = "Python client for the StatHead fantasy football model — rookie career predictions, historical ADP, and flattened feature matrices."
 readme = "README.md"
 license = { text = "MIT" }

{stathead-0.3.1 → stathead-0.3.3}/src/stathead/__init__.py

@@ -35,13 +35,14 @@ from .projections import (
     load_share_projections,
     load_taxi_predictions,
     load_volume_projections,
+    load_weekly_projections,
 )
 from .polars import load_polars, to_polars
 from .prospects import load_prospect_grades
 from .sql import list_tables, query, register
 from .stats import load_player_stats
 
-__version__ = "0.3.1"
+__version__ = "0.3.3"
 
 __all__ = [
     "__version__",
@@ -67,6 +68,7 @@ __all__ = [
     "load_share_projections",
     "load_taxi_predictions",
     "load_volume_projections",
+    "load_weekly_projections",
     "get_player",
     "resolve_player",
     "query",

{stathead-0.3.1 → stathead-0.3.3}/src/stathead/projections.py

@@ -45,6 +45,69 @@ def load_redraft_projections() -> pd.DataFrame:
     return _stamp_keys(df)
 
 
+def load_weekly_projections() -> pd.DataFrame:
+    """Per-week 2026 projections — the season projection split across the
+    schedule, one row per player per scheduled game (17 rows/player; byes
+    omitted). Covers QB/RB/WR/TE plus kickers (position ``K``, the current
+    depth-chart PK1 per team) and team defenses (position ``DST``, name
+    ``"<TEAM> DST"``, ``sleeper_id`` = team code).
+
+    Weekly points = season PPG x opponent defense-vs-position multiplier
+    (prior-season PPR allowed per game vs league average, heavily regressed)
+    x home/away nudge, normalized per team so the 17 games sum back to the
+    season line. Points assume the player plays; ``gp`` carries the season
+    games (health) discount. Half/Std conversion: weekly receptions scale
+    with the same multiplier, so ``rec_w = recPG * proj_ppr / ppg``.
+
+    Columns: ``player_key``, ``name``, ``position``, ``team``, ``gsis_id``,
+    ``sleeper_id``, ``week``, ``opp``, ``home``, ``matchup_mult``,
+    ``proj_ppr``, ``ppg``, ``recPG``, ``gp``, ``season``. The gsis/sleeper
+    ids are stamped at build time from the player crosswalk (None for
+    pre-NFL rookies).
+
+    Metadata on ``df.attrs``: ``meta`` (generatedAt + method note) and
+    ``def_vs_pos`` (per-team defense-vs-position multiplier table).
+    """
+    data = fetch_json("public/data/weekly-projections-2026.json")
+    team_weeks = {
+        team: {g["w"]: g for g in games}
+        for team, games in (data.get("teamWeeks") or {}).items()
+    }
+    def_vs_pos = data.get("defVsPos") or {}
+    rows = []
+    for p in data.get("players") or []:
+        sched = team_weeks.get(p["team"], {})
+        for i, pts in enumerate(p["wk"]):
+            week = i + 1
+            game = sched.get(week)
+            if pts is None or game is None:
+                continue
+            rows.append({
+                "name": p["name"],
+                "position": p["pos"],
+                "team": p["team"],
+                "gsis_id": p.get("gsis"),
+                "sleeper_id": p.get("sleeper"),
+                "week": week,
+                "opp": game["opp"],
+                "home": game["home"],
+                "matchup_mult": def_vs_pos.get(game["opp"], {}).get(p["pos"]),
+                "proj_ppr": pts,
+                "ppg": p["ppg"],
+                "recPG": p["recPG"],
+                "gp": p["gp"],
+            })
+    df = pd.DataFrame(rows)
+    df["season"] = data.get("season")
+    df = _stamp_keys(df)
+    df.attrs["meta"] = {
+        "generatedAt": data.get("generatedAt"),
+        "note": data.get("note"),
+    }
+    df.attrs["def_vs_pos"] = def_vs_pos
+    return df
+
+
 def load_ppg_projections() -> pd.DataFrame:
     """Model-predicted points-per-game for established players.
 

{stathead-0.3.1 → stathead-0.3.3}/tests/test_smoke.py

@@ -131,6 +131,25 @@ def test_redraft_projections():
     assert {"player_key", "name", "position", "ppg", "recPG"}.issubset(df.columns)
 
 
+def test_weekly_projections():
+    df = stathead.load_weekly_projections()
+    assert not df.empty
+    assert {"player_key", "name", "position", "team", "week", "opp", "home",
+            "matchup_mult", "proj_ppr", "ppg", "gp"}.issubset(df.columns)
+    # 17 scheduled games per player (byes omitted), weeks within 1-18.
+    assert (df.groupby("name")["week"].count() == 17).all()
+    assert df["week"].between(1, 18).all()
+    # Normalization: weekly points sum back to ppg * 17 for every player.
+    sums = df.groupby("name").agg(total=("proj_ppr", "sum"), ppg=("ppg", "first"))
+    assert ((sums["total"] - sums["ppg"] * 17).abs() < 1.0).all()
+    assert isinstance(df.attrs.get("def_vs_pos"), dict)
+    # K + DST: one per team, 32 each.
+    assert (df[df["position"] == "K"]["team"].nunique()) == 32
+    dst = df[df["position"] == "DST"]
+    assert dst["team"].nunique() == 32
+    assert (dst["sleeper_id"] == dst["team"]).all()
+
+
 def test_ppg_and_adp_value_model():
     ppg = stathead.load_ppg_projections()
     adp = stathead.load_adp_value_model()