Game and get_game

Game and get_game#

Get Game#

databallpy.get_game

get_game(tracking_data_loc: str | None = None, tracking_metadata_loc: str | None = None, event_data_loc: str | None = None, event_metadata_loc: str | None = None, event_match_loc: str | None = None, event_lineup_loc: str | None = None, tracking_data_provider: str | None = None, event_data_provider: str | None = None, check_quality: bool = True, _check_game_class_: bool = True, verbose: bool = True) → Game[source]#

Function to get all information of a game given its datasources

Parameters:

  • tracking_data_loc (str, optional) – location of the tracking data. Defaults to None.

  • tracking_metadata_loc (str, optional) – location of the metadata of the tracking data. Defaults to None.

  • event_data_loc (str, optional) – location of the event data. Defaults to None.

  • event_metadata_loc (str, optional) – location of the metadata of the event data. Defaults to None.

  • event_match_loc (str, optional) – location of the game file of the event data. Only used for statsbomb event data. Defaults to None.

  • event_lineup_loc (str, optional) – location of the lineup file of the event data. Only used for statsbomb event data. Defaults to None.

  • tracking_data_provider (str, optional) – provider of the tracking data. Defaults to None. Supported providers are [tracab, metrica, inmotio]

  • event_data_provider (str, optional) – provider of the event data. Defaults to None. Supported providers are [opta, metrica, instat, scisports]

  • check_quality (bool, optional) – whether you want to check the quality of the tracking data. Defaults to True

  • verbose (bool, optional) – whether or not to print info about progress

Returns:

a game object with all information available of the game.

Return type:

(Game)

get_open_game(provider: str = 'sportec', game_id: str = 'J03WMX', verbose: bool = True, use_cache: bool = True) → Game[source]#

Function to load a game object from an open datasource

Parameters:

  • provider (str, optional) – What provider to get the open data from. Defaults to “sportec”. Options are [“metrica”, “dfl”, “sportec”, “tracab”]

  • game_id (str, optional) – The Game id of the open game. Defaults to ‘J03WMX’,

  • verbose (bool, optional) – Whether or not to print info about progress

  • terminal (in the)

  • True. (Defaults to)

  • use_cache (bool, optional) – Use cached version of match if available.

Returns:

All information about the game

Return type:

Game

get_saved_game(name: str, path: str = '/home/docs/checkouts/readthedocs.org/user_builds/databallpy/checkouts/latest/docs') → Game[source]#

Function to load a saved game object

Parameters:

  • name (str) – the name with the to be loaded game, should be a folder.

  • contain (The folder should) –

    • tracking_data.parquet

    • event_data.parquet

    • periods.parquet

    • pass_events.parquet

    • shot_events.parquet

    • dribble_events.parquet

    • away_players.parquet

    • home_players.parquet

    • metadata.json

    path (str, optional): path of directory where game is saved. Defaults

    to current working directory.

Returns:

All information about the game

Return type:

Game

Game object#

databallpy.game.Game

class Game(tracking_data: TrackingData, event_data: EventData, pitch_dimensions: list[float], periods: DataFrame, home_team_id: int, home_team_name: str, home_players: DataFrame, home_score: int, home_formation: str, away_team_id: int, away_team_name: str, away_players: DataFrame, away_score: int, away_formation: str, country: str | None, shot_events: DataFrame, dribble_events: DataFrame, pass_events: DataFrame, allow_synchronise_tracking_and_event_data: bool = False, _is_synchronised: bool = False, _tracking_timestamp_is_precise: bool = False, _event_timestamp_is_precise: bool = False, _periods_changed_playing_direction: list[int] | None = None, _check_inputs_: bool = True)[source]

Bases: object

This is the game class. It contains all information of the game and has some simple functions to easily obtain information about the game.

Parameters:

  • tracking_data (TrackingData) – Tracking data of the game.

  • event_data (EventData[pd.DataFrame]) – Event data of the game.

  • pitch_dimensions (Tuple) – The size of the pitch in meters in x and y direction.

  • periods (pd.DataFrame) – The start and end idicators of all periods.

  • home_team_id (int) – The id of the home team.

  • home_team_name (str) – The name of the home team.

  • home_players (pd.DataFrame) – Information about the home players.

  • home_score (int) – Number of goals scored over the game by the home team.

  • home_formation (str) – Indication of the formation of the home team.

  • away_team_id (int) – The id of the away team.

  • away_team_name (str) – The name of the away team.

  • away_players (pd.DataFrame) – Information about the away players.

  • away_score (int) – Number of goals scored over the game by the away team.

  • away_formation (str) – Indication of the formation of the away team.

  • country (str) – The country where the game was played.

  • shot_events (pd.DataFrame) – A df with all th shot events.

  • dribble_events (pd.DataFrame) – A df with all the dribble events.

  • pass_events (pd.DataFrame) – A df with all the pass events.

  • allow_synchronise_tracking_and_event_data (bool) – If True, the tracking and

  • False (event data can be synchronised. If)

  • False. (it can not. Default =)

copy() → Game[source]

Function to create a copy of the game object

Returns:

copy of the game object

Return type:

Game

property date: Timestamp | None

Function to get the date of the game

Returns:

The date of the game

Return type:

pd.Timestamp | None

property event_timestamp_is_precise: bool

Function to check if the event timestamps are precise or not Timesamp is considered precise if the start of the game is not exactly at the start of the initial game time (e.g. 20:00:00), but at the actual start of the game (e.g. 20:00:03.2378).

Returns:

True if the event timestamps are precise, False otherwise

Return type:

bool

get_column_ids(team: str | None = None, positions: list[str] = ['goalkeeper', 'defender', 'midfielder', 'forward', 'unspecified'], min_minutes_played: float | int = 0.01, idx: int | None = None, remove_offside_players: bool = False) → list[str][source]

Function to get the column ids that are used in the tracking data. With this function you can filter on team side, position, or minimum minutes played. If no arguments are specified, all column ids are returned of players that j played at least 0.1 minute.

Parameters:

  • team (str | None, optional) – Which team to add, can be {home, away, None}. If None, both teams are added. Defaults to None.

  • positions (list[str], optional) – The positions to include {goalkeeper, defender, midfielder, forward}. Defaults to [“goalkeeper”, “defender”, “midfielder”, “forward”].

  • min_minutes_played (float | int, optional) – The minimum number of minutes a player needs to have played during the game to be returned. Defaults to 0.01.

  • idx (int | None) – Get only the column ids of players that have valid data in this index in game.TrackingData. If none, returns column ids of valid players on any frame during the game. Defaults to None.

  • remove_offside_players (bool) – Whether to remove players that are offside. Note, this only works when idx is not None. Defaults to None.

Raises:

  • ValueError – If team is not in {None, home, away}

  • ValueError – If there is an unknown position

  • TypeError – if min_minutes_played is not numeric

Returns:

The column ids of the players.

Return type:

list[str]

get_event(event_id: int) → Series[source]

Function to get the event with the given event_id

Parameters:

event_id (int) – The id of the event

Raises:

ValueError – if the event with the given event_id is not found in the game

Returns:

The event with the given event_id

Return type:

pd.Series

get_event_frame(event_id: int | str, playing_direction: str = 'team_oriented') → DataFrame[source]

Function to get the frame of the event with the given event_id

Parameters:

  • event_id (int | str) – The id of the event

  • playing_direction (str, optional) – The coordinate system of the frame. Defaults to “team_oriented”, options are {team_oriented, possession_oriented}. For more info on the coordinate systems, see the databallpy documentation

Raises:

  • ValueError – if the event with the given event_id is not found in the game

  • ValueError – if the event with the given event_id is not found in the tracking data

Returns:

The frame of the game with the given event_id

Return type:

pd.DataFrame

get_frames(frames: int | list[int], playing_direction: str = 'team_oriented') → DataFrame[source]

Function to get the frame of the game with the given frame

Parameters:

  • frames (int|list[int]) – The frames of the game

  • playing_direction (str, optional) – The coordinate system of the frame. Defaults to “team_oriented”, options are {team_oriented, possession_oriented}. For more info on the coordinate systems, see the documentation

Returns:

The frame of the game with the given frames

Return type:

pd.DataFrame

property is_synchronised: bool

Function to check if the tracking and event data are synchronised

Returns:

True if the tracking and event data are synchronised, False otherwise

Return type:

bool

property name: str

Function to get the name of the game

Returns:

The name of the game

Return type:

str

player_column_id_to_full_name(column_id: str) → str[source]

Simple function to get the full name of a player from the column id

Parameters:

column_id (str) – the column id of a player, for instance “home_1”

Returns:

full name of the player

Return type:

str

player_id_to_column_id(player_id: int) → str[source]

Simple function to get the column id based on player id

Parameters:

player_id (int) – id of the player

Returns:

column id of the player, for instance “home_1”

Return type:

str

save_game(name: str | None = None, path: str | None = None, verbose: bool = True, allow_overwrite: bool = False) → None[source]

Function to save the current game object. The path name will create a folder with different parquet and json files that stores all the information of the match.

Parameters:

  • name (str) – name of the folder where the match will be saved,

  • game. (if not provided or not a string the name will be the name of the)

  • path (str) – path to the directory where the folder will be saved. If

  • provided (not)

  • used. (the current working directory will be)

  • verbose (bool) – if True, saved name will be printed

  • allow_overwrite (bool) – if True, the function will overwrite the

  • name. (existing folder with the same)

synchronise_tracking_and_event_data(n_batches: int | str = 'smart', verbose: bool = True, offset: int = 1, cost_functions: dict = {}, _optimize: bool = False)[source]
Function that synchronises tracking and event data using Needleman-Wunsch

algorithmn. Based on: https://kwiatkowski.io/sync.soccer

Parameters:

  • game (Game) – Game object

  • n_batches (int or str) – the number of batches that are created. A higher number of batches reduces the time the code takes to load, but reduces the accuracy for events close to the splits. Default = ‘smart’. If ‘smart’, the number of batches is determined based on the number of dead moments in the game.

  • verbose (bool, optional) – Wheter or not to print info about the progress in the terminal. Defaults to True.

  • offset (float, optional) – Offset in seconds that is added to the difference between the first event and the first tracking frame. This is done because this way the event is synced to the last frame the ball is close to a player. Which often corresponds with the event (pass and shots). Defaults to 1.0.

  • cost_functions (dict, optional) – Dictionary containing the cost functions that are used to calculate the similarity between the tracking and event data. The keys of the dictionary are the event types, the values are the cost functions. The cost functions will be called with the tracking data and the event as arguments. The cost functions should return an array containing the cost of the similarity between the tracking data and the event, scaled between 0 and 1. If no cost functions are passed, the default cost functions are used.

  • _optimize (bool, optional) – Whether or not to optimize the algorithm. If errors or warnings are raised, try if setting to False works. Defaults to False.

Currently works for the following databallpy events:

‘pass’, ‘shot’, ‘dribble’, and ‘tackle’

property tracking_timestamp_is_precise: bool

Function to check if the tracking timestamps are precise or not Timesamp is considered precise if the start of the game is not exactly at the start of the initial game time (e.g. 20:00:00), but at the actual start of the game (e.g. 20:00:03.2378).

Returns:

True if the tracking timestamps are precise, False otherwise

Return type:

bool