NBA Team Grader

NBA Team Grader is a team-level evaluation system in the spirit of Basketball Index’s player grades. Roughly 80 granular team attributes (rim pressure, shot quality, rim deterrence, transition defense, and so on) roll up into 10 category grades, 5 master dimensions, and an overall team profile that keeps quality, process, style, results, and confidence as separate questions instead of collapsing them into one ranking. The output is a machine-readable, statistically grounded language for saying what a team does, how well it does it, how reliably, and whether the results are supported by the underlying process.

The project started as a player grader and pivoted to teams in September 2026. The player-era data plumbing was kept because it was already verified and directly reusable.

Everything builds on free, unofficial stats.nba.com endpoints via nba_api, with no API keys but plenty of throttling and schema quirks. Of the 80 attributes, about 45 come straight from verified dashboards, 25 are derived from play-by-play parsing and per-game aggregation, 5 ship as declared proxies, and 5 (defensive scheme classification, rotation and closeout events) are not feasible on public data and are reported as missing rather than faked.

What is built so far:

• Verified acquisition – every endpoint family the spec depends on is probed live, then season tables are pulled into immutable, fetch-dated Parquet snapshots with a manifest. Verifying the endpoints rather than trusting them turned up three corrections, one of which would have broken four attributes.
• Canonical tables and a metric registry – possessions segmented from a full season of play-by-play, shots by team and zone, play types by team, and 74 metrics that each carry their source, formula, unit, direction, reliability constant, and feasibility tier. The documented formula is the executed formula, so the two cannot drift.
• A 30-attribute MVP – 14 offense, 11 defense, and 5 profile attributes, each with opponent and game-state adjustment from a regression over 2,460 team-games, shrinkage toward the mean, and a confidence score.
• Grades and team profiles – 0–100 attribute grades, category rollups, master dimensions and Overall Quality, process-versus-result residuals, and a double-counting audit.
• Out-of-sample validation across five seasons: year-to-year persistence, predictive validity, and a recalibration of the shrinkage constants from within-season split-half reliability.

The honest headline from validation: Overall Quality in one season predicts the next season’s net rating at about the same rate as simply reusing net rating, and the two correlate 0.99 by construction. So the grader is a descriptive instrument, not a forecast. Along the way it also caught three attributes that correlated negatively with winning (volume-allowed measures standing in for quality measures), a shot-quality model whose location component had to be dropped because teams pick shot profiles to suit their personnel, and one attribute (3PT suppression) that turned out to measure nothing at all and now grades every team at roughly 50 with about 1% confidence.

The player-era pieces still in use include a play-by-play parser that matches the NBA’s official box scores on all 39,090 stat cells across 100 validation games, a shot-zoning module that reproduces the NBA’s own zone labels on every shot of 2025-26, and a log5 matchup projection with a held-out backtest.

Next up is expanding to the remaining attributes, then team archetypes and team cards. The 2026-27 season is the genuinely live out-of-sample test.