Skip to main content

Standardizing soccer tracking- and event data

Project description

klop·pen (klopte, heeft geklopt) - juist zijn; overeenkomen, uitkomen met: dat klopt, dat kan kloppen is juist; dat klopt als een zwerende vinger dat is helemaal juist

PyPI Latest Release Downloads Powered by PySport

Soccer Data Processing, Simplified

Each data provider uses its own proprietary formats, event definitions, and coordinate system to capture soccer match data. This lack of standardization makes it difficult to build software or perform analysis across multiple providers. Kloppy solves this challenge by introducing a vendor-independent data model for both event and tracking data. It also streamlines data preprocessing, ensuring seamless integration into your data analysis and video analysis workflows. By standardizing and simplifying access to soccer match data, kloppy aims to be an essential building block for anyone working with soccer data.

Table of Contents

Supported data providers

Kloppy provides support for loading data from the following providers:

Provider Event Data Tracking Data Public Data Docs Notes
DataFactory
Hawkeye (2D) Joint tracking data is not yet supported
Metrica
PFF
SecondSpectrum
Signality
SkillCorner
Sportec
StatsBomb Includes 360 freeze frame data support
Stats Perform Includes support for MA1, MA3, and MA25 data feeds
Opta Includes support for F7, F24 and F73 XML data feeds
Tracab
Wyscout Includes support for v2 and v3 data

✓ Implemented    ⧗ In progress or partial support

Main features

Here are just a few of the things that kloppy does well.

🗄️ Loading data

Kloppy implements a standardized data model that can load event and tracking data from the most common data providers, supporting both public and proprietary data. Moreover, it does not matter where or how the data is stored: kloppy can handle compressed files and load data directly from the cloud.

from kloppy import sportec

dataset = sportec.load_open_event_data(match_id="J03WMX")

🔍 Querying data

Video analysts spend a lot of time searching for bespoke moments. Often, these moments follow recognizable patterns—like pass, pass, shot. Kloppy provides a powerful search mechanism based on regular expressions, enabling you to find these bespoke moments more quickly and easily.

goals = dataset.filter("shot.goal")

🔄 Transforming data

Different data providers use different coordinate systems, which can make combining datasets challenging. Additionally, it can be convenient to change the orientation of the data or normalize pitch dimensions for specific analyses. Kloppy handles these data transformations seamlessly.

goals_ltr = goals.transform(
    to_coordinate_system="opta",
    to_orientation="ACTION_EXECUTING_TEAM"
)

💾 Exporting data

Once your data is in the right shape, export it as a Polars or Pandas dataframe for efficient analysis, or as SportsCode XML to support your video analysis workflow. Kloppy's data model is also compatible with other popular soccer analytics libraries.

df_goals = goals_ltr.to_df(
  "player", 
  "coordinates_*", 
  assist=lambda event: event.prev("pass"),
  engine="polars"
)

Where to get it

The source code is hosted on GitHub at: https://github.com/PySport/kloppy.

The easiest way to install kloppy is via pip:

pip install kloppy

You can also install from GitHub for the latest updates:

pip install git+https://github.com/PySport/kloppy.git

For more details, refer to the installation guide.

Documentation

The official documentation is hosted at https://kloppy.pysport.org.

Contributing to kloppy

Kloppy can only exist because of a passionate and dedicated open-source community. All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome. An overview on how to contribute can be found in the contributing guide.

Made with contrib.rocks.

Sponsors

Kloppy is powered by PySport (non-profit, RSIN: 866294211). Consider contributing or donating to ensure its longevity!

License

Kloppy is distributed under the terms of the BSD 3 license.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kloppy-3.17.0.tar.gz (203.1 kB view details)

Uploaded Source

Built Distribution

kloppy-3.17.0-py3-none-any.whl (265.4 kB view details)

Uploaded Python 3

File details

Details for the file kloppy-3.17.0.tar.gz.

File metadata

  • Download URL: kloppy-3.17.0.tar.gz
  • Upload date:
  • Size: 203.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for kloppy-3.17.0.tar.gz
Algorithm Hash digest
SHA256 74ad3bdf5f9e5d8922a871182b076071afc36d0c10e04a305db224ed86f7cf57
MD5 b4fbab729059d99e7bcc5387715eba4e
BLAKE2b-256 e78ba82b783f25fdfdd962d1119c5c81388682dc5118dd4f977b972acbf4abac

See more details on using hashes here.

Provenance

The following attestation bundles were made for kloppy-3.17.0.tar.gz:

Publisher: release.yml on PySport/kloppy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kloppy-3.17.0-py3-none-any.whl.

File metadata

  • Download URL: kloppy-3.17.0-py3-none-any.whl
  • Upload date:
  • Size: 265.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for kloppy-3.17.0-py3-none-any.whl
Algorithm Hash digest
SHA256 c4be489109ddb9adfb2af3016c948951d22b23c284d544a8ad4589ad6dfa7aa0
MD5 1b0acad05b799bb870c846a2e8f617e2
BLAKE2b-256 27547734b548b63e2e6fb7e733107c6646d006ed4f9ee586ca249a79c9e74053

See more details on using hashes here.

Provenance

The following attestation bundles were made for kloppy-3.17.0-py3-none-any.whl:

Publisher: release.yml on PySport/kloppy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page