ValidBboxesInputs

class movement.validators.datasets.ValidBboxesInputs(*, position_array, confidence_array=None, individual_names=None, fps=None, source_software=None, shape_array, frame_array=None)

Bases: _BaseDatasetInputs

Class for validating input data for a movement bboxes dataset.

The validator considers 2D bounding boxes only. It ensures that within the movement bboxes dataset:

• The required position_array and shape_array are numpy arrays of shape (n_frames, n_space, n_individuals) with the space dimension containing 2 spatial coordinates. The position_array contains the tracks of the bounding box centroids, while the shape_array contains the width and height of the bounding boxes.

• The optional confidence_array, if provided, is a numpy array containing confidence scores for the bounding boxes, with its shape matching that of the position_array, excluding the space dimension; otherwise, it defaults to an array of NaNs.

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

• The optional frame_array, if provided, is a column vector with the frame numbers; otherwise, it defaults to an array of 0-based integers.

• 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 bboxes dataset requirements.

Methods

to_dataset()	Convert validated bboxes inputs to a movement bboxes 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 bboxes inputs to a movement bboxes dataset.

Returns:

movement dataset containing the bounding boxes tracks, shapes, confidence scores and associated metadata.

Return type:

Dataset

DIM_NAMES: ClassVar[tuple[str, ...]] = ('time', 'space', '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', 'shape', '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.

frame_array: ndarray | None

Array containing the frame numbers for which bounding boxes are defined. The frame_array should be a column vector of shape (n_frames, 1) and should be monotonically increasing. If None (default), frame numbers will be assigned based on the first dimension of the position_array, starting from 0.

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.

position_array: ndarray

Array containing the position data.

shape_array: ndarray

Array containing the shape of the bounding boxes. The shape of a bounding box is its width (extent along the x-axis of the image) and height (extent along the y-axis of the image). The shape_array must have the same shape as the position_array.

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.