pymovements.gaze.transforms_numpy.pos2vel

pymovements.gaze.transforms_numpy.pos2vel(arr: list[float] | list[list[float]] | np.ndarray, sampling_rate: float = 1000, method: str = 'smooth', **kwargs: int | float | str) → np.ndarray

Compute velocity time series from 2-dimensional position time series.

Methods ‘smooth’, ‘neighbors’ and ‘preceding’ are adapted from

Engbert et al.: Microsaccade Toolbox 0.9.

Parameters:

• arr (list[float] | list[list[float]] | np.ndarray) – Continuous 2D position time series

• sampling_rate (float) – Sampling rate of input time series. (default: 1000)

• method (str) – Following methods are available: * smooth: velocity is calculated from the difference of the mean values of the subsequent two samples and the preceding two samples * neighbors: velocity is calculated from difference of the subsequent sample and the preceding sample * preceding: velocity is calculated from the difference of the current sample to the preceding sample (default: ‘smooth’)

• **kwargs (int | float | str) – Additional keyword arguments used for savitzky golay method.

Returns:

Velocity time series in input_unit / sec

Return type:

np.ndarray

Raises:

ValueError – If selected method is invalid, input array is too short for the selected method or the sampling rate is below zero

Examples

>>> arr = [(0., 0.), (1., 1.), (2., 2.), (3., 3.), (4., 4.), (5., 5.)]
>>> pos2vel(
...    arr=arr,
...    sampling_rate=1000,
...    method="smooth",
... )
array([[ 500.,  500.],
       [1000., 1000.],
       [1000., 1000.],
       [1000., 1000.],
       [1000., 1000.],
       [ 500.,  500.]])