name: nflverse description: Comprehensive NFL data via nflreadpy - play-by-play, player stats, team stats, schedules, rosters, injuries, contracts, NextGen stats, snap counts, draft picks, combine, depth charts, trades, and fantasy data. Uses Polars DataFrames. Python 3.12 venv required.

nflverse - NFL Data Skill

Complete NFL data access via nflreadpy (Python port of R's nflreadr). All data is FREE, CC-BY 4.0 licensed from nflverse repositories.

Setup

# Activate the venv (REQUIRED for every command)
source /Users/home/.openclaw/workspace/skills/nflverse/.venv/bin/activate

All commands below assume the venv is active. Always prefix python commands with:

cd /Users/home/.openclaw/workspace/skills/nflverse && source .venv/bin/activate && python3 ...

Quick Reference

import nflreadpy as nfl

# Utility
nfl.get_current_season()    # Current NFL season year
nfl.get_current_week()      # Current NFL week number

# Core Data Loading (all return Polars DataFrames)
nfl.load_pbp(seasons)              # Play-by-play (since 1999) - THE main dataset
nfl.load_player_stats(seasons, summary_level)  # Player stats (week/reg/post/reg+post)
nfl.load_team_stats(seasons, summary_level)    # Team stats
nfl.load_schedules(seasons)        # Game schedules & results (default: all seasons)
nfl.load_players()                 # Player info + cross-platform IDs
nfl.load_rosters(seasons)          # Team rosters (since 1920!)
nfl.load_rosters_weekly(seasons)   # Weekly rosters (since 2002)
nfl.load_snap_counts(seasons)      # Snap counts (since 2012)
nfl.load_nextgen_stats(stat_type, seasons)  # NGS: "passing"/"rushing"/"receiving"
nfl.load_ftn_charting(seasons)     # FTN charting data
nfl.load_participation(seasons)    # Historical participation
nfl.load_draft_picks(seasons)      # Draft picks
nfl.load_injuries(seasons)         # Injury reports & practice participation
nfl.load_contracts()               # Contract data from OTC
nfl.load_officials(seasons)        # Game officials
nfl.load_combine(seasons)          # NFL Combine results
nfl.load_depth_charts(seasons)     # Depth charts
nfl.load_trades(seasons)           # Trades
nfl.load_teams()                   # Team info, colors, logos
nfl.load_ff_playerids()            # Fantasy player ID mappings
nfl.load_ff_rankings()             # FantasyPros rankings
nfl.load_ff_opportunity(seasons)   # Expected yards/TDs/fantasy points

Parameter Patterns

• seasons=None → current season
• seasons=True → ALL available seasons
• seasons=2024 → single season
• seasons=[2023, 2024] → multiple seasons
• summary_level="week" (default) | "reg" | "post" | "reg+post"
• stat_type for NextGen: "passing" | "rushing" | "receiving"

Key Columns (PBP)

Filtering for QB analysis (from Discord community):

# Filter to actual plays
pbp = pbp.filter(
    ((pl.col("rush") == 1) | (pl.col("pass") == 1)) & 
    pl.col("down").is_not_null()
)
# Use qb_epa for QB-specific EPA (not epa)

Key PBP columns: play_id, game_id, posteam, defteam, down, ydstogo, yardline_100, play_type, yards_gained, epa, wp, wpa, qb_epa, air_yards, yards_after_catch, pass, rush, touchdown, interception, fumble

For aDot calculation (from Discord):

# Filter air_yards
df = df.with_columns(
    pl.when(pl.col("play_type").is_in(["no_play", "run"])).then(None).otherwise(pl.col("air_yards")).alias("air_yards"),
)
df = df.filter(pl.col("air_yards") > -15)  # Remove outliers

Data Availability by Year

| Dataset | From | Notes | |---------|------|-------| | PBP | 1999 | Main dataset, ~50k rows/season | | Player Stats | 1999 | Weekly/season summaries | | Schedules | 1999 | Game results, spreads, o/u | | Rosters | 1920 | Historical rosters | | Weekly Rosters | 2002 | Week-by-week changes | | Snap Counts | 2012 | From PFR | | NextGen Stats | 2016 | AWS tracking data | | FTN Charting | 2022 | Detailed charting | | Injuries | 2009 | Practice reports | | Contracts | Current | From OTC | | Draft Picks | 2000 | All rounds | | Combine | 2000 | Athletic testing | | Depth Charts | 2001 | Weekly depth charts |

Common Patterns for Betting Models

Get QB stats for a matchup

import nflreadpy as nfl
import polars as pl

stats = nfl.load_player_stats(2025, summary_level="week")
qb_stats = stats.filter(pl.col("position") == "QB")
# Join with schedules for opponent info

Check injuries before making picks

injuries = nfl.load_injuries(2025)
# Filter to current week, check status
active = injuries.filter(
    (pl.col("report_status").is_in(["Questionable", "Out", "Doubtful"]))
)

Line movement context (schedules have spreads)

sched = nfl.load_schedules(2025)
# Has: spread_line, total_line, result, div_game, roof, surface, temp, wind

Player prop research (snap counts + stats)

snaps = nfl.load_snap_counts(2025)
stats = nfl.load_player_stats(2025, summary_level="week")
# Join on player_id + week for usage rate analysis

Caching

Data is cached in memory by default. For persistent caching:

from nflreadpy.config import update_config
update_config(cache_mode="filesystem", cache_dir="~/.nflverse_cache")

Clear cache: nfl.clear_cache()

MCP Server

Run via: cd /Users/home/.openclaw/workspace/skills/nflverse && source .venv/bin/activate && python3 scripts/mcp_server.py

Data Sources

• nflverse-data - Main data repo
• dynastyprocess - Fantasy data
• ffopportunity - Expected fantasy points
• Data update schedule

Tips from nflverse Discord

• STL → LA standardized across all datasets (historical consistency)
• load_teams() has team logos (not listed on landing page but works)
• PBP data updates may lag ~24h after games; clear cache if stale
• Routes run data NOT available in nflverse (need PFF/FantasyLife paywall)
• Coin flip data NOT available in nflverse
• For kicker stats, use load_player_stats() not calculate_stats (bug in R version)
• Player IDs: use GSIS IDs for joining across datasets