-
Notifications
You must be signed in to change notification settings - Fork 0
Getting started
libratools is a python package to process animal movement trajectories in the form of a series of locations (as x, y coordinates) with times. It is designed primarily for quantitative biology research projects that involve processing high-throughput tracking data collected in a laboratory setting.
libratools does not provide functionality to label trajectories; it operates on existing trajectories which are sequences of (x, y, time) coordinates. It can be used with any x, y, times data but is specifically built for a production ready data pipeline built using the loopbio motif video recording system and the BioTracker computer vision framework for visual animal tracking. It does, however, provide some functionality to generate random trajectories for simulation or testing of analyses.
You can either download the repository as a zipped folder (see here for instructions) or clone it using the command line (advised). You have two options to clone a repo using the command line.
- You can clone the repository using HTTPS (advised), by clicking 📋 under "Clone with HTTPS".
- Or you can use an SSH key, including a certificate issued by your organization's SSH certificate authority, by clicking use SSH, then click 📋.
After choosing a cloning methods, you need to open your terminal and change the current working directory to the location where you want the cloned directory, then run:
$ git clone git@github.com:username/developing-exploration-behavior.git
where username will be your GitHub username.
To get started with using libratools and DevExDashboard, simply follow the usage instructions contained in each application's respective README.md file.
DevExDashboard is a web-based dashboard based on Streamlit and libratools to monitor daily tracking activity of animal movement trajectories. While aimed at data recorded with a motif video recording system and tracked with BioTracker, it works with any x, y, time data. Currently it only supports data stored in CSV files. More information is provided in the application's README.md.
See here for a video demo of how to load the dashboard, and here for how to use the dashboard.
What does data processing mean in the context of libratools and DevEx dashboard?
Data processing is taken to be composed of two main stages: pre-processing and post-processing. Data pre-processing here denotes the typical process by which tracking data, CSV files, are transformed into the cleaned (x, y, t) format (e.g., missing data, outliers, or errors are detected and removed) via validation and aggregation. Whilst post-processing refers to summarization, the computation of summary statistics, which are useful for posterior analyses.
Do I need to install the entire repository to use libratools and DevEx dashboard?
No, you can also install both applications separately by following the installation guide contained in their respective README.md files. Note that libratools is a required package for DevEx dashboard and hence will need to be installed. In general, if you wish to make use of DevEx dashboard, it is strongly recommended that you install the entire developing-exploration-behavior repository, as detailed in the repo-install-instructions.
What does a production ready data pipeline built using motif and BioTracker look like?
libratools and DevEx dashboard are specifically built for the DevEx research project, which involves monitoring fish in several experimental tanks for up to 12 hours a day using a single camera per tank. That means a large amount of video data coming in (approximately 40GB or 2.600.000 frames per day). To automate the recording, storage, and tracking of videos, the project relied on a data pipeline built using the loopbio motif video recording system and the BioTracker computer vision framework for visual animal tracking. Motif is offered as a complete system (software, camera, and computer together) and can be configured for single camera or multiple camera recording. BioTracker can be used to track each video chunk, individual MP4 files corresponding to single recordings generated by our motif. Tracking involves applying computer vision algorithms to label the recorded animal's motion history for the respective video chunk. After tracking, BioTracker outputs a trajectory (individual CSV file). A production ready data pipeline using motif and BioTracker therefore involves automating the process of generating MP4 recordings using motif and tracking each video recording using BioTracker so that one is left with individual trajectories that can be directly processed using libratools and visualized using DevEx dashboard.