temporal features¶

angular_speed(trajectory, *, step, pad_value='same', keypoint_pairs, flat=False)¶

Angular speed of posture segments (orientation change / step).

Parameters:

trajectory (Trajectory) – The trajectory to calculate the angular speed for.
step (int) – The number of steps to shift the trajectory by.
pad_value (int | float | str, default: 'same') – The value to pad the output with.
keypoint_pairs (Iterable[tuple[int, int]]) – The keypoint indices to use for posture segments and orientation change calculation.
flat (bool, default: False) – Whether to flatten the output along all but the first dimension.

Return type:

ndarray

Returns:

The angular speed of posture segments.

orientation_change(trajectory, *, step, pad_value='same', keypoint_pairs, flat=False)¶

Compute signed angles between posture vectors of instance at t - step and instance at t.

Parameters:

trajectory (Trajectory) – The trajectory to compute the orientation change for.
step (int) – The number of steps to shift the trajectory by.
pad_value (int | float | str, default: 'same') – The value to pad the output with.
keypoint_pairs (Iterable[tuple[int, int]]) – The keypoint indices to use for the orientation change calculation.
flat (bool, default: False) – Whether to flatten the output along all but the first dimension.

Return type:

ndarray

Returns:

The orientation change between the two instances.

projected_velocity(trajectory, *, step, pad_value='same', keypoints_1, keypoint_pairs_2, element_wise=False, flat=False, suffixes=('proj', 'rej'))¶

Keypoint velocity projected onto posture vectors at t - step.

Parameters:

trajectory (Trajectory) – The trajectory to calculate the velocity for.
step (int) – The number of steps to shift the trajectory by.
pad_value (int | float | str, default: 'same') – The value to pad the output with.
keypoints_1 (Iterable[int]) – The keypoints to calculate the velocity for.
keypoint_pairs_2 (Iterable[tuple[int, int]]) – The keypoint pairs to specify posture vectors.
element_wise (bool, default: False) – Whether to perform the operation element-wise.
flat (bool, default: False) – Whether to flatten the output along all but the first dimension.
suffixes (tuple[str, ...], default: ('proj', 'rej')) – The suffixes to use for the output when decorated with as_dataframe().

Return type:

ndarray

Returns:

The projected velocity and (projection and rejection components).

speed(trajectory, *, step, pad_value='same', keypoints, flat=False)¶

Speed of trajectory keypoints, calculated as magnitude of velocity.

Parameters:

trajectory (Trajectory) – The trajectory to calculate the speed for.
step (int) – The step size to use for the velocity calculation.
pad_value (int | float | str, default: 'same') – The value to use for padding the output.
keypoints (Iterable[int]) – The keypoint indices to use for the velocity calculation.
flat (bool, default: False) – Whether to flatten the output along all but the first dimension.
suffixes – The suffixes to use for the output when decorated with as_dataframe().

Return type:

ndarray

Returns:

The speed of the trajectory keypoints.

target_velocity(trajectory, *, step, pad_value='same', trajectory_other=None, keypoints_1, keypoint_pairs_2, element_wise=False, origin_on_other=False, target_on_other=True, flat=False, suffixes=('proj', 'rej'))¶

Keypoint velocity projected onto target vectors between origin and target keypoints (keypoint_pairs_2).

Origin and target keypoints can be on either trajectory or trajectory_other.

Parameters:

trajectory (Trajectory) – The trajectory to calculate the target velocity for.
step (int) – The number of steps to shift the trajectory by.
pad_value (int | float | str, default: 'same') – The value to pad the trajectory with.
trajectory_other (Trajectory | None, default: None) – The other trajectory for the target keypoints, if None, falls back to trajectory.
keypoints_1 (Iterable[int]) – The indices of the origin keypoints.
keypoints_2 – The indices of the target vector keypoints.
element_wise (bool, default: False) – Whether to calculate the velocity element-wise.
origin_on_other (bool, default: False) – Whether the origin keypoints are on the other trajectory.
target_on_other (bool, default: True) – Whether the target keypoints are on the other trajectory.
flat (bool, default: False) – Whether to flatten the output along all but the first dimension.
suffixes (tuple[str, ...], default: ('proj', 'rej')) – The suffixes to use for the output when decorated with as_dataframe().
keypoint_pairs_2 (Iterable[tuple[int, int]])

Return type:

ndarray

Returns:

The target velocity for the given trajectory and keypoints.

translation(trajectory, *, step, pad_value='same', keypoints, flat=False, suffixes=('x', 'y'))¶

Retrieve 2D translation vectors of trajectory keypoints from t - step to t.

Parameters:

trajectory (Trajectory) – The trajectory to retrieve the translation vectors from.
step (int) – The number of steps to shift the trajectory.
pad_value (int | float | str, default: 'same') – The value to pad the translation vectors with.
keypoints (Iterable[int]) – The keypoint indices to retrieve the translation vectors for.
flat (bool, default: False) – Whether to flatten the output along all but the first dimension.
suffixes (tuple[str, ...], default: ('x', 'y')) – The suffixes to use for the output when decorated with as_dataframe().

Return type:

ndarray

Returns:

The translation vectors of the trajectory keypoints.

velocity(trajectory, *, step, pad_value='same', keypoints, flat=False, suffixes=('x', 'y'))¶

Calculate the 2D velocity of trajectory keypoints (translation / step).

Note that this not calculating the cumulative distance between all instances during the step, but the translation between the instance at t - step to the instance at t.

Parameters:

trajectory (Trajectory) – The trajectory to calculate the velocity for.
step (int) – The number of timesteps to use for the velocity calculation.
pad_value (int | float | str, default: 'same') – The value to use for padding the output.
keypoints (Iterable[int]) – The keypoint indices to use for the velocity calculation.
flat (bool, default: False) – Whether to flatten the output along all but the first dimension.
suffixes (tuple[str, ...], default: ('x', 'y')) – The suffixes to use for the output when decorated with as_dataframe().

Return type:

ndarray

Returns:

The velocity vectors of the trajectory keypoints.