Skip to content

Hudl Statsbomb

kloppy.statsbomb

Functions for loading Hudl StatsBomb event data.

load 

1
2
3
4
5
6
7
8
9
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 
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
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 

1
2
3
4
5
6
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 
 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
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
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=f"https://raw.githubusercontent.com/statsbomb/open-data/master/data/events/{match_id}.json",
        lineup_data=f"https://raw.githubusercontent.com/statsbomb/open-data/master/data/lineups/{match_id}.json",
        three_sixty_data=Source(
            f"https://raw.githubusercontent.com/statsbomb/open-data/master/data/three-sixty/{match_id}.json",
            skip_if_missing=True,
        ),
        event_types=event_types,
        coordinates=coordinates,
        event_factory=event_factory,
    )