floodlight.io.dfl
- floodlight.io.dfl.read_event_data_xml(filepath_events, filepath_mat_info, teamsheet_home=None, teamsheet_away=None)[source]
Parses a DFL Match Event XML file and extracts the event data as well as teamsheets.
The structure of the official tracking system of the DFL (German Football League) contains two separate xml files, one containing the actual data as well as a metadata file containing information about teams, pitch size, and start- and endframes of match periods. This function provides high-level access to DFL data by parsing “the full match” and returning Events-objects parsed from the event data xml-file as well as Teamsheet-objects parsed from the metadata xml-file. The number of segments is inferred from the data, yet data for each segment is stored in a separate object.
- Parameters
filepath_events (str or pathlib.Path) – Full path to XML File where the Event data in DFL format is saved.
filepath_mat_info (str or pathlib.Path) – Full path to XML File where the Match Information data in DFL format is saved.
teamsheet_home (Teamsheet, optional) – Teamsheet-object for the home team used to assign the tIDs of the teams to the “Home” and “Away” position. If given as None (default), teamsheet is extracted from the Match Information XML file.
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 (events_objects, teamsheets, pitch).
events_objects
is a nested dictionary containingEvents
objects for each team and segment of the formevents_objects[segment][team] = Events
. For a typical league match with two halves and teams this dictionary looks like:{ 'firstHalf': {'Home': Events, 'Away': Events}, 'secondHalf': {'Home': Events,'Away': Events} }
.teamsheets
is a dictionary containingTeamsheet
objects for each team of the formteamsheets[team] = Teamsheet
.pitch
is aPitch
object corresponding to the data.- Return type
Tuple[Dict[str, Dict[str, Events]], Dict[str, Teamsheet], Pitch]
Notes
The DFL format of handling event data information involves an elaborate use of certain event attributes, which attach additional information to certain events. There also exist detailed definitions for these attributes. Parsing this information involves quite a bit of logic and is planned to be included in further releases. As of now, qualifier information is parsed as a string in the qualifier column of the returned DataFrame and might be transformed to a dict of the form: {attribute: value}.
- floodlight.io.dfl.read_pitch_from_mat_info_xml(filepath_mat_info)[source]
Reads match_information XML file and returns the playing Pitch.
- Parameters
filepath_mat_info (str or pathlib.Path) – Full path to XML File where the Match Information data in DFL format is saved.
- Returns
pitch – Pitch object with actual pitch length and width.
- Return type
- floodlight.io.dfl.read_position_data_xml(filepath_positions, filepath_mat_info, teamsheet_home=None, teamsheet_away=None)[source]
Parse DFL files and extract position data, possession and ballstatus codes as well as pitch information and teamsheets.
The structure of the official tracking system of the DFL (German Football League) contains two separate xml files, one containing the actual data as well as a metadata file containing information about teams, pitch size, and start- and endframes of match periods. However, since no information about framerate is contained in the metadata, the framerate is estimated from the time difference between individual frames. This function provides high-level access to DFL data by parsing “the full match” and returning XY- and Code-objects parsed from the position data xml-file as well as Pitch- and Teamsheet-objects parsed from the metadata xml-file.
- Parameters
filepath_positions (str or pathlib.Path) – Full path to XML File where the Position data in DFL format is saved.
filepath_mat_info (str or pathlib.Path) – Full path to XML File where the Match Information data in DFL format is saved.
teamsheet_home (Teamsheet, optional) – Teamsheet-object for the home team used to create link dictionaries of the form links[team][jID] = xID and links[team][pID] = jID. 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 Match Information XML 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, ballstatus_objects, teamsheets, pitch).
xy_objects
is a nested dictionary containingXY
objects for each team and segment of the formxy_objects[segment][team] = XY
. For a typical league match with two halves and teams this dictionary looks like:{'firstHalf': {'Home': XY, 'Away': XY}, 'secondHalf': {'Home': XY, 'Away': XY}}
.possession_objects
is a dictionary containingCode
objects with possession information (home or away) for each segment of the formpossession_objects[segment] = Code
.ballstatus_objects
is a dictionary containingCode
objects with ballstatus information (dead or alive) for each segment of the formballstatus_objects[segment] = Code
.teamsheets
is a dictionary containingTeamsheet
objects for each team of the formteamsheets[team] = Teamsheet
.pitch
is aPitch
object corresponding to the data.- Return type
Tuple[Dict[str, Dict[str, XY]], Dict[str, Code], Dict[str, Code], Dict[str, Teamsheet], Pitch]
- floodlight.io.dfl.read_teamsheets_from_mat_info_xml(filepath_mat_info)[source]
Reads match_information XML file and returns two teamsheet objects for the home and the away team.
- Parameters
filepath_mat_info (str or pathlib.Path) – Full path to XML File where the Match Information data in DFL format is saved.
- Returns
teamsheets – Dictionary with teamsheets for the home team and the away team.
- Return type
Dict[str, Teamsheet]