Python NFL Visualization Package - Complete nflplotR Equivalent
nflplotpy is a comprehensive Python visualization package for NFL data analysis, providing complete feature parity with R's popular nflplotR package. Built for the NFL analytics community, it seamlessly integrates with matplotlib, plotly, seaborn, and pandas to create stunning NFL-themed visualizations.
Inspired by and building upon the amazing work of the nflverse ecosystem and nflplotR package.
pip install nflplotpyimport nflplotpy as nflplot
import matplotlib.pyplot as plt
import pandas as pd
# Create a simple team performance scatter plot
fig, ax = plt.subplots(figsize=(12, 8))
# Add team logos at coordinates
nflplot.add_nfl_logo(ax, 'KC', x=0.5, y=0.5, width=0.1)
nflplot.add_nfl_logo(ax, 'BUF', x=0.3, y=0.7, width=0.1)
# Apply NFL theme
nflplot.apply_nfl_theme(ax, team='KC')
plt.show()All Teams EPA Analysis
Division Breakdown
Examples using real 2024 NFL Expected Points Added (EPA) data with team logos
Check out our examples directory for detailed code and documentation:
nfl_examples.py: Real 2024 NFL data analysis with team logosnflplotpy_demo.py: Complete feature demonstrationstable_examples.py: NFL table styling examplesquick_test.py: Quick functionality verification
➤ View Full Examples Documentation for detailed tutorials and customization guides.
# Get team colors
nflplot.get_team_colors('KC', 'primary') # '#e31837'
nflplot.get_team_colors(['KC', 'BUF', 'GB']) # Multiple teams
# Create color palettes
palette = nflplot.NFLColorPalette()
afc_colors = palette.create_conference_palette('AFC')
gradient = palette.create_gradient('KC', 'SF', n_colors=10)import matplotlib.pyplot as plt
fig, ax = plt.subplots()
# Add team logos
nflplot.add_nfl_logo(ax, 'KC', x=0.5, y=0.5, width=0.1)
# 🆕 Add team wordmarks
nflplot.add_team_wordmark(ax, 'KC', x=0.3, y=0.8, width=0.12)
# 🆕 Add player headshots
nflplot.add_player_headshot(ax, 'Patrick Mahomes', x=0.7, y=0.2, width=0.1)
# Add reference lines
nflplot.add_median_lines(ax, data, axis='both')
# Apply NFL theme
nflplot.apply_nfl_theme(ax, team='KC', style='default')# Team performance scatter plot
fig = nflplot.plot_team_stats(
data, x='offensive_epa', y='defensive_epa',
show_logos=True, add_reference_lines=True
)
# Player comparison radar chart
fig = nflplot.plot_player_comparison(
player_data, players=['Josh Allen', 'Patrick Mahomes'],
metrics=['passing_yards', 'passing_tds', 'qbr'],
plot_type='radar'
)# Style pandas DataFrames with team logos
styled = nflplot.style_with_logos(df, 'team')
styled.to_html('nfl_table.html')
# 🆕 Add team wordmarks to tables
styled_wm = nflplot.style_with_wordmarks(df, 'team', wordmark_height=25)
# 🆕 Add player headshots to tables
styled_hs = nflplot.style_with_headshots(
player_df, 'player', id_type='name', headshot_height=40
)
# Comprehensive NFL-themed tables
table = nflplot.create_nfl_table(
standings_df,
team_column='team',
title='2024 NFL Standings'
)
table.save_html('standings.html')# Preview plots with specified dimensions
nflplot.nfl_preview(fig, width=12, height=8, dpi=150)
# Quick preview with presets
nflplot.preview_with_dimensions(fig, 'presentation') # 16:9 format# Add logos to axis labels
nflplot.set_xlabel_with_logos(ax, ['KC', 'BUF', 'NE', 'NYJ'])
# Add logo watermarks
nflplot.add_logo_watermark(ax, 'KC', position='bottom_right')
# Create team comparison layouts
left_ax, right_ax = nflplot.create_team_comparison_axes(fig, 'KC', 'BUF')| Function | Description | nflplotR Equivalent |
|---|---|---|
get_team_colors() |
Get NFL team colors | team_colors |
add_nfl_logo() |
Add team logo to plot | geom_nfl_logos() |
add_median_lines() |
Add reference lines | geom_median_lines() |
style_with_logos() |
Add logos to tables | gt_nfl_logos() |
nfl_preview() |
Preview plots | ggpreview() |
nfl_sitrep() |
System information | nflverse_sitrep |
plot_team_stats() |
High-level team plots | Custom implementation |
team_factor() |
Ordered team factors | nfl_team_factor() |
team_tiers() |
Group teams by tiers | nfl_team_tiers() |
NFLAssetManager: Manages logo caching and asset downloadsNFLColorPalette: Advanced color palette managementNFLTableStyler: Pandas DataFrame styling with NFL elementsAssetURLManager: Comprehensive URL management for all NFL assets
- Matplotlib:
nflplotpy.matplotlib.* - Plotly:
nflplotpy.plotly.* - Seaborn:
nflplotpy.seaborn.*
# Basic installation
pip install nflplotpy
# With plotly support
pip install nflplotpy[plotly]
# With seaborn support
pip install nflplotpy[seaborn]
# Complete installation with all backends
pip install nflplotpy[all]
# Development installation
pip install nflplotpy[dev]nflplotpy/
├── core/ # Core functionality (colors, logos, utilities, URLs)
├── matplotlib/ # Matplotlib integration (artists, scales, preview, elements)
├── plotly/ # Plotly integration
├── seaborn/ # Seaborn integration
├── pandas/ # Pandas table styling integration
├── data/ # Team metadata
├── examples/ # Usage examples and tutorials
└── tests/ # Comprehensive test suite
nflplotpy welcomes contributions! Here's how you can help:
- Report Issues: Found a bug? Open an issue
- Feature Requests: Have an idea? We'd love to hear it!
- Code Contributions: Fork, develop, and submit a pull request
- Documentation: Help improve our docs and examples
git clone https://github.com/joelfeinberg/nflplotpy.git
cd nflplotpy
pip install -e .[dev]
pytest tests/- Discord: Join the nflverse Discord
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Python: 3.8+
- Core Dependencies: matplotlib, pandas, numpy, pillow, requests
- Optional: plotly (5.0+), seaborn (0.11+)
- Supports: CPython, PyPy
MIT License - see LICENSE file for details.
This package is inspired by and builds upon the amazing work of the nflverse ecosystem and nflplotR package.
- nflplotR: Original R package that inspired this work
- nflverse: Amazing NFL data ecosystem and community
- NFL Analytics Community: For continuous feedback and support
Built for the NFL analytics community 🏈
Compatible with nfl_data_py, nflfastR, and other nflverse tools.