1. ABOUT INSTALLATION COMPATIBILITY SURESIM WORKFLOWS a. Workflow b. Workflow SURESIM TUTORIAL...

Transcription

1 SuReSim manual 1. ABOUT INSTALLATION COMPATIBILITY SURESIM WORKFLOWS... 2 a. Workflow b. Workflow SURESIM TUTORIAL... 5 a. Import Data... 5 b. Parameter Selection... 6 c. Direct Simulation d. Tiff Stack Creation e. Editor f. Evaluation Of Ground Truth Data DATA FORMATS a. WIMP b. NFF c. PLY d. Epitope Data e. Point List Data f. Calibration File

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 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 , MacOS X , MacOS X 10.10, MacOS X 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. 2

3 a. Workflow 1 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 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 timeconsuming 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. 3

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 4

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 exampledrop-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. 5

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. 6

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. 7

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. 8

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. 9

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. 10

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. 11

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. 12

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. 13

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. 14

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. 15

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. 16

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. 17

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. 18

19 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 Only one object per file is supported, all information beside the vertex position and polygon information is ignored. 20

21 c. PLY 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: 21

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. 22