movement Python Toolbox

The GUI can only open netCDF files that satisfy specific movement dataset requirements.

Requirements:

• The ds_type attribute must be set to either poses or bboxes.
• The data variables, dimensions, and coordinates must match the structure required for that ds_type. For example, a poses dataset must include both position and confidence variables.

To ensure compatibility when processing data, it is recommended to create a copy of your original dataset before applying filters and then saving it using .to_netcdf().

from movement.io import load_dataset
from movement.filtering import rolling_filter

# Load existing data
ds_orig = load_dataset(
    "path/to/my_data.h5", source_software="DeepLabCut", fps=30
)

# Create a copy to avoid modifying the original dataset
ds_new = ds_orig.copy()

# Apply processing (e.g., rolling median filter)
# Ensure the variable name (e.g., 'position') is preserved
ds_new["position"] = rolling_filter(
    ds_orig["position"], window=5, statistic="median"
)

# Save as a GUI-compatible netCDF file
ds_new.to_netcdf("my_data_processed.nc")

Because a movement dataset is an xarray.Dataset, you can use the full xarray API for data manipulation.

Key capabilities include:

• Accessing data: Use dot notation to access data variables and attributes (e.g., ds.position, ds.fps).
• Indexing and Selection: Use .sel() to select data by coordinate labels (e.g., ds.sel(individual=['ind1'])) or .isel() to select by integer index (e.g., ds.isel(time=slice(0, 50))).
• Aggregation: Use dimension names for broadcasting and aggregation.
• Plotting: Use built-in xarray plotting methods.
• I/O: Save/load datasets using netCDF (recommended format) or export to Pandas DataFrames and NumPy arrays.

Note: Selecting from a data variable (e.g., ds.position.sel(...)) returns an xarray.DataArray, whereas selecting from the dataset returns an xarray.Dataset.

# Select by time slice
ds_sel = ds.sel(time=slice(0, 100))

# Select specific individuals or keypoints
ds_sel = ds.sel(individual=["individual1", "individual2"])
ds_sel = ds.sel(keypoint="snout")

# Combine selections
ds_sel = ds.sel(
    time=slice(0, 100),
    individual=["individual1", "individual2"],
    keypoint="snout",
)

# Selecting from a specific variable returns a DataArray
position = ds.position.sel(
    individual="individual1", keypoint="snout"
)

The movement.napari.regions_widget uses the Qt Model/View pattern to separate data from display. This involves three components:

1. RegionsTableModel (subclass of QAbstractTableModel): Wraps a napari shapes layer. It exposes region names (layer.properties["name"]) and shape types to Qt, listening to napari layer events and emitting Qt signals.
2. RegionsTableView (subclass of QTableView): Renders the model data and handles user interactions like row selection and inline editing. It keeps table selection in sync with napari shape selection.
3. RegionsWidget: The orchestrator that connects the model and view, manages layer selection, and handles layer lifecycle events.

Data Flow: napari shapes layer <-> RegionsTableModel <-> RegionsTableView <-> User

Note on Bidirectional Sync: To prevent circular updates (e.g., selecting a shape selects a row, which re-triggers shape selection), use guard flags like _syncing_row_selection and _syncing_layer_selection to ignore events while a sync is in progress.

movement is a Python-based suite of tools designed to facilitate the study of animal behaviour by analysing body movements across space and time.

Core Functionality

The library focuses on handling the position and/or orientation of one or more individuals over time. It is designed to operate downstream of animal tracking frameworks (like DeepLabCut or SLEAP) and provides functionalities for:

• Data cleaning
• Visualisation
• Motion quantification
• Feature generation (useful for action recognition tasks)

Supported Data Representations

movement provides a consistent interface for representing various types of motion tracks in both 2D (x, y) and 3D (x, y, z) formats:

• Pose tracks: Trajectories of a set of keypoints (e.g., body parts, limbs, or appendages).
• Bounding box tracks: Trajectories of bounding box centroids.
• Motion tracks: A general term for trajectories representing an individual's movement.

It can handle data for single or multiple individuals.

When developing the napari plugin, decide where to place callbacks based on their intended lifetime and purpose:

1. In movement.napari.layer_wiring: Use this if the callback mutates layer or viewer state (e.g., layer data, properties, symbols, editable, or frame slider range). These callbacks must outlive the widget because the state they modify is part of the user's work.

   • Viewer lifetime: Use connect_viewer_callbacks(viewer) to react to viewer-level events (e.g., layer insertion/removal).
   • Layer lifetime: Connect directly to layer events (e.g., points_layer.events.data.connect(...)) so the callback lives and dies with the layer.

2. As a widget method: Use this if the callback only refreshes the widget's own UI (e.g., updating a dropdown, table, or button). Once the widget is closed, there is no need for the callback to persist.

# Example of layer lifetime connection in loader_widgets
points_layer.events.data.connect(on_points_data_changed)