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.