pymovements.transforms

Transforms module.

Functions

cut_into_subsequences	Example: if old seq len was 7700, window_size=1000: Input arr has: 144 x 7700 x n_channels Output arr has: 144*8 x 1000 x n_channels The last piece of each trial 7000-7700 gets padded with first 300 of this piece to be 1000 long
downsample	Downsamples array by integer factor.
pix2deg	Converts pixel screen coordinates to degrees of visual angle.
pos2vel	Compute velocity time series from 2-dimensional position time series.
vnorm	Takes the velocity norm sqrt(x^2 + y^2).

pymovements.transforms.cut_into_subsequences(arr: ndarray, window_size: int, keep_padded: bool = True)

Example: if old seq len was 7700, window_size=1000: Input arr has: 144 x 7700 x n_channels Output arr has: 144*8 x 1000 x n_channels The last piece of each trial 7000-7700 gets padded with first 300 of this piece to be 1000 long

Parameters

• arr (np.ndarray) – uncut sequence

• window_size (int) – size of subsequences

• keep_padded (bool) – If True, last subsequence (which is padded) is kept in the output array.

Return type

np.ndarray

pymovements.transforms.downsample(arr: ndarray, factor: int)

Downsamples array by integer factor.

Parameters

• arr (np.ndarray) – sequence to be downsampled

• factor (int) – factor to be downsampled with

Return type

np.ndarray

pymovements.transforms.pix2deg(arr: float | list[float] | list[list[float]] | np.ndarray, screen_px: float | list[float] | tuple[float, float] | np.ndarray, screen_cm: float | list[float] | tuple[float, float] | np.ndarray, distance_cm: float, center_origin: bool = True) → np.ndarray

Converts pixel screen coordinates to degrees of visual angle.

Parameters

• arr (float, array_like) – Pixel coordinates to transform into degrees of visual angle

• screen_px (int, int) – Screen dimension in pixels

• screen_cm (float, float) – Screen dimension in centimeters

• distance_cm (float) – Eye-to-screen distance in centimeters

• center_origin (bool) – Center origin to (0,0) if arr origin is in bottom left corner

Returns

degrees_of_visual_angle – Coordinates in degrees of visual angle

Return type

np.ndarray

Raises

ValueError – If dimension screen_px or screen_cm don’t match dimension of arr. If screen_px or screen_cm or one of its elements is zero. If distance_cm is zero.

pymovements.transforms.pos2vel(arr: list[float] | list[list[float]] | np.ndarray, sampling_rate: float = 1000, method: str = 'smooth', **kwargs) → 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 (array_like) – Continuous 2D position time series

• sampling_rate (int) – Sampling rate of input time series

• 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

• kwargs (dict) – Additional keyword arguments used for savitzky golay method.

Returns

velocities – Velocity time series in input_unit / sec

Return type

array_like

Raises

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

pymovements.transforms.vnorm(arr: np.ndarray, axis: int | None = None) → np.ndarray

Takes the velocity norm sqrt(x^2 + y^2).

Parameters

• arr (np.ndarray) – velocity sequence

• axis (int, optional) – axis to take norm. If None it is inferred from arr.shape.

Return type

np.ndarray