floodlight.models.kinetics

class floodlight.models.kinetics.MetabolicPowerModel[source]

Class for calculating Metabolic Power and derived metrics from spatiotemporal data.

Upon calling the fit()-method, this model calculates the frame-wise Metabolic Power for each player. The following calculations can subsequently be queried by calling the corresponding methods:

Frame-wise Metabolic Power –> metabolic_power()

Cumulative Metabolic Power –> cumulative_metabolic_power()

Frame-wise Equivalent Distance –> equivalent_distance()

Cumulative Equivalent Distance –> cumulative_equivalent_distance()

Notes

Metabolic Power is defined as the energy expenditure over time necessary to move at a certain speed, and is calculated as the product of energy cost of transport per unit body mass and distance [\(\frac{J}{kg \cdot m}\)] and velocity [\(\frac{m}{s}\)]. Metabolic Power and Energy cost of walking is calculated according to di Prampero & Osgnach 1. Energy cost of running is calculated with the updated formula of Minetti & Parvei 2.

Examples

>>> import numpy as np
>>> from floodlight import XY
>>> from floodlight.models.kinetics import MetabolicPowerModel

>>> xy = XY(np.array(((0, 0), (0, 1), (1, 1), (2, 2))), framerate=20)

>>> metabolic_power_model = MetabolicPowerModel()
>>> metabolic_power_model.fit(xy)

>>> metabolic_power_model.metabolic_power()
PlayerProperty(property=array([[1164.59773017],
       [ 185.59792131],
       [9448.10007077],
       [8593.05199423]]), name='metabolic_power', framerate=20)
>>> metabolic_power_model.cumulative_equivalent_distance()
PlayerProperty(property=array([[ 323.49936949],
   [ 375.05434763],
   [2999.52658952],
   [5386.4854768 ]]), name='cumulative_equivalent_distance', framerate=20)

References

1: di Prampero P.E., Osgnach C. (2018). Metabolic power in team sports - Part 1: An update. International Journal of Sports Medicine, 39(08), 581-587.
2: Minetti, A.E., Parvei, G. (2018). Update and extension of the ‘Equivalent Slope’ of speed changing level locomotion in humans: A computational model for shuttle running. Journal Experimental Biology, 221:jeb.182303.

cumulative_equivalent_distance(eccr=3.6)[source]

Returns cumulative equivalent distance defined as the distance a player could have run if moving at a constant speed and calculated as the fraction of metabolic work and the cost of constant running.

Parameters: eccr (Numeric) – Energy cost of constant running. Default is set to 3.6 \(\frac{J}{kg \cdot m}\) according to di Prampero (2018). Can differ for different turfs.
Returns: cumulative_equivalent_distance – A Player Property object of shape (T, N), where T is the total number of frames and N is the number of players. The columns contain the cumulative equivalent distance calculated by numpy.nancumsum() over axis=0.
Return type: PlayerProperty

cumulative_metabolic_power()[source]

Returns the cumulative metabolic power.

Returns: metabolic_power – A Player Property object of shape (T, N), where T is the total number of frames and N is the number of players. The columns contain the cumulative metabolic power calculated by numpy.nancumsum() over axis=0.
Return type: PlayerProperty

equivalent_distance(eccr=3.6)[source]

Returns frame-wise equivalent distance, defined as the distance a player could have run if moving at a constant speed and calculated as the fraction of metabolic work and the cost of constant running.

Parameters: eccr (Numeric) – Energy cost of constant running. Default is set to 3.6 \(\frac{J}{kg \cdot m}\) according to di Prampero (2018). Can differ for different turfs.
Returns: equivalent_distance – A Player Property object of shape (T, N), where T is the total number of frames and N is the number of players. The columns contain the frame-wise equivalent distance.
Return type: PlayerProperty

fit(xy, difference='central', axis=None, eccr=3.6)[source]

Fit the model to the given data and calculate metabolic power for every player.

Notes

To give appropriate results, unit of coordinates must be in meter.

Parameters

xy (XY) – Floodlight XY Data object.
difference ({‘central’, ‘forward}, optional) – The method of differentiation to calculate velocity and acceleration. See VelocityModel() for further details.
axis ({None, ‘x’, ‘y’}, optional) – Optional argument that restricts distance calculation to either the x- or y-dimension of the data. If set to None (default), distances are calculated in both dimensions.
eccr (Numeric) – Energy cost of constant running. Default is set to 3.6 \(\frac{J}{kg \cdot m}\) according to di Prampero (2018). Can differ for different turfs.

metabolic_power()[source]

Returns the frame-wise metabolic power as computed by the fit()-method.

Returns: metabolic_power – A Player Property object of shape (T, N), where T is the total number of frames and N is the number of players. The columns contain the frame-wise metabolic power.
Return type: PlayerProperty