neuroinformatics-unit/movement: v0.16.0

To update movement to the latest version, see the update guide.

What's Changed

⚡️ Highlight 1: draw, save, and load Regions of Interest in the GUI

• Widget for drawing Regions of Interest (ROIs) as napari Shapes by @niksirbi in https://github.com/neuroinformatics-unit/movement/pull/617
• Add conversion between napari Shapes and movement RoIs by @niksirbi in https://github.com/neuroinformatics-unit/movement/pull/927

You can now define Regions of Interest (RoIs) interactively in the movement napari GUI, export them to a GeoJSON file, and load them back into Python for analysis — all without writing any coordinates by hand.

https://github.com/user-attachments/assets/2231a49c-ec13-4d31-9310-d486de663185

The Define regions of interest menu lets you draw shapes directly on the video frames, name them, and save them via the Save layer button. The saved .geojson file can then be loaded with movement.roi.load_rois():

from movement.roi import load_rois

rois = load_rois("my_regions.geojson")
[roi.name for roi in rois]  # ['arena', 'nest', 'corridor']

# use in analysis — e.g. check if the animal is inside a region
is_in_nest = rois[1].contains_point(ds.position)

You can also load a .geojson file back into napari via the Load layer button to review or edit your regions.

See the Define regions of interest section of the GUI guide and the updated boundary_angles example for a full walkthrough.

⚡️ Highlight 2: automatic detection of source software in load_dataset

• Add source_software auto-detection for dataset loading by @M0hammed-Reda in https://github.com/neuroinformatics-unit/movement/pull/920

Thanks to a first contribution from @M0hammed-Reda, load_dataset() can now infer source_software automatically from the file format. When you know which software produced your file, we still recommend passing it explicitly, but automatic inference can be a convenient fallback.

from movement.io import load_dataset

# recommended: explicit is clearer and faster
ds = load_dataset("path/to/file.h5", source_software="DeepLabCut", fps=30)

# convenient fallback: automatic inference from file format
ds = load_dataset("path/to/file.h5", fps=30)

You can also call infer_source_software() directly to check what movement would infer for a given file.

🚀 Performance improvements

• Speed up and improve memory use when loading VIA tracks file by @sfmig in https://github.com/neuroinformatics-unit/movement/pull/769

@sfmig has substantially sped up loading of VIA-tracks bounding box files. Loading a 34 MB file now takes ~0.5 s (down from ~30 s), and a 100 MB file takes ~1.7 s (down from ~1-2 min). Memory use at peak is now comparable to the final in-memory size of the dataset.

⚠️ Breaking changes

• Make transforms.scale require an explicit factor by @Tushar7012 in https://github.com/neuroinformatics-unit/movement/pull/839

transforms.scale() no longer has a default value for the factor parameter. Previously, omitting factor silently multiplied the data by 1.0 (equivalent to no scaling). If you were omitting factor, add it explicitly:

# Before (silently did nothing)
ds_scaled = scale(ds)

# After
ds_scaled = scale(ds, factor=0.01)  # e.g. convert pixels to centimetres

🛠️ Refactoring

• Convert CLI from argparse to typer by @roaldarbol in https://github.com/neuroinformatics-unit/movement/pull/962

@roaldarbol has been a long-time collaborator and a constant source of ideas for movement — and this is his first, but not last, PR! He migrated the CLI from argparse to Typer, giving the movement command automatic shell completion support and a cleaner foundation for future CLI additions.

📚 Documentation

• Update and add missing docstrings by @lochhh in https://github.com/neuroinformatics-unit/movement/pull/885
• Added link to TheBehaviourForum virtual workshop talk by @niksirbi in https://github.com/neuroinformatics-unit/movement/pull/951
• Add acknowledgements to examples by @niksirbi in https://github.com/neuroinformatics-unit/movement/pull/952
• Replace fixed contributor table with responsive grid by @lochhh in https://github.com/neuroinformatics-unit/movement/pull/954
• Update pandas URL in intersphinx config by @lochhh in https://github.com/neuroinformatics-unit/movement/pull/895

🧹 Housekeeping and dependencies

• Updated supported Python versions to 3.12 - 3.14 by @niksirbi in https://github.com/neuroinformatics-unit/movement/pull/810
• [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci[bot] in https://github.com/neuroinformatics-unit/movement/pull/950

New Contributors

• @M0hammed-Reda made their first contribution in https://github.com/neuroinformatics-unit/movement/pull/920
• @roaldarbol made their first contribution in https://github.com/neuroinformatics-unit/movement/pull/962

Full Changelog: https://github.com/neuroinformatics-unit/movement/compare/v0.15.0...v0.16.0