Skip to content

Metrica Sports

kloppy.metrica

Functions for loading Metrica Sports event and tracking data.

load_event 

1
2
3
4
5
6
7
load_event(
    event_data,
    meta_data,
    event_types=None,
    coordinates=None,
    event_factory=None,
)

Load Metrica Sports JSON event data.

PARAMETER DESCRIPTION
event_data

A json feed containing the raw event data.

TYPE: FileLike

meta_data

A xml feed containing the match meta data.

TYPE: FileLike

event_types

A list of event types to load.

TYPE: Optional[List[str]] DEFAULT: None

coordinates

The coordinate system to use.

TYPE: Optional[str] DEFAULT: None

event_factory

A custom event factory.

TYPE: Optional[EventFactory] DEFAULT: None

RETURNS DESCRIPTION
EventDataset

The parsed event data.
Source code in kloppy/_providers/metrica.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
def load_event(
    event_data: FileLike,
    meta_data: FileLike,
    event_types: Optional[List[str]] = None,
    coordinates: Optional[str] = None,
    event_factory: Optional[EventFactory] = None,
) -> EventDataset:
    """Load Metrica Sports JSON event data.

    Args:
        event_data: A json feed containing the raw event data.
        meta_data: A xml feed containing the match meta data.
        event_types: A list of event types to load.
        coordinates: The coordinate system to use.
        event_factory: A custom event factory.

    Returns:
        The parsed event data.
    """
    deserializer = MetricaJsonEventDataDeserializer(
        event_types=event_types,
        coordinate_system=coordinates,
        event_factory=event_factory or get_config("event_factory"),
    )

    with open_as_file(event_data) as event_data_fp, open_as_file(
        meta_data
    ) as meta_data_fp:
        return deserializer.deserialize(
            inputs=MetricaJsonEventDataInputs(
                event_data=event_data_fp, meta_data=meta_data_fp
            )
        )

load_open_data 

1
2
3
4
5
6
load_open_data(
    match_id="1",
    sample_rate=None,
    limit=None,
    coordinates=None,
)

Load Metrica Sports open data.

This function loads tracking data directly from Metrica's open data GitHub repository.

PARAMETER DESCRIPTION
match_id

The id of the match to load data for.

TYPE: Union[str, int] DEFAULT: '1'

sample_rate

Sample the data at a specific rate.

TYPE: Optional[float] DEFAULT: None

limit

Limit the number of frames to load to the first limit frames.

TYPE: Optional[int] DEFAULT: None

coordinates

The coordinate system to use.

TYPE: Optional[str] DEFAULT: None

RETURNS DESCRIPTION
TrackingDataset

The parsed event data.
Source code in kloppy/_providers/metrica.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
def load_open_data(
    match_id: Union[str, int] = "1",
    sample_rate: Optional[float] = None,
    limit: Optional[int] = None,
    coordinates: Optional[str] = None,
) -> TrackingDataset:
    """Load Metrica Sports open data.

    This function loads tracking data directly from Metrica's open data
    GitHub repository.

    Args:
        match_id: The id of the match to load data for.
        sample_rate: Sample the data at a specific rate.
        limit: Limit the number of frames to load to the first `limit` frames.
        coordinates: The coordinate system to use.

    Returns:
        The parsed event data.
    """
    if match_id == "1" or match_id == 1:
        return load_tracking_csv(
            home_data="https://raw.githubusercontent.com/metrica-sports/sample-data/"
            "master/data/Sample_Game_1/Sample_Game_1_RawTrackingData_Home_Team.csv",
            away_data="https://raw.githubusercontent.com/metrica-sports/sample-data/"
            "master/data/Sample_Game_1/Sample_Game_1_RawTrackingData_Away_Team.csv",
            sample_rate=sample_rate,
            limit=limit,
            coordinates=coordinates,
        )
    elif match_id == "2" or match_id == 2:
        return load_tracking_csv(
            home_data="https://raw.githubusercontent.com/metrica-sports/sample-data/"
            "master/data/Sample_Game_2/Sample_Game_2_RawTrackingData_Home_Team.csv",
            away_data="https://raw.githubusercontent.com/metrica-sports/sample-data/"
            "master/data/Sample_Game_2/Sample_Game_2_RawTrackingData_Away_Team.csv",
            sample_rate=sample_rate,
            limit=limit,
            coordinates=coordinates,
        )
    elif match_id == "3" or match_id == 3:
        return load_tracking_epts(
            meta_data="https://raw.githubusercontent.com/metrica-sports/sample-data/"
            "master/data/Sample_Game_3/Sample_Game_3_metadata.xml",
            raw_data="https://raw.githubusercontent.com/metrica-sports/sample-data/"
            "master/data/Sample_Game_3/Sample_Game_3_tracking.txt",
            sample_rate=sample_rate,
            limit=limit,
            coordinates=coordinates,
        )
    else:
        raise KloppyError(
            f"Don't know where to fetch Metrica open data for {match_id}"
        )

load_tracking_csv 

1
2
3
4
5
6
7
load_tracking_csv(
    home_data,
    away_data,
    sample_rate=None,
    limit=None,
    coordinates=None,
)

Load Metrica Sports CSV tracking data.

PARAMETER DESCRIPTION
home_data

The raw tracking data for the home team.

TYPE: FileLike

away_data

The raw tracking data for the away team.

TYPE: FileLike

sample_rate

Sample the data at a specific rate.

TYPE: Optional[float] DEFAULT: None

limit

Limit the number of frames to load to the first limit frames.

TYPE: Optional[int] DEFAULT: None

coordinates

The coordinate system to use.

TYPE: Optional[str] DEFAULT: None

RETURNS DESCRIPTION
TrackingDataset

The parsed tracking data.
Source code in kloppy/_providers/metrica.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def load_tracking_csv(
    home_data: FileLike,
    away_data: FileLike,
    sample_rate: Optional[float] = None,
    limit: Optional[int] = None,
    coordinates: Optional[str] = None,
) -> TrackingDataset:
    """
    Load Metrica Sports CSV tracking data.

    Args:
        home_data: The raw tracking data for the home team.
        away_data: The raw tracking data for the away team.
        sample_rate: Sample the data at a specific rate.
        limit: Limit the number of frames to load to the first `limit` frames.
        coordinates: The coordinate system to use.

    Returns:
        The parsed tracking data.
    """
    deserializer = MetricaCSVTrackingDataDeserializer(
        sample_rate=sample_rate, limit=limit, coordinate_system=coordinates
    )
    with open_as_file(home_data) as home_data_fp, open_as_file(
        away_data
    ) as away_data_fp:
        return deserializer.deserialize(
            inputs=MetricaCSVTrackingDataInputs(
                home_data=home_data_fp, away_data=away_data_fp
            )
        )

load_tracking_epts 

1
2
3
4
5
6
7
load_tracking_epts(
    meta_data,
    raw_data,
    sample_rate=None,
    limit=None,
    coordinates=None,
)

Load Metrica Sports EPTS tracking data.

PARAMETER DESCRIPTION
meta_data

A xml feed containing the match meta data.

TYPE: FileLike

raw_data

A feed containing the raw tracking data in the EPTS format.

TYPE: FileLike

sample_rate

Sample the data at a specific rate.

TYPE: Optional[float] DEFAULT: None

limit

Limit the number of frames to load to the first limit frames.

TYPE: Optional[int] DEFAULT: None

coordinates

The coordinate system to use.

TYPE: Optional[str] DEFAULT: None

RETURNS DESCRIPTION
TrackingDataset

The parsed tracking data.
Source code in kloppy/_providers/metrica.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def load_tracking_epts(
    meta_data: FileLike,
    raw_data: FileLike,
    sample_rate: Optional[float] = None,
    limit: Optional[int] = None,
    coordinates: Optional[str] = None,
) -> TrackingDataset:
    """
    Load Metrica Sports EPTS tracking data.

    Args:
        meta_data: A xml feed containing the match meta data.
        raw_data: A feed containing the raw tracking data in the EPTS format.
        sample_rate: Sample the data at a specific rate.
        limit: Limit the number of frames to load to the first `limit` frames.
        coordinates: The coordinate system to use.

    Returns:
        The parsed tracking data.
    """
    deserializer = MetricaEPTSTrackingDataDeserializer(
        sample_rate=sample_rate, limit=limit, coordinate_system=coordinates
    )
    with open_as_file(raw_data) as raw_data_fp, open_as_file(
        meta_data
    ) as meta_data_fp:
        return deserializer.deserialize(
            inputs=MetricaEPTSTrackingDataInputs(
                raw_data=raw_data_fp, meta_data=meta_data_fp
            )
        )