BABAM User Guide

The Browsable Atlas of Behavior-Anatomy Maps (BABAM) is a Graphical User Interface for exploring hypotheses of correlations between neural activity in regions of the brain and behavior for Drosophila melanogaster. These correlation hypotheses are the result of our thermogenetic neural activation screen of 2,205 lines from the Janelia GAL4 collection. More information on this data can be found here.


Contents


Download

The git repository for BABAM is hosted on github.

Compiled binaries and source code releases are available here.


Start-up

BABAM is a MATLAB-based program. To run it:
  1. Start MATLAB.
  2. Within MATLAB, change into the directory containing the BABAM code:
    cd BABAM;
  3. Run StartBABAM on the command line to start BABAM:
    StartBABAM;

Specifying Data Locations

BABAM will then try to locate the Fly Bowl behavior and expression data it needs. These values are memorized in the file .BABAM_rc.mat, so once they are entered, they will not need to be entered the next time you run BABAM. You can change the locations of any of the data within the GUI under the Edit -> Data locations menu item. BABAM needs to know the location of the following:
  1. Behavior Data MAT File: MAT file containing the behavior screen results. This data can be downloaded at BehaviorData.mat.
  2. Supervoxel Clustering Data MAT File: MAT file containing the supervoxel clustering of the brain. This data can be downloaded at SupervoxelClusteringData.mat.
  3. Per-line Anatomy Image Directory: Directory containing normalized, registered images of the expression patterns for each brain. This data can be downloaded at AverageAnatomyData. This data set is large, and BABAM can run without it. In this case, supervoxel-compressed representations of the per-line expression patterns will be shown. BABAM will ask whether this data is available at start-up.

Creating a Behavior-Anatomy Map

Immediately after starting the GUI, the main axes will be blank. To create and show a behavior-anatomy map, use the Map Behavior panel in the bottom-left of the GUI.
  1. Specify a (combination of) behavior statistic(s) by:
  2. Click the purple Update button to perform a statistical test of the significance of the correlation between the specified behavior statistic and the expression level in each supervoxel across all GAL4 lines.
  3. The GUI updates the main plot to show the regions of the brain significantly correlated with the specified behavior statistic. Each supervoxel is colored by its p-value.

Specifying behavior statistics

Specify the behavior statistics to map using the Map Behavior panel.

In Basic mode (Advanced mode not checked), you can specify the behavior statistics using the drop-down menus. Specify the first behavior statistic (e.g. backup) and whether to look for higher-than-control (More) or lower-than-control (Less) values for that statistic with the top row of drop-down menus. Using the bottom-left drop-down, select None if you want to map a single behavior statistic. Otherwise, select a logical operator (AND, OR, or AND NOT) to use when combining behavior statistics. Use the bottom row of drop-down menus to select the second behavior.

In Advanced mode, you can specify a logical combination of any number of behavior statistics using the text edit menu. For example:

{backup_plus} AND NOT {jump_plus} AND NOT {stop_minus}
Specify behavior statistic tests in {braces}, combining a behavior statistic name (e.g. backup) and whether to test for a higher-than-control (plus) or lower-than-control (minus) value for that statistic. Behavior statistics specified in the above example: {backup_plus}, {jump_plus}, and {stop_minus}. Combine these with the logical operators AND, OR, or AND NOT.

Behavior-Index Computation

The behavior index computed for a given GAL4 line, based on the logical expression specified, is a number between 0 and 1. For example, a value of 1 for Backup More indicates that the given GAL4 line performs more back-ups than control, a value of 0 indicates that the given GAL4 line does not perform more back-ups than control, and intermediate values indicate confidence. The behavior index is a thresholded and normalized version of the measured value for the behavior statistic. To logically combine multiple behavior statistics, we interpret these behavior indices as probabilities. Under this interpretation, ANDs correpond to multiplication, ORs to addition, and NOTs to the complement (1-x). Details of the computation are provided here.

Behavior-Anatomy Correlation Hypothesis Test

For the specified behavior statistic, and for each supervoxel subregion of the brain, we compute the correlation ρ between estimates of whether the supervoxel has expression and whether the behavior statistic has a high (or low) value, across all GAL4 lines. We use a bootstrapping method to compute how unexpectedly high this measured correlation is given the null hypothesis that there is no correlation between behavior and anatomy, which we estimate by shuffling the lines. The larger the number of shuffled samples, the more precise this p-value estimate will be, but the longer it will take. The number of samples can be specified in the GUI parameters.

To create a single map, a hypothesis test for positive correlation is performed for each of the 7,065 supervoxels. We suppress (by setting the reported p-value to 1) all correlations with a Benjamini-Hochberg false discovery rate (FDR) greater than 0.25. The FDR threshold can be specified in the GUI parameters.


Exploring a Behavior-Anatomy Map

The behavior-anatomy map is shown in the main plot axes.

Viewing Mode

Initially, the maximum projection over the z-axis is shown (well, really minimum projection, as small p-values are more significant). The viewing mode can be changed under the View menu. Options:

P-value Colormap

The jet colormap is used to display the significance of the correlation hypothesis tests, with red indicating high significance (small p-value), and blue to black indicating low significance (large p-value). By default, a log scale is used when choosing a color, thus the difference in color between .01 and .001 should be the same as the difference between .001 and .0001. Parameters of the colormap can be changed using the P-value colormapping section of the dialog from the Edit->Parameters... menu item. These parameters are:

Current Supervoxel Information Panel

The panel at the bottom-center of the GUI shows information about the supervoxel or cluster of supervoxels over which the mouse pointer is currently hovering. The following information is shown:

Exploring a Supervoxel

Right-clicking on a supervoxel results in a menu with a list of ways of understanding the source of the correlation between the selected behavior and the clicked supervoxel. The menu has the following items, all of which are described in detail in the following sections:

Show important lines

By selecting the Show important lines option from the supervoxel menu, one can find and investigate GAL4 lines which both have expression in the selected supervoxel and have a high value for the selected behavior index.

More specifically, it selects lines according to the product of their behavior and anatomy indices. It selects the first n lines whose totalled behavior-anatomy-product indices account for a set fraction of the total behavior-anatomy-product indices across all lines. As reading in information about all these lines can be slow, we also limit the maximum number of lines shown to a fixed value. The number of lines selected can be controlled in the Show important lines for a cluster/supervoxel section of the dialog at the Edit->Parameters... menu item:

The lines selected will be shown in three ways:

  1. Line-information webpage: Information for these lines about the behavioral effects of activation and their neural expression patterns will be shown in a webpage generated on the fly in the user's temporary directory. More information available below.
  2. Max-projection expression-pattern images: The maximum-projection image of the expression patterns for each of the lines will be plotted in a figure.
  3. Masked max-projection expression-pattern images: We first compute the average image stack (in 3-d) over all the selected lines. This is shown in the bottom right plot. For each of the lines, we show the maximum projection of the expression pattern masked (multiplied) by this average image stack. Thus, this max-projection will focus on common regions of expression between the selected lines. The true image stacks for each line can either be read in from disk (True) or approximated from their low-dimensional supervoxel representation (Supervoxel). The user is queried for which type of data to use with the Line average type dialog. True is slower but more accurate, and requires access to the original registered and normalized image stacks, while Supervoxel is faster but less accurate.

Show lines with expression but not behavior

By selecting the Show lines with expression but not behavior option from the supervoxel menu, one can find and investigate GAL4 lines which have expression in the selected supervoxel but do not have a high value for the selected behavior index. Here, lines are ordered and selected based on the product of one minus the behavior index and the anatomy index. We limit the lines shown based on the following parameters (accessed via the Edit->Parameters... dialog:

Other than this change in the lines selected, the same visualizations of these lines as described for Show important lines will be shown.

Map expression correlation

Suppose that activity in supervoxel i is correlated with a behavioral effect, and, genetically, expression in supervoxel j is correlated with expression in supervoxel i. Then, we would observe a correlation between expression in supervoxel j and the behavioral effect. To examine whether this could be the case, we can look at the correlation in expression between the selected supervoxel and all other supervoxels. Selecting the Map expression correlation option from the supervoxel menu will result in coloring each supervoxel by the Pearson's correlation coefficient of its expression across our line collection between the selected supervoxel. Positive correlation is shown in red, negative correlation is shown in blue, and no correlation is shown as white. The selected supervoxel is outlined in black. To return to the behavior-anatomy correlation map, click the X box labeled Showing correlation in expression to SV ??? in ?? at the bottom right of the GUI.

Show lines with expression

By selecting the Show lines with expression option from the supervoxel menu, one can find and investigate GAL4 lines which have expression in the selected supervoxel regardless of their behavior. Here, lines are ordered and selected based only on their expression. Other than this change in the lines selected, the same visualizations of these lines as described for Show important lines will be shown.

Line-Information Webpage

For each of the selected lines, the webpage shows:

Clustering a Behavior-Anatomy Map

One can cluster the supervoxels that are significantly correlated with the current behavior by selecting Cluster supervoxels under the Analyze menu. The supervoxels are clustered based on their expression patterns. Instead of looking at expression across all GAL4 lines, we cluster based on expression across a subset of the GAL4 lines — those with a high enough value of the selected behavior index and those with a high enough expression level in some correlated supervoxel(s).

The clustering will be shown in the main axes, with each cluster shown in a different color. In max-projection modes, we try to show smaller clusters above larger ones. When showing a clustering, all methods of Exploring a supervoxel are applied to the clicked cluster instead.

There are several parameters associated with the clustering, all of which can be adjusted in the panel at the bottom-right of the GUI when a clustering is shown:

To affect the current clustering after changing the parameters, press the Update button. To stop showing the clustering and return to the behavior-anatomy map, click the X labeled Showing clustering.


Showing Correlated Behaviors

Selecting Show behaviors correlated w/ ??? from the Analyze menu results in a plot of behavior statistics that are most positively and most negatively correlated with the currently selected behavior statistics.


Exporting Results

The current map can be exported to an image and/or to a .mat file using the options under the File->Export menu.

When exporting an image, the type of image saved is dependent on the current View Mode. In max-projection modes, a .png file containing the max-projection of the mapis saved. In slice modes, a .tiff file containing the entire map image stack is saved.

Exporting data saves a .mat file containing a number of variables. Some of the important variables stored in this mat file are: