Hudl Statsbomb

kloppy.statsbomb

Functions for loading Hudl StatsBomb event data.

load

load(event_data, lineup_data, three_sixty_data=None, event_types=None, coordinates=None, event_factory=None, additional_metadata={})

Load StatsBomb event data.

PARAMETER	DESCRIPTION
event_data	JSON feed with the raw event data of a game. TYPE: FileLike
lineup_data	JSON feed with the corresponding lineup information of the game. TYPE: FileLike
three_sixty_data	JSON feed with the 360 freeze frame data of the game. TYPE: Optional[FileLike] DEFAULT: None
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
additional_metadata	A dict with additional data that will be added to the metadata. See the Metadata entity for a list of possible keys. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
EventDataset	The parsed event data.

Source code in kloppy/_providers/statsbomb.py

def load(
    event_data: FileLike,
    lineup_data: FileLike,
    three_sixty_data: Optional[FileLike] = None,
    event_types: Optional[list[str]] = None,
    coordinates: Optional[str] = None,
    event_factory: Optional[EventFactory] = None,
    additional_metadata: dict = {},
) -> EventDataset:
    """
    Load StatsBomb event data.

    Args:
        event_data: JSON feed with the raw event data of a game.
        lineup_data: JSON feed with the corresponding lineup information of the game.
        three_sixty_data: JSON feed with the 360 freeze frame data of the game.
        event_types: A list of event types to load.
        coordinates: The coordinate system to use.
        event_factory: A custom event factory.
        additional_metadata: A dict with additional data that will be added to
            the metadata. See the [`Metadata`][kloppy.domain.Metadata] entity
            for a list of possible keys.

    Returns:
        The parsed event data.
    """
    deserializer = StatsBombDeserializer(
        event_types=event_types,
        coordinate_system=coordinates,
        event_factory=event_factory
        or get_config("event_factory")
        or StatsBombEventFactory(),
    )
    with (
        open_as_file(event_data) as event_data_fp,
        open_as_file(lineup_data) as lineup_data_fp,
        open_as_file(
            Source.create(three_sixty_data, optional=True)
        ) as three_sixty_data_fp,
    ):
        return deserializer.deserialize(
            inputs=StatsBombInputs(
                event_data=event_data_fp,
                lineup_data=lineup_data_fp,
                three_sixty_data=three_sixty_data_fp,
            ),
            additional_metadata=additional_metadata,
        )

load_open_data

load_open_data(match_id='15946', event_types=None, coordinates=None, event_factory=None)

Load StatsBomb open data.

This function loads event data directly from the StatsBomb open data GitHub repository.

PARAMETER	DESCRIPTION
match_id	The id of the match to load data for. TYPE: Union[str, int] DEFAULT: '15946'
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/statsbomb.py

def load_open_data(
    match_id: Union[str, int] = "15946",
    event_types: Optional[list[str]] = None,
    coordinates: Optional[str] = None,
    event_factory: Optional[EventFactory] = None,
) -> EventDataset:
    """
    Load StatsBomb open data.

    This function loads event data directly from the StatsBomb open data
    GitHub repository.

    Args:
        match_id: The id of the match to load data for.
        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.
    """
    warnings.warn(
        "\n\nYou are about to use StatsBomb public data."
        "\nBy using this data, you are agreeing to the user agreement. "
        "\nThe user agreement can be found here: https://github.com/statsbomb/open-data/blob/master/LICENSE.pdf"
        "\n"
    )

    return load(
        event_data=github_resolve_raw_data_url(
            repository="statsbomb/open-data",
            branch="master",
            file=f"data/events/{match_id}.json",
        ),
        lineup_data=github_resolve_raw_data_url(
            repository="statsbomb/open-data",
            branch="master",
            file=f"data/lineups/{match_id}.json",
        ),
        three_sixty_data=Source(
            github_resolve_raw_data_url(
                repository="statsbomb/open-data",
                branch="master",
                file=f"data/three-sixty/{match_id}.json",
            ),
            skip_if_missing=True,
        ),
        event_types=event_types,
        coordinates=coordinates,
        event_factory=event_factory,
    )