ValidPosesInputs

class movement.validators.datasets.ValidPosesInputs(*, position_array, confidence_array=None, individual_names=None, fps=None, source_software=None, keypoint_names=None)

Bases: _BaseDatasetInputs

Class for validating input data for a movement poses dataset.

The validator ensures that within the movement poses dataset:

• The required position_array is a numpy array of shape (n_frames, n_space, n_keypoints, n_individuals) with the space dimension containing 2 or 3 spatial coordinates.

• The optional confidence_array, if provided, is a numpy array containing confidence scores for the pose data. It supports either point-wise confidence with shape matching that of position_array, excluding the space dimension, or individual-wise confidence with shape (n_frames, n_individuals); otherwise, it defaults to an array of NaNs.

• The optional individual_names and keypoint_names, if provided, is a list of unique names for the individuals and keypoints, with lengths matching the number of individuals and keypoints in the dataset, respectively; otherwise, default names are assigned.

• The optional fps is a positive float; otherwise, it defaults to None.

• The optional source_software is a string; otherwise, it defaults to None.

Raises:

ValueError – If the dataset does not meet the movement poses dataset requirements.

Methods

to_dataset()	Convert validated poses inputs to a movement poses dataset.
validate(ds)	Validate that the dataset has the required variables and dimensions.

classmethod validate(ds)

Validate that the dataset has the required variables and dimensions.

Parameters:

ds (Dataset) – Dataset to validate.

Raises:

• TypeError – If the input is not an xarray Dataset.

• ValueError – If the dataset is missing required data variables or dimensions for a valid movement dataset.

Return type:

None

to_dataset()

Convert validated poses inputs to a movement poses dataset.

Returns:

movement dataset containing the pose tracks, confidence scores, and associated metadata.

Return type:

Dataset

DIM_NAMES: ClassVar[tuple[str, ...]] = ('time', 'space', 'keypoints', 'individuals')

Required dimension names for the dataset. The order of dimension names must match the order of dimensions in the position_array.

VAR_NAMES: ClassVar[tuple[str, ...]] = ('position', 'confidence')

Required variable names for the dataset.

confidence_array: ndarray | None

Array containing point-wise confidence scores for the position data. The shape of this array is the same as that of position_array, but without the space dimension. If None (default), the confidence scores will be set to an array of NaNs.

fps: float | None

Frames per second of the video. If None (default), time coordinates will be expressed in frames. If a non-positive value is provided, fps will be set to None and a warning will be issued.

individual_names: list[str] | None

List of unique names for the individuals in the video. The length of this list should match the size of the ‘individuals’ dimension in the position_array. If None (default), the names will be in the format of id_<N>, where <N> is an integer from 0 to the size of the ‘individuals’ dimension minus 1.

keypoint_names: list[str] | None

List of unique names for the keypoints in the skeleton. If None (default), the keypoints will be named “keypoint_0”, “keypoint_1”, etc.

position_array: ndarray

Array containing the position data.

source_software: str | None

Name of the software from which the data were loaded. This is stored as a dataset attribute in the resulting xarray.Dataset. Defaults to None.