MovementDataset

class movement.move_accessor.MovementDataset(ds)

Bases: object

An xarray.Dataset accessor for movement data.

A movement dataset is an xarray.Dataset with a specific structure to represent pose tracks or bounding boxes data, associated confidence scores and relevant metadata.

Methods/properties that extend the standard xarray functionality are defined in this class. To avoid conflicts with xarray’s namespace, movement-specific methods are accessed using the move keyword, for example ds.move.validate() (see [1] for more details).

dim_names

A dictionary with the names of the expected dimensions in the dataset, for each dataset type ("poses" or "bboxes").

Type:

dict

var_names

A dictionary with the expected data variables in the dataset, for each dataset type ("poses" or "bboxes").

Type:

dict

References

[1]

https://docs.xarray.dev/en/stable/internals/extending-xarray.html

Methods

filtering_wrapper(fn_name, *args[, data_vars])	Provide convenience method for filtering data variables.
kinematics_wrapper(fn_name, *args, **kwargs)	Provide convenience method for computing kinematic properties.
validate()	Validate the dataset.

filtering_wrapper(fn_name, *args, data_vars=None, **kwargs)

Provide convenience method for filtering data variables.

This method forwards filtering and/or smoothing to the respective functions in movement.filtering. The data variables to filter can be specified in data_vars. If data_vars is not specified, the position data variable is selected by default.

Parameters:

• fn_name (str) – The name of the filtering function to call.

• args (tuple) – Positional arguments to pass to the function.

• data_vars (list[str] | None) – The data variables to apply filtering. If None, the position data variable will be passed by default.

• kwargs (dict) – Keyword arguments to pass to the function.

Returns:

The filtered data variable or a dictionary of filtered data variables, if multiple data variables are specified.

Return type:

xarray.DataArray | dict[str, xarray.DataArray]

Raises:

RuntimeError – If the requested function fails to execute.

Examples

Filter the position data variable to drop points with confidence below 0.7 and store the result back into the Dataset ds. Since data_vars is not supplied, the filter will be applied to the position data variable by default.

>>> ds["position"] = ds.move.filter_by_confidence(threshold=0.7)

Apply a median filter to the position data variable and store this back into the Dataset ds.

>>> ds["position"] = ds.move.median_filter(window=3)

Apply a Savitzky-Golay filter to both the position and velocity data variables and store these back into the Dataset ds. filtered_data is a dictionary, where the keys are the data variable names and the values are the filtered DataArrays.

>>> filtered_data = ds.move.savgol_filter(
...     window=3, data_vars=["position", "velocity"]
... )
>>> ds.update(filtered_data)

kinematics_wrapper(fn_name, *args, **kwargs)

Provide convenience method for computing kinematic properties.

This method forwards kinematic property computation to the respective functions in movement.analysis.kinematics.

Parameters:

• fn_name (str) – The name of the kinematics function to call.

• args (tuple) – Positional arguments to pass to the function.

• kwargs (dict) – Keyword arguments to pass to the function.

Returns:

The computed kinematics attribute value.

Return type:

xarray.DataArray

Raises:

RuntimeError – If the requested function fails to execute.

Examples

Compute displacement based on the position data variable in the Dataset ds and store the result in ds.

>>> ds["displacement"] = ds.move.compute_displacement()

Compute velocity based on the position data variable in the Dataset ds and store the result in ds.

>>> ds["velocity"] = ds.move.compute_velocity()

Compute acceleration based on the position data variable in the Dataset ds and store the result in ds.

>>> ds["acceleration"] = ds.move.compute_acceleration()

validate()

Validate the dataset.

This method checks if the dataset contains the expected dimensions, data variables, and metadata attributes. It also ensures that the dataset contains valid poses or bounding boxes data.

Raises:

ValueError – If the dataset is missing required dimensions, data variables, or contains invalid poses or bounding boxes data.

Return type:

None