MoveR

The MoveR package aims to help users analyze the output of automated video-tracking solutions in a reproducible, reliable and open framework.

Edited version of the article published in SoftwareX (Open Access) is available here:
https://www.softxjournal.com/article/S2352-7110(24)00045-1/fulltext
Preprint is available here:
https://biorxiv.org/cgi/content/short/2023.11.08.566216v1
Documentation website is available here:
https://qpetitjean.github.io/MoveR/

Dependencies

In a sack of flexibility, MoveR is mainly coded using base .
However it still relies on a few dependencies:

graphics, grDevices and hexbin to display graphical elements.

progress to display a progress bar showing the advancement of the computations.

reticulate and R.matlab to import Python and Matlab formatted data.

stats and pracma to perform basic and advanced calculations.

trajr to load R functions to compute basic movement descriptors (e.g., speed, sinuosity).

Installation

You can install the development version from GitHub with:

# install.packages("remotes")
remotes::install_github("qpetitjean/MoveR")

Then you can attach the package MoveR:

library("MoveR")

To update with the latest version, first remove the package:

detach("package:MoveR", unload=TRUE)
remove.packages("MoveR")

and repeat the above installation commands.

Overview

MoveR is an package allowing to import, clean/filter and analyze raw particles/animal movement data obtained from video-tracking softwares.

Main workflow steps

More particularly, MoveR provides tools to:

IMPORT the raw data from various video-tracking software such as TRex, trackR, Ctrax, idtracker.ai and AnimalTA (for now) as a tracklets class object (S3).

VISUALIZE the tracklets of all or specified particles over time.

MANAGE ROIs (regions of interest) by importing the location of area edges or specifying it from scratch and assign ROIs identity to particle’s position over trajectories.

CLEAN/FILTER the data according to custom functions specified by the user. For instance, it can easily remove suspected tracking errors based on expected particles’ size or speed. It is also possible to sample particles’ tracklets (i.e., a fragment of particle’s trajectory) according to a specified time step or split tracklets’ and remove parts that are detected outside an arena or a given area.

EVALUATE the quantity of data removed over the cleaning/filtering process and check the amount of true and false detection compared to manual annotations.

ANALYSE the data over tracklets, time, or space (e.g., across areas). It is possible to compute basics or high (advanced) level descriptors over each tracklet and further investigate temporal trends and/or identify spatial patterns (e.g., sequences of area visited). In a nutshell, Basic and High-level descriptors return the results of a given computation over each tracklet, while temporal trends functions return the results of a given calculation over time by averaging the value of each tracklet. It is also possible to compute a studentized 95% confidence interval by bootstrapping over the tracklets. Also, it is possible to identify specified spatial patterns.

Breakthroughs

Besides the high flexibility and unified environment, the primary innovations provided by MoveR are the possibility to:

Characterize behavioral states (i.e., active vs. inactive states) using unsupervised learning methods (i.e., density-based clustering - see activity2 function).

Compute the expected diffusion coefficient D, a proxy of population dispersal, assuming a correlated random walk model (from Turchin’s 2015 result; see Dcoef function)

Identify and extract arbitrary patterns, in terms of changes among behavioral states, spatial regions or areas of interest, patch crosses, or any other patterns, using a very versatile regular-expression syntax.

Roadmap/future development

What	When
Publish the three missing “How to” - parallel computation, sequences identification, performance detection.	mid-2024
Providing functions to convert “tracklets” objects to other formats used in other libraries such as “sf”.	mid-2024
speed up MoveR’s computation.	Continuous implementation

Citation

Please cite this package as:

Petitjean, Q., Lartigue, S., Cointe, M., Ris, N., Calcagno, V., 2024. MoveR: An R package for easy processing and analysis of animal video-tracking data. SoftwareX 26, 101674. https://doi.org/10.1016/j.softx.2024.101674

Code of Conduct

Please note that the MoveR project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

qpetitjean / MoveR