nfl-tracks 1.3.1

Python library written on top of matplotlib library for customizable nfl charts

nfl-tracks

nfl-tracks is a Python library built on top of Matplotlib for creating insightful and customizable visualizations of NFL player tracking data. Designed with the NFL Big Data Bowl in mind, it provides a simple interface to plot static plays, generate dynamic animations, and view detailed, context-rich breakdowns of individual plays.

Key Features

• Standard Field Visualization: Generate a regulation NFL field with customizable markings.
• Single Frame Plotting: Visualize player positions at any specific moment in a play.
• Dynamic Animations: Create smooth, animated GIFs or videos of entire plays.
• "Relay" Dashboard View: A comprehensive visualization that includes:
  • Live scoreboard with team details and win probabilities.
  • Highlighted player card with key stats (name, position, height, etc.).
  • On-field play and game context.
  • Automatic highlighting of the targeted or predicted player.
• Kaggle Notebook Compatibility: Easily render animations directly within Kaggle notebooks.
• Out-of-Bounds Tracking: Players and the ball are visualized even when they go outside the field of play, without distorting the field's proportions.

Installation

You can install nfl-tracks using pip:

pip install nfl_tracks

Function Overview

The core of the library is the visuals.Play class, which you initialize once for a specific play. You can then call its methods to generate different visualizations.

Initialization of a visualization object for a specific play. This is the first step before you can plot or animate anything.

• data (pd.DataFrame): The main tracking data.
• gameId (int): The unique identifier for the game.
• playId (int): The identifier for the play.
• context_data (pd.DataFrame): The supplementary data containing game and play context.

# Data Preparation
import pandas as pd
from nfl import visuals

tracking_data = pd.read_csv(f'data/train/input_2023_w02.csv')
context_data = pd.read_csv(f'data/supplementary_data.csv', dtype={25: str})

data = tracking_data[(tracking_data['game_id'] == 2023091400) & (tracking_data['play_id'] == 3438)]

play = visuals.Play(data, gameId, playId, context_data)

plot_snap

This is useful for analyzing player formations and positions at a key moment, like the snap or the moment a pass is thrown.

Standard View (relay=False)
This is the default mode. It generates a clean and simple plot of the football field with the players' positions.

# Plots frame 10 of the play on a standard field
fig, ax = play.plot_snap(frameId=10)
plt.show()

Relay Dashboard View (relay=True)
This mode creates a rich, informational dashboard around the field, providing deep context for the play. It includes a scoreboard, game information, and a detailed card for a highlighted player.

# Plots frame 10 using the advanced relay dashboard
fig, ax = play.plot_snap(frameId=10, relay=True)
plt.show()

play.animate

Generates a full animation of the play from the first frame to the last. This is the best way to see a play unfold, showing player routes and movements in real-time.

Standard Animation (relay=False)
This creates a simple, clean animation of the players moving on the field. It's great for embedding in presentations or for a quick look at the play's dynamics.

# Generates a standard animation of the play
# Use kaggle=True to display it in a notebook
standard_animation = play.animate(kaggle=True)
standard_animation

Relay Dashboard Animation (relay=True)
This creates a simple, clean animation of the players moving on the field. It's great for embedding in presentations or for a quick look at the play's dynamics.

# Generates a relay dashboard animation of the play
relay_animation = play.animate(relay=True, kaggle=True)
relay_animation

Additional Parameters (**kwargs) You can customize your plots and animations with these optional arguments:

• highlight_player_id (int): Manually specify an nfl_id to highlight in the relay view. If not provided, it defaults to the player with player_to_predict=True.
• club_colors (dict): A dictionary to override default offense/defense colors (e.g., {'Offense': '#006400', 'Defense': '#8B0000'}).
• size (int): The marker size for players on the field.
• speed (int): The delay between frames in milliseconds for animations (a lower number is faster).

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

This library is ideal for visualizing football plays with clear, customizable graphics and animations. For further assistance, refer to Matplotlib's documentation or provide specific details for troubleshooting.