rapidSTORM manual

Version 3.3

Steve Wolter

Würzburg University
Biophysik & Biotechnologie

Sven Proppert

Würzburg University
Biophysik & Biotechnologie

Sarah Aufmkolk

Würzburg University
Biophysik & Biotechnologie

André Lampe

Freie Universität Berlin
Labor für Membranbiochemie und Molekulare Zellbiologie

Teresa Klein

Würzburg University
Biophysik & Biotechnologie

This document is the official manual of the rapidSTORM software. It is generated deterministically during the build process and can be identified and cited using the version number on the front cover as the edition. Dieses Dokument wurde automatisch erstellt und ist ohne Unterschrift gültig.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

January 15, 2014


Table of Contents

Motivation and scope of rapidSTORM
Help on Help
1. User interface
1.1. Basic use tutorial
1.2. Behaviour of input fields
1.2.1. Immediate effects and committing values
1.2.2. Multi-dimensional chaining
1.2.3. Optional values
1.2.4. Selecting input files
1.2.5. The output options tree
1.3. The menu bar
1.3.1. Job
1.3.2. User level
1.3.3. Help
1.4. Image window
2. Usage examples
2.1. Evaluate 3D data with a bead calibration sample
2.2. Evaluate spectral demixing measurement
3. Input options
4. rapidSTORM engine options
5. Output options
Localizations file
Image display
Count localizations
Memory Cache
Slice localization set — Split the input along the time axis to make a movie
Average images
Display progress
Estimate PSF form
Look up 3D via sigma difference
3D PSF width calibration table
Expression filter
6. Common error messages
7. Fundamental concepts
7.1. Input channels
7.2. dSTORM engine
7.3. Localization
7.4. Fluorophore type
7.5. 3D fitting
7.6. Piecewise cubic model
7.7. Z calibration file
7.8. Polynomial model
7.9. Repeater
7.10. PSF model
7.11. Two-kernel analysis
7.12. Linear drift correction
Bibliography

List of Tables

5.1. Variable base names for expressions
5.2. Variable name modifiers for expressions
5.3. Variable example names for expressions
5.4. Operators in expressions
5.5. Example actions

List of Equations

7.1. Polynomial 3D PSF Width

Motivation and scope of rapidSTORM

The rapidSTORM software is a single-molecule localization microscopy evaluation software. Its aim is to identify single fluorophores in sequences of images of sparsely emitting samples. Such images are generated by techniques such as dSTORM, STORM, PALM and FPALM and are used there to achieve super-resolution imaging. Since a sequence usually consists of several thousand images and nanometre precision is necessary for super-resolution, computational speed and precision are both extremely important. Delivering these attributes is the goal of rapidSTORM.

rapidSTORM aims to support both three-dimensional imaging and spectral unmixing applications. Three-dimensional imaging refers to the computation of individual fluorophore's Z positions via the observation of shape changes in the point spread function. Both astigmatic and multi-layer approaches are supported here. Spectral unmixing refers to distinguishing multiple fluorophore types by their differential emission strength in multiple optical detection paths. For example, a dichroic mirror might be used to project the red part of the fluorescence on one camera and the blue part on a second camera.

rapidSTORM is not meant as an all-purpose evaluation tool for super-resolution microscopy or as a camera driver. It is, however, designed to play nice with other systems and has a good number of evaluation options built in. You are encouraged to interface the direct camera input driver with a camera system or use the different output options for necessary control systems.

You can find discussions, help, advice and announcements for rapidSTORM on the rapidstorm-discuss mailing list. The source code is available from the GitHub repository. Bugs can be reported at the GitHub issue tracker.

Help on Help

It is recommended to read Chapter 1, User interface first to get a broad overview over the user interface. Further information can be found in the relevant reference sections, which can be studied in any order.

Chapter 1. User interface

rapidSTORM's user interface is based on a single window (the main window) with multiple tabs. Each tab represents either a job configuration or a running job. When rapidSTORM is started, a single job configuration for a localization job is opened by default.

Jobs can be started by clicking the Run button at the bottom of a job configuration. Further job configurations can be found in the Job menu.

This chapter will first exemplify basic usage and the process of opening jobs in a tutorial. Then, the general behaviour of input elements and the different kinds of job configurations will be explained.

1.1. Basic use tutorial

Start an evaluation

This tutorial will exemplify basic rapidSTORM usage by showing how to convert an Andor SIF acquisition to a super-resoluted image with rapidSTORM. We will load an Andor SIF file, characterize the optics by giving a pixel size and the PSF full width at half maximum, give a target image resolution and start an evaluation.
  1. Start rapidSTORM via the icon in the Start menu
  2. Select the input file by dragging & dropping it from a Windows Explorer window to the Input file field (1.
  3. Set the input pixel size by entering the value in the Size of one input pixel field (2).
  4. Enter the full width at half maximum of your point spread function into the PSF FWHM field (3. You can estimate this value from the numerical aperture of your microscope by the approximation λ / 2 NA, where λ is the detection wavelength and NA the numerical aperture of your objective.
  5. Show the options of the image display output by clicking on it (4) in the output option tree.
  6. Optionally change the resolution of the result image by changing the resolution fields (5).
  7. Start the computation by clicking the Run button (6).

After you finished starting the evaluation, a new tab will appear in the job tab bar, and a new window will be opened. Continue with the next task: Manage an evaluation.

Manage an evaluation

This tutorial shows how to interpret the job window and to modify the output image. We assume you have started a job, as described in the Start an evaluation tutorial.
  1. Enhance the image contrast by raising the Extent of histogram normalization value to 0.5. Note how the intensity key next to the image display window changes.
  2. Filter out low-intensity localizations by checking the box next to Minimum localization strength and entering a value of 4500. Filtering out weak localizations reduces background noise and enhances the image resolution slightly, but reduces the number of localizations available for image construction.
  3. Change the colour code by changing Color palette for display to Vary hue with coordinate value. The color of the image now shows the X coordinate, resulting in a rainbow-coloured image.
  4. Change the hue-producing coordinate by changing Coordinate to vary hue with to emission strength. The colour code would now display the intensity of each localization, but stays grey because the range is not set.
  5. Change the Color range fields at the lower right end of the result image window to 5000 and 30000 by entering each value and pressing enter.
  6. Close the job by pressing Close job. The image window will stay active until it is closed.

1.2. Behaviour of input fields

Job configurations consist of a series of input fields and control elements that configure the job. Most of them are standard UI tools like buttons and checkboxes, and we assume you are familiar with their use. However, there are a number of specialities, and we will introduce them in this section.

1.2.1. Immediate effects and committing values

The visibility of many input fields in rapidSTORM is dependent on previous choices, i.e. the value of fields that are displayed above the current field. Therefore, changes in text fields are not immediately committed while you type. While a field is not committed, its values do not take effect, and its background is red. You can commit a textfield by pressing Enter or switching the keyboard focus away from the field, e.g. with the Tab key or clicking another field.

1.2.2. Multi-dimensional chaining

Text fields in rapidSTORM are often part of a matrix. You can recognize matrices by the presence of multiple text fields with one description. Next to a matrix field, a button with a chain is shown.

The chain button is used to "chain" the matrix elements, that is to change all elements at once (chained) or individually (unchained). When text fields are chained, entering text in one of the fields immediately changes the text in all fields. When text fields are unchained, each field is changed and committed individually. Leading unchained text fields in a matrix do not commit their values when they lose focus; only the last text field in the matrix behaves in this way.

1.2.3. Optional values

Some values in rapidSTORM are optional, that is, they can have no value at all. These fields have a checkbox in front of them. The checkbox controls the presence of a value, and the text field is not displayed while the checkbox is not checked. When you check the checkbox, the text field will be uncommitted and has to be committed in the usual way to take effect.

1.2.4. Selecting input files

When a text field in rapidSTORM requires a file name, you can enter the file name directly, select it interactively with a dialog by clicking the Select button next to the field, or by dragging & dropping the file on the input field.

1.2.5. The output options tree

Localization jobs and replay jobs organize their output in an output options tree. This tree is displayed with a tree element on the left, which shows the structure of the tree and allows selecting a single node, and the node detail field, which shows the detailed options for the tree node selected on the left-hand side.

Each node in the output tree represents an output module, which will perform some action with or display information about the output. Some of the output modules such as the Expression filter modify their input and can have subordinate output modules. The subordinate output modules will act on the localizations that were modified by their parent output modules.

The first, root node (called "dSTORM engine output") symbolizes the output of the Section 7.2, “dSTORM engine”. Each module connected to it receives all localizations found by the engine without filtering or processing.

For an example, consider the tree shown in the graphic: The first Localizations file, Count localizations, Display progress, Filter localizations and Average images receive the unmodified output from the Section 7.2, “dSTORM engine”. The localizations received by the second Localizations file and for Image display are those modified by the Filter localizations module.

Clicking on an output module in the tree view shows this module's configuration in the right part of the display. Each module has specific configuration options, which are documented together with the module's description in the Chapter 5, Output options chapter. You can manage the suboutputs by the following standard control elements:

Output configuration items

Choose new output

This button opens a dialog for choosing new output modules.

Remove output

The current output module and all its children are removed from the output tree.

1.3. The menu bar

1.3.1. Job

The job menu is used to open and save job configurations.

You can open new jobs by selecting any of the template entries in one of the submenus. The submenu selects the type of the new job configuration, e.g. Localization for localizing fluorophores in images, Replay for reading a localizations file, or Alignment fitter for fitting a linear alignment matrix to two localization files.

You can save the configuration of the current job tab by clicking on Save .... You can open a saven configuration by using the From file ... menu item in the submenu with the same job type (e.g. Localization for a saved localization config).

1.3.2. User level

The user level menu is used to limit the number of available input fields. At low user levels, only the most important input fields are displayed. You can change the user level by clicking on the appropriate menu entry.

1.3.3. Help

In the help menu, you can interactively open the section of the manual that describes a given input item. Click first on the menu item What's this?, and then on the input field's label.

1.4. Image window

When a job is started with the Image display output module active, a window showing an image with the already computed localizations is displayed.

The image display window shows one or two keys on its right side. If there is one key, it shows the mapping of intensity values, i.e. accumulated emission intensities, to colors. The numbers are suffixed with SI unit prefixes, and the unit is displayed at the top of the key.

If the image is hued by coordinate, a second key appears. The left key is in black and white and shows the image intensity, while the right key shows a color spectrum and displays the values indicated by the colours. The two text boxes at the bottom of the right key allow setting the range of the hueing. If the right key is completely black, the range is unknown and must be entered.

Chapter 2. Usage examples

2.1. Evaluate 3D data with a bead calibration sample

Record a bead calibration data file

We assume that you have an appropriate cylindrical lens in detection path and are using an objective piezo (e.g. PIfoc, Physik Instrumente). The sample should be a thinly coated Tetraspeck bead sample. Beads should be preferred because of the superior brightness and - in case of tetraspec beads - of the sub-resoulution size. You should know the size of the input pixels.

  1. place Tetraspeck surface on microscope
  2. Set the piezo to a sawtooth or triangular pattern that scans your whole planned axial localization range. Exceeding the localization range is not critical, the excess measurements can be cropped later. For an example, we used the following settings:

    function
    triangular
    low position
    45 μm
    high position
    55 μm
    frequence
    0.02 Hz
  3. Set camera exposure time (0.02 s)
  4. Compute and remember piezo movement per frame ((55 μm - 45 μm) · 2 · 0.02 Hz · 0.02 s/fr = 8 nm/fr). This will later be needed as an evaluation input.
  5. focus on Tetraspeck
  6. start piezo
  7. record data

Produce calibration curve

We assume that you have recordad a bead calibration data file and have some plotting software, e.g. gnuplot, Origin or Matlab, at your disposal.
  1. Start rapidSTORM 2 and set User level to Intermediate or higher
  2. Set Input file to calibration data file (in this example: foo.tif)
  3. Set Size of one input pixel to pre-calibrated values (e.g. 142 and 125 nm in X/Y, respectively)
  4. Set Intensity threshold to a high value (5000 ADC) in order to filter noise
  5. Set Fit window radius to a value considerably higher than the best-focused PSF FWHM in order to include the PSF tails, and remember the input. (1100 nm)
  6. Set Fit iteration limit to 100 (optional)
  7. Check boxes PSF width is free fit parameter and Store PSF width
  8. Go to the Expression filter output and set
    1. Set Number of expressions to 4
    2. First Value to assign to to posz
    3. First Expression to assign from to 8 nm/fr * frame
    4. Second Value to assign to to psffwhmx
    5. Second Expression to assign from to psffwhmx - 25 nm[1]
    6. Third Value to assign to to psffwhmy
    7. Third Expression to assign from to psffwhmy - 25 nm
    8. Choose new output to 3D PSF width calibration table
  9. Go to the 3D PSF width calibration table output and set Number of B spline breakpoints to 10
  10. Click Run
  11. Plot the PSF widths in the localization file foo.txt (columns 6 and 7) against the Z truth (column 3) and check for local maxima and outlier points
    • If local maxima exist, narrow the range of usable Z data by setting an appropriate filter expression in the fourth Expression to assign from field in the Expression filter output. In our example, we used posz > 2000 nm && posz < 6000 nm . Go back to Step 11.
    • If outliers are present, raise Intensity threshold and go back to Step 11
    • Otherwise continue with Step 12
  12. You are done with the generation of the calibration file. The generated calibration curves are stored in foo-sigma-table.txt (see the Fundamental Section 7.7, “Z calibration file” for details about the file format).

Make 3D super-resolved image colour-coded by Z

We assume that you have a correct bead calibration data file file for your setup.
  1. (Re-)Start rapidSTORM
  2. Set 3D PSF model to Interpolated 3D
  3. Set Z calibration file to the file name of the calibration curve file.
  4. Set Intensity threshold to a similar value as in 2D (e.g. 1000)
  5. Set Fit window radius to the same value you used for producing the calibration curve (1100 nm)
  6. Go to the Image Display output and
    1. Set Colour palette for display to Vary hue with sample coordinate
    2. Set Coordinate to vary hue with to position in sample space z
  7. Run evaluation and wait for job to finish

Make 3D super-resolved Z stack

We assume that you have a correct calibration curve file for your setup.
  1. (Re-)Start rapidSTORM
  2. Follow Step 2 to Step 5 of Make 3D super-resolved image colour-coded by Z.
  3. Set user level to Intermediate
  4. Go to the Image Display output and
    1. Set Resolution in X direction to 20 nm
    2. Set Resolution in Y direction to 20 nm
    3. Set Resolution in Z direction to 50 nm
    4. Check Make 3D image
    5. Change extension of Save image to to .tif
  5. Run evaluation and wait for job to finish

2.2. Evaluate spectral demixing measurement

This usage example shows how to produce two-color images from spectrally unmixed data sets. It was written for an Alexa647/Alexa700 measurement on the Würzburg 1 biplane setup as documented in [Aufmkolk2012]. The first two tasks in this example produce prerequisite knowledge for the image generation, the alignment information (Produce linear alignment matrix) and the F2 ratios, i.e. the relative intensity of fluorophores between the channels.

Produce linear alignment matrix

We assume you have two input data files X1.tif and X2.tif showing 2 spectrally overlapping fluorophores. The images in both files are assumed to be synchronous, spectrally different views of the same sample area.

  1. Start rapidSTORM
  2. Set Input file to X1.tif
  3. Check Ignore libtiff warnings

    We use Andor SOLIS for recording, which records broken TIFF files.

  4. Set Size of input pixel to precalibrated value (107 nm)

  5. Go to the Expression filter output option and set Choose new output to Count localizations
  6. Start evaluation
  7. Enable the Minimum localization strength field and set its value very high, adjusting it until the second counter shows approximately as many localizations as the acquisition has frames.

    This ensures a sparse population of multi-fluorophore localizations in the output, which can easily be paired through the time coordinate. This is the "bead of opportunity" technique.

  8. Close the job
  9. Set Input file to X2.tif
  10. Repeat Step 6 to Step 8
  11. Open an alignment fitter job with Job->Alignment fitter->Minimal
  12. Set File 1 to X1.tif
  13. Set File 2 to X2.tif
  14. Set Output file to linMatrix_X1toX2.txt
  15. Set Sigma to 1
  16. Click Compute
  17. Wait for an alignment job to open and its progress bar to fill
  18. The final alignment matrix is displayed in the text fields. Check that it is sane, i.e. scale factors are close to 1, shear close to 0 and translation smaller than 2 micrometers
    • If the parameters are sane, this task is finished and the alignment matrix is stored in linMatrix_X1toX2.txt.
    • If the parameters are not sane, try a different setting of Sigma or different values in the Shift, Scale or Shear fields and repeat from step Step 16.

Analyze two-colour acquisition

We assume you have the same two input data files as in Produce linear alignment matrix and have a linear alignment matrix linMatrix_X1toX2.txt.

  1. Set user level to Intermediate
  2. Set Number of input channels to 2
  3. Select tab Channel 1 and set Input file to X1.tif
  4. Select tab Channel 2 and set Input file to X2.tif

    It is crucial to keep the channel naming

  5. Set Join inputs on to Spatially in z dimension
  6. Set Number of fluorophore types to 2
  7. In Input layer 2, set Plane alignment to Linear alignment
  8. In Input layer 2, set Plane Alignment file to linMatrix_X1toX2.txt
  9. Set Size of input pixel (107 nm) and PSF FWHM (370 and 390 nm, respectively) in both Input layer tabs

  10. Are the F2 ratios of the fluorophores already known?

    • No: Continue with Step 11
    • Yes: Run the evaluation and skip to Step 17
  11. Set the Transmission coefficient fields in both layers to the approximate relative brightnesses of the fluorophores. In this example, we estimated values of 2.5 and 0 for the first channel and 1 and 1 for the second channel.
  12. Go to the dSTORM engine output output and set Choose new output to Estimate PSF form
  13. Go to the Estimate PSF Form output and uncheck Fit PSF FWHM
  14. Run the evaluation
  15. A PSF selection window appears, showing the two channels in alternating rows. In each row pair, each column shows a pair of ROIs with a localization. The localizations are pre-classified as belonging to fluorophore 0 (red taint), 1 (green taint) or being ignored (grey taint). You can switch the classification by drawing a box around the image pair. When you are satisfied with the classification, close the window. The window reappears with new localizations until you have classified sufficiently many localizations. Make sure that both fluorophores are represented; if a particular fluorophore is overrepresented, switch it to ignored (grey taint).
  16. In the job tab, a tab box with the input layers shows the result of the PSF estimation once the form estimation is finished. Write down the new Transmission coefficient values for all tabs, these can be re-used in later evaluations.
  17. Wait for the evaluation to finish. The generated localizations file contains color-assigned localizations with the correct F2 values.

Produce a single two-colour image from two-colour localizations file

We assume that you have a localizations file with assigned colors X1.txt.

  1. Set Input File to X1.txt.
  2. Go to the Image display output and
    1. Set Colour palette for display to Vary hue with coordinate value
    2. Set Coordinate to vary hue with to fluorophore type
    3. Set Range of hue to 0.5 (cyan)
  3. Run the evaluation. The result image will be color-coded by fluorophore intensity.
  4. You can adjust the relative intensity by setting Value to assign to to amp and Expression to assign from to (fluo == 0) ? amp * 1.5 : amp, varying the 1.5 as necessary.

Produce two spectrally separated images from two-colour localizations file

We assume that you have a localizations file with assigned colors X1.txt.

  1. Set user level to Intermediate or higher
  2. Set Input File to X1.txt.
  3. Set Output file basename to X1-fluo1.
  4. Go to the Expression filter output and
    1. Set Value to assign to to Filter
    2. Set Expression to assign from to fluo == 0
  5. Run the evaluation, wait until it is finished and close the job
  6. Set Output file basename to X1-fluo2.
  7. Go to the Expression filter output and set Expression to assign from to fluo == 1
  8. Repeat Step 5


[1] This value is a wild guess. It should denote how much wider a fairly large object like a Tetraspec looks than a fluorophore.

Chapter 3. Input options

Table of Contents

Input fields

3D PSF model

The 3D PSF model denotes the functional form of the PSF's change with respect to the emitter's Z position.

See Also No 3D, Polynomial 3D, Interpolated 3D.

Andor SIF file

This input driver can read the Andor SIF file format produced by Andor Technology software such as SOLIS.

SIF files are stored in an uncompressed binary format with a simple text header. Because reading SIF files cannot be implemented in a forward-compatible way (reading new SIF files with old software), this driver might be unable to open the file; in this case, an error message is shown indicating the maximum known and the encountered version of the Andor SIF structure. Please obtain a newer version of this software in this case.

bUnwarpJ transformation

A bUnwarpJ raw transformation file is given in this field to characterize the channel alignment.

Camera response to photon

This option allows to give the mean intensity each photon generates on the camera. In other terms, a value of 5 in this field assumes that the value of a pixel goes up by 5 (on average) every time the pixel is hit by a photon.

Dark intensity

This option allows to give the dark intensity of the camera, i.e. the mean pixel value for a pixel that is hit by no photons during the integration time.

Dual view

This option allows splitting an image that contains two logical layers. For example, if the reflected beam of a beam splitter is projected onto the left side of the camera and the transmitted on the right side, this output allows to separate them into two different layers that can be used for 3D estimation.

The options are None, which indicates no splitting at all, Left and right, which splits the image at X = Width/2, and Top and bottom, which splits the image at Y = Height/2.

The dual view output always splits images exactly in the middle. Use plane alignment to configure other shifts.

File

This choice for Input method indicates that a file is used for input instead of generating the input stochastically or reading directly from a camera.

File type

This field is used to select the type of data that are present in the input file. Usually, this is auto-detected, and when the Input file location is changed, this field is updated with the auto-determined file type for the selected input file.

See Also File, Input file.

First image

This option allows skipping of the initial frames of the input. The frames are indexed sequentially from 0, and the value given here is inclusive. Consequently, the default value of 0 in this field causes all images to be loaded. A value of 5 would skip the first 5 images.

See Also Last image.

Fluorophore types

The number of fluorophore types present in the input should be given here. When multiple fluorophores are selected, Transmission of fluorophore N fields can be used to characterize the spectra.

Input file

The location of the input data is selected in this field. You can put any existing file here. It's interpretation (file type) and file-type-specific input options are set in the File type field. This field is only available when you have selected File as Input type.

See Also File, File type.

Input method

This field is used to select the type of data that are present in the input file. Usually, this is auto-detected, and when the Input file location is changed, this field is updated with the auto-determined file type for the selected input file.

You can enforce the file type instead of auto-detection by explicitly selecting a choice in this field after entering a file name.

Input type

This field is used to select the general type of input that should be used. If input should be read from some kind of file, select File here and the specific type of file in the File type field.

See Also File.

Interpolated 3D

The piecewise cubic 3D model (see Section 7.6, “Piecewise cubic model”) determines PSF widths from the Z coordinate.

Join inputs on

When multiple channels are selected, this field is used to declare how these multiple channels are combined into a single image or dataset. The available options are:

  1. Spatial joining in X/Y dimension, which means that images or datasets are pasted next to each other. For spatial joining of image data in the X/Y dimension, the not-joined dimension (e.g. the Y dimension for X joining) must match.
  2. Spatial joining in Z dimension. When processing images, each input channel is considered as a separate layer, with the first channel forming the first layer. For localization data, this is identical to X/Y joining in Z dimension.
  3. Joining in time. Channels are processed after each other in the sequence of their declaration. For images, the dimensions of the images must match.
Last image

If this option is enabled, it allows limiting the length of the computation. All images past the given frame number, counted from 0 and excluding the given number, are skipped. For example, a value of 3 would case the four images with indices 0, 1, 2 and 3 to be computed.

See Also First image.

Linear alignment

Naive pixel coordinates are computed identically to No alignment and then transformed by an affine transformation matrix.

Localizations file

This input driver can be used to read the files written by the Localizations file output module. The file format is documented with the output module.

Maximum Z range

The PSF model will be considered valid up to this distance from the point of sharpest Z. Any considered Z coordinate further away than this value will be immediately discarded.

Mirror input data along Y axis

If this option is enabled, each input image is flipped such that the topmost row in each image becomes the bottommost row.

No 3D

The PSF width is constant, and no Z coordinate is considered.

No alignment

The upper left pixel is assumed to be at (0,0) nanometers. The Size of one input pixel field gives the offset of each pixel to the next. For example, if the pixel sizes are 100 nm in X and 110 nm in Y, the pixel at (10,15) is at (1,1.65) μm.

Number of input channels

This field is used to declare how many Section 7.1, “Input channels” should be made available. New input channel configuration tabs are added or removed as needed when this field is changed.

Output file basename

This is the location and filename prefix for rapidSTORM output files. More precisely, the filenames for rapidSTORM's output files are produced by adding a file-specific suffix to the value of this field.

This field is automatically set when a new input file is selected.

Plane alignment

This option allows to describe the mapping from input pixels to sample space coordinates. For the majority of single-layer applications, the default choice of No alignment is appropriate.

See Also No alignment, Linear alignment, Support point alignment.

Plane alignment file

A plain text file containing a 3x3 affine matrix for linear alignment, with the translation given in meters. The matrix is assumed to yield the aligned coordinate positions if multiplied with a vector (x, y, 1), where x and y are the unaligned coordinates. The upper left 2x2 part of the matrix is a classic rotation/scaling matrix, the elements (0,2) and (1,2) give a translation. For now, the bottom row must be (0,0,1), i.e. not a projective transform.

Point of sharpest Z

The Z coordinate of the focal plane (the plane where the PSF has the lowest width). You can indicate astigmatism by giving different positions for the two dimensions of one layer, or biplane by giving different positions for two layers.

Polynomial 3D

The polynomial 3D model (see Section 7.8, “Polynomial model”) determines PSF widths from the Z coordinate.

Processed planes

This option allows selecting a single layer from a multi-layer acquisition. The default option, All planes, has no effect. All other options select a single layer from the available input layers, which will be the only layer that is processed.

PSF FWHM

The full width at half maximum of the optical point spread function. More precisely, the typical width of an emitter's image should be entered here, including fluorophore size and camera pixelation effects. rapidSTORM will fit spots in the images with a Gaussian with the same FWHM as given here. If the PSF is unknown, it can be determined semi-automatically by using the Estimate PSF form output.

PSF FWHM at sharpest Z

The width of the PSF at the Z position indicated by Point of sharpest Z. This is typically the same value as PSF FWHM.

Size of one input pixel

This field gives the size of the sample part that is imaged in a single camera pixel. Typically, this value should be in the order of 100 nm. See [Thompson2002] for a discussion about ideal values.

Support point alignment

Naive pixel coordinates are computed identically to No alignment. A nonlinear transformation image is read from a file. The naive coordinates are projected into the source image of the nonlinear transformation, and the transformation is applied with linear interpolation.

TIFF file

This input driver reads a multipage TIFF stack. All images in the TIFF stack must have the same size, and be greyscale images of up to 64 bit depth. Both integer and floating point data are allowed, even though all data are converted internally to 16 bit unsigned format.

Transformation resolution

The resolution (pixel size) of the file given in bUnwarpJ transformation. This resolution is not necessarily the same as the value of Size of one input pixel. For example, you can super-resolve two images with an easily aligned structure such as the nuclear pore complex ([Loeschberger2012]), which will result in a raw transformation with a 10 nm resolution.

Transmission of fluorophore N

There is one transmission coefficient field for each layer and fluorophore. The fields give the relative intensities of each fluorophore in each layer, and will be used as scaling factors for the intensity for multi-colour inference or for biplane imaging.

As an example, values of 0.1 in layer 1, fluorophore 0 and 0.9 in layer 2, fluorophore 0 would indicate that 90\% of the photons arrive on the second camera and 10\% on the first.

Widening slopes

These entries give the speed of PSF growth. They have to be determined experimentally, and we know of no reliable method to do so. For more information, see Section 7.8, “Polynomial model”.

Z calibration file

The filename of a Z calibration file (Section 7.7, “Z calibration file”) should be given in this option. The calibration file will be used to determine PSF widths as a function of the Z coordinate during fitting.

Chapter 4. rapidSTORM engine options

Table of Contents

Allow disjoint fitting

Employ the computational optimization of separating the X and Y dimensions of the Gaussian for computing the function's derivatives. This optimization is only performed if the alignment is set to No alignment, but can drastically improve computation time for large fit windows.

Background mask width

The full width of a square structuring element for the background averaging.

Compute two kernel improvement

Perform the Section 7.11, “Two-kernel analysis” computation, which sets the two kernel improvement field.

Disjoint amplitude fit

Fit the emission intensity in each plane independently. This option can be useful if the number and nature of fluorophore populations in the sample is unknown. However, it will break multi-colour inference, and all Transmission of fluorophore N fields should be set to 1.

Erode image

Smooth by applying a morphological erosion with a square structuring element of the specified size.

Erosion mask size

The full width of a square erosion mask.

Fit iteration limit

The nonlinear fit process for a localization attempt is stopped after this number of iterations.

See Also Relative epsilon, Lateral epsilon.

Fit judging method

The fit judging method controls the decision whether a set of fitted PSF parameters is a localization or just background noise.

See Also Fixed global threshold.

Fit window radius

All pixels within this radius of a spot are used for fitting. The selected pixels form the data points for the nonlinear fitting routine, and the PSF is fitted to their intensities.

A larger value here allows more precise fitting at the cost of slower computation.

Fixed global threshold

This fit judging method judges parameter sets by their intensity. If the intensity surpasses the threshold, the parameter set is counted as a localization, and discarded otherwise.

See Also Intensity threshold.

Foreground mask width

The full width of a square structuring element for the foreground averaging.

Improve fit with ML estimate

After successfully fitting a spot with a least squares error model, improve the fitted position using a maximum likelihood error model. This improves precision, especially for low photon counts, in exchange for a considerable increase in computation time. The Camera response to photon and Dark intensity fields must be set if this option is used.

Initial lambda factor

The usual lambda factor of Levenberg-Marquardt fitting controls the size of the trust region for Gauss-Newton steps. Refer to a good textbook for its meaning, e.g. [Recipes].

Intensity threshold

Minimum fitted emission intensity necessary for a spot to be considered a localization. If the fitted position has an intensity lower than this value, it is discarded as an artifact.

See Also Fixed global threshold.

Laempi fit for positions

Fit the lateral emitter position (x,y) in each plane independently. This option can mitigate small errors in alignment at the cost of reduced precision.

Lateral epsilon

The nonlinear fit process for a localization attempt is continued while the lateral mean position (x,y) changes absolutely by more than this parameter.

See Also Fit iteration limit, Relative epsilon.

Levenberg-Marquardt fitter

Currently, Levenberg-Marquardt fitting is the only implementation of a spot fitter, i.e. a routine that localizes a fluorescence emission to subpixel precision. The LM fitter works by building a PSF model (in most cases a Gaussian function), estimating crude initial guesses for a the parameter of this model, and then optimizing the distance between the data in the immediate surroundings of the spot and the theoretical model. The parameters of the model then give the location of the emitter and its intensity.

Local relative threshold

This fit judging method judges parameter sets by their intensity and the local background. Both values are the estimations from fitting the PSF model to the data. If the ratio of intensity to square root of local background surpasses a threshold, the parameter set is counted as a localization, and discarded otherwise. The square root of the background is used because it estimates the standard deviation of a Poisson-distributed background. The Dark intensity and the Camera response to photon should be set to use this option.

See Also Signal-to-noise ratio.

Minimum spot distance

The minimum distance between local maxima of the smoothed image that will be used as fit start locations. In other terms, this entry gives the size of a local maximum suppression window that selects the spots.

High values will ensure a higher noise tolerance at the cost of some missed localizations.

Morphologically reconstruct image

Smooth the input by performing a morphological fillhole transformation (using reconstruction by dilation) followed by a rectangular erosion.

PSF width is free fit parameter

Treat the PSF width as variables in the fit process rather than as constants. The estimated or fixed standard deviation parameters act as initial values for the estimation when the free covariancce matrix is selected.

This checkbox will drastically reduce the localization precision and increase noise localizations, but is useful when the PSF width is variable between spots (e.g. in 3D estimation). If it is merely unknown, you should prefer using the Estimate PSF form output.

See also: PSF model

Relative epsilon

The nonlinear fit process for a localization attempt is continued while any parameter (except the lateral means x and y) changes relatively by more than this parameter.

See Also Fit iteration limit, Lateral epsilon.

Signal-to-noise ratio

Minimum ratio of emission intensity to square root of background signal intensity necessary for a spot to be considered a localization.

See Also Local relative threshold.

Smooth by average

Smooth by applying a square moving window average filter.

Smooth by difference of averages

Smooth by applying a square moving window average filter. Then substract the result of a wider square moving window average filter, which estimates the local background and can thereby deal with uneven backgrounds.

Smooth by median

Smooth by applying a square median filter of the specified width.

Smooth with gaussian kernel

Smooth the input images with a Gaussian kernel of the specified width. This kernel can be set to the PSF size or specified independently. Gaussian smoothing is often suboptimal, see [WolterDiplomarbeit] for details.

Smoothing kernel std.dev.

The standard deviation (σ) of a Gaussian smoothing kernel.

Smoothing mask width

The full width of a square structuring element used for Smooth by median and Smooth by average smoothing.

Spot finding method

Select a smoothing method to be employed before selecting local maximums as spot candidates. The standard method here is smoothing with an average mask (Spalttiefpass), which gives good performance for most images. Median smoothing provides slower, but sometimes more accurate and less blurring smoothing. Erosion (also known as local minimum filter) is faster than the median filter and gives similar results for small (standard deviation close to 1) spots, while the fillhole transformation followed by erosion is better for large spots. For a complete discussion and quantitative comparison, see [WolterDiplomarbeit] and [Wolter2010].

Spot fitting method

The spot fitting method is the method for converting suspected fluorophore positions (spots) into localizations. There is currently only one useful choice, Levenberg-Marquardt fitter.

Spot search eagerness

The rapidSTORM engine uses dynamical thresholding, i.e. fits the spots with at the most intense positions in the smoothed image first and continues in order of decreasing intensity. Fitting is aborted when a number of spots equal to the motivation is rejected by the Fit judging method. This parameter controls the motivation.

Higher values in this field will cause more localizations to be found, albeit at the cost of more false positives.

Store PSF width

Set the psffwhmx and psffwhmy fields of localizations to the widths used in computation. If this field is checked, the localization output files will contain PSF width information, and all outputs working with localization widths depend on this checkbox.

Two-kernel distance threshold

When performing two-kernel analysis (see Section 7.11, “Two-kernel analysis”), any double-kernel fit with the two kernels further apart than this number is immediately discarded, resulting in a two-kernel improvement of 0.

This parameter ensures that large fitting windows and two-kernel analysis can cooperate.

See Also Compute two kernel improvement.

Use 64 bit floats

Compute values and derivatives of the PSF with 64 bit wide floating point numbers instead of 32 bit. Ensures higher reliability and precision, but with a small speed cost.

Chapter 5. Output options

This chapter is dedicated to the description of the different output modules that can be inserted into the output tree. Each of these modules will be defined by a general description of its purpose and its mode of operations, a table of the configuration options it will display in job options window (if any), and a table of the configuration options it will display in the job status window (if any).

Name

Localizations file

Synopsis

The localizations file module stores received localizations in an ASCII text file. This text file is line-based with one line per localization and one line header information. Both the header line and localization lines consist of at least 4 space-delimited fields. For the localizations, the fields denote X and Y position in pixels, the image number of the localization and the strength of the localization (Gaussian fit amplitude) in camera A/D counts. The header consists of the maximum allowed X/Y coordinates and image number and of a 0 for the amplitude.

More fields may be present, but will not be documented. Forward compatibility can be achieved by ignoring all but the first four fields.

Configuration items

Write localizations to

Output localizations file name. Is derived automatically from input file name.


Name

Image display

Synopsis

The image display module displays all received localizations in an image and optionally saves this image to a file.

Image construction algorithm

The image construction is performed with the algorithm documented in [WolterDiplomarbeit]. Summarizing this algorithm, a localization density map is constructed by linearly interpolating and accumulating the localizations, weighted by their amplitude, on a pixel lattice. This density map is discretized with a very high depth to generate a high dynamic range image; this high-dynamic range image is reduced to a displayable range via weighted histogram equalization.

The histogram equalization operation modifies the absolute brightness differences between image areas to optimize contrast. This means that a pixel in the result image with a brightness of 200 did not necessarily receive twice as many localizations as a pixel with brightness 100 did. Histogram equalizations guarantees only that a brighter pixel represents at least as many localizations as a weaker pixel.

You can change the extent to which histogram equalization is performed by changing the histogram equalization power between 0 and 1. 0 means no histogram equalization, and pixel values are linear with localization density. 1 means full equalization: All brightness values appear equally often in the image. While images without histogram equalization aplied often suffer in contrast due to few, very bright pixels suppressing the normal structures, too much histogram equalization overemphasises regions with weak signals and background noise. The default value for the histogram power is usually a good compromise.

Color coding

Several different coloring schemes are available for the resulting image. All of these operate on the histogram-normalized brightness, but display the brightness in various ways to enhance information depth, produce a pretty-looking image or give information about the time coordinate. All of these color schemes show brighter colors to indicate more localizations; to invert this meaning and show, for example, black localizations on a white background, use the "Invert colours" option.

The black and white colour scheme is the fastest colour code. It displays the equalized brightness directly on a scale ranging from black (no localizations) to white (maximum amount).

The black, red, yellow and white colour scheme offers a higher dynamic range by displaying the lowest third of the brightness values on a scale ranging from black to red, the middle third on a scale from red to yellow and the highest third on a scale from yellow to white. In total, about 760 brightness levels are displayed.

The constant colour colour scheme is similar to the black-and-white scheme, but uses an arbitray colour instead of white. You can use the "Select colour hue" and "Select saturation" to choose the colour.

The Vary hue by time coordinate colour scheme colour-codes each localization by its time coordinate, that is, by the number of the image it occured in. The code starts at the hue selected in "Select colour hue" and then follows the colour circle of the HSV colour model, that is, ranges from red over yellow, green, cyan, blue to violet. If multiple localizations contribute to the same pixel, hue and variance are interpreted as angle and radius on a plane, converted to cartesian coordinates, averaged arithmetically and converted back to hue and variance. For example, if red (hue 0, saturation 1) and yellow-green (hue 0.25, saturation 1) are present with amplitudes 1 and 4 on a pixel, they are converted to the points (1,0) and (0,1), averaged to (0.2,0.8) and transformed back to (hue 0.21, saturation 0.82), which is a slightly pale yellow. Observe that a point with localizations equally distributed over a long range of images tends to have a low saturation, that is, appear white.

Changing parameters after starting a job

If a Repeater service is available through a parent module, most image display parameters can be changed even after the job is started.

Configuration items

Color palette for display

Select one of the color schemes given in the section called “Color coding”.

Display dSTORM result image

If this checkbox is checked, the result image will be shown online in an image window. Disable for faster computation.

Invert colors

Invert the color display. Each color is inverted among the three primary color axes (red, green, blue), making red to cyan and black to white.

Resolution Enhancement

Set the aspect ratio of source (camera detector) pixels to target pixels. If set to 10, for example, the result image will be have 10 times more pixels in X direction and 10 times more pixels in Y direction.

Save image to

If a filename is given here, the final result image will be saved to the given file. The file extension determines the file type, and all common file formats (GIF, JPG, PNG, TIF) are supported.

Select color hue

Set the hue for constant color coding or the starting hue for variable hueing. Ranges from 0 (red) over 1/6 (yellow), 1/3 (green), 1/2 (cyan), 2/3 (blue) and 5/6 (violet) to 1 (red again).

Select saturation

Set the saturation for constant color coding. Ranges from 0 (no colors at all, only grey) to 1 (fully saturated colors).

Job status items

Extent of histogram normalization

Interactively change the intensity scale of the result image from a linear scale (value 0) to a contrast-enhanced image (value 1).

Resolution enhancement

Shows the current resolution enhancement (see job options table for a definition) and allows, if a Repeater service is present, to dynamically change it.

Save image

Save the image at the current state of computation to the file given by Save image to.

Save image to

Shows and changes the file name where the result image should be written to. The file extension determines the file type, and all common file formats (GIF, JPG, PNG, TIF) are supported.

Zoom level

Control element for zooming in (positive values) or out (negative values) in the displayed image.


Name

Count localizations

Synopsis

This output module outputs a count of all received localizations.

Job status items

Number of localizations found

Displays the total number of localizations propagated by the parent module.


Name

Memory Cache

Synopsis

This output module stores all its input localizations in the computer's main memory. It provides a Repeater service to its submodules, enabling features like interactive range selection in the image viewer, but also does not store the source images, preventing modules like Estimate PSF form from working as submodules of this module.


Name

Slice localization set — Split the input along the time axis to make a movie

Synopsis

This output module can automatically slice one input acquisition into a number of output acquisitions, each of which is processed seperately.

After determining the number of slices, this module makes one copy of its children output modules for each slice. Each copy will receive only the localizations in its slice. To keep memory usage low, the copies will be made on demand, when the first localization of a slice arrives, and will be closed as soon as the last localization of its slice has been processed.

Configuration items

File name pattern

Pattern for output file basenames. The output files (for example for images or localization files) will be generated by this pattern, where %i will be replaced with the slice number.

Size of one slice in images

Each slice will have as many images as specified here. Suppose slices in an acquisition 1000 images long start at 0, 300, 600 and 900 and this parameter is set to 500, there will be the four slices 0-499, 300-799, 600-999 and 900-999.

Start new slice every n images

One slice will be started at each image number divisible by this number. Suppose 1000 images are in an acquisition and this parameter is set to 300, slices will be started at images 0, 300, 600 and 900.


Name

Average images

This module does not process localizations, but rather averages all source images it receives to produce one averaged image. This image can be used to see how the specimen would have looked without dSTORM processing.

Note

This module will only work when source images are available.

Source images are unavailable for children, direct or indirect, of the Memory Cache module or if the input comes from the Localizations file file type.

Configuration items

Write averaged image to

Target file to write the gained average image to. The file extension determines the file type, and all common file formats (GIF, JPG, PNG, TIF) are supported.


Name

Display progress

Show a progress bar to indicate state of computation.

Job status items

Progress on this job

This progress bar shows the progress on the current job, that is, which percentage of the input images has been successfully computed.


Name

Estimate PSF form

Synopsis

Configuration items

3D widening common to all layers

Assume that the polynomial 3D widening parameters are the same in all layers, and fit them as common coordinates.

Allow astigmatism

Allow the X and Y focal planes to differ. If this option is unchecked, both planes are set to the same value and fitted together. Checking this option allows fitting data on an astigmatic 3D setup, e.g. with a cylindrical lens.

Assume circular PSF

Assume that the PSF has the same parameters in X and Y, and fit these parameters in common. Enhances estimation precision and stability at the cost of flexibility and thruthful replication of the PSF. This option applies to PSF width and 3D widening factors, but not to the focus plane coordinates, which are controlled by Allow astigmatism

Disjoint amplitude fit

When fitting multiple layers, fit intensities in all layers independently. This allows fitting a multi-plane data set without knowing the prefactors or making assumptions about fluorophore populations, at the cost of reduced precision and the inability to fit transmission coefficients.

Fit focus plane Z coordinate

When this option is checked, the Z position of the best-focused planes (i.e. the Z positions at which the X and Y PSF FWHMs are smallest, respectively) will be fitted to the data.

Fit PSF FWHM

When this option is checked, the width of the PSF will be fitted to the data. Otherwise, it will be treated as ground truth and not changed. If the PSF FWHM has been established reliably on other measurements, disabling this option enhances estimation stability and reliability.

Fit transmission factors

When this option is checked, the fluorophore transmission factors are fitted to the data. This allows for straightforward multi-color calibration on live data.

Fit window radius

Include all pixels into the fit window that are closer than this radius to the selected spot. This is currently an L1 distance.

Laempi fit for positions

When fitting multiple layers, fit fluorophore positions in all layers independently. This can mitigate an imprecise plane alignment at the cost of reduced precision.

Manually select good spots

If this option is checked, the selection window (as described above) is shown. Otherwise, all eligible spots are used in estimation.

Number of spots used in estimation

This option configures the total number of spots that are used to fit the PSF form. Localizations are scanned and presented until this number of spots is selected.

Number of spots used per image

This option configures the maximum number of spots that are eligible for estimation in each source image. The spots with the highest amplitude are selected, the rest is discarded and not shown in the selection window. If this number is exceeded, the rest of the spots in an image is not displayed. A fractional number can be entered in this field, translating to one spot being picked in each n-th frame. For example, a value of 0.25 selects one spot every fourth frame.

PSF FWHM common to all layers

Assume that the PSF FWHM is the same in all layers, and fit it as a common coordinate. This option is related, but orthogonal to Assume circular PSF.

Use MLE to fit PSF form

Optimize for maximum likelihood (ML) of the data with the optimized model instead of minimizing the squared deviations. You should use the same distance model for fitting the PSF as you configured in the engine.

Z position is ground truth

Treat the fluorophore's Z position as ground truth, i.e. do not fit it. This option is useful when calibrating polynomial 3D and in conjunction with setting a ground-truth Z position in the Expression filter output.


Name

Look up 3D via sigma difference

Synopsis

This output sets the Z position on its input localizations by computing the difference between the X and Y PSF widths and looking up the difference in the provided Section 7.7, “Z calibration file”. Thereby, a Z coordinate can be estimated on data that have been fitted with free PSF widths. For more information, see [Henriques2010].

It is preferable to provide the Section 7.7, “Z calibration file” directly to the fitting module by choosing the Interpolated 3D as 3D PSF model. Thereby, a degree of fitting freedom is avoided and precision is enhanced.

Configuration items

Calibration file

Input file name for the calibration table in which the difference is looked up. The format is described in Section 7.7, “Z calibration file”.


Name

3D PSF width calibration table

Synopsis

This output stores a Section 7.7, “Z calibration file” for the relationship between the Z position and the PSF widths. It assumes that the Z position and PSF widths are set on its input localizations, orders the input localizations, smoothes them with cubic B splines and stores the values at the control points in the calibration output file.

Configuration items

Calibration output file

Output file name for calibration table. The format is described in Section 7.7, “Z calibration file”.

Number of B spline breakpoints

Number of breakpoints to use for cubic B-spline interpolation. The number of breakpoints determines the number of cubic pieces used to approximate the measured PSF width curve. This number can be viewed as the adaptibility of the sigma curve to the measured PSF widths.


Name

Expression filter

This output allows filtering on and changing individual localization fields. It is distributed into two parts: The simple input fields for minimum localization strength, linear drift correction and maximum two kernel improvement give easy access to often-needed manipulations, while the more complex test-based expressions give full access to all localization fields.

The number of Value to assign to and Expression to assign from fields in this output is variable and can be changed with the Number of expressions field. These fields form pairs called "actions", and all of the actions take effect. The order of application is top-to-bottom.

Configuration items

Expression to assign from

This text field gives an arithmetic expression for the value of the action. An expression consists of variables explained in Value to assign to and constants, linked by the usual arithmetic operators. Constants are given as numbers with units, which can be m, ADC or fr for meters, camera A/D counts of frames, respectively, and be prefixed with the usual SI prefixes (with u for μ). The available operators are given in Table 5.4, “Operators in expressions”. Examples for complete actions are listed in Table 5.5, “Example actions”

Linear drift correction

If this field is enabled, all localizations are shifted in space by an amount proportional to the time coordinate of their detection. This is used to implement linear drift correction.

Maximum two kernel improvement

If this field is checked, all localizations with a two-kernel improvement (quotient of residues with two kernels and residues with one kernel) greater than the given value are discarded. This value is used for artifact suppression and is only available when Compute two kernel improvement has been checked.

Minimum localization strength

If this field is enabled, all localizations with a strength lower than its value are discarded and not displayed or stored in the suboutputs. The localization strength denotes the total signal detected in the PSF, i.e. the integral of the point spread function.

Value to assign to

This option box determines the effect of the action. It can either take the value of Filter, in which case Expression to assign from must give a boolean result, or a variable name, in which case Expression to assign from must give a numerical result which matching dimensions. The possible variable names are formed by applying the modifiers from Table 5.2, “Variable name modifiers for expressions” to Table 5.1, “Variable base names for expressions”, with examples in Table 5.3, “Variable example names for expressions”.

Table 5.1. Variable base names for expressions

Variable base name Dimension Type Meaning
pos m 3D vector Position in sample space
amp ADC scalar Intensity of emission
frame fr scalar Time of emission
psffwhm m 2D vector PSF model's full width at half maximum
fishy dimensionless scalar Two-kernel improvement
chisq dimensionless scalar Fit residues. For least-squares fitting, this value gives the sum of squared deviations between PSF model and data in photons squared. For MLE fitting, this value gives the total likelihood score. In both cases, the value is not normed in any way and unlikely to be comparable between measurements.
fluo dimensionless scalar Fluorophore type (0 for first fluorophore, 1 for second, etc.)
bg ADC scalar Local background intensity

Table 5.2. Variable name modifiers for expressions

Modifier Meaning
x … in X dimension
y … in Y dimension
z … in Z dimension
sigma uncertainty of …
min lower bound of …
max upper bound of …

Table 5.3. Variable example names for expressions

Example variable name Meaning
posx Localization's X coordinate
posminy Highest possible Y localization coordinate
fluo Fluorophore type

Table 5.4. Operators in expressions

Operator Result type Meaning
(n1) numerical grouping of numerical expressions
n1^n2 numerical exponentiation
n1 * n2, n1 / n2 numerical multiplication, division
n1 + n2, n1 - n2 numerical addition, subtraction
(b1) ? n1 : n2 numerical choice operator (if b1 is true, use n1, else n2
n1 == n2, n1 != n2, n1 = n2, n1 >= n2, n1 <= n2, n1 > n2, n1 < n2 boolean comparison for equality, inequality, equality (same as ==), greater-equality, less-equality, greater, less
!b1 boolean negation
b1 && b2 boolean conjunction (and)
b1 || b2 boolean disjunction (or)

Table 5.5. Example actions

Value to assign to Expression to assign from Intention
Filter fluo = 0 Only show localizations from the first fluorophore
Filter posx > 1 um Only show localizations right of a line at 1 μm
Filter amp < 5 kADC Discard emissions with intensities above 5000 counts
Filter posx > 2300 nm && posx < 2800 nm && posy > 1800 nm && posy < 2200 nm && frame < 500 fr Limit region of interest to a single bead early in the acquisition to calibrate 3D
posz 8 nm/fr * frame Set a Z ground truth raising 8 nanometre per frame
amp (fluo == 0) ? 1.5 * amp : 1 * amp Make all localizations from the first fluorophore type more intense by a half

Chapter 6. Common error messages

Table of Contents

No output selected

Before starting a computation job, each filter output module must have at least one output assigned. Filter outputs are those that can have more outputs as children; in other terms, output modules that have the "Add output" control element.

You can fix this error by assigning an output to each filter output. If you just want to test something and are concerned about file overwriting, choose a simple output like Count localizations.

Chapter 7. Fundamental concepts

>

7.1. Input channels

Foobar

7.2. dSTORM engine

The dSTORM engine is the collective term for the core of the rapidSTORM software that is not part of the input or output drivers. The dSTORM engine is responsible for converting a vector of input images into a set of localizations, performing the steps of spot detection, spot fitting and spot judging defined in [WolterDiplomarbeit]. While the exact algorithms are out of the scope of this manual, a short summary of the engine operation can be given:

First, the input images are smoothed to reduce the amount of noise present. The local maximums of these noise-reduced images are located and stored as spot candidates, that is, positions where spot positions are likely to be present. The candidates are sorted with the strongest values first in the list and then nonlinearly fitted with the PSF model in the order established by that sorting. Once three successive candidates have failed to be fitted as localizations, the fitting process for the image is aborted.

7.3. Localization

A localization denotes the position (space and time) and the strength of a suspected fluorophore emission. A localization denotes only a suspected position because the high noise conditions in photoswitching micrsocopy introduce false localizations, either through background noise or multiple close-by emitters.

Localization coordinates are not given on a lattice as pixels are, but are rather subpixel-accurate. The accuracy is mostly given by the emission strength and the background noise as described by [Thompson2002].

7.4. Fluorophore type

7.5. 3D fitting

rapidSTORM can fit both astigmatic and biplane 3D data by introducing an explicit Z parameter into the point spread function. It is assumed that the 2D Gaussian model describes the PSF and that the widths of the PSF in X and Y direction are functions of the emitter's Z coordinate. Two different models are supported for this function, a set of piecewise cubic functions or a single quartic function (polynomial model).

7.6. Piecewise cubic model

The points in a Section 7.7, “Z calibration file” are interpolated with a cubic B-spline. This approach is described in depth in [Proppert2014]. A short overview over the theoretical background is available from Sven Propperts description included with this package.

7.7. Z calibration file

A Z calibration file is a plain text file with three whitespace-separated columns. The first column gives an emitter's Z coordinate in nanometres, and the second and third columns give the standard deviation of a Gaussian describing the PSF for an emitter at the given Z coordinate. They describe the X and Y dimension of the camera, respectively, and are given in micrometers.

The range of the Z calibration file (lowest and highest Z coordinate) gives the working depth of the approximation.

7.8. Polynomial model

rapidSTORM can fit both astigmatic and biplane 3D data by introducing an explicit Z parameter into the point spread function. The Z parameter modifies the width parameters of the PSF according to Equation 7.1, “Polynomial 3D PSF Width”. In other terms, we model the variance of the PSF in the lateral directions (σx) as a polynom of the axial offset from the best-focused plane. The necessary parameters are the axial positions of the best-focused planes (zx and zy), the standard deviation of the PSF in the best-focused plane (σ0,x and σ0,y) and the effective focus depths for the polynomial terms (Δσi,x and Δσi,y). The point spread function model has been adapted from [Huang2008] and expanded with the natural linear term. However, rapidSTORM improves upon it by fitting the Z coordinate directly instead of using the complicated variance-space distance determination presented in the paper.

Equation 7.1. Polynomial 3D PSF Width


These parameters are normally determined externally from calibration samples. For astigmatic imaging, the best-focused planes zx and zy are set to different values. While the distance between the planes is crucially important for 3D localization, the absolute values and relative sign of the best-focused plane coordinates determine the direction and offset of the Z axis in the results. For biplane imaging, zx and zy are set equal to each other, but take different values for each plane.

Polynomial 3D configuration items

Widening slopes
Δσi,jΔσi,j

Traditionally, rapidSTORM supported two PSF models called "Parabolic 3D" and "Holtzer 3D". Both of these models are subsets of to the polynomial model, and their parameters can be converted. For the Holtzer model, only the second derivative needs to be given as

, where ω denotes the Holtzer widening constant. For the parabolic model, the second and fourth derivatives must be given as

, where ω denotes the parabolic widening constant.

7.9. Repeater

A repeater is any output module that stores all received localizations in memory and can repeat them if necessary. While this costs, naturally, roughly 32 bytes of memory per localization, it allows changing many processing parameters even after computation has started.

However, repeaters are not able to store the input images used in computation because doing so would quickly exhaust the available memory. Therefore, output modules that need access to source images may not be used as children of repeater modules.

7.10. PSF model

The point spread function (PSF) is modeled for rapidSTORM purposes as a two-dimensional Gaussian function added to a background signal. This function has the parameters amplitude, background signal, center position and covariance matrix. We can assume the covariance matrix to be constant for any acquisition, and so only the amplitude, the background signal and the center position are fitted by the engine, while the covariance matrix is estimated iteratively by a second fitting process or given a-priori.

While this Gaussian model does not match the point spread functions of real systems exactly, it is a good approximation with easily computed derivatives. Studies such as Thomann et al. have shown that the approximation is good enough for practical purposes.

7.11. Two-kernel analysis

When (FOO) indicated a likely double emission, this hypothesis is tested by fitting a model consisting of the sum of two Gaussian functions with a common background to the data. This is called two-kernel analysis. When two-kernel analysis produces a two-kernel fit with two nonnegligible kernels and with significantly smaller residues than the normal one-kernel fit, the hypothesis of a double emission is deemed confirmed.

7.12. Linear drift correction

Instabilities in the experimental setup can, despite all experimental effort, lead to a slow, creeping shift (called drift) of the specimen's image on the camera detector. In this case, the quality of the resulting image is greatly degraded because structures appear smeared in the direction of the drift.

In most cases, the drift is small and approximately linear over the course of the acquisition. Such a drift can be corrected by substracting the drift velocity times the time elapsed since acquisition start from each image.

A convenient way to fine-tune drift correction is to add a time-hued image display as a child of the localization filter and optimize the settings for a mostly white or, at least, largely color-uncorrelated image.

Bibliography

[WolterDiplomarbeit] An accurate and efficient algorithm for real-time localisation of photoswitchable fluorophores. Steve Wolter. Bielefeld University. 2009-mar.

[Wolter2010] Real-Time Computation of Subdiffraction-Resolution Fluorescence Images. Steve Wolter. Mark Schüttpelz. Marko Tscherepanow. Sebastian van Linde. Mike Heilemann. Markus Sauer. 2010. j-microsc. 2010. 237. 1. 12-22.

[Thompson2002] Precise Nanometer Localization Analysis for Individual Fluorescent Probes. Russell E Thompson. Daniel R Larson. Watt W Webb. 2002. biophys-j. http://www.biophysj.org/cgi/content/abstract/82/5/2775. 2002. 82. 5. 2775-2783.

[Huang2008] Three-Dimensional Super-Resolution Imaging by Stochastic Optical Reconstruction Microscopy. Bo Huang. Wenqin Wang. Mark Bates. Xiaowei Zhuang. 2008-February-08. sci. 1095-9203. doi:10.1126/science.1153529http://dx.doi.org/10.1126/science.1153529. 2008-February-8. 319. 5864. 810-813.

[Henriques2010] QuickPALM. 3D real-time photoactivation nanoscopy image processing in ImageJ. Ricardo Henriques. Mickael Lelek. Eugenio F Fornasiero. Flavia Valtorta. Christophe Zimmer. Musa M Mhlanga. 2010-may-01. nat-methods. Nature Publishing Group. 1548-7091. doi:10.1038/nmeth0510-339http://dx.doi.org/10.1038/nmeth0510-339. 2010-may-01. 7. 5. 339-340.

[Aufmkolk2012] Hochauflösende Mehrfarben-Fluoeszenzmikroskopie. Sarah Aufmkolk. Julius-Maximilians-Universität Würzburg. 2012-mar.

[Loeschberger2012] Super-resolution imaging visualizes the eightfold symmetry of gp210 proteins around the nuclear pore complex and resolves the central channel with nanometer resolution. Anna Löschberger. Sebastian van de Linde. Marie-Christine Dabauvalle. Bernd Rieger. Mike Heilemann. Georg Krohne. Markus Sauer. 2012. Journal of Cell Science. doi:10.1242/jcs.098822http://jcs.biologists.org/content/125/3/570.abstract. 2012. 125. 3. 570-575.

[Proppert2014] Cubic B-spline calibration for 3D-Superresolution measurements. Sven Proppert. Steve Wolter. Thorge Holm. Teresa Klein. Sebastian van de Linde. Markus Sauer. 2014. opt-express. OSA. 2014.

[Recipes] Numerical Recipes in C . The Art of Scientific Computing. William H Press. Brian P Flannery. Saul A Teukolsky. William T Vetterling. 1992-October. Cambridge University Press. second. 0521431085.