chickenstats
About
- Scrape & manipulate data from various NHL endpoints with
chickenstats.chicken_nhl, including play-by-play, rosters, and shifts data, including score-adjusted shot metrics - Augment play-by-play data & generate custom aggregations from raw csv files downloaded from
Evolving-Hockey (subscription required) with
chickenstats.evolving_hockey
For more in-depth explanations, tutorials, & detailed reference materials, consult the Documentation.
Compatibility
chickenstats requires Python 3.10 or greater & runs on the latest stable versions of Linux, Mac, & Windows
operating systems.
Installation
Very simple - install using PyPi. Best practice is to develop in an isolated virtual environment (conda or otherwise), but who's a chicken to judge?
pip install chickenstats
To confirm installation & the latest version (1.8.2):
pip show chickenstats
Optional extras
Core installation includes only the essentials. Install extras for additional output formats or features:
| Extra | Command | What it adds |
|---|---|---|
pandas |
pip install chickenstats[pandas] |
Pandas DataFrame output (backend="pandas") |
pyarrow |
pip install chickenstats[pyarrow] |
PyArrow Table output (backend="pyarrow") |
plotting |
pip install chickenstats[plotting] |
Matplotlib, Bokeh, Plotly, Seaborn chart helpers |
Usage
chickenstats is structured as two underlying modules, each used with different data sources:
chickenstats.chicken_nhlchickenstats.evolving_hockey
The packages and resulting outputs are largely interchangeable, with similar fields across chicken_nhl
and evolving_hockey, including high-danger scoring chances, and score- and venue-adjusted fenwick
and corsi.
Feel free to use whichever package and data source that you prefer. If you have questions about differences between packages, you can find me on Bluesky at @chickenandstats.com or email me at chicken@chickenandstats.com.
Please note that chickenstats is under active development - features will continue to be added or modified over time.
chicken_nhl
chickenstats.chicken_nhl allows you to scrape play-by-play data and aggregate individual, line, and team statistics.
After importing the module, scrape the schedule for game IDs, then play-by-play data for your team of choice:
from chickenstats import Season, Scraper
import polars as pl
season = Season(2025)
schedule = season.schedule("NSH")
game_ids = schedule.filter(pl.col("game_state") == "OFF")["game_id"].to_list()
scraper = Scraper(game_ids)
play_by_play = scraper.play_by_play
You can then aggregate the play-by-play data for individual and on-ice statistics with one line of code:
stats = scraper.stats
It's very easy to introduce additional detail to, as well as change the level of, aggregations, including for season-level statistics accounting for teammates on-ice:
stats = scraper.prep_stats(level="season", teammates=True).stats
There is similar functionality for forward line / defensive pairing stats:
forward_lines = scraper.prep_lines(position="f").lines # Forward lines, defaults to game-level
defense_lines = scraper.prep_lines(position="d", level="season").lines # Defensive pairings, at season level
As well as for team stats:
team_stats = scraper.team_stats
For additional information on usage and functionality, consult the relevant user guide
evolving_hockey
The chickenstats.evolving_hockey module manipulates raw csv files downloaded from
Evolving-Hockey. Using their original shifts & play-by-play data, users can add additional
information & aggregate for individual & on-ice statistics,
including high-danger shooting events, faceoffs, & changes.
First, prep a play-by-play dataframe using raw play-by-play and shifts CSV files from the Evolving-Hockey website:
import polars as pl
from chickenstats.evolving_hockey import prep_pbp, prep_stats, prep_lines
raw_shifts = pl.read_csv('./raw_shifts.csv')
raw_pbp = pl.read_csv('./raw_pbp.csv')
play_by_play = prep_pbp(raw_pbp, raw_shifts)
You can use the play_by_play dataframe in various aggregations. This will return individual game statistics, including on-ice (e.g., GF, CF) & usage (i.e., zone starts), accounting for teammates & opposition on-ice:
individual_game = prep_stats(play_by_play, level='game', teammates=True, opposition=True)
This will return game statistics for forward-line combinations, accounting for opponents on-ice:
forward_lines = prep_lines(play_by_play, level='game', position='f', opposition=True)
For additional information on usage and functionality, consult the relevant user guide
Help
If you need help with any aspect of chickenstats, from installation to usage, please don't hesitate to reach out!
You can find me on Bluesky at @chickenandstats.com or
email me at chicken@chickenandstats.com.
Please report any bugs or issues via the chickenstats issues page, where you can also post feature requests.
Contributing
Contributions are welcome! Please read CONTRIBUTING.md for development setup, commit conventions, and the PR process. Found a bug or have a feature request? Open an issue.
This project follows a Code of Conduct. By participating, you are expected to uphold it.
Acknowledgements
chickenstats wouldn't be possible without the support & efforts of countless others. I am obviously
extremely grateful, even if there are too many of you to thank individually. However, this chicken will do his best.
First & foremost is my wife - the lovely Mrs. Chicken has been patient, understanding, & supportive throughout the countless hours of development, sometimes to her detriment.
Sincere apologies to the friends & family that have put up with me since my entry into Python, programming, & data analysis in January 2021. Thank you for being excited for me & with me throughout all of this, especially when you've had to fake it...
Thank you to the hockey analytics community on (the artist formerly known as) Twitter. You're producing & reacting to cutting-edge statistical analyses, while providing a supportive, welcoming environment for newcomers. Thank y'all for everything that you do. This is by no means exhaustive, but there are a few people worth calling out specifically:
- Josh & Luke Younggren (@EvolvingWild)
- Bryan Bastin (@BryanBastin)
- Max Tixador (@woumaxx)
- Micah Blake McCurdy (@IneffectiveMath)
- Prashanth Iyer (@iyer_prashanth)
- The Bucketless (@the_bucketless)
- Shayna Goldman (@hayyyshayyy)
- Dom Luszczyszyn (@domluszczyszyn)
- Carlie Markey (@quarkyhockey)
- An Nguyen (@nguyenank.bsky.social)
I'm also grateful to the thriving community of Python educators & open-source contributors on Twitter. Thank y'all for your knowledge & practical advice. Matt Harrison (@mharrison) deserves a special mention for his books on Pandas and XGBoost, both of which are available at his online store. Again, not exhaustive, but others worth thanking individually:
- Will McGugan (@willmcgugan)
- Rodrigo Girão Serrão (@mathsppblog)
- Mike Driscoll (@driscollis)
- Trey Hunner (@treyhunner)
- Pawel Jastrzebski (@pawjast)
Finally, this library depends on a host of other open-source packages. chickenstats is possible because of the efforts
of thousands of individuals, represented below:
1 maintainer
Metadata
1 maintainer
Release files for chickenstats 1.8.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| chickenstats-1.8.2.tar.gz | 868.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| chickenstats-1.8.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.1 MB
Release files / chickenstats-1.8.2.tar.gz
| Download URL | chickenstats-1.8.2.tar.gz |
|---|---|
| Size | 868.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d1c8ec42353020dbe9c5a3e6c0520dc331c93eb198b7d14850f56c403ef5c7ac
|
|
BLAKE2b-256 checksum How to use checksums |
9927e306857aaac98845426520deab5fb5d6a67ddc839f5c8f97d11809d88437
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / chickenstats-1.8.2-py3-none-any.whl
| Download URL | chickenstats-1.8.2-py3-none-any.whl |
|---|---|
| Size | 208.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f60e991b8691c68b5fa035ff70559d368ae8e43705c1412756a5d9814a98a71a
|
|
BLAKE2b-256 checksum How to use checksums |
7ef297cf13aaa69a441d5be0f420ebe43c0f1f99a99d86078e76dd5472b80e92
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
