# NFL Field Visualization and Animation Library
This library provides utilities to visualize a football field, plot player positions, and animate plays. It is designed to handle data from tracking datasets, such as those used in football analytics.
Installing the library:
```bash
pip install nfl_tracks
```
After successfully installing the nfl_tracks package, import it in the file using the code below:
```python
# Import nfl_tracks
from nfl import visuals
```
## Table of Contents
1. Function Overview
* field()
* snap()
* play_game()
2. Usage Examples
3. Error Handling
4. Customization Options
---
## 1. Function Overview
## field()
Generates a plot of a football field with customizable features.
```pythonverboseregexp
field(yard_numbers=True, touchdown_markings=True, fifty_yard=False, fig_size=(12, 6.33))
```
#### Parameters:
* **yard_numbers (bool, default True)**: Whether to display yard numbers on the field.
* **touchdown_markings (bool, default True)**: Whether to show touchdown zone labels.
* **fifty_yard (bool, default False)**: Highlights the 50-yard line in gold.
* **fig_size (tuple, default (12, 6.33))**: Specifies the figure size.
#### Returns:
* **fig (matplotlib.figure.Figure)**: The figure object.
* **ax (matplotlib.axes.Axes)**: The axes object containing the plot.
#### Example Usage:
```python
fig, ax = visuals.field()
plt.show()
```
---
## snap()
Plots the positions of players during a specific frame of a play.
```pythonverboseregexp
snap(data, gameId, playId, frameId, yard_numbers=True, touchdown_markings=True, fifty_yard=False, fig_size=(12, 6.33), **kwargs)
```
#### Parameters:
* **data (pd.DataFrame)**: Contains tracking data with columns including gameId, playId, frameId, x, y, and club.
* **gameId (int)**: Identifier for the game.
* **playId (int)**: Identifier for the play.
* **frameId (int)**: Identifier for the specific frame within the play.
* **yard_numbers (bool, default True)**: Whether to display yard numbers on the field.
* **touchdown_markings (bool, default True)**: Whether to show touchdown zone labels.
* **fifty_yard (bool, default False)**: Highlights the 50-yard line in gold.
* **fig_size (tuple, default (12, 6.33))**: Specifies the figure size.
* ****kwargs**: Additional arguments
* **size (int, default 10)**: Marker size for players.
* **club_colors (dict)**: Custom mapping of club indices to colors.
#### Returns:
* **fig (matplotlib.figure.Figure)**: The figure object.
* **ax (matplotlib.axes.Axes)**: The axis object.
#### Example Usage:
```python
fig, ax = visuals.snap(data, gameId=2022091200, playId=64, frameId=10)
plt.show()
```
---
## play_game()
Animates a play by visualizing player movements over time.
```pythonverboseregexp
play_game(data, gameId, playId, kaggle=True, yard_numbers=True, touchdown_markings=True, fifty_yard=False, fig_size=(12, 6.33), save=False, loop=False, **kwargs)
```
#### Parameters:
* **data (pd.DataFrame)**: Contains tracking data with columns including gameId, playId, frameId, x, y, and club.
* **gameId (int)**: Identifier for the game.
* **playId (int)**: Identifier for the play.
* **kaggle (bool, default True)**: Enables compatibility with Kaggle's notebook environments.
* **yard_numbers (bool, default True)**: Whether to display yard numbers on the field.
* **touchdown_markings (bool, default True)**: Whether to show touchdown zone labels.
* **fifty_yard (bool, default False)**: Highlights the 50-yard line in gold.
* **fig_size (tuple, default (12, 6.33))**: Specifies the figure size.
* **save (bool, default False)**: Saves the animation as a play.gif file if True.
* **loop (bool, default False)**: Repeats the animation if True.
* ****kwargs**: Additional arguments
* **size (int, default 10)**: Marker size for players.
* **speed (int, default 100)**: Time interval between frames (in milliseconds).
* **club_colors (dict)**: Custom mapping of club indices to colors.
* **save_params (dict)**: Parameters for saving the animation.
#### Returns:
* **ani (matplotlib.animation.FuncAnimation)**: The animation object.
#### Example Usage:
```python
ani = visuals.play_game(data, gameId=2022091200, playId=64)
ani
```
---
## 2. Usage Examples
Plotting a Field
```python
fig, ax = visuals.field(touchdown_markings=False, fifty_yard=True)
plt.show()
```
Visualizing a Single Frame
```python
fig, ax = visuals.snap(data, gameId=2022091200, playId=52, frameId=15, size=20)
plt.show()
```
Plotting a Field
```python
ani = visuals.play_game(data, gameId=2022091200, playId=24, save=True, speed=150)
ani
```
---
## 3. Error Handling
* **Data Validation**: Functions check whether _gameId_, _playId_, and _frameId_ exist in the data.
* **Color Mapping**: Ensures all _club_ values map to valid colors. Raises an error if a _club_ is unmapped.
* **Saving Animations**: Errors in saving are explained with links to relevant Matplotlib documentation.
---
## 4. Customization Options
* **Player Marker Sizes**: Control player marker sizes using the _size_ parameter.
* **Color Mapping**: Customize player colors by passing a dictionary to _club_colors_.
* **Animation Speed**: Adjust frame transition time with the _speed_ parameter.
* **Output Formats**: Save animations with customized parameters for the _PillowWriter_.
---
## 5. License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/shammeer-s/nfl/blob/master/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.
Raw data
{
"_id": null,
"home_page": "https://github.com/shammeer-s/nfl-tracks",
"name": "nfl-tracks",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "nfl, visualization, animated charts",
"author": "Mohammed Shammeer",
"author_email": "mohammedshammeer.s@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a3/7f/5991d5429f474a5049651f0d9ffaff1e1a0ff5910e0c0f6297d96b1c2b78/nfl_tracks-1.3.0.tar.gz",
"platform": null,
"description": "# NFL Field Visualization and Animation Library\r\n\r\nThis library provides utilities to visualize a football field, plot player positions, and animate plays. It is designed to handle data from tracking datasets, such as those used in football analytics.\r\n\r\nInstalling the library:\r\n\r\n```bash\r\npip install nfl_tracks\r\n```\r\n\r\nAfter successfully installing the nfl_tracks package, import it in the file using the code below:\r\n```python\r\n# Import nfl_tracks\r\nfrom nfl import visuals\r\n```\r\n## Table of Contents\r\n1. Function Overview\r\n * field()\r\n * snap()\r\n * play_game()\r\n2. Usage Examples \r\n3. Error Handling \r\n4. Customization Options\r\n---\r\n## 1. Function Overview\r\n## field()\r\nGenerates a plot of a football field with customizable features.\r\n\r\n```pythonverboseregexp\r\nfield(yard_numbers=True, touchdown_markings=True, fifty_yard=False, fig_size=(12, 6.33))\r\n```\r\n\r\n#### Parameters:\r\n* **yard_numbers (bool, default True)**: Whether to display yard numbers on the field.\r\n* **touchdown_markings (bool, default True)**: Whether to show touchdown zone labels.\r\n* **fifty_yard (bool, default False)**: Highlights the 50-yard line in gold.\r\n* **fig_size (tuple, default (12, 6.33))**: Specifies the figure size.\r\n\r\n#### Returns:\r\n* **fig (matplotlib.figure.Figure)**: The figure object.\r\n* **ax (matplotlib.axes.Axes)**: The axes object containing the plot.\r\n\r\n#### Example Usage:\r\n```python\r\nfig, ax = visuals.field()\r\nplt.show()\r\n```\r\n![field.png](https://raw.githubusercontent.com/shammeer-s/nfl-tracks/e0d4dcada2bab940d84978964a52b3f5a06ed60b/outputs/field.png \"Field\")\r\n---\r\n\r\n## snap()\r\nPlots the positions of players during a specific frame of a play.\r\n\r\n```pythonverboseregexp\r\nsnap(data, gameId, playId, frameId, yard_numbers=True, touchdown_markings=True, fifty_yard=False, fig_size=(12, 6.33), **kwargs)\r\n```\r\n\r\n#### Parameters:\r\n* **data (pd.DataFrame)**: Contains tracking data with columns including gameId, playId, frameId, x, y, and club.\r\n* **gameId (int)**: Identifier for the game.\r\n* **playId (int)**: Identifier for the play.\r\n* **frameId (int)**: Identifier for the specific frame within the play. \r\n* **yard_numbers (bool, default True)**: Whether to display yard numbers on the field.\r\n* **touchdown_markings (bool, default True)**: Whether to show touchdown zone labels.\r\n* **fifty_yard (bool, default False)**: Highlights the 50-yard line in gold.\r\n* **fig_size (tuple, default (12, 6.33))**: Specifies the figure size.\r\n* ****kwargs**: Additional arguments\r\n * **size (int, default 10)**: Marker size for players.\r\n * **club_colors (dict)**: Custom mapping of club indices to colors.\r\n\r\n#### Returns:\r\n* **fig (matplotlib.figure.Figure)**: The figure object.\r\n* **ax (matplotlib.axes.Axes)**: The axis object.\r\n\r\n#### Example Usage:\r\n```python\r\nfig, ax = visuals.snap(data, gameId=2022091200, playId=64, frameId=10)\r\nplt.show()\r\n```\r\n![snap.png](https://raw.githubusercontent.com/shammeer-s/nfl-tracks/refs/heads/master/outputs/snap.png \"snap\")\r\n---\r\n\r\n## play_game()\r\nAnimates a play by visualizing player movements over time.\r\n```pythonverboseregexp\r\nplay_game(data, gameId, playId, kaggle=True, yard_numbers=True, touchdown_markings=True, fifty_yard=False, fig_size=(12, 6.33), save=False, loop=False, **kwargs)\r\n```\r\n\r\n#### Parameters:\r\n* **data (pd.DataFrame)**: Contains tracking data with columns including gameId, playId, frameId, x, y, and club.\r\n* **gameId (int)**: Identifier for the game.\r\n* **playId (int)**: Identifier for the play.\r\n* **kaggle (bool, default True)**: Enables compatibility with Kaggle's notebook environments.\r\n* **yard_numbers (bool, default True)**: Whether to display yard numbers on the field.\r\n* **touchdown_markings (bool, default True)**: Whether to show touchdown zone labels.\r\n* **fifty_yard (bool, default False)**: Highlights the 50-yard line in gold.\r\n* **fig_size (tuple, default (12, 6.33))**: Specifies the figure size.\r\n* **save (bool, default False)**: Saves the animation as a play.gif file if True.\r\n* **loop (bool, default False)**: Repeats the animation if True.\r\n* ****kwargs**: Additional arguments\r\n * **size (int, default 10)**: Marker size for players.\r\n * **speed (int, default 100)**: Time interval between frames (in milliseconds).\r\n * **club_colors (dict)**: Custom mapping of club indices to colors.\r\n * **save_params (dict)**: Parameters for saving the animation.\r\n\r\n#### Returns:\r\n* **ani (matplotlib.animation.FuncAnimation)**: The animation object.\r\n\r\n#### Example Usage:\r\n```python\r\nani = visuals.play_game(data, gameId=2022091200, playId=64)\r\nani\r\n```\r\n![play.gif](https://raw.githubusercontent.com/shammeer-s/nfl-tracks/refs/heads/master/outputs/play.gif \"play_game\")\r\n---\r\n## 2. Usage Examples\r\nPlotting a Field\r\n```python\r\nfig, ax = visuals.field(touchdown_markings=False, fifty_yard=True)\r\nplt.show()\r\n```\r\n\r\nVisualizing a Single Frame\r\n```python\r\nfig, ax = visuals.snap(data, gameId=2022091200, playId=52, frameId=15, size=20)\r\nplt.show()\r\n```\r\n\r\nPlotting a Field\r\n```python\r\nani = visuals.play_game(data, gameId=2022091200, playId=24, save=True, speed=150)\r\nani\r\n```\r\n---\r\n## 3. Error Handling\r\n* **Data Validation**: Functions check whether _gameId_, _playId_, and _frameId_ exist in the data.\r\n* **Color Mapping**: Ensures all _club_ values map to valid colors. Raises an error if a _club_ is unmapped.\r\n* **Saving Animations**: Errors in saving are explained with links to relevant Matplotlib documentation.\r\n---\r\n## 4. Customization Options\r\n* **Player Marker Sizes**: Control player marker sizes using the _size_ parameter.\r\n* **Color Mapping**: Customize player colors by passing a dictionary to _club_colors_.\r\n* **Animation Speed**: Adjust frame transition time with the _speed_ parameter.\r\n* **Output Formats**: Save animations with customized parameters for the _PillowWriter_.\r\n---\r\n## 5. License\r\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/shammeer-s/nfl/blob/master/LICENSE) file for details.\r\n\r\n---\r\nThis 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.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Python library written on top of matplotlib library for customizable nfl charts",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://github.com/shammeer-s/nfl-tracks"
},
"split_keywords": [
"nfl",
" visualization",
" animated charts"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6cb8fdc292d5158370ac2ad5c1a6239a5a8a13b166358f9206c0df5229d4f1e8",
"md5": "0877769c53b3bf5e49f63bc78e878949",
"sha256": "a7f5dcfab0e35c2788c5a55b8865dfe14e886d81c3bcf783bc42d0e5597068f1"
},
"downloads": -1,
"filename": "nfl_tracks-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0877769c53b3bf5e49f63bc78e878949",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6461,
"upload_time": "2024-11-15T22:06:52",
"upload_time_iso_8601": "2024-11-15T22:06:52.477526Z",
"url": "https://files.pythonhosted.org/packages/6c/b8/fdc292d5158370ac2ad5c1a6239a5a8a13b166358f9206c0df5229d4f1e8/nfl_tracks-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a37f5991d5429f474a5049651f0d9ffaff1e1a0ff5910e0c0f6297d96b1c2b78",
"md5": "88dde74df3825af76486b747f5903de9",
"sha256": "a5fa97b28795f7ed753c6ee3d2d1ecfe34e460bfbd949ca0d041e3d2a303d9ce"
},
"downloads": -1,
"filename": "nfl_tracks-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "88dde74df3825af76486b747f5903de9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6633,
"upload_time": "2024-11-15T22:06:54",
"upload_time_iso_8601": "2024-11-15T22:06:54.976269Z",
"url": "https://files.pythonhosted.org/packages/a3/7f/5991d5429f474a5049651f0d9ffaff1e1a0ff5910e0c0f6297d96b1c2b78/nfl_tracks-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 22:06:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shammeer-s",
"github_project": "nfl-tracks",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "nfl-tracks"
}
JSON
