suresim manual - heidelberg university · suresim (super resolution simulation) is an open-source...
Post on 21-Jan-2021
8 Views
Preview:
TRANSCRIPT
1
SuReSim manual
1. ABOUT........................................................................................................................................... 2
2. INSTALLATION ........................................................................................................................... 2
3. COMPATIBILITY ........................................................................................................................ 2
4. SURESIM WORKFLOWS ........................................................................................................... 2
a. Workflow 1 .............................................................................................................................................. 3
b. Workflow 2 .............................................................................................................................................. 4
5. SURESIM TUTORIAL ................................................................................................................. 5
a. Import Data ............................................................................................................................................. 5
b. Parameter Selection ................................................................................................................................ 6
c. Direct Simulation ................................................................................................................................... 11
d. Tiff Stack Creation .................................................................................................................................. 15
e. Editor ..................................................................................................................................................... 17
f. Evaluation Of Ground Truth Data ........................................................................................................... 17
6. DATA FORMATS ...................................................................................................................... 20
a. WIMP ..................................................................................................................................................... 20
b. NFF ........................................................................................................................................................ 20
c. PLY ......................................................................................................................................................... 21
d. Epitope Data .......................................................................................................................................... 21
e. Point List Data ........................................................................................................................................ 21
f. Calibration File ....................................................................................................................................... 22
2
1. About SuReSim (Super Resolution Simulation) is an open-source simulation software for Single Molecule Localization Microscopy (SMLM). The workflow of the SuReSim algorithm starts from a ground truth structure and lets the user choose to either directly simulate 3D localizations or to create simulated *.tiff-stacks that the user can analyze with any given SMLM reconstruction software.
A 3D structure of any geometry, either taken from electron microscopy, designed de-novo from assumptions or known structural facts, is fluorophore-labeled in silico. A defined set of parameters is used to calculate and visualize the 3D localizations of the corresponding labels.
The software package is accompanied with a library of model structures that can be imported and simulated.
2. Installation SuReSim is written in Java and licensed under the terms of the GNU GPLv3 license as a standalone
software package.
To execute the runnable JAR file Java Runtime Environment 8 (JRE) is required. The current version of
the JRE can be downloaded for free from oracle.com.
For Mac users the latest version of Java did not work reliably. We recommend version 1.8.51 which
worked perfectly well on all our test setups.
To install SuReSim download the latest version and place it in any directory you like. Be sure to copy
the folder SuReSim_lib as well.
3. Compatibility SuReSim has been tested on
Windows 7 (64-bit), Windows 8 (64-bit), Windows 10
Ubuntu Linux (64-bit)
MacOS X 10.7.5, MacOS X 10.8.5, MacOS X 10.10, MacOS X 10.11
4. SuReSim Workflows There are two basic workflows that can be further adapted by the user. Workflow 1 shows the
fastest and easiest way to simulate 2D - and 3D -SMLM data. This workflow allows to import a
ground truth model, choose simulation parameters and to directly simulate the SMLM image. This
simulated SMLM data can be exported and further processed.
3
a. Workflow 1
Workflow 1 is a best-case scenario workflow that works with a minimal set of the most important
imaging parameters. This is especially helpful for users who want to evaluate quickly whether a given
structure can be resolved in principal.
Workflow 2 shows a more laborious simulation procedure for the advanced user. It is more time-
consuming but also yields more realistic simulations. A raw data tiff stack (either 2D or 3D) is
exported and needs to be reconstructed with any given SMLM reconstruction software. These
reconstructed data can be again imported and compared to the ground truth model. Furthermore,
statistical tools allow to compare ground truth data to localizations quantitatively.
Workflow 2 takes all mistakes into account that are due to dense photoswitching events and
imperfect detection during reconstruction. If Workflow 1 yields a positive result we recommend to
test Workflow 2 in order to analyze how a give structure might look like under realistic conditions.
Workflow 2 is also helpful in evaluating the performance of SMLM analysis algorithms.
Import Ground Truth Model
Choose Simulation Parameters
Direct Three-Dimensional Simulation of Localisations
Export Localisation File and Rendered Projection Images
Postprocessing of Localisations with further Analysis Tools
4
b. Workflow 2
Import Ground Truth Structure
Choose Simulation Parameters
Create Raw Data Tiff Stack
Analyse with SMLM reconstruction software
Import localisations and compare to ground truth
and/or postprocessing of data
5
5. SuReSim Tutorial SuReSim’s user interface consists of a visualization surface on the left and a settings panel on the
right. The following tutorial illustrates how SuReSim can be used to simulate the expected outcome
of Super Resolution Light Microscopy experiments based on imported structural data.
This picture shows the GUI (Graphical User Interface) of SuReSim without any loaded files or set
parameters.
a. Import Data The user can either import one of the predefined example data sets by choosing it from the example-
drop-down-list
or
import data sets from one of the following data formats.
Filamentous data: WIMP
Surface data: PLY and NFF
Specific epitope locations: EPI (SuReSim specific format)
More detailed information can be found in the section Data Formats.
Both WIMP and NFF files can be extracted from the electron tomography reconstruction
software suite IMOD.
6
or
import previously saved project files.
or
import lists with localizations previously created by simulation
b. Parameter Selection
Detailed Description of Simulation Parameters
Basic Settings I
Epitope Density:
This parameter describes the number of available binding sites for the assumed label. For
filamentous structures it is given in epitopes per nanometer, for surfaces in epitopes per square
nanometer.
Radius of Filaments:
This parameter only applies for filamentous structures. It describes which distance the surface of the
filament has to the given center line. Epitopes are assumed to be placed on this cylindrical surface
around the given line. Regardless of the chosen radius the epitope number is only based on the
epitope density given in epitopes per nanometer.
7
Labeling Efficiency:
Labeling efficiency describes which part of all available epitopes is labeled. It may take values from
0% to 100%. Whether a label binds or not is individually decided for each epitope. This leads to slight
variations in the number of labeled epitopes for each calculation.
On-Off Duty cycle:
This parameter determines the number of blinking events per frame. A ratio of 1 over 2000 means on
average one blinking event per fluorophore per 2000 frames.
Recorded Frames:
This parameter described the number of simulated frames.
Basic Settings II
Binding Angle:
For filamentous structures the binding angle describes the angle between the straight part of the
filament and the label. For 90 degree the label points away from the line, for 0 degree it is parallel to
the line.
For surface data a binding angle of 90 degree means that the label is parallel to the normal vector of
the surface.
For epitope data 0 degree means the orientation of the label is exactly as specified in the epitope
data set by column 4 to 6, any other angle leads to deviation from this specified orientation.
Sigma of Angular Distribution:
Variations of the binding angle can be simulated as well, the sigma of angular distribution describes
the standard deviation of Gaussian distribution which is centered at the given binding angle and used
to determine draw the used binding angle for each label individually. A sigma of 0 leads to all labels
exactly binding under the binding angle. Large values for the sigma (e.g. several thousands) can be
used to get completely randomly distributed angles.
Label Epitope Distance:
This parameter determines the distance of the simulated fluorophore from the epitope.
Fluorophores Per Label:
Antibodies might be labeled with multiple fluorophores per label. The density of the label can be
varied. For any value larger than 1 a Poisson distribution is used to determine the number of
fluorophores for each antibody. The fluorophores are distributed based on a Gaussian distribution
around the end of the label (σ=1.5 nm).
Bleaching:
A bleach constant can be set to determine the mean number of frames until a fluorophore bleaches.
The constant can be calculated by dividing one by the mean frame number.
Background Label:
This parameter determines the number of unspecific bound labels. Higher values lead to more
unspecific binding. The unspecific labels are randomly distributed over the whole box containing the
imported models.
8
Reproducible Output:
The seed of the random number generator can be fixed resulting in the exactly same results for each
calculation with the same parameters. This includes number of blinking events, position, etc.
Direct Simulation
Localization Precision:
This parameter applies only for the direct simulation. Individual localization precisions can be set for
xy- and z-dimension. This parameter is used as standard deviation of a Gaussian distribution centered
at the fluorophore position. From this Gaussian distribution the coordinates for each blinking event
are drawn.
Constant Localization Precision:
If this checkbox is unchecked the simulated photon count for each blinking event is used to alter the
mean localization error. Bright blinking events are simulated to have a smaller localization error, dark
blinking events will be simulated with a larger error.
The localization error is assumed to be proportional to the inverse square root of the photon
number.
If it is checked the same localization precision will be used for all blinking events.
Detection Efficiency:
This parameter determines how many of the simulated blinking events will be kept. In a real
experiment there might be factors like inhomogeneous background which decreases the number of
fitted PSFs.
Pixel Size In Nm:
For the direct simulation it is possible to export rendered 2D projections. The pixelsize for this images
can be set here.
Standard Deviation For Rendering:
In the rendering step each localization is represented as a 2D Gaussian with a standard deviation
based on this parameter.
Alternative Colorcode:
If this option is checked a color gradient from orange to blue is used, instead of the gradient from
blue to green to red, to indicate z-information in the rendered projections.
Tiff Stack Creation
Mean Photon Output:
Intensities of blinking events are simulated based on an exponential model. With the mean photon
output parameter the average number of photons per blinking event can be set.
For the tiff stack creation the actual mean photon number might be larger if the minimal photon
count is set to values so low that the PSF was not fitted by the fitting algorithm.
Minimal Photon Count:
This parameter sets the minimal intensity assigned to the blinking events. It might not be larger than
the mean photon count, otherwise value will be ignored.
9
Mean Blinking Duration:
The mean blinking duration defines the time a blinking event lasts on average. Longer values increase
the probability that the blinking event will be spread over multiple consecutive frames.
Pixel to Nm Ratio:
Pixel size in nanometers for the exported tiff stack.
Frame Rate:
The frame rate sets the number of simulated frames per second. It is the inverse of the exposure
time. This parameter only affects the tiff stack simulation.
Dead Time:
The dead time describes the time the camera is insensitive to incoming photons. The inverse of the
frame rate is equal to the sum of dead time and exposure time. The exposure time cannot be set
directly. The dead time is simulated after each frame. On average, longer dead times lead to less
photons per frame since a longer part of each blinking event falls to the dead time.
Readout Noise:
Readout noise occurs when transferring charge to a common readout structure. The readout noise is
given in digital numbers. All camera relevant parameters should be found in the performance data
sheet of the respective camera.
Constant Offset:
A constant offset is applied in the last step of the tiff stack creation and can be specified by the user.
EM Gain:
Photon electrons are multiplied with the EM gain value. Higher EM gain values will reduce the
influence of readout noise.
Quantum Efficiency:
The simulated photon number for each blinking event is multiplied with the quantum efficiency
before simulation.
Electrons per Digital Number:
This values describes the conversion factor from electrons to digital numbers.
Window Size PSF Rendering:
The rectangle in which the PSF is sampled can be set here. Larger values lead to more precise results
but decrease the performance, especially for large wavelengths.
2D/ 3D simulations:
This option lets the user switch the simulation mode between the 2D and the 3D (astigmatism)
simulation mode.
Outer Rim:
To avoid cropped PSFs a rim of background pixels is put around the simulated tiff stack. This
parameter influences the width of the rim.
10
Numerical Aperture:
This value is used for the 2D PSF model (Gaussian PSF model) and describes the numerical aperture
of the simulated objective.
Wavelength:
This value is used for the 2D PSF model and describes the wavelength of the simulated fluorophore.
Larger wavelengths lead to wider PSFs in the tiff stack.
Focus/ Defocus:
The position of the focal plane in nanometer is set by the focus parameter. PSFs will have the
smallest width in the focal plane (2D PSF simulation only).
The defocus parameter describes the plane in which the PSF width will be doubled compared to the
focal plane.
Calibration File:
For 3D PSF simulation a custom calibration file can be imported. The calibration file contains the
information of the width in the x and y dimension of the Gaussian model for different z values (See
section “Data Formats”.
Ensure Single PSFs:
If this checkbox is checked the exported tiff stack will have no overlapping PSFs. This is ensured by
checking all PSFs for other PSFs within 1500 nm and in the same frame. If another near PSF is found
its frame number is increased to an empty frame.
Distribute PSFs:
With this option checked, the blinking events may contribute to several consecutive frames. If it is
not checked all photons are rendered in one frame. This option is useful to either get realistic data to
test merging algorithms or to get a defined photon number.
Visualization Parameters
Basic Settings
Point Size:
Point size affects the size of the rendered SMLM Points in the 3D viewer. The width for the rendered
2D projections which can be exported is not affected by this parameter.
Line Width:
Line width determines the width of the lines for labels and filamentous structures in the 3D viewer.
Show STORM Points/ Labels/ EM:
For each data set each component can be individually turned on and off. The color of each
component can be set individually by clicking on the colored box.
Fix Viewpoint:
After importing a new data set or calculation the viewpoint is automatically adjusted to fit everything
on the screen. If this button is pressed the current viewpoint is preserved.
11
Projections:
Pressing one of these buttons will set the current viewpoint to the chosen perspective. This option
also affects which projection will be saved when direct simulation results are exported.
Advanced Settings
Rendering Quality:
Rendering quality sets the rendering mode for the 3D viewer. Higher quality includes round points
and transparent surfaces.
Cropping:
The field of view can be cropped to only display a small region of the simulated data. The values for
the cropped field of view also affect which part of the data is rendered to 2D projections and in the
tiff stack.
To keep the set borders even when calculating or importing another data set, the “Keep Borders”
checkbox can be selected.
c. Direct Simulation After importing the ground truth data various parameters can be set. Most important are epitope
density and in the case of filamentous structure the radius of the given structure. For the other
parameters the default settings should be sufficient for a quick start.
If an epitope data set is imported no model is shown directly after the import. Only labels and SMLM
points are displayed after calculation.
12
After pressing the “Calculate” and “Visualize” button the simulated localizations along with the
simulated label and the ground truth structure can be visualized.
If multiple data sets are imported the current data set is chosen by clicking its name.
Multiple Structures
Additional structures can be imported.
13
All structures can be individually visualized at once and individual colores can be set for each data set
and component.
Also each component can be individually turned on and off.
14
Export
For all simulated localisations a coordinate file, rendered images and a setting file can be saved using
the “Export” button.
The individual rendered images can be overlayed to get a realistic impression of the expected
outcome of a super-resolution meassurement on the selected structures.
15
d. Tiff Stack Creation Instead of the direct simulation it is also possible to create tiff stacks. This tiff stacks are very close to
raw SMLM data. Different parameters like noise or EM gain can be set.
There are two different PSF models to simulate 2D SMLM or 3D SMLM using the astigmatism
approach.
After the import of any supported structure the appropriate parameters form the Basic Settings I and
II tab can be chosen. Additionally the parameters from the create tiff-stack branch might be altered.
For a quick start the default parameters will be sufficient.
16
The user can choose between a 2D and 3D PSF model.
After that the tiff stack can easily exported. A text file containing all ground truth data is exported as
well.
There are two options available for the tiff stack export. Ensure single PSF will lead to tiff stacks with
no overlapping PSF by shifting all PSF which might be overlapping to larger frames. Distribute PSF
leads to realistically distribution of blinking events over multiple frames, depending on the actual
blinking duration of the blinking event.
17
e. Editor SuReSim includes an editor to create 2D WIMP files by drawing lines on imported images.
First an image is loaded on which lines can be drawn. After completion of a single line object, which
might consist of many points the next object can be drawn by adding the completed line using the
add button.
Using the “+” and “-“ key the image can be zoomed in and out.
There is a toggle button to choose between draw and scroll mode.
At the end the nanometer to pixel ratio must be set before saving.
f. Evaluation Of Ground Truth Data SuReSim includes a tool to easily compare the ground truth data with the fitting result of the created
tiff stack.
The ground truth and the reconstructed localization list can be imported and compared both visually
and statistically. The output of the reconstruction software must be converted to the point list data
format described later.
Visualizing Results
To directly visualize both reconstructed localizations and ground truth both files can be imported to
the 3D viewer by either file import or drag-and-drop.
18
Two data sets will be displayed in the upper right corner and individual colors for the localizations
can be assigned.
Calculating Statistical Measures
For the comparison of ground truth data and the reconstructed tiff stack a tolerance must be
defined. These tolerances correspond to the main axis of an ellipse.
For the comparison the program considers the nearest localization from the test set to each ground
truth data localization as a true positive match if it lies within an ellipse with specified tolerances.
Different measures such as the Jaccard index, f-score or the root mean square error are calculated
and displayed.
Since the coordinate system of the reconstruction algorithm might be shifted by half a pixel size, this
can be corrected using the shift x and shift y parameter. To detect shift there are two easy ways. One
option is to set large tolerances and look at the delta x and delta y output which indicates an
absolute shift between ground truth and test set. The other option is to import both data sets into
the 3D viewer and see if there is a general shift as described above.
19
20
6. Data Formats
a. WIMP In the Wimp data format lines are represented as objects containing an arbitrary number of points.
All this points of one object will be connected. For multiple lines multiple objects must be defined.
Example File:
b. NFF http://paulbourke.net/dataformats/nff/nff2.html
Only one object per file is supported, all information beside the vertex position and polygon
information is ignored.
21
c. PLY https://en.wikipedia.org/wiki/PLY_(file_format)
Only triangles are supported.
d. Epitope Data This data format can be used to create epitopes with well-defined positions and label orientations.
For example to model the epitopes of the nuclear pore complex.
Example File:
First three columns contain spatial information about the epitopes, the last three rows determine the
orientation of the label. Only the orientation but not the label length is determined from this file, the
label length is set in the GUI.
e. Point List Data The output of the direct simulation as well as the ground truth data created by the tiff stack export
can be imported directly into SuReSim. This file format uses space as delimiter. The output of
rapidSTORM in the following order can also be imported (x, y, z, frame, intensity).
The header is important for SuReSim to automatically recognize the file format.
Example File:
22
f. Calibration File The calibration file for the 3D rendering consists of three columns. The first column specifies the focal
position in nanometers. Second and third column specify the PSF width in x and y direction in
micrometers.
top related