Skip to content

TRACAB

kloppy.tracab

Functions for loading Tracab tracking data.

load 

1
2
3
4
5
6
7
8
9
load(
    meta_data,
    raw_data,
    sample_rate=None,
    limit=None,
    coordinates=None,
    only_alive=True,
    file_format=None,
)

Load TRACAB tracking data.

PARAMETER DESCRIPTION
meta_data

A JSON or XML feed containing the meta data.

TYPE: FileLike

raw_data

A JSON or dat feed containing the raw tracking data.

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

only_alive

Only include frames in which the game is not paused.

TYPE: bool DEFAULT: True

file_format

Deprecated. The format will be inferred based on the file extensions.

TYPE: Optional[str] DEFAULT: None

RETURNS DESCRIPTION
TrackingDataset

The parsed tracking data.
Notes

Tracab distributes its metadata in various formats. Kloppy tries to infer automatically which format applies. Currently, kloppy supports the following formats:

  • Flat XML structure:

    13331 55 ...

  • Hierarchical XML structure:

    ...

  • JSON structure:

    { "GameID": 1, "CompetitionID": 1, "SeasonID": 2023, ... }

If parsing fails for a supported format or you encounter an unsupported structure, please create an issue on the kloppy GitHub repository with a sample of the problematic data.

Source code in kloppy/_providers/tracab.py 
12
13
14
15
16
17
18
19
20
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
52
53
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
85
86
87
88
def load(
    meta_data: FileLike,
    raw_data: FileLike,
    sample_rate: Optional[float] = None,
    limit: Optional[int] = None,
    coordinates: Optional[str] = None,
    only_alive: bool = True,
    file_format: Optional[str] = None,
) -> TrackingDataset:
    """
    Load TRACAB tracking data.

    Args:
        meta_data: A JSON or XML feed containing the meta data.
        raw_data: A JSON or dat feed containing the raw tracking data.
        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.
        only_alive: Only include frames in which the game is not paused.
        file_format: Deprecated. The format will be inferred based on the file extensions.

    Returns:
        The parsed tracking data.

    Notes:
        Tracab distributes its metadata in various formats. Kloppy tries to
        infer automatically which format applies. Currently, kloppy supports
        the following formats:

        - **Flat XML structure**:

            <root>
                <GameID>13331</GameID>
                <CompetitionID>55</CompetitionID>
                ...
            </root>

        - **Hierarchical XML structure**:

            <match iId="1" ...>
                <period iId="1" iStartFrame="1848508" iEndFrame="1916408"/>
                ...
            </match>

        - **JSON structure**:

            {
                "GameID": 1,
                "CompetitionID": 1,
                "SeasonID": 2023,
                ...
            }

        If parsing fails for a supported format or you encounter an unsupported
        structure, please create an issue on the kloppy GitHub repository
        with a sample of the problematic data.
    """
    # file format is deprecated
    if file_format is not None:
        warnings.warn(
            "file_format is deprecated. This is now automatically infered.",
            DeprecationWarning,
            stacklevel=2,
        )

    deserializer = TRACABDeserializer(
        sample_rate=sample_rate,
        limit=limit,
        coordinate_system=coordinates,
        only_alive=only_alive,
    )
    with open_as_file(meta_data) as meta_data_fp, open_as_file(
        raw_data
    ) as raw_data_fp:
        return deserializer.deserialize(
            inputs=TRACABInputs(meta_data=meta_data_fp, raw_data=raw_data_fp)
        )