floodlight.core.events

class floodlight.core.events.Events(events, direction=None)[source]

Event data fragment. Core class of floodlight.

Event data is stored in a pandas DataFrame, where each row stores one event with its different properties organized in columns. Columns may contain any relevant information. An “eID” (event ID) and “gameclock” column is required for instantiation, to identify and time-locate events. Some particular column names are protected (see Notes).

Parameters
  • events (pd.DataFrame) – DataFrame containing rows of events and columns of respective event properties.

  • direction (str, optional) – Playing direction of players in data fragment, should be either ‘lr’ (left-to-right) or ‘rl’ (right-to-left).

Variables
  • essential (list) – List of essential columns available for stored events.

  • protected (list) – List of protected columns available for stored events.

  • custom (list) – List of custom (i.e. non-essential and non-protected) columns available for stored events.

  • essential_missing (list) – List of missing essential columns.

  • essential_invalid (list) – List of essential columns that violate the definitions.

  • protected_missing (list) – List of missing protected columns.

  • protected_invalid (list) – List of protected columns that violate the definitions.

Notes

Event data, particularly information available for each event, may vary across data providers. To accommodate all data flavours, any column name or data type is permissible. However, two essential column are required (“eID” and “gameclock). Other column names are protected. Using these names assumes that data stored in these columns follows conventions in terms of data types and value ranges. These are required for methods working with protected columns to assure correct calculations. Definitions for essential and protected columns can be found in floodlight.core.definitions.

add_frameclock(framerate)[source]

Add the column “frameclock”, computed as the rounded multiplication of gameclock and framerate, to the inner events DataFrame.

Parameters

framerate (int) – Temporal resolution of data in frames per second/Hertz.

column_values_in_range(col, definitions)[source]

Check if values for a single column of the inner event DataFrame are in correct range using the specifications from floodlight.core.definitions.

Parameters
  • col (str) – Column name of the inner events DataFrame to be checked

  • definitions (Dict) – Dictionary (from floodlight.core.definitions) containing specifications for the columns to be checked.

    The definitions need to contain an entry for the column to be checked and this entry needs to contain information about the value range in the form: definitions[col][value_range] = (min, max).

Returns

True if the checks for value range pass and False otherwise

Return type

bool

Notes

Non-integer results of this computation will always be rounded to the next smaller integer.

get_event_stream(fade=0, **kwargs)[source]

Generates a Code object containing the eIDs of all events at the respective frame and optionally subsequent frames as defined by the fade argument.

This function translates the object’s DataFrame of temporally irregular events to a continuous frame-wise representation. This can be especially helpful to connect event data with spatiotemporal data, e.g., for filtering the latter based on the former. Events overwrite preceding event’s fade, and unfilled values are set to np.nan.

Notes

Requires the DataFrame to contain the protected frameclock column.

Parameters
  • fade (int, optional) – Number of additional frames for which the Code object should stay at a value after the event occurred. The value is overwritten if another event occurs within the fade duration. If chosen to zero, the value is maintained only for a single frame. If chosen to None, the value is maintained until either the next event or until the end of the sequence. Defaults to 0.

  • kwargs – Keyword arguments of the Code object (“name”, “definitions”, “framerate”) that are passed down to instantiate the returned event_stream.

Returns

event_stream – Generated continuous event stream describing the designated game state.

Return type

Code

reflect(axis)[source]

Reflects data on given axis.

Parameters

axis ({‘x’, ‘y’}) – Name of reflection axis. If set to “x”, data is reflected on x-axis, if set to “y”, data is reflected on y-axis.

rotate(alpha)[source]

Rotates data on given angle ‘alpha’ around the origin.

Parameters

alpha (float) – Rotation angle in degrees. Alpha must be between -360 and 360. If positive alpha, data is rotated in counter clockwise direction. If negative, data is rotated in clockwise direction around the origin.

scale(factor, axis=None)[source]

Scales data by a given factor and optionally selected axis.

Parameters
  • factor (float) – Scaling factor.

  • axis ({None, ‘x’, ‘y’}, optional) – Name of scaling axis. If set to ‘x’ data is scaled on x-axis, if set to ‘y’ data is scaled on y-axis. If None, data is scaled in both directions (default).

select(conditions)[source]
Returns a DataFrame containing all entries from the inner events DataFrame

that satisfy all given conditions.

Parameters

conditions (Tuple or List of Tuples) – A single or a list of conditions used for filtering. Each condition should follow the form (column, value). If value is given as a variable (can also be None), it is used to filter for an exact value. If given as a tuple value = (min, max) that specifies a minimum and maximum value, it is filtered for a value range.

For example, to filter all events that have the eID of "Pass" and that happened within the first 1000 seconds of the segment, conditions should look like: conditions = [("eID", "Pass"), ("gameclock", (0, 1000))]

Returns

filtered_events – A view of the inner events DataFrame with rows fulfilling all criteria specified in conditions. The DataFrame can be empty if no row fulfills all specified criteria.

Return type

pd.DataFrame

slice(start=None, end=None, slice_by='gameclock', inplace=False)[source]

Return copy of object with events sliced in a time interval.

Intended columns for using this function are gameclock (total seconds) or frameclock. However, also allows slicing by any other column that manifests a temporal relation between events (e.g. minute). Excludes all entries without a valid entry in the specified column (e.g. None).

Parameters
  • start (float, optional) – Start frame or second of slice. Defaults to beginning of segment.

  • end (float, optional) – End frame or second of slice (endframe is excluded). Defaults to last event of segment (including).

  • slice_by ({‘gameclock’, ‘frameclock’}, optional) – Column used to slice the events. Defaults to gameclock.

  • inplace (bool, optional) – If set to False (default), a new object is returned, otherwise the operation is performed in place on the called object.

Returns

events_sliced

Return type

Union[Event, None]

translate(shift)[source]

Translates data by shift vector.

Parameters

shift (list or array-like) – Shift vector of form v = (x, y). Any iterable data type with two numeric entries is accepted.