duckstatsbomb

Get flat tables from Hudl StatsBomb data, in multiple formats, in seconds once cached.

DuckDB does the parsing in parallel. You can parse a whole Premier League season of 1.3 million events from JSON into pandas, Polars or Arrow tables in a few seconds. Or use the default output, a DuckDB relation, and filter to the shots and sum the xG before building a DataFrame, so you can query the whole open-data set on your laptop.

Installation

The duckstatsbomb default has one dependency, DuckDB. You can install optional dependencies to export to pandas, Polars, or Arrow:

pip install duckstatsbomb
pip install "duckstatsbomb[pandas]"  # pandas
pip install "duckstatsbomb[polars]"  # Polars & PyArrow
pip install "duckstatsbomb[arrow]"  # PyArrow
pip install "duckstatsbomb[all]"  # pandas, Polars & PyArrow

Quick start

By default the library outputs a DuckDBPyRelation, which you can filter, aggregate, or query.

from duckstatsbomb import Sbopen
parser = Sbopen()
events = parser.competition_data(competition_id=43, season_id=106, kind='events')
shots = events.filter("type_name = 'Shot'")
# top 4 goal scorers at the 2022 World Cup
top = (
    shots.aggregate(
        'player_name, team_name, count(*) as shots, '
        'round(sum(shot_statsbomb_xg), 2) as xg, '
        "count(*) filter (outcome_name = 'Goal') as goals"
    )
    .order('goals desc, xg desc')
    .limit(4)
)
top.show()

You can also export to different formats:

df_pandas = shots.df()  # pip install "duckstatsbomb[pandas]"
df_polars = shots.pl()  # pip install "duckstatsbomb[polars]"
arrow_table = shots.to_arrow_table()  # pip install "duckstatsbomb[arrow]"
shots.to_csv('world_cup_2022_shots.csv')
shots.to_parquet('world_cup_2022_shots.parquet')

Or set the output format when creating the parser:

parser = Sbopen(output_format='pandas')  # 'relation', 'pandas', 'polars' or 'arrow'

Three parsers

There is one parser for each place the data comes from:

• Open-data with Sbopen, for the free StatsBomb open-data

• API with Sbapi, which needs a Hudl StatsBomb API subscription

• Files with Sbfiles, for JSON files you already have, on disk or in an object store

Want to help?

Take a look at the open issues for inspiration. Please get in touch at rowlinsonandy@gmail.com to find out more.

License

MIT

The StatsBomb open-data has its own licence, which is for non-commercial use.