Skip to content

Possession-level modeling infrastructure

NBA Lineup Model

A reproducible NBA play-by-play data spine for context-sensitive player and lineup value. The immediate goal is trustworthy five-on-five possession samples; the longer horizon is nonlinear lineup modeling with interpretable context.

Direct source Byte-preserved NBA source responses
Exact context Five players per team at every boundary
Validated output Score, duration, and lineup invariants 
flowchart LR
    RAW["NBA source data"] --> EVT["Typed events"]
    EVT --> LUP["Lineups"]
    EVT --> POSS["Possessions"]
    LUP --> SEG["Fixed-lineup segments"]
    POSS --> SEG
    SEG --> MODEL["Contextual models"]

Workflows

01 Build one game Fetch, normalize, reconstruct, and persist six Parquet contracts. 02 Audit across seasons Exercise reconstruction against regulation, playoff, and overtime feeds. 03 Fetch a season Run resumable, bounded-concurrency acquisition from the game catalog. 04 Process a season Reconstruct and quality-gate cached games through Prefect. 05 Compact a season Publish lossless, provenance-rich analytical Parquet datasets. 06 Understand the pipeline Review ownership boundaries, decisions, and failure policy. 07 Inspect data contracts Trace raw source documents through modeling-ready segments. 08 Train the baselines Compare mean, team, and one-number RAPM predictions chronologically.

Current system

  • Fetch play-by-play and boxscore JSON directly from NBA CDN endpoints.
  • Preserve historical Stats V3 responses when CDN game objects are unavailable.
  • Preserve raw response bytes with fetch metadata and SHA-256 digests.
  • Discover historical season schedules directly into a canonical game catalog.
  • Fetch complete seasons through a resumable local Prefect flow.
  • Process cached seasons through validation-gated Prefect tasks.
  • Compact quality-gated games into resumable season-level Parquet datasets.
  • Collect historical player identities and leakage-safe season bios.
  • Normalize source actions into typed canonical events.
  • Reconstruct event-level lineups and stable lineup stints.
  • Reconstruct basketball possessions with explicit terminal reasons.
  • Split possessions when substitutions change either lineup.
  • Audit exact invariants across regular-season, playoff, and overtime games.
  • Train sparse mean, team, and one-number RAPM baselines on regular-season stints.

Engineering stance

  1. Preserve source information before deriving basketball semantics.
  2. Keep identifiers and clocks typed without lossy coercion.
  3. Treat feed fields as evidence, not unquestionable ground truth.
  4. Surface anomalies through structured issues and audit reports.
  5. Establish trustworthy samples before optimizing model complexity.

Contract status

Processed schemas are explicit and tested, but remain experimental until modeling requirements and cross-season feed behavior are better understood.