Project context

GLAX pipeline — project context & roadmap

Results-anchored, stat-informed rankings for Missouri girls HS lacrosse. Complements powerwise_lax (published Powerwise pairwise method); see docs/ALGORITHMS.md. Connects team strength, individual production, and next-season / scheduling risk.

Keep this document updated as tasks complete. Domain math lives in composite_score.py; data lives in source-data/; runnable pipeline is run_glax_analysis.py.

Why we are building this

Problem

1. Team strength is often summarized by win–loss and ranking systems (Powerwise, RPI, etc.), but coaches and ADs also care about how a team wins (offense, defense, possession) and whether margins are sustainable.

2. Graduation and roster turnover change competitive balance. A team ranked 16th can look very different in August if its top three scorers and starting goalie graduate. We need a structured way to estimate how much team power walks off the field, not just “they were 16th last year.”

3. Scheduling should reduce predictable blowouts where possible. That requires an estimate of expected score delta between two teams after roster change—not only last year’s final rank.

What success looks like

Design principles (do not break these)

1. Anchor strength on game results only — finish tiers (1–4, 5–8, 9–16, 17–32) from finish_2026.tsv / finish_2025.tsv. League rank and schedule margins do not use composite (Phases A–B, 2026). Box-score domains remain for player impact and board columns only. See docs/PHASE_C_ROADMAP.md for retiring composite from coach exports.

2. Two separate metrics - Team power — three domains (offense, defense, possession). - Player impact on team power — SOS-weighted share of production + defense (goalies).

3. Context weighting — stats vs weak opponents count less (tier SOS × game leverage).

4. Subtract → adjust rank off prior — graduation uses departure loss % (not composite drop) with capped moves vs prior finish.

5. Scheduling — projected margin ratings (results-only) → expected margin & blowout-risk matrix.

6. Board ranking packet — default recommended rank = roster-adjusted outlook; teams flagged when metrics conflict. Flagged cases get secondary regression (surge, assists, manual notes) before the board votes. See ranking_board_report_*.md.

Run

cd glax-pipeline
python3 fetch_awards.py 2026              # optional: refresh awards_2026.csv
python3 run_glax_analysis.py              # 2025-26 → output/
python3 run_glax_analysis.py --season both   # + backtest → output/backtest_2024_25/
python3 tune_roster_predictor.py             # goal-seek board-line MAE (holdout)
python3 tune_possession_weights.py           # draw / GB / CTO weight grid

Model overview

finish_2026.tsv / finish_2025.tsv  →  tier SOS weights
         ↓
team-game stats + results  →  team power (calibrated possession baseline)
         ↓
player-game stats  →  SOS-weighted impact  →  subtract seniors  →  T′
         ↓
league re-rank + schedule_risk_matrix (expected margin, blowout flag)

Possession baseline: league p90 weighted events/game (~42 for 2025–26), not 10.

Tier SOS: 1.0 / 0.80 / 0.55 / 0.30 for finish tiers 1–4.

Outputs

Task tracker

Phase 1 — Foundation

• [x] Wire GLAX CSVs (glax_data.py, run_glax_analysis.py)
• [x] Fix domain aggregation ×100 bug
• [x] PROJECT.md + finish_2026.tsv + finish_2025.tsv

Phase 2 — Anchor & calibration

• [x] Finish tier map + anchor.py tier SOS
• [x] Possession baseline from league median
• [x] SOS × leverage on player-game rows

Phase 3 — Two metrics

• [x] team_power_2025_26.csv
• [x] player_impact_2025_26.csv (raw + SOS + power points)
• [x] Goalie/defense slice in player impact & graduation

Phase 4 — League projection & scheduling

• [x] projected_power_2027.csv
• [x] league_rerank_2027.csv
• [x] Margin coefficient k in run_meta.json
• [x] schedule_risk_matrix_2027.csv

Phase 5 — Polish

• [x] sanity_report_2025_26.md
• [x] README updated
• [x] RPI+AGD from results (results_anchor.py, --anchor finish|rpi_agd|blend)

Phase 6 — Backtest

• [x] Full 2024–25 data wired
• [x] output/backtest_2024_25/ pipeline run
• [x] backtest_report.md vs finish_2026.tsv
• [x] Graduation: default damping=1.0 + domain caps (ablation MAE 6.8) + ablation.py
• [x] tests/test_anchor.py — Francis Howell + defense regression tests
• [x] composite_score.py + ScoringConfig (no module-global mutation)
• [x] Position-aware player impact + goalie minutes weighting

Code map

Related files

• docs/archive/ — legacy notes (sample_code_legacy.py, design scratch)
• ../README.md — Powerwise repo
• benchmark.py — prior-finish naive baseline + MAE cohorts
• docs/VALIDATION.md — process & statistics audit guide
• docs/COACH_EXPLAINER.md — coach-friendly explainer of the approach
• docs/presentations/ — slide-deck prompts (coach onboarding, MAE slide, appendix glossary, conference realignment)

Prioritized roadmap (product order)

Work in this sequence. #0 is mandatory on every evaluation before claiming the model adds value.

#0 — Prior-year finish benchmark (default expectation)

• [x] Implemented: benchmark.py; backtest_report.md compares Prior finish (2025) vs Graduation model with MAE for all / top-8 / top-16 / top-20; output/benchmark_2027.md for forward outlook vs naive carry-forward.
• Definition: Next-year rank = last year’s finish_*.tsv rank (what schedulers and coaches already use).
• Why: Unfair to rebuild programs (strong senior class leaves → still scheduled as elite) and too easy for legacy programs (long-term contenders keep soft schedules on reputation). The model must beat or justify this baseline.
• Primary metric: Top-20 finish MAE (scheduling and league balance focus).
• Roster-adjusted model (prior + capped turnover) beats naive on top-20 / top-16 / top-8 in backtest; all-teams MAE still slightly behind naive (~3.1 vs 2.7).

#1 — Missouri-only league set (drop out-of-state from ranking)

• [x] League pool = finish_*.tsv teams — team_power, player_impact, graduation, league_rerank, and schedule_risk_matrix are MO-only (e.g. Wentzville and all IL/KY/TN opponents excluded from ranks).
• [x] OOS games excluded from ranking stats: player/team game rows and results used for composite, SOS/RPI, and leverage only when both teams are in finish.tsv (in-state league). OOS exhibitions are dropped (often not played to win / incomplete rosters).
• [x] run_meta.json lists excluded_from_league_ranking and non_league_opponents_in_results; margin k fit on MO vs MO games only.
• Why: Rankings and blowout-risk are for the MO girls D1 scheduling pool, not national opponents.

#2 — Graduation, roster turnover & legacy team score (primary predictor path)

Rank outlook = prior finish + capped roster move, not full composite re-sort. Box-score domain weights and composite sort amplify noise; turnover + returning production + legacy explain adjustments off last year.

• [x] Roster-adjusted finish rank: roster_rank_predictor.py; league_rerank_*.csv uses projected_league_rank; projected_league_rank_composite kept for comparison.
• [x] Returning production share (offense / possession / defense) in graduation output + projected CSV.
• [x] Replacement-level subtraction: max(share − baseline[position], 0); baselines calibrated from 2024-25 + 2025-26 non-senior SOS shares (roster_projection.py, get_replacement_baselines()).
• [x] Concentration risk: extra offense loss when a departing senior held ≥32% SOS goals.
• [x] Class-year depth: junior/soph SOS goal share reduces projected senior loss (up to ~30%).
• [x] Goalie continuity: boost defense loss when starter goalie leaves with <22% backup minutes.
• [x] Legacy program prior: multi-year finish_*.tsv → legacy_program_priors.csv + small composite nudge on projection (LEGACY_COMPOSITE_WEIGHT=0.12).
• [x] Board outlier flags: ranking_outliers.py → recommendations CSV, outliers CSV, ranking_board_report_*.md (automated each pipeline run).
• [x] Secondary regression on flagged teams: secondary_regression.py → recommended_rank_adjusted (late surge, legacy pull, feeders, draw %).
• [x] Manual program notes / board override: board_overrides_{label}.csv → program_notes, board_voted_rank, final_rank.
• [x] Late-season underclass surge: roster_stats.py in graduation + secondary (last-third goal share).
• [x] Assist rate / feeder–scorer: team_assist_rate, feeder_pair_departing, offense concentration.
• [x] Draw control %: returning_draw_pct / departing_draw_pct + possession loss relief.
• [x] Per-player departure loss: graduation_player_loss_{season}.csv.

#3 — SOS accuracy for top-20 teams

• [x] Smooth SOS: smooth_finish_sos_weight (log-scaled rank → [0.30, 1.00]); default --anchor finish. Use --anchor finish_tier for legacy cliffs.
• [x] Top-20 matchup boost: +8% context weight when both teams are finish rank ≤ 20 (TOP20_SOS_BOOST).
• [x] Metro-east IL in league pool: Belleville West, Edwardsville, O'Fallon in finish_*.tsv (games count toward ranking).
• [x] RPI fallback: SOS opponent rank from RPI strength for teams not in finish.tsv (resolve_opponent_sos_rank); RPI pool = all results games (incl. OOS exhibitions).
• [x] Rolling in-season RPI: rolling_rpi_{season}.csv — snapshot after each date using games before that date.
• [x] Game-rooted margin stats: game_margin_stats.py → game_margin_stats_{season}.csv + columns on team_power_* / board packet (avg_margin_vs_top16, margin_std, etc.).
• [x] Margin k vs top-16: margin_k_top16 in run_meta.json (schedule calibration on elite matchups only).
• [x] Tier-conditioned MAE: backtest_benchmark_by_tier.csv, backtest_team_rank_errors.csv, tier table in backtest_report.md.

#4 — Offense / defense recalibration (after MO-only + top-20 SOS focus)

• [x] Percentile calibration per season (domain_calibration.py); anchors in run_meta.json.
• [x] Soft squash offense / possession / defense (p50→~55, p90→~92, soft tail to 100).
• [x] Defense: shot volume + save % separately (45/55), MO sf p20–p80 anchors.
• [x] Skip stat_type=combined rows in team game aggregation.
• [x] Domain weight sensitivity — not useful (top-20 MAE ~4.9–5.0 vs 5.0 default); high box-score variance. Deprioritized.
• [x] Roster-adjusted rank (roster_rank_predictor.py): prior finish + capped turnover (returning %, legacy); composite re-sort is diagnostic only.

#5 — Player awards (STL Lacrosse Awards)

Independent recognition signal for individual talent (not team finish). Source: STL Lacrosse Awards — Results (2026 season is a static snapshot on that site; filter by conference, school, position).

• [x] Ingest awards per season — fetch_awards.py + awards_{year}.csv from https://stl-lacrosse-awards.fly.dev/data/season-results-{year}.json (2026 live; prior years when published).
• [x] Match to GLAX roster (canonical_team_name + normalize_player_name + last-name fallback).
• [x] Team rollup: awards_points, departing_awards_points, returning_awards_points on projected_power_*.csv and board CSVs.
• [x] Graduation: departing award boost + returning award relief on domain losses (awards.py).
• [x] Board packet: departing_awards, returning_awards, flag award_talent_loss (≥5 departing points).
• [x] Backtest: backtest_award_loss_analysis.csv + section in backtest_report.md (when awards_{date_year}.csv exists).

Award tier weights (tuned on 2025-26 holdout → finish_2026): see awards_weights.TUNED_AWARD_WEIGHTS and python3 awards_tune.py.

Board flag award_talent_loss when departing points ≥ 10. Tune grid: output/awards_tune_results.csv.

Follow-up backlog (Opus review + analysis session)

Done since Opus review

• P0 canonicalization, defense GA=0, results-joined goals allowed
• p90 possession baseline, margin k, ablation, ScoringConfig
• Position + goalie minutes; (#) player name strip; damping=1.0 + caps

Still open (reference)

Game-rooted predictors (for #2–#4)

• [x] Capped margin vs top-16 (avg_margin_vs_top16, margin_k_top16)
• [x] Margin consistency (margin_std, margin_std_vs_top16)
• [ ] Goals per possession (efficiency diagnostic)
• [ ] SOS-weighted GA vs elite opponents only
• [ ] H2H nudge within tight composite clusters (optional, results-only)