Preparing Data for JAABA

On this page, we describe the format of the data JAABA uses. We provide a program called PrepareJAABAData for converting data output from several trackers to JAABA's format.


Experiment Directory Structure

The inputs to JAABA are the video and the animals' trajectories in the videos. JAABA terms all data associated with a given video an experiment. All data associated with a single video (the video, the trajectories file, and other data used within JAABA) must be stored in a single, separate directory, called an experiment directory. JAABA uses the directory's name to refer to this experiment. Within this directory, all the files must be named consistently. For example, the filename for the video for different experiments should always be the same (e.g., movie.avi). JAABA can open avi, seq, mov, ufmf, fmf, mmf, and sbfmf video formats. The PrepareJAABAData program can be used to convert the outputs from several existing trackers to the experiment directory structure used by JAABA. Users familiar with MATLAB programming can refer to the tracks file structure below.

The screenshots shows 2 JAABA experiments: pBDPGAL4U_TrpA_Rig1Plate15BowlB_20110922T145928 and pBDPGAL4U_TrpA_Rig2Plate14BowlD_20110615T164545. Each contains the following:

The files movie.ufmf and trx.mat are inputs to JAABA, while the directory perframe and the file labeledChases.mat are created by JAABA.

Screenshot of two JAABA experiment directories.

PrepareJAABAData GUI

With JAABA, we have included a standalone program called PrepareJAABAData which allows users to create experiment directories compatible with JAABA from the outputs of several existing tracking systems.

Screenshot of PrepareJAABAData GUI

PrepareJAABAData Usage

  1. Under Input Data Type, select the program used to track your animals.
  2. Under Input Files, choose the input files specific to this tracker. Most tracking systems require a video file and file(s) containing the trajectories. Some trackers require additional files. Details of the types of input files required for each tracking system are given below.
  3. Under Output Files, Experiment directory choose the output experiment directory location. This is the directory in which the converted data will be created. There should be one directory per video, see above.
  4. Under Output Files, set the names of the video and trx files, and the per-frame directory. When creating a new JAABA project, the names of these files should correspond.
  5. Under Conversion, set the conversion between frames and seconds and between pixels and millimeters. This is necessary because behavior definitions created using JAABA should be somewhat independent of the video's resolution. Thus, JAABA's per-frame features are all defined in real units, e.g. the speed of an animal is measured in mm/s. The "Conversion" panel also allows the user to set the type of arena the animals are contained within. Options include a circular arena, a rectangular arena, and no arena. The location of the arena wall is used when computing JAABA's landmark-based per-frame features such as the distance to the wall. The unit conversion factors and the arena parameters can be set in any of three ways:
    1. Numbers can be entered into the text boxes.
    2. After pushing the "Compute arena parameters..." button, the user can draw on a frame of video and label known arena parameters (circular arena diameter, rectangular arena width, or distance between two landmark points if arena type is set to "None").
    3. For several of the tracking systems, the conversions and/or landmark parameters can be read from the input files. Pushing "Read arena parameters..." attempts to read the arena parameters and/or spatial conversion factor from the input files. Similarly, pushing "Read FPS..." attempts to read the frame to second conversion factor from either the video or the input files.
  6. Under Options, set any optional parameters.
  7. Push the Convert button to perform the conversion and create an experiment directory that can be input into JAABA. This potentially will take some time. After conversion is done, you will be prompted with a message indicating whether the process was successful and a summary of what was done.

Input Data Type

PrepareJAABAData has currently been extended to work with the following tracking systems: Ctrax, Marta Rivera-Alba's larva tracker, and Motr are the trackers used in the original JAABA paper. Please email to discuss the possibility of extending PrepareJAABAData to work with the output of your tracking system.

Input Files

The required input files depend on the tracking system used. Almost all tracking systems require a video file and file(s) containing the trajectories. The input files for each of the input data types are listed below.

Output Files


Some or all of the following controls are found in the Conversion panel, depending on the type of tracking input. Some types of tracking systems are required to contain some or all of the Conversion parameters (e.g. the output of the Qtrax tracker is in real units), in which case these conversion parameters cannot be changed. Pushing the Compute arena parameters... button brings up a dialog allowing the user to annotate the arena location and set known lengths in millimeters.

Dialog for labeling circular arena wall after pushing "Compute Arena Parameters...".


The following conversion options can be set:

Save and Load

The configuration parameters can be saved to a MATLAB mat file by pushing the Save button. These configuration parameters can be loaded in at a later time by pushing the Load button.

Tracks File Structure

The trajectories of the animals computed by automatic tracking systems such as Ctrax are stored in the tracks file, which is a MATLAB .mat file. The tracks file contains the variable trx. trx is a MATLAB structure array where each element corresponds to an animal. The details of the structure fields are listed in the table below.

Structure FieldDescription
xx-coordinate of the animal in pixels (1 x nframes).
yy-coordinate of the animal in pixels (1 x nframes).
thetaOrientation of the animal (head) (1 x nframes).
a1/4 of the major-axis length in pixels (1 x nframes).
b1/4 of the minor-axis length in pixels (1 x nframes).
nframesNumber of frames in the trajectory of the current animal (scalar).
firstframeFirst frame of the animal's trajectory (scalar).
endframeLast frame of the animal's trajectory (scalar).
offOffset for computing index into x, y, etc. Always equal to 1 - firstframe (scalar).
idIdentity number of the trajectory (scalar).
x_mmx-coordinate of the animal in mm (1 x nframes).
y_mmy-coordinate of the animal in mm (1 x nframes).
theta_mmOrientation of the animal in real coordinates. This is often the same as theta, if no transformation other than translation and scaling is performed between pixels and real coordinates (1 x nframes).
a_mm1/4 of the major-axis length in mm (1 x nframes).
b_mm1/4 of the major-axis length in mm (1 x nframes).
sexSex of the animal. Can be just one value ('M' or 'F' or '?') or a cell array of 'M' and 'F' giving the sex for each frame. The size of the cell array should be nframes.
dtDifference in timestamps of the current frame and next frame, in seconds (1 x nframes-1).
fpsAverage frames-per-second (scalar).
timestampsTimestamp of each frame (optional), in days (1 x nframes).
area Larvae only. Area of the larva in pixels (1 x nframes).
xcontour Larvae only. x-coordinates of the contour of the larva in pixels (1 x nframes cell array).
ycontour Larvae only. y-coordinates of the contour of the larva in pixels (1 x nframes cell array).
xspine Larvae only. x-coordinates of the spine fit to the larva in pixels (nspinepts=11 x nframes).
yspine Larvae only. y-coordinates of the spine fit to the larva in pixels(nspinepts=11 x nframes).
area_mm Larvae only. Area of the larva in mm2 (1 x nframes).
xspine_mm Larvae only. x-coordinates of the spine fit to the larva in mm (nspinepts=11 x nframes).
yspine_mm Larvae only. y-coordinates of the spine fit to the larva in mm(nspinepts=11 x nframes).

Below is a screenshot of the MATLAB command window showing the trx variable.

Example trx variable

The optional variable timestamp in the trxfile gives timestamps for each frame of the movie, represented as a serial date number (described in the table above).

Per-Frame Directory Structure

The per-frame features for a given experiment directory are pre-computed and stored in the per-frame directory. Within this directory, there is a MATLAB mat file for each per-frame feature.