floodlight.io.statsperform

floodlight.io.statsperform.read_event_data_from_url(url, teamsheet_home=None, teamsheet_away=None)

Reads a URL containing a StatsPerform events CSV file and extracts the stored event data, pitch information, and teamsheets.

The event data from the URL is downloaded into a temporary file stored in the repository’s internal root .data-folder and removed afterwards.

Parameters

• url (str) – URL to the XML file containing the event data.

• teamsheet_home (Teamsheet, optional) – Teamsheet-object for the home team used to create link dictionaries of the form links[pID] = team. The links are used to map players to the home and away teams. If given as None (default), teamsheet is extracted from the event data XML file.

• teamsheet_away (Teamsheet, optional) – Teamsheet-object for the away team. If given as None (default), teamsheet is extracted from the event data XML file. See teamsheet_home for details.

Returns

data_objects – Tuple of (nested) floodlight core objects with shape (events_objects, teamsheets, pitch).

events_objects is a nested dictionary containing Events objects for each team and segment of the form events_objects[segment][team] = Events. For a typical league match with two halves and teams this dictionary looks like: {'HT1': {'Home': Events, 'Away': Events}, 'HT2': {'Home': Events, 'Away': Events}}.

teamsheets is a dictionary containing Teamsheet objects for each team of the form teamsheets[team] = Teamsheet.

pitch is a Pitch object corresponding to the data.

Return type

Tuple[Dict[str, Dict[str, Events]], Dict[str, Teamsheet], Pitch]

floodlight.io.statsperform.read_event_data_xml(filepath_events, teamsheet_home=None, teamsheet_away=None)

Parses a StatsPerform XML file and extracts event data and pitch information.

This function provides high-level access to the StatsPerform match events XML file and returns Events objects for both teams and information about the pitch.

Parameters

• filepath_events (str or pathlib.Path) – Full path to the XML file containing the event data.

• teamsheet_home (Teamsheet, optional) – Teamsheet-object for the home team used to create link dictionaries of the form links[pID] = team. The links are used to map players to the home and away teams. If given as None (default), teamsheet is extracted from the event data XML file.

• teamsheet_away (Teamsheet, optional) – Teamsheet-object for the away team. If given as None (default), teamsheet is extracted from the event data XML file. See teamsheet_home for details.

Returns

data_objects – Tuple of (nested) floodlight core objects with shape (events_objects, teamsheets, pitch).

events_objects is a nested dictionary containing Events objects for each team and segment of the form events_objects[segment][team] = Events. For a typical league match with two halves and teams this dictionary looks like: {'HT1': {'Home': Events, 'Away': Events}, 'HT2': {'Home': Events, 'Away': Events}}.

teamsheets is a dictionary containing Teamsheet objects for each team of the form teamsheets[team] = Teamsheet.

pitch is a Pitch object corresponding to the data.

Return type

Tuple[Dict[str, Dict[str, Events]], Dict[str, Teamsheet], Pitch]

floodlight.io.statsperform.read_open_event_data_csv(filepath_events, teamsheet_home=None, teamsheet_away=None)

Parses an open StatsPerform Match Event CSV file and extracts the event data and teamsheets.

This function provides high-level access to the particular openly published StatsPerform match events CSV file (e.g. for the Pro Forum ‘22) and returns Event objects for both teams.

Parameters

• filepath_events (str or pathlib.Path) – Full path to xml File where the Event data in StatsPerform csv format is saved

• teamsheet_home (Teamsheet, optional) – Teamsheet-object for the home team. If given as None (default), teamsheet is extracted from the event data CSV file.

• teamsheet_away (Teamsheet, optional) – Teamsheet-object for the away team. If given as None (default), teamsheet is extracted from the event data CSV file.

Returns

data_objects – Tuple of (nested) floodlight core objects with shape (events_objects, teamsheets).

events_objects is a nested dictionary containing Events objects for each team and segment of the form events_objects[segment][team] = Events. For a typical league match with two halves and teams this dictionary looks like: {'1': {'Home': Events, 'Away': Events}, '2': {'Home': Events, 'Away': Events} }.

teamsheets is a dictionary containing Teamsheet objects for each team of the form teamsheets[team] = Teamsheet.

Return type

Tuple[Dict[str, Dict[str, Events]], Dict[str, Teamsheet]]

Notes

StatsPerform’s open format of handling provides certain additional event attributes, which attach additional information to certain events. As of now, these information are parsed as a string in the qualifier column of the returned DataFrame and can be transformed to a dict of form {attribute: value}.

floodlight.io.statsperform.read_open_position_data_csv(filepath_position, teamsheet_home=None, teamsheet_away=None)

Parses an open StatsPerform CSV file and extract position data and possession codes as well as teamsheets and pitch information.

Openly published StatsPerform position data (e.g. for the Pro Forum ‘22) is stored in a CSV file containing all position data (for both halves) as well as information about players, the pitch, and the ball possession. This function provides high-level access to StatsPerform data by parsing the CSV file.

Parameters

• filepath_position (str or pathlib.Path) – Full path to the CSV file.

• teamsheet_home (Teamsheet, optional) – Teamsheet-object for the home team used to create link dictionaries of the form links[team][jID] = xID. The links are used to map players to a specific xID in the respective XY objects. Should be supplied for custom ordering. If given as None (default), teamsheet is extracted from the open StatsPerform CSV file and its xIDs are assigned in order of appearance.

• teamsheet_away (Teamsheet, optional) – Teamsheet-object for the away team. If given as None (default), teamsheet is extracted from the Match Information XML file. See teamsheet_home for details.

Returns

data_objects – Tuple of (nested) floodlight core objects with shape (xy_objects, possession_objects, teamsheets, pitch).

xy_objects is a nested dictionary containing XY objects for each team and segment of the form xy_objects[segment][team] = XY. For a typical league match with two halves and teams this dictionary looks like: {0: {'Home': XY, 'Away': XY}, 1: {'Home': XY, 'Away': XY}}.

possession_objects is a dictionary containing Code objects with possession information (home or away) for each segment of the form possession_objects[segment] = Code.

teamsheets is a dictionary containing Teamsheet objects for each team of the form teamsheets[team] = Teamsheet.

pitch is a Pitch object corresponding to the data.

Return type

Tuple[Dict[int, Dict[str, XY]], Dict[int, Code], Dict[str, Teamsheet], Pitch]

floodlight.io.statsperform.read_position_data_from_url(url, teamsheet_home=None, teamsheet_away=None)

Reads a URL from the StatsPerform API (StatsEdgeViewer) containing a position data TXT file and extracts position data and teamsheets.

The position data from the URL is downloaded into a temporary file stored in the repository’s internal root .data-folder and removed afterwards.

Parameters

• url (str or pathlib.Path) – URL to the TXT file containing the position data.

• teamsheet_home (Teamsheet, optional) – Teamsheet-object for the home team used to create link dictionaries of the form links[team][jID] = xID. The links are used to map players to a specific xID in the respective XY objects. Should be supplied for custom ordering. If given as None (default), teamsheet is extracted from the position data TXT file and its xIDs are assigned in order of appearance.

• teamsheet_away (Teamsheet, optional) – Teamsheet-object for the away team. If given as None (default), teamsheet is extracted from the position data TXT file. See teamsheet_home for details.

Returns

data_objects – Tuple of (nested) floodlight core objects with shape (xy_objects, teamsheets).

xy_objects is a nested dictionary containing XY objects for each team and segment of the form xy_objects[segment][team] = XY. For a typical league match with two halves and teams this dictionary looks like: {1: {'Home': XY, 'Away': XY}, 2: {'Home': XY, 'Away': XY}}.

teamsheets is a dictionary containing Teamsheet objects for each team of the form teamsheets[team] = Teamsheet.

Return type

Tuple[Dict[int, Dict[str, XY]], Dict[int, Teamsheet]]

Notes

Statsperform position data does not contain any player information expect jersey numbers by default. Thus, the teamsheet objects generated by this method will name players ‘Player i’ with i starting at 1. To identify players, use the jersey numbers of players or provide custom teamsheets (e.g. by parsing teamsheets from the Statsperform event data or another data provider).

floodlight.io.statsperform.read_position_data_txt(filepath_position, teamsheet_home=None, teamsheet_away=None)

Parses a StatsPerform TXT file and extracts position data and teamsheets.

Internal StatsPerform position data is stored as a TXT file containing all position data (for both halves). This function provides high-level access to StatsPerform data by parsing the TXT file. Since no information about framerate is delivered in the data itself, it is estimated from time difference between individual frames. Teamsheets are extracted from the event data, if filepath_events is provided. Otherwise, minimal Teamsheet-objects are inferred from the position data.

Parameters

• filepath_position (str or pathlib.Path) – Full path to the TXT file containing the position data.

• teamsheet_home (Teamsheet, optional) – Teamsheet-object for the home team used to create link dictionaries of the form links[team][jID] = xID. The links are used to map players to a specific xID in the respective XY objects. Should be supplied for custom ordering. If given as None (default), teamsheet is extracted from the position data TXT file and its xIDs are assigned in order of appearance.

• teamsheet_away (Teamsheet, optional) – Teamsheet-object for the away team. If given as None (default), teamsheet is extracted from the position data TXT file. See teamsheet_home for details.

Returns

data_objects – Tuple of (nested) floodlight core objects with shape (xy_objects, teamsheets).

xy_objects is a nested dictionary containing XY objects for each team and segment of the form xy_objects[segment][team] = XY. For a typical league match with two halves and teams this dictionary looks like: {1: {'Home': XY, 'Away': XY}, 2: {'Home': XY, 'Away': XY}}.

teamsheets is a dictionary containing Teamsheet objects for each team of the form teamsheets[team] = Teamsheet.

Return type

Tuple[Dict[int, Dict[str, XY]], Dict[int, Teamsheet]]

Notes

Statsperform position data does not contain any player information expect jersey numbers by default. Thus, the teamsheet objects generated by this method will name players ‘Player i’ with i starting at 1. To identify players, use the jersey numbers of players or provide custom teamsheets (e.g. by parsing teamsheets from the Statsperform event data or another data provider).

floodlight.io.statsperform.read_teamsheets_from_event_data_xml(filepath_events)

Parses the StatsPerform event file and returns two Teamsheet-objects with detailed player information for the home and the away team.

Parameters

filepath_events (str or pathlib.Path) – Full path to the XML file containing the event data.

Returns

teamsheets – Dictionary with teamsheets for the home team and the away team.

Return type

Dict[str, Teamsheet]

floodlight.io.statsperform.read_teamsheets_from_open_data_csv(filepath_csv)

Parses the entire open StatsPerform position data CSV file for unique jIDs (jerseynumbers) and creates teamsheets for both teams.

Parameters

filepath_csv (str or pathlib.Path) – CSV file containing either open position or open event data.

Returns

teamsheets – Dictionary with teamsheets for the home team and the away team.

Return type

Dict[str, Teamsheet]

Notes

Statsperform open data does not contain any player names. Thus, the teamsheet objects generated by this method will name players ‘Player i’ with i starting at 1. To identify players, use the jersey numbers of players or provide custom teamsheets generated by a different parser if Statsperform open data is used in combination with other data providers.

floodlight.io.statsperform.read_teamsheets_from_position_data_txt(filepath_position)

Parses the StatsPerform position file and returns two simple Teamsheet-objects containing only two columns “player” and “jID” for the home and the away team.

Parameters

filepath_position (str or pathlib.Path) – Full path to the TXT file containing the position data.

Returns

teamsheets – Dictionary with teamsheets for the home team and the away team.

Return type

Dict[str, Teamsheet]