Skip to contents

animovement

Overview

animovement is a “meta-package” for analysing movement across space and time. Whether your data comes from pose estimation, centroid tracking, a trackball or a treadmill, the analysis follows much the same arc: read the data, check what you got, clean it, put it in a sensible frame of reference, derive the metrics you care about, and look at the result. The animovement ecosystem splits that arc into focused packages, each doing one part well — and the animovement package bundles them, so a single library(animovement) gives you the whole workflow with versions and conflicts sorted out for you.

It includes a core set of packages that are loaded on startup:

  • aniframe provides the core data structures that the rest of the ecosystem is built on — the shared representation that lets these packages hand data to one another.

  • aniread reads and writes movement data, turning the output of tracking tools and recording hardware into that common structure.

  • anicheck diagnoses data quality, so you find the gaps, outliers and low-confidence stretches before they reach your results.

  • aniprocess does signal processing and filtering — smoothing, interpolating and otherwise cleaning up trajectories.

  • anispace handles spatial transformations, such as changing the origin, rotating, or converting between coordinate systems.

  • animetric calculates movement-based metrics, from kinematics through to summary statistics.

  • anivis visualises movement data and diagnostics.

Tutorials showing these packages working together live at animovement.dev; each package’s own function reference lives on its own site, linked above. This page documents the meta-package itself — attaching the suite, tailoring it, and keeping it up to date.

We work actively with the developers of the Python movement package to reach similar data standards, workflows and use cases; if you prefer analysing your data in Python, we highly recommend using movement.

Installation

The animovement packages are published on R-universe rather than CRAN, so the repository has to be named when installing:

install.packages('animovement', repos = c('https://animovement.r-universe.dev', 'https://cloud.r-project.org'))

Installing the meta-package brings the whole ecosystem with it.

Usage

When loading the package, the versions and any conflicts are listed:

library(animovement)
#> -- Attaching packages -------------------------------- animovement 0.7.4.9000 --
#> v aniframe   0.7.0.9000     v anicheck   0.2.0     
#> v aniread    0.6.0.9000     v animetric  0.4.0     
#> v anispace   0.2.0          v anivis     0.2.0     
#> v aniprocess 0.4.0

If a function name is exported by two attached packages, the one attached later masks the other, and the startup message says so. animovement_conflicts() lists them again at any point, and works for any attached packages — not just ours. To see what is currently in your animovement, and how it is doing:

animovement_packages()  # Which packages are attached as part of animovement
animovement_conflicts() # Conflicts with other attached packages
animovement_sitrep()    # Versions, and whether anything is out of date
animovement_detach()    # Remove them from the search path again

Extending

Most analyses need more than the core set. animovement_extend() adds packages to your animovement for the session — attaching them, checking their conflicts alongside the core ones, and including them in everything that follows, such as animovement_update():

animovement_extend(ggplot2, tidyr, install = TRUE)

For a set that belongs to a project rather than a session, put a file named .animovement in the project root and list the packages you want — one per line, or separated by commas or spaces:

aniframe, aniread, aniprocess
ggplot2

When this file is present it replaces the standard core set, so list everything the project needs. That makes the project’s dependencies explicit to anyone who opens it, and keeps library(animovement) meaning the same thing for all of them.

Options can be set in the same file by prefixing them with _opt_ and placing them before the package names (for example _opt_animovement.install = TRUE), or set directly in R:

  • options(animovement.quiet = TRUE) — silence startup, conflict and install messages
  • options(animovement.styling = FALSE) — disable styling of console output
  • options(animovement.extend = c(...)) — extend before library(animovement)
  • options(animovement.install = TRUE) — install missing packages on attach

Keeping up to date

The ecosystem packages are released independently, so they drift out of step if updated one at a time. These two check and fix the whole set together:

animovement_update()  # Check for updates, and install them
animovement_install() # Install any ecosystem packages you are missing

Both look in the animovement R-universe by default, via animovement_repos(). To point the rest of your session at the same repositories:

To keep installation light, functionality that only some users need is a soft dependency rather than a hard one. Instead of meeting them one error message at a time, take them all at once:

animovement_show_suggested()    # What the ecosystem suggests
animovement_install_suggested() # Install all of it

Getting help and contributing

If your favourite type of movement data is not currently supported, we would love to get a sample of your data to support it!

  • For questions and discussion about animovement, movement data and analysis, come and chat with us on Zulip.

  • Most issues belong on the repository of an individual package — aniread for a reader that trips up, aniprocess for a filter that misbehaves. If you think you have found a bug in the meta-package itself, open an issue here.

  • Either way, a reprex (a minimal, reproducible example) is the fastest route to an answer.

  • See CONTRIBUTING.md for the pull request process.

Citation

If you enjoy the package, please make sure to cite it. To cite animovement in publications use:

citation("animovement")
#> To cite the animovement toolbox in publications use:
#> 
#>   Roald-Arbøl M (2026). "animovement: An R toolbox for analysing
#>   movement across space and time." doi:10.5281/zenodo.13235277
#>   <https://doi.org/10.5281/zenodo.13235277>.
#>   <https://animovement.dev/animovement/>.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Misc{animovement,
#>     title = {animovement: An R toolbox for analysing movement across space and time},
#>     author = {Mikkel Roald-Arbøl},
#>     year = {2026},
#>     doi = {10.5281/zenodo.13235277},
#>     version = {0.7.4.9000},
#>     url = {https://animovement.dev/animovement/},
#>   }