04Readers and formats

DataBallPy

Loads tracking and event data, then synchronises the two, so that each event sits on the tracking frame where it happened.

  • Tracking + events
  • Reader
  • Event sync
  • MIT
Events are logged on one clock and tracking on another. Synchronisation pins each event to its frame.
Modality
Tracking and event data
Output
Synchronised dataframes and analytical representations
Evidence
Documented open Python package
Code and weights
Python package
Licence
MIT

Event data and tracking data describe the same match on different clocks. Events are logged by people, with timestamps that trail the action. Tracking is sampled 25 times a second by machines. Asking where everyone stood when a pass was played means putting the event on the right frame.

DataBallPy treats that as a central job. It reads tracking and event files into dataframes, then synchronises them, so that events carry the tracking frame they belong to. Around that it provides preprocessing and visualisation for the combined data.

Where it wins

  • It solves event-to-tracking alignment, which most loaders leave to the user.
  • Synchronised events are touch labels on the tracking clock, the best cheap supervision there is for possession boundaries.
  • One package from files to analysis-ready frames.
  • MIT.

What it costs

  • Synchronisation quality depends on both feeds. A missing ball track or anonymous players leave little to match against.
  • A dataframe-centric design is convenient, and slower than arrays at match scale.
  • Event-derived columns sit next to tracking columns. Using them as model inputs leaks the answer.

How it plugs into possession

For building reference labels on external matches. Synchronised events turn into possession spells directly: a pass by a home player starts or continues a home spell at a known frame. That is how event data becomes a per-frame possession reference where a provider ships no possession flag.

The leak warning is the practical one. A possession method must be validated with event-derived columns removed from its inputs, or it is being graded on an open book.

kloppy covers the broader range of providers. The datasets themselves are under Datasets.

Our read

The reader to use when events must land on frames. Its synchronisation is the feature. Keep its event columns out of your model's inputs.

Sources

  1. databallpy: read, preprocess, visualise and synchronise soccer event and tracking data (repository)github.com