DOCSEARCHbyAlgolia
Submit Docs

nfl_data_py

repository·main·Indexed 16 days ago

https://github.com/nflverse/nfl_data_py

A Python library for interacting with NFL data from sources such as nflfastR, nfldata, and Draft Scout. It enables the import of play-by-play, weekly, seasonal, and specialized statistical datasets—including Next Gen Stats (NGS), QBR, and Pro-Football-Reference (PFR) data—directly into Python dataframes. Note: nfl_data_py is deprecated in favor of nflreadpy.

Tokens
3.8K
Snippets
21
Records
24
Agent score
56%

What's inside nfl_data_py

  3. Cache play-by-play data locally

    main

    Use cache_pbp() to save play-by-play data to your local machine to speed up subsequent downloads.

    Parameters:

    • years (required): List or range of years to cache.
    • downcast (optional): Converts float64 to float32 (default True).
    • alt_path (optional): Alternate path to store the cache. The default is a local folder created in the user's program directory.

    Note: If using in-season, you must call this once per week to capture the most recent data. Calling this on already cached years will overwrite them.

    import nfl_data_py as nfl

nfl.cache_pbp([2023, 2024], alt_path='/path/to/cache')

  4. Clean NFL dataframes

    main

    Use clean_nfl_data(df) to run descriptive data (such as team names and player names) through various cleaning processes to ensure consistency.

    import nfl_data_py as nfl

raw_df = nfl.import_team_desc()
cleaned_df = nfl.clean_nfl_data(raw_df)

  6. Import additional NFL data types

    main

    The library provides several other specialized data imports:

    • import_win_totals(years): Returns win total lines.
    • import_sc_lines(years): Returns scoring lines.
    • import_officials(years): Returns official information by game.
    • import_draft_picks(years): Returns a list of draft picks.
    • import_draft_values(): Returns relative values by generic draft pick using various valuation methods.
    • import_team_desc(): Returns team information (colors, logos, etc.).
    • import_schedules(years): Returns schedule information (earliest: 1999).
    • import_combine_data(years, positions): Returns combine results. positions is an optional list (e.g., ['WR', 'QB']).
    • import_ids(columns, ids): Returns mapped IDs for players across major platforms.
    • import_depth_charts(years): Returns depth chart data.
    • import_injuries(years): Returns injury reports.
    • import_snap_counts(years): Returns snap count records.

  7. Import seasonal data and market share stats

    main

    Use import_seasonal_data to retrieve seasonal data, including calculated receiving market share statistics.

    Parameters:

    • years (required): A list of years to pull data for (earliest: 1999).
    • s_type (optional): Season type to include in average. Options: 'ALL', 'REG' (default), or 'POST'.

    Available Market Share Columns:

    • tgt_sh: target share
    • ay_sh: air yards share
    • yac_sh: yards after catch share
    • wopr: weighted opportunity rating
    • ry_sh: receiving yards share
    • rtd_sh: receiving TDs share
    • rfd_sh: receiving 1st Downs share
    • rtdfd_sh: receiving TDs + 1st Downs share
    • dom: dominator rating
    • w8dom: dominator rating (weighted for receiving yards over TDs)
    • yptmpa: receiving yards per team pass attempt
    • ppr_sh: PPR fantasy points share
    import nfl_data_py as nfl

seasonal_data = nfl.import_seasonal_data([2023], s_type='REG')

  9. Import FTN charting data

    main

    Access FTN charting data (available from 2022 onwards). Data is released within 48 hours of game completion.

    Parameters:

    • years (required): List of years.
    • columns (optional): List of specific columns.
    • downcast (optional): Convert float64 to float32 (default True).
    • thread_requests (optional): Use a thread pool to read files (default False).

    Note: Attribution to FTN Data via nflverse is required under CC-BY-SA 4.0.

    import nfl_data_py as nfl

ftn_data = nfl.import_ftn_data([2023], thread_requests=True)

  10. Import play-by-play data

    main

    Use import_pbp_data to retrieve play-by-play data. The earliest available year is 1999.

    Parameters:

    • years (required): A list of years to pull data for.
    • columns (optional): A list of specific columns to pull.
    • downcast (optional): If True, converts float64 columns to float32. This reduces memory usage by ~30% but increases initial load time by ~50%.
    • cache (optional): Determines whether to pull from the GitHub repo or a local cache generated by cache_pbp().
    • alt_path (optional): Required if cache_pbp() was called using an alternate path.
    import nfl_data_py as nfl

# Example usage
pbp_data = nfl.import_pbp_data([2023], columns=['play_type', 'desc'], downcast=True)

  11. Import rosters (seasonal and weekly)

    main

    Retrieve roster information using either seasonal or weekly functions.

    Seasonal Rosters: import_seasonal_rosters(years, columns)

    • years (required): List of years (earliest: 1999).
    • columns (optional): List of columns.

    Weekly Rosters: import_weekly_rosters(years, columns)

    • years (required): List of years (earliest: 1999).
    • columns (optional): List of columns.
    import nfl_data_py as nfl

seasonal_rosters = nfl.import_seasonal_rosters([2023])
weekly_rosters = nfl.import_weekly_rosters([2023])

  12. Import weekly player data

    main

    Use import_weekly_data to retrieve weekly performance data. The earliest available year is 1999.

    Parameters:

    • years (required): A list of years to pull data for.
    • columns (optional): A list of specific columns to pull.
    • downcast (optional): Converts float64 to float32 to save memory (~30% reduction) at the cost of slower load speed (~50% slower).
    import nfl_data_py as nfl

weekly_data = nfl.import_weekly_data([2023], columns=['player_id', 'fantasy_points'])