Nflreadpy

nflreadpy / nflverse Loader

Outcome

Create a documented, user-owned NFL data artifact at the grain required by the analysis. Record seasons, loader function and arguments, retrieval time, installed package version, source release, schema, natural key, row count, filters, and transformations.

Use nflreadpy for acquisition. Do not let source loading silently define the analytical grain, prediction cutoff, or legal feature set.

When to use this skill

Use for NFL schedules and scores, play-by-play, rosters, player or team stats, snap counts, injuries, and other nflverse releases. For non-NFL sources use the appropriate public package. Use data-sources when the source is undecided and feature-rules before turning loaded fields into prospective predictors.

Installation

bashCopy code
python -m pip install nflreadpy polars pyarrow

The first retrieval may require network access. Record the package version and cache or snapshot any data used for a durable claim.

Release selection

Read references/nflverse_releases.md when choosing among releases. Select the narrowest source that contains the required fields; do not load all play-by-play seasons for a schedule-only question.

Direct loads

pythonCopy code
import nflreadpy as nfl

seasons = [2022, 2023, 2024]
schedules = nfl.load_schedules(seasons)
pbp = nfl.load_pbp([2024])
player_stats = nfl.load_player_stats(seasons)
rosters = nfl.load_rosters([2024])

Loader availability, return types, and schemas can change by release. Inspect the installed interface and one bounded result before assuming a function, column, dtype, or natural key.

pythonCopy code
import nflreadpy as nfl

print(getattr(nfl, "__version__", "unknown"))
print([name for name in dir(nfl) if name.startswith("load_")])

Acquisition workflow

1. Lock question, analytical grain, seasons, and required fields.
2. Choose the narrowest nflverse release.
3. Load one season first and inspect object type, schema, row count, nulls, and key.
4. Save an immutable raw snapshot before normalization or filtering.
5. Identify schedule status values and distinguish scheduled, completed, postponed, canceled, and missing-score rows.
6. Validate team codes, game identifiers, dates, weeks, seasons, and score units.
7. Normalize in a separate derived artifact; preserve source columns or a mapping.
8. Save Parquet plus a JSON or Markdown manifest.
9. Validate the artifact at its intended grain and document known gaps.
10. Hand the explicit saved artifact to EDA, feature, or modeling work.

Team-game contract

When deriving one row per team per game, require at least:

textCopy code
game_id, season, week, gameday, team, opponent, is_home,
game_type, points_for, points_against, won, tied, point_diff

Consider retaining status, season type, kickoff timestamp, neutral-site flag, overtime/tie indicators, and raw team identifiers. Completed non-tied games should yield two complementary rows: points and margin reverse, home flags oppose, and exactly one won value is true. For ties, both won values may be false, so preserve an explicit tied flag.

Read references/panel_contract.md before normalizing schedules into team-game rows. Preserve raw schedule rows so every derived row can be audited.

Validation checks

Raw game grain

• requested seasons and season types are present;
• game_id is unique or duplication is explained;
• completed games have both teams and plausible scores;
• home and away teams differ;
• week, date, season, and status fields are internally consistent;
• duplicate and missing rates are reported by season;
• future or incomplete events are not mislabeled completed.

Derived team-game grain

• exactly two rows per included contest;
• team/opponent and home/away values are complementary;
• points-for/against and margins reverse across the pair;
• won, tied, and point_diff follow the documented label rule;
• unique-game count is reported beside row count;
• overall row-level win rate is interpreted as a construction property, not home advantage.

Joins

• stable player/team/game identifiers are preferred over display names;
• join cardinality and unmatched rates are checked;
• roster, injury, and weekly tables use a documented as-of timestamp;
• relocations and historical team abbreviations are mapped explicitly, not silently rewritten.

Sports-specific traps

• Doubled-panel trap: overall win rate is approximately 0.5 because each game contributes opponent rows. Estimate home advantage from home rows.
• Postgame feature trap: EPA, final score, snap share, and many summaries are known after the event. They require lagging or a different decision time.
• Roster hindsight: a current roster is not a historical roster snapshot.
• Week ordering: postponed games and rescheduling can make week labels differ from event-time order. Use timestamps for as-of features.
• Ties: coding won == 0 for both teams is not equivalent to two losses.
• Schema drift: columns and dtypes can change across releases or seasons; validate before concatenation.
• Identifiers: display-name joins can duplicate or mismatch players; use IDs.

Snapshot manifest

Record:

textCopy code
source: nflverse via nflreadpy
package_version
loader_function_and_arguments
retrieval_timestamp_utc
requested_and_observed_seasons
raw_artifact_path_and_checksum
derived_artifact_path_and_checksum
grain_and_natural_key
row_and_unique_event_counts
filters_and_status_rule
schema_or_schema_path
transformations_and_identifier_mapping
known_gaps_and_validation_results

Hard constraints and integrity rules

1. Prefer documented release loaders over ad-hoc scraping.
2. Do not load broad play-by-play when schedules or stats suffice.
3. Do not use raw post-event fields as pre-event predictors without as-of rules.
4. Do not treat current rosters as historical.
5. Do not train outcome models on incomplete events unless forecasting those future events is the explicitly separate purpose.
6. Do not join on player names when stable IDs exist.
7. Do not silently rewrite historical team codes or schemas.
8. Do not model a doubled panel without accounting for paired contest rows.
9. Snapshot the exact data used for claims.
10. Never swallow a load/schema error and return an empty artifact as success.

Anti-patterns

• pulling every play from every season for a game-score question;
• using postgame EPA in a pre-kickoff model;
• claiming home advantage from the full team-game panel's win rate;
• joining current rosters to historical games;
• concatenating seasons before checking schema drift;
• retaining only normalized output with no source snapshot;
• reporting only row count while hiding duplicate games;
• retry loops that hammer public infrastructure or obscure failure.

Helpers

bashCopy code
python <path-to-nflreadpy>/scripts/smoke_load.py --season 2024

python <path-to-nflreadpy>/scripts/load_game_panel.py \
  --seasons 2023-2024 \
  --game-types REG \
  --raw-out data/nfl_schedules.parquet \
  --out data/nfl_team_games.parquet

python <path-to-nflreadpy>/scripts/describe_panel.py \
  --input data/nfl_team_games.parquet

All helpers parse --help before importing nflreadpy. The output files are user-owned and consumable by any dataframe or modeling tool. The panel helper defaults to regular-season (REG) games, records game_type on every derived row, and requires the requested scope to be verifiable from the source. Pass an explicit comma-separated scope such as REG,WC,DIV,CON,SB when postseason games belong in the analysis. The panel helper does not replace manifest review or decision-time feature validation.

Worked example

For a pregame home-advantage analysis, load schedules rather than play-by-play, retain completed regular-season games under an explicit status rule, save raw Parquet, derive paired team-game rows, and report both unique games and rows. Compute the home rate on is_home == 1; do not use the full-panel rate.

Output contract

Return artifact paths, source release, package version, retrieval timestamp, loader arguments, requested/observed seasons, grain, natural key, row and event counts, columns/schema, filters, transformations, known gaps, and sanity-check results. Name the next artifact consumer without requiring a particular project.

Resources

• references/nflverse_releases.md — read when selecting the narrowest NFL release.
• references/panel_contract.md — read before building or validating paired team-game rows.
• scripts/smoke_load.py — bounded source probe.
• scripts/load_game_panel.py — raw schedule to team-game export.
• scripts/describe_panel.py — standalone panel validation and summary.