Home

Airlocalize how-to guide

• Before you get started

• Analyze an example image with the visual interface

• Analyze an example image without the visual interface

• Get started with your own file

Before you get started

• Matlab needs to be pre-installed, along with the following Matlab toolboxes: Image Processing Toolbox, Optimization Toolbox
• Download the AIRLOCALIZE folder containing the code to your computer.
• Add the AIRLOCALIZE folder (including its subfolders) to Matlab's path: On Matlab's Home tab, in the Environment section, click 'Set Path'. Click 'Add with subfolders' and select the AIRLOCALIZE folder. (see https://www.mathworks.com/help/matlab/matlab_env/add-remove-or-reorder-folders-on-the-search-path.html)

Analyze an example image with the visual interface

This is the easiest way to get started. You will be able to set all parameters visually. Let's demonstrate that on one of the example files.

Launch

To launch airlocalize, type AIRLOCALIZE(); in the Matlab command line:

Analysis Mode

You will then be asked to choose the analysis mode. Let's will start with Single Image File, which lets you process a single file containing either a 2D image or a 3D z-stack. Select the Single Image File button, then click Next

Select data

Select the 3DsmFISH_humCells.tif image located in the examples subfolder:

Choose to set parameters interactively

In the next window, you will instruct Airlocalize to:

• set the parameters of the spot size and threshold intensity for the spots interactively (check the two radio buttons marked by the red arrows below)
• output an image that reconstructs the spots detected (check the radio button marked by a green arrow)
• all other parameters can be left to default.

Measure spot radius interactively

In the next window, you will measure the radius of the spots directly on the image. The interface shows the z-stack we have loaded. You can set the slice of the z-stack using the slider at the bottom.

In grab mode (green status at the center top), the plots on the right represent the intensity in the z-stack along x, y and z lines centered on the current mouse position. If you left-click on the mouse, the interface switches to snap mode (red status at the center top), and the plots remain frozen on the position of the left-click. You can toggle back and forth between snap and grab by left-clicking the mouse.

While in grab mode, the goal is to center the mouse on top of a spot, then left-click to freeze the spot position in snap mode. The plots on the right side should remain frozen on an intensity peak marking the spot (the blue curve is the data, the red line indicates the mouse position).

Once frozen near the center of a spot, left-click on local gaussian fit. You will see a fit appear overlaid to the plots on the right side. The curve is a fit of the spot intensity profile to a gaussian intensity distribution, and the radius of the gaussian is used by Airlocalize to infer the spot size. If the fit results look reasonable, click on the Record fit results in the center bottom.

The Fits recorded counter should increase by one. You can repeat this operation multiple times to record a few spots, in which case Airlocalize will use the average of the fitted radii across all spots as the spot size. You need to record at least one fit to be able to proceed. When ready to continue, click Done.

Select intensity threshold interactively

In the next window, you will set the threshold to discriminate real spots from background fluctuations. This is done visually and hence is subjective. It is recommended to test different threshold values on different images acquired in positive and negative control conditions in order to find the best threshold minimizing false positive and false negative detection rates.

The data is in green and the red channel represents pixels that will be considered by Airlocalize as spot candidates. You can increase or decrease the Detection Threshold Value in the central lower panel to increase or decrease the stringency of detection. Toggling the overlay using the Show Overlay/Hide overlay button helps checking which spots get selected. The goal is that all desired spots are covered in red pixel(s) and that no red pixels appear in the background. Only a single red pixel is needed on top of a spot for it to become detected later on. Once the threshold value looks satisfactory, click 'done'. This will close the user interface and launch the analysis. Analyzing the file (a few hundred spots) takes a few seconds on a standard laptop.

Localization Results

By default, all outputs are saved in the same folder as the original image. If running Airlocalize multiple times on the same image, results will get overwritten without warning.

The main result is the 3DsmFISH_humCells.loc4 file that should have been created in the examples folder. It is a tab-delimited text file where each row lists the position of a spot, its intensity, the intensity residuals, the number of the image and/or frame. Spots are ranked by decreasing intensity. The intensity value represent the intensity of the spot summed over all the pixels that contribute to the spot (after subtracting the local background). Note that Matlab {x,y} coordinates are flipped relative to ImageJ/Fiji conventions, so in this case, the brightest spot with coordinates [154.2, 326.4, 6.0] is centered on the voxel [326, 154, 6] in Fiji.

Parameters

Airlocalize saves all parameters of the analysis in a dedicated text file 3DsmFISH_humCells.par4. This file can be subsequently loaded directly as an argument to Airlocalize to reproduce the analysis using the exact same set of parameters.

Reconstructed image

The optional output image 3DsmFISH_humCells_spots.tif represents the spots detected by Airlocalize to enable visual verification of the results. By default, the spots have the size measured by Airlocalize and each spot is assigned its intensity measured by Airlocalize.

Analyze an example image without the visual interface

Once familiar with the interface and if repeating analyses with the same parameters, it becomes more practical to skip the user interface and feed the parameters using a configuration file. The syntax is simply AIRLOCALIZE('path/to/your/config/file');

Let's demonstrate this on an one of the example image files.

• First, make sure that Matlab's current folder is set to the AIRLOCALIZE root folder.

• In the Matlab command line, type:

AIRLOCALIZE('examples/3DsmFISH_humCells.ini');

(use a backslash on a PC).

• the analysis should start and output as before a .loc4 a .par4 and a reconstructed image.

The .par4 file has the same format as a config file and can be used as a template to analyze other images using the same parameters. To do this, duplicate the .par4 file. Then edit the following:

• the dataFileName entry (enter the path to the new file you want to analyze)
• the saveDirName entry (enter the path to the folder where you want to save the results)

Get started with your own file

You only need your image file. It should be tif, single color channel file; can be either 2D or 3D. Follow the steps above and you should create output results in the same folder as your input image.