de-bivort-lab/margo

High-throughput real-time tracker for delivery of stimuli and measurement of animal behavior.

MARGO

Description

The Massively Automated Real-time GUI for Object-tracking (MARGO) is a MATLAB based tracking platform designed with an emphasis on high-throughput tracking of large groups of animals and tracking applications requiring closed-loop hardware control. See below for examples of MARGO applications.

Sample video clip from an experiment featuring continuous high-throughput tracking of 960 fruit flies tracked at 8Hz for 6 days

Installation

Prerequisites

MATLAB

For best results, use MARGO with MATLAB 2016b or newer. MARGO has generally been designed to be backwards compatible with older versions of MATLAB. In addition to the base installation of MATLAB, MARGO requires the following toolboxes:

• image acquisition toolbox
• image processing toolbox
• computer vision system toolbox
• instrument control toolbox
• statistics and machine learning toolbox

Psychtoolbox (optional)

MARGO requires on Psychtoolbox 3 for support of external displays.

MARGO installation

1. The MARGO repository can be cloned via the github UI by downloading and extracting a zip file of the repository (Clone or Download > Download ZIP)   OR  clone via the git command line API with the following command:

git clone https://github.com/de-Bivort-Lab/margo.git

2. After cloning the repository, add the MARGO directory to MATLAB's path by navigating to the margo directory and running:

addpath(genpath(pwd));

OR

Alternatively, permanently add MARGO and all sub folders to the MATLAB path by running:

    pathtool

3. Once the margo directory is added to the MATLAB path, launch the GUI from the command line:

margo

Getting Started

We recommend that new users read the overview of MARGO's functionality and use the sample video included in this repository to follow the tracking tutorial included in the documentation for more complete instructions on getting started in MARGO.

Documentation

Complete documentation of MARGO including tutorial examples, descriptions of parameters, data outputs, and hardware configurations can be found on the MARGO wiki.

Sample Applications

Closed-loop control of stimuli

   

Closed-loop applications: (left) triggering LEDs based on position of flies in a Y-shaped mazes, (right) targeting optomotor stimuli to individual flies in circular arenas

Multi-species tracking

The Massively Automated Real-time GUI for Object-tracking (MARGO) is a MATLAB based tracking platform designed with an emphasis on high-throughput tracking of large groups of animals and tracking applications requiring closed-loop stimulus control.

   

Sample tracking of bumblebees (left) in a nestbox and larval zebrafish (right) in a multi-well culture plate

   

Tracking of fruit fly larvae (left) in a chemotactic gradient and nematodes (right) in response to an optogenetic stimulus in the wormotel high-throughput platform

Reporting issues

Although the core functionality has been thoroughly tested, MARGO is still a work in progress. Please report any errors to this repository. To help solve issues quickly, please provide a detailed description of the error, the MATLAB error message, and the MARGO error log file (if possible).

Contributors

• Zach Werkhoven primarily developed and maintains MARGO.
• Chuan Qin contributed to the development of MARGO's multitracker algorithm.
• Christian Rohrsen contributed to the development of MARGO's camera/display co-registration system.

Acknowledgements

Support for external display detection and visual stimulus crafting and display is dependent on the Psychtoolbox, developed by Mario Kleiner et al. MARGO's random dot display registration uses Andriy Myronenko's Coherent Point Drift algorithm and mex implementation. Multispecies tracking example videos provided by: James Crall (bumblebees), Jess Kanwal (fly larvae), and Matt Churgin (C. Elegans).

License

MIT License. See LICENSE for details.