stathead 0.3.2__tar.gz → 0.3.4__tar.gz

{stathead-0.3.2 → stathead-0.3.4}/.gitignore

@@ -18,6 +18,7 @@ public/data/clay-projections-*.json
 public/data/clay-unit-grades-*.json
 public/data/clay-matchups-*.json
 public/data/clay-team-projections-*.json
+!public/data/tankathon-2027.json
 !public/data/training-rows-cache-*.json
 !public/data/trained-models-cache-*.json
 !public/data/model-cache-*.json
@@ -42,6 +43,20 @@ public/data/clay-team-projections-*.json
 !public/data/redraft-projections.json
 !public/data/projection-base-*.json
 !public/data/weekly-projections-*.json
+!public/data/kicker-projections-*.json
+!public/data/dst-projections-*.json
+!public/data/idp-projections-*.json
+!public/data/return-projections-*.json
+!public/data/fb-projections-*.json
+!public/data/punter-projections-*.json
+!public/data/hc-projections-*.json
+!public/data/coach-overrides.json
+# Market lines, derived from nflverse's schedule (scripts/build-odds-from-schedule.mjs)
+!public/data/odds_nfl_lines.json
+!public/data/schedule-strength-*.json
+# Weekly archive of what we projected, for next offseason's backtests
+# (refresh-data.yml, Tuesdays). Small, gzipped, append-only.
+!public/data/projection-history/
 !public/data/model-eval-*.json
 !public/data/team-metrics-*.json
 !public/data/coach-tendencies.json
@@ -119,7 +134,25 @@ public/data/sfb16-cheatsheet.json
 # Never committed — absent in the public deploy so Clay's numbers ship nowhere.
 /public/data/clay/
 
+# Workbooks written by the MCP's export_excel tool. With no `path` argument it
+# writes stathead-<kind>-<tag>-<date>.xlsx into process.cwd(), which is the repo
+# root whenever the server runs from a checkout (`npm run mcp`) — so ordinary
+# use litters untracked exports here. They're generated output, never sources.
+/stathead-*.xlsx
+
 # Downloaded headshot images
 headshots.zip
 headshots_part*.zip
 !public/data/depth-starters-*.json
+# Fitted abandonment-hazard weights. StatHead's own model output — no
+# per-manager data — so it ships with the app. The population it was fitted on
+# does not (see docs/sleeper-engagement-model.md).
+!public/data/abandonment-model-v*.json
+!public/data/dynasty-departure-*.json
+
+# Engagement reporting suite — generated audit reports are reproducible from
+# their input, and crawled Sleeper populations contain per-manager behavioural
+# data on named real people (see docs/sleeper-engagement-model.md). Neither is
+# committed: reports go up as CI artifacts, populations stay local.
+reports/
+sleeper-population*.json

{stathead-0.3.2 → stathead-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: stathead
-Version: 0.3.2
+Version: 0.3.4
 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,7 +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, one row per player-game (opp, home, matchup mult, PPR pts; `df.attrs['def_vs_pos']`) | ~445 × 17 rows/player |
+| `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, depth-chart rank, roster `status`/`active` — IR/exempt/practice-squad rows are zeroed from the current week with the conditional number in `proj_ppr_if_active` — and a `backup` flag for 1–3 game lines; `df.attrs['def_vs_pos']`, `df.attrs['meta']['currentWeek']`) | ~780 × 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.2 → stathead-0.3.4}/README.md

@@ -126,7 +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, one row per player-game (opp, home, matchup mult, PPR pts; `df.attrs['def_vs_pos']`) | ~445 × 17 rows/player |
+| `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, depth-chart rank, roster `status`/`active` — IR/exempt/practice-squad rows are zeroed from the current week with the conditional number in `proj_ppr_if_active` — and a `backup` flag for 1–3 game lines; `df.attrs['def_vs_pos']`, `df.attrs['meta']['currentWeek']`) | ~780 × 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.2 → stathead-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stathead"
-version = "0.3.2"
+version = "0.3.4"
 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.2 → stathead-0.3.4}/src/stathead/__init__.py

@@ -42,7 +42,7 @@ from .prospects import load_prospect_grades
 from .sql import list_tables, query, register
 from .stats import load_player_stats
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"
 
 __all__ = [
     "__version__",

{stathead-0.3.2 → stathead-0.3.4}/src/stathead/projections.py

@@ -48,7 +48,9 @@ def load_redraft_projections() -> pd.DataFrame:
 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).
+    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)
@@ -57,12 +59,28 @@ def load_weekly_projections() -> pd.DataFrame:
     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``, ``week``,
-    ``opp``, ``home``, ``matchup_mult``, ``proj_ppr``, ``ppg``, ``recPG``,
-    ``gp``, ``season``.
-
-    Metadata on ``df.attrs``: ``meta`` (generatedAt + method note) and
-    ``def_vs_pos`` (per-team defense-vs-position multiplier table).
+    Roster status (QB/RB/WR/TE, from the nflverse roster at build time):
+    ``status`` is ``ACT`` / ``RES`` (IR, PUP, NFI) / ``EXE`` (commissioner
+    exempt) / ``DEV`` (practice squad) / ``INA`` (game-day inactive) /
+    ``FA`` (unrostered), or None for K/DST/IDP rows. ``active`` is False for
+    RES/EXE/DEV/FA rows, whose ``proj_ppr`` is 0 from the current week on;
+    ``proj_ppr_if_active`` on those rows is the un-zeroed conditional
+    number (NaN elsewhere). Retired and cut players carry no rows.
+    ``backup`` is True for a 1-3 game season line on a depth-2+ player:
+    ``proj_ppr`` is then a per-game rate conditional on playing, not an
+    expectation of starting — rank those below starters. ``depth`` is the
+    position rank on the newest nflverse depth chart (1 = starter).
+
+    Columns: ``player_key``, ``name``, ``position``, ``team``, ``gsis_id``,
+    ``sleeper_id``, ``depth``, ``status``, ``active``, ``backup``, ``week``,
+    ``opp``, ``home``, ``matchup_mult``, ``proj_ppr``, ``proj_ppr_if_active``,
+    ``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,
+    ``playedThrough`` = last week with every game final, ``currentWeek``,
+    ``statusNote``) and ``def_vs_pos`` (per-team defense-vs-position
+    multiplier table).
     """
     data = fetch_json("public/data/weekly-projections-2026.json")
     team_weeks = {
@@ -73,6 +91,7 @@ def load_weekly_projections() -> pd.DataFrame:
     rows = []
     for p in data.get("players") or []:
         sched = team_weeks.get(p["team"], {})
+        if_active = p.get("wkIfActive")
         for i, pts in enumerate(p["wk"]):
             week = i + 1
             game = sched.get(week)
@@ -82,11 +101,18 @@ def load_weekly_projections() -> pd.DataFrame:
                 "name": p["name"],
                 "position": p["pos"],
                 "team": p["team"],
+                "gsis_id": p.get("gsis"),
+                "sleeper_id": p.get("sleeper"),
+                "depth": p.get("depth"),
+                "status": p.get("status"),
+                "active": p.get("active", True),
+                "backup": bool(p.get("backup", False)),
                 "week": week,
                 "opp": game["opp"],
                 "home": game["home"],
                 "matchup_mult": def_vs_pos.get(game["opp"], {}).get(p["pos"]),
                 "proj_ppr": pts,
+                "proj_ppr_if_active": if_active[i] if if_active else None,
                 "ppg": p["ppg"],
                 "recPG": p["recPG"],
                 "gp": p["gp"],
@@ -97,6 +123,9 @@ def load_weekly_projections() -> pd.DataFrame:
     df.attrs["meta"] = {
         "generatedAt": data.get("generatedAt"),
         "note": data.get("note"),
+        "playedThrough": data.get("playedThrough"),
+        "currentWeek": data.get("currentWeek"),
+        "statusNote": data.get("statusNote"),
     }
     df.attrs["def_vs_pos"] = def_vs_pos
     return df

{stathead-0.3.2 → stathead-0.3.4}/tests/test_smoke.py

@@ -135,7 +135,20 @@ 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)
+            "matchup_mult", "proj_ppr", "ppg", "gp",
+            "depth", "status", "active", "backup", "proj_ppr_if_active"}.issubset(df.columns)
+    # Roster status only applies to skill positions; K/DST/IDP rows are None.
+    assert df.loc[df["position"].isin(["QB", "RB", "WR", "TE"]) & df["status"].notna(), "status"].isin(
+        ["ACT", "RES", "EXE", "DEV", "INA", "FA"]).all()
+    assert df["active"].dtype == bool and df["backup"].dtype == bool
+    # Inactive rows are zeroed from the current week on; the conditional strip
+    # rides along so a consumer can redistribute what was vacated.
+    inactive = df[~df["active"]]
+    if not inactive.empty:
+        assert (inactive["proj_ppr"] == 0).any()
+        assert inactive["proj_ppr_if_active"].notna().all()
+    # Normalization below only holds for rows the builder did not zero.
+    df = df[df["active"]]
     # 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()
@@ -143,6 +156,11 @@ def test_weekly_projections():
     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():