motion-tracking

Repository for code for tracking the motion of mice during behavioral tests.

---

Installation

1. Download and install Miniconda with Python 3.6 (Skip if you already have Miniconda installed.)
2. Open Anaconda Prompt and type: conda env create -f motion-tracking\py36.yml -n py36 where the last argument is relative path to the environment configuration file with respect to your current working directory. This will install a new Python environment with necessary setup.
3. In Anaconda Prompt type activate py36 to activate your newly installed environment (source activate py36 on Mac/Linux)

Note:
The code can be downloaded also from pypi or using pip.

pip install --index-url https://test.pypi.org/simple/ motrack

You still will need to manually download requirments from anaconda environment file.

Usage

Overall pipeline

activate py36
cd /path/to/motion-tracking
python process.py
python analyze.py

Detailed pipeline

1. Convert videos to .avi file format with 800x600 resolution using for example Free MP4 Video Converter or ffmpeg. In the former this corresponds to:
2. Put videos to be analyzed into motion-tracking\vids folder, add also start_stop.csv file. You may need to check code in process.py file to make sure that your file looks as expected (sep = ";", skip_rows = 2, .MP4 extension after filename).
3. Open Anaconda Command Prompt, locate to motion_tracking directory and type python process.py

• First video that is processed will prompt you to pick ROI and range of pixel values in hsv_space
  • You should select a ROI bigger than the animal
  • For HSV range you may try (H: 0-179, S: 0-50, V: 160-255)
• All other videos in the vids folder are processed using the information you provided in start_stop.csv and during the initial user interaction
  • You can inspect the tracking visually or you can turn off the plotting by adjusting show_frames and show_mask parameters in files params_init (applies to 1st video), or params.py (applies to all other videos)

Results

Results of the tracking are stored in res folder. You will find the total time and distance together with eventual warnings at the bottom each .txt file. To collect aggregate information for all the files corresponding to all your videos in vids folder, you type python analyze.py in the command prompt. The result will be a single file in your motion-tracking directory with the aforementioned results pulled out.

Warnings

The algorithm flags files for manual revision if an issue with tracking occurs. You can check if there are any warnings in the results file after running python analyze.py. Reruning the analysis only on the problematic videos with adjusted HSV range (e.g. increasing upper threshold for saturation S) is likely to solve the problem.

Intermediate parameters

Several parameters get saved during the processing of each video. You will find them in inits folder. They should enable you to reproduce the whole analysis without the initial user interaction (i.e. the results should be the same for all such runs). To do that call python process.py --reproduce 1

Tests

You may test that the code runs as expected by invoking python -m pytest.

Reporting issues

If you spot a bug or something is not working as you would expect, you can go to issues page and create an issue where you descibe what is the problem and what lead to its occurence.