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
- 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)
. Ifvalue
is given as a variable (can also be None), it is used to filter for an exact value. If given as a tuplevalue = (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) orframeclock
. 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]