Enhanced Mouse Tracker - EMT

Description

Enhanced Mouse Tracker is an evolution of the Live Mouse Tracker Analysis. It is a new toolbox with an improved pipeline to reconstruct LMT events with faster, more precise and more robust algorithms.

Improvements

• Traveled distance: with the use of the coherence speed filtering algorithm.
• Inclusion of drinker/feeders contact detection algorithm.
• Huddling: with a much faster and precise algorithm.
• WallJump, SAP: with a new rule-based algorithm based on animals masks.
• Eliminating inconsistencies on events sequence through redefinition of some criteria.
• All the events number and length using the events filtering pipeline.
• An algorithm to re-draw colors markers on animals in output videos for visualisation.
• Inclusion of automatic extraction of video bouts (gif) for visualization of events.

How to use

To make it easy to use, please install EMT as a local python package. This way you can use LMT/EMT functionalities on other codes on other directories as easily as any other python package. To do so type this command when you are in your working python evironment at this directory (./LMT):

pip install -e .

You can use either the jupyter notebooks, to run each processing separately, or you can use the python script to run the full pipeline in a once. Notebooks are in ./EMT/EMT_notebooks/. Scripts are in ./EMT/EMT_scripts/. In order to use the jupyter notebooks you just have to follow the given instructions. All the parameters you may modify to adapt the functionality to your need are in one of the first cells of the notebook, check it. To use the python scripts, you can run the run_EMT_pipeline.py which will run all the functions in a once. It will rebuild all LMT events with the new algorithms and paramenters, it will also plot the cage conditions registered throughout the experiment and it will compute the traveled distance in 1h intervals, the timeleine of the stops (> 1s) of each animal and the post-processing of the events, outputing filtered events in either csv files, time graphics and/or sqlite databases. Although this processing is long (for a 3-day database it will take a whole day to fully process), it is relatively lightweight and ou may process many databases in parallel, if your machine is powerful enough (An Intel i9 with 64 GB RAM can handle up to 8 databases simultaneously without much effort.)

Using script to detect drinking and eating

If you have feeders/drinkers in the cage, ou can detect the contact of the animals with these structures by setting up the coordinates of the contours of the structure in a file named feeders.txt (a model can be found at ./EMT/images/) to be put on the same directory of the database (sqlite file). The original script expects to find the coordinates of 1 drinker and 4 feeders, but you can adapt it easily four your needs by manipulating the script. Each object can have an arbitrary number of coordinates to set up the contour.

Event filtering

One of the improvements brought by EMT is the event filtering. Many events are noisily detected. A single event is broken in many because of the noise in detection, segmentation or orientation of the individuals. In order to overcome this failures, we propose a chain of filters for events. The parameters for filtering each actions can be found (and modified) at ./EMT/lmtanalysis/actions_pproc_params.yaml.

Processing sequences of events

Using the filtered databases (output of the post_processing_events script/notebook with save_sqlite option enabled), you can process the sequences of events. First you must run the extract_actions.py to extract one action per frame for each animal. You can modify the priority of the frame in the dictionary of this file. Then, using the processing_events.py script, for each animal, you can save the semantic vectors for each action, plot these vectors in a 'semantic space' to visualize, save the transition probabilities between two successive actions as well as find most probable sequences, and even generate new sequences.

lmt-analysis

Live Mouse Tracker analysis

What can you do with this package ?

lmt-analysis provides all the analysis tools needed to extract information from the tracking performed by live mouse tracker.

This view shows the basic output of live mouse tracker, and this package let you get the juice of it :)

With this package, you can

• draw trajectories of the animals
• filter trajectories
• access the detection at each frame and the masks of the animals
• access your lmt .sqlite database files and query them to get the graph or output you need
• compute the following events (and create your own)

Tutorial

A full tutorial is available in this google doc