Domain Concepts

The kloppy.domain module defines entities that reflect real-world concepts within the domain of soccer match data. These entities serve as the framework upon which kloppy's logic is structured. The domain concepts are arranged hierarchically. At the highest level, kloppy defines the concept of a Dataset. Each dataset is linked with a Metadata entity, which holds all external information that describes the dataset.

Dataset

A Dataset describes specific aspects of what happened during a single match as a sequence of DataRecord entities. Kloppy defines three main types of match datasets: EventDataset, TrackingDataset, and CodeDataset.

First, we describe the entities related to each of these three dataset types. Next, we discuss the structure of the metadata.

EventDataset

An EventDataset is a chronologically ordered sequence of Event entities. Each Event represents an on-the-ball action (e.g., pass, shot, tackle) or tactical change (e.g., substitution) and is annotated with a set of attributes that describe the event:

• an EventType,
• a Time when the event happened,
• a Team involved in the event,
• the AttackingDirection of the team executing the event,
• the ball owning Team,
• a Player involved in the event,
• a Point on the pitch where the event happened,
• the BallState during the event,
• a list of Qualifier entities providing additional details, and
• optionally a tracking data Frame.

Depending on the EventType, an event can have additional attributes.

TrackingDataset

A TrackingDataset is a sequence of Frame entities. Each frame describes the locations of the ball and the players as a Point on the pitch at a particular Time.

CodeDataset

A CodeDataset is a sequence of Code entities, each representing a tagged event within a match.

Metadata

A Metadata object contains all external information describing the match: two Team entities that describe the line-ups of both teams, the Period entities that describe the start and end times of each period of the match, the final Score, the Provider that collected the data, the Orientation (i.e., playing direction) of both teams, and the CoordinateSystem in which locations are defined.