Metrica Sports

kloppy.metrica

Functions for loading Metrica Sports event and tracking data.

load_event

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

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

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

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=github_resolve_raw_data_url(
                repository="metrica-sports/sample-data",
                branch="master",
                file="data/Sample_Game_1/Sample_Game_1_RawTrackingData_Home_Team.csv",
            ),
            away_data=github_resolve_raw_data_url(
                repository="metrica-sports/sample-data",
                branch="master",
                file="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=github_resolve_raw_data_url(
                repository="metrica-sports/sample-data",
                branch="master",
                file="data/Sample_Game_2/Sample_Game_2_RawTrackingData_Home_Team.csv",
            ),
            away_data=github_resolve_raw_data_url(
                repository="metrica-sports/sample-data",
                branch="master",
                file="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=github_resolve_raw_data_url(
                repository="metrica-sports/sample-data",
                branch="master",
                file="data/Sample_Game_3/Sample_Game_3_metadata.xml",
            ),
            raw_data=github_resolve_raw_data_url(
                repository="metrica-sports/sample-data",
                branch="master",
                file="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

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

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

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

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
            )
        )