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, with the space dimension containing 2 spatial coordinates.

• The optional confidence_array, if provided, is a numpy array 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, match 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.

position_array

Array of shape (n_frames, n_space, n_individuals) containing the tracks of the bounding box centroids.

Type:

np.ndarray

shape_array

Array of shape (n_frames, n_space, n_individuals) 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).

Type:

np.ndarray

confidence_array

Array of shape (n_frames, n_individuals) containing the confidence scores of the bounding boxes. If None (default), the confidence scores are set to an array of NaNs.

Type:

np.ndarray, optional

individual_names

List of individual names for the tracked bounding boxes in the video. If None (default), bounding boxes are assigned names based on the size of the position_array. The names will be in the format of id_<N>, where <N> is an integer from 0 to position_array.shape[1]-1.

Type:

list of str, optional

frame_array

Array of shape (n_frames, 1) containing the frame numbers for which bounding boxes are defined. If None (default), frame numbers will be assigned based on the first dimension of the position_array, starting from 0.

Type:

np.ndarray, optional

fps

Frames per second defining the sampling rate of the data. Defaults to None.

Type:

float, optional

source_software

Name of the software that generated the data. Defaults to None.

Type:

str, optional

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.

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:

xarray.Dataset

classmethod validate(ds)

Validate that the dataset has the required variables and dimensions.

Parameters:

ds (xarray.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