Launch nucloc:
Type 'nucloc' in the Matlab command window.  The window below will appear:




Each button corresponds to a specific stage of processing. In the following, we explain what each button does and how you can use the programs to map and quantify gene localization. Beware that some actions can close this window. This is normal, you can always bring it up again by typing 'nucloc' in the command window.

  • "detect cells" : automatically detect individual nuclei in fluorescence images
pressing this button will open another window (shown below). First check the image parameters on the left. Then press the "Open and process folder" button on the top left and select the folder containing all the images you want to analyze. Nucloc will then automatically process one image after the other and carve out small regions of interest around individual nuclei, as shown by the dashed rectangles in the center image. Each region of interest will then be saved as a matlab file in a folder named 'nuclocROIs', together with the image parameters.



If you want to check the result of automated processing on a single image first, use the button 'Open single image'.

  • "select cells manually": select individual nuclei by clicking manually on the fluorescence image, or a combined fluorescence + transmission image.
You can use this as an alternative to the automated detection tool, for example if the automated detection gives unsatisfactory results, or if you want to inspect cell morphology from the transmission image (see Berger et al., Supplementary Figure 1a).

  • "extract localizations": extract localization of loci and nuclear landmarks from images of individual nuclei obtained with one of the tools above.
First, select the folder containing the original images. Nucloc will then automatically find all nuclei detected previously. Next, another window appears that lets you choose different options. For example, you can specify the number of loci to be detected in each color channel (currently only 0 or 1), or whether you want to detect the nuclear envelope. You can also specify if you want nucloc to show and save figures with localization results during processing (this makes nucloc much slower, but is needed if you want to visually inspect results on each nucleus - see "quality control" below).



Next, press the button on the bottom left. Nucloc will ask you to confirm or change the default name of the output file (e.g. 'nucloc_output_5478cells_suppl.mat' if 5478 cells were processed). Then, nucloc automatically analyzes all individual nuclei one after the other and saves the extracted localization information from all nuclei in the output file.

  • "extract localizations from 1 cell": same as above, but for a single nucleus image (optional)
This button can be useful if you want to test nucloc on individual cells, as it produces more figures than the automated tool above.

  • "group & label":
If the extracted data stems from images located in different subfolders, or if you have combined data extracted at different times using "combine data " (see below), then subsequent processing will treat these groups of data as separate experiments (for example, "1-D analysis" will show different curves for each group). Also, by default, sets of images and their corresponding nuclei will be labeled using the folder name.  This button allows you to group different sets of data under a category labels of your choice. For example, if your data are from 3 folders named "WT-Nov-2008",  "WT-Dec-2008", and "Delta-Dec-2008-JoeSmith", you can group the first two under the label "WT" and relabel the third as "Delta". The output is a new .mat file starting with "labeled".

  • "quality control":
The automated localization of nuclear structures is prone to errors. In practice, this is particularly important for the nuclear envelope, which is estimated by fitting an ellipsoid to clusters of nuclear pores. The quality control feature allows to remove (or flag) nuclei with excessive localization errors.
Also, this feature checks if some nuclei have been mistakenly duplicated, which often occurs during the automated detection step. If duplications are detected, a warning shows up. Press "Proceed", and then "Remove apparent duplicates", which will do so automatically.
Next, you can then define acceptable ranges for the number of nuclear pore clusters and the semi-axes of the nuclear envelope ellipsoid (the histograms and cumulative probabilities of these quantities are shown in a figure). All nuclei satisfying these criteria will be automatically flagged internally as as "QC_OKauto" whereas those that do not will be flagged as "QC_BADauto".
Next, you are asked if you want to proceed to the visual quality control. If you answer "Yes" (default is "No"), a window will show 2D side views of nuclei together with the extracted localizations overlaid. Use the keys '0' and '1' to quickly accept or reject the nucleus and move to the next ('Backspace' moves back to the previous nucleus). Internally, nuclei will be flagged as "QC_OKvis" or "QC_BADvis".
Note that for the visual quality control to work, you must previously have checked "Show and Save" in "extract localizations", otherwise a warning message appears.
If you choose to add flagged categories to the group label of each nucleus, nucloc will automatically add labels such as "QC_OKauto" or "QC_BADvis" to individual nuclei.
Finally, nucloc creates several .mat files starting with "QC" for each category. For example, files starting with "QC_OKauto" contain only the information from the nuclei that have survived the automatic quality control.
  • "1-D analysis":
Use this feature to analyze the 1-D distributions of various parameters. Press "Analyze" and select the file containing all extracted localizations. Nucloc will then do some computations and plot the cumulative probabilities of the following parameters: radial distance of locus from nuclear center (R), elevation angle with respect to central axis (alpha), signed distance to nuclear envelope (negative if inside the nucleus, positive otherwise), R^3, cos(alpha), R*cos(alpha), and R*sin(alpha) as in the figure below.  If the input file contains nuclei with different labels ("Tel7L" and "rDNA" in the example), then each curve will correspond to a unique label (see "group & label"). This allows to directly compare the distributions of different loci or loci under different experimental conditions, with each other.




Nucloc also generates a tabulated .txt file that can be opened by a spreadsheet program such as Excel (right, below). In this file, each row corresponds to a single nucleus and each column corresponds to a parameter (e.g. the x-coordinate of the locus), as indicated by the header. Using Excel or other spreadsheet programs, you can compute statistics on these parameters or other quantities that can be computed from them. A distinct .txt file is generated for each label, e.g. Tel7L.txt and rDNA.txt in the example.

   

  • "align landmarks": aligns the nuclear landmarks from many different nuclei
This is a necessary step before generating probability maps, as described in Berger et al. (2008). First, select the file containing the extracted localization information. If the file contains several labels, nucloc will ask you to choose one of them. You can then select different processing options. For example, you can check the 'box transform' to align nuclear envelopes (but this will distort distances). If you are not interested in the shape of the nucleolus, uncheck 'transform surface of nucleolus', and the program will run much faster.
Nucloc will then align all nuclei and generate a new .mat file ending with 'aligned.mat'. In addition, you will see a 3D rendering of the aligned nuclei as in Berger et al., Fig. 1d, and the point pattern in cylindrical coordinates as in Fig. 1e (except for the grid).

  • "generate map":
First  select the file resulting from the nuclear landmark alignement step above. Next, choose the parameters. Default parameters are as used in Berger et al. 2008. Then press "Compute & show map". A figure will show up showing the locus probability map (as in Fig. 1f, Fig. 2 and Fig. 3). In addition, you can create a figure showing the point pattern in cylindrical coordinates as in Fig. 1e (check 'projected loci positions") or a graph allowing to quantify volumic confinement (see example below).


  • "combine maps":
Once you have created maps for different loci, you can combine them into a single color-coded view using this tool. Simply select the .fig files of individual maps, and press cancel where you are done. Nucloc will then create a combined figure such as this example:



  •  "combine data":
if you have extracted localization information from different sets of images at different times, this feature allows you to gather the different results files into a single file for further processing.

  • "red vs. green":
we used this feature to estimate the chromatic shift between the red and green color channels, as well as the random localization errors. To do this, we first analyzed images of nucleoli stained in red and in green using "extract localizations" twice: once normally, and once after swapping the red and green color channels. After pressing the "red vs. green" button, select each of the two resulting output files, and nucloc will compute the average and standard deviation of the differences between "red" and "green" x, y and z-coordinates, giving estimates of the chromatic shift and random localization errors, respectively. 
  • "simulate": create synthetic localization data.
this button opens a window where you can choose the type of spatial distributions you want to simulate, e.g. 2000 points located randomly in a sphere of radius 1 mu with positioning errors of 30 nm (this is the default). Press "simulate and save". Nucloc will show a 3D view of the simulated positions (below, left). In addition, it saves an output file that you can use as an input for either "generate map" or "align landmarks". This allows for example to simulate a probability map of a random localization in the nuclear volume (below, right):