Step 0. Image acquisition and program setup
Acquire the raw data, calibration scan, control point scan, and dark offset images described in Equipment. Ensure that you have saved a sequence log file for the calibration and control point scans.
Step 1. Two-color DHPSF calibrations
This section will outline the steps to perform two-color calibrations of the DHPSF either with beads or with a NHA.
1.1 Open an instance of the Easy-DHPSF GUI by entering ‘easy_dhpsf’ in the MATLAB command line.
1.2 Before running any of the modules, set the conversion gain and pixel size of the detector using the fields under ‘Setup.’ Note that changing these parameters after processing the data does not retroactively change the calculated results (Figure 2).
1.3 Under Setup > Channel, select a channel ‘G’ for green or ‘R’ for red.
1.4 Under ‘Calibrate DHPSF’, click ‘Run.’
1.5 Follow the prompts if you would like to automatically save the partly processed dataset after this module.
1.6 Open the calibration images file, the dark offset image file matching the calibration, and the sequence log file (either .mat or .dat) for the calibration. The program will prompt you for these files via dialog boxes.
1.7 Set the EM gain used during the acquisition of the calibration images, whether you would like use wavelet subtraction, NHA holes if using NHA and whether the holes are at 45 degrees, whether the DHPSF’s two lobes are horizontal when in focus, and the box radius for fitting.
1.8 Select a region of interest to analyze. Follow 1.8.1 if using beads on a coverslip, or 1.8.2 if using an NHA.
1.8.1 Select a region of interest (ROI) containing at least one bright fluorescent object by adjusting the box and double-clicking inside it. Even though the calibration bead may be isolated, it is helpful to select an entire wide-field excitation region so that the background fluorescence can be estimated accurately. Select fluorescent objects by clicking the center of each DHPSF (Figure 3).
1.8.2 Select an ROI by adjusting the box and double-clicking inside it. Select 4 holes that form a large square, then select fiducials to outline the edge of your field of view (Figure 4). Make sure to try to click the center of each DHPSF, halfway between the two lobes. Hit enter when finished DHPSFs.
1.9 Each frame of raw data, as well as the accompanying double Gaussian fit, is displayed as it is processed.
1.10 After processing, an output of calibration information will be generated in the ‘calibration [DateAndTime]’ folder. Inspect this for each bead to ensure that the angle vs. z position curve is roughly linear, and that the variation of angle measurements in each step is not unreasonably high (error bars in upper-left plot) (see Figure 5 below). Additional information from the calibration, such as the observed shift in x and y position with axial position or wobble, may be useful when aligning the DH phase mask.
1.11 Select the most reliable calibration bead in the Easy-DHPSF main window using the drop-down menu. The calibration information and templates generated from this bead will be used in all later processing steps.
1.12 Go back to step 1.2 and repeat the calibration process for the other color channel. When done, click the save icon (located on the top left of the window) to save your calibrations. You can open this calibration file for use in the subsequent steps.
Step 2. Single-molecule detection calibration for SMACM data
In this module, the templates generated from the calibration subroutine are used to generate a large array of matches to the raw SMACM image data. This step serves to assess what value of phase correlation is typical for a good match to an SM image. After this step, the user will define a threshold for each template such that only DHPSF images of reasonable quality will be analyzed with the double-Gaussian fitting algorithm.
2.1 Under Setup > Channel, select a channel ‘G’ for green or ‘R’ for red.
2.2 Click the ‘Run’ button in the ‘Calibrate SM identification’ panel.
2.3 Follow the prompts if you would like to automatically save the GUI after this module.
2.4 Set the EM gain used, load in the SM data .tif file(s), select what frames to perform the SM detection calibration on, and select the templates to be used. By default, templates are chosen by the program such that the angle of the line connecting the two lobes is given by {-60°, -30°, 0°, 30°, 60°, 90°}, and this selection should generally be appropriate (Figure 6).
2.5 Load in the dark offset .tif file with the same parameters as the SM data.
2.6 The program will then prompt the user to choose a background processing algorithm such as median filtering, wavelet filtering, no background subtraction, or select if the data is an NHA, Figure 7. Median filtering parameters should be filled in if choosing this option.
2.7 Select a region containing the SMs of interest. This exact ROI will be used for the single-molecule fitting module and ideally should not contain fluorescent objects that are much (≥10x) brighter than the SMs you wish to analyze. Template matches are indicated as circles drawn over the raw data. Stronger matches are drawn as larger circles, and each color corresponds to a different template match.
2.8 After the template-matching module is complete, open the ’threshold [DateAndTime]’ folder. This contains a selection of .png files that represent potential template matches. The filenames describe which template matched the data and the value of the phase correlation for the match (e.g. ‘template 3 threshold 272.png’).
2.9 Select appropriate thresholds for each template, and enter these into the ‘threshold’ field in the GUI. These thresholds should be chosen such that the two lobes of the DHPSF are faintly visible and that there is a low rate of false matches for higher correlation values. You should not be concerned if there are a few incorrect matches, say to one lobe of the DHPSF from a very bright molecule, because these will be rejected by the subsequent double-Gaussian fit module.
Step 3. Fiducial tracking (optional)
This module tracks the movement of one or more fluorescent beads or other stationary markers. Stage drift during a SM experiment can be thus be removed by subtracting the movement of the fiducial marker from the SM localizations.
3.1 Click the ‘Run’ button in the ‘Track fiduciaries’ panel.
3.2 Follow the prompts if you would like to automatically save the GUI after this module.
3.3 Select a region of interest containing at least one bright fiducial by adjusting the box and double-clicking inside it.
3.4 Select one or more fiducials by clicking in the center of each DHPSF.
Step 4. Single-molecule localization for SMACM data
Using the results of the previous processing steps, this module identifies single molecules that score above the template matching threshold identified in step 2.9, then fits them using nonlinear least squares minimization to a double-Gaussian function.
4.1 Click the ‘Run’ button in the ‘Localize DHPSF SMs’ panel.
4.2 Follow the prompts if you would like to automatically save the GUI after this module.
4.3 Choose the frames from the raw data to process, as well as whether you would like to estimate the laser profile and find true lobe widths (sigmas). By default, the entire image stack is processed.
4.4 Whenever starting analysis of a new experiment, monitor this process as it proceeds to ensure that the threshold used includes the single molecules visible in the raw data, and to ensure that the fits are performed successfully. Only matches that score above the thresholds are fit, and good fits are plotted in the frame-by-frame reconstruction. Here the definition of a good double-Gaussian fit is a fit that meets several straightforward criteria, hard-coded into the module. The tests performed to define a good fit are listed below under Troubleshooting (Step 4).
4.5 Save this Easy-DHPSF file using the save icon at the top of the GUI, ensuring that the Channel selected is the correct one.
4.6 Go back to Step 2, this time selecting the other color channel.
4.7 Ensure that you have two saved easy-dhpsf files, one for each color.
Step 5. Single-molecule detection calibration for control points
5.1 Load in the Easy-DHPSF GUI file from Step 1, saved after calibrating both the green and red channels.
5.2 Under Setup > Channel, select a channel ‘G’ for green or ‘R’ for red.
5.3 Click ‘Run’ in the ‘Calibrate SM identification’ panel.
5.4 Follow the prompts if you would like to automatically save the GUI after this module.
5.5 Set the EM Gain used, load in the control point scan .tif file(s), select what frames to perform the control point detection calibration on, and select the templates to be used. A subset of the frames may be used, but ensure that the frames you selected are ones that include at least 1-2 full axial scans so that different z positions are included in the calibration.
5.6 Load in the sequence log file (.dat or .mat) with the sequence of steps used for the control point scan.
5.7 Load in dark offset .tif with the same parameters as the control point scan.
5.8 The program will then prompt the user to choose background median filtering, wavelet filtering, no background subtraction, or select if the data is a NHA array. Median filtering parameters should be filled in if choosing this option. If an NHA is used, select NHA so that the program will fit localizations found in a grid – this will increase the number of PSFs detected. If NHA is selected, median background subtraction is performed.
5.9 A frame of the scan will pop up, and the user will be prompted to select an ROI of the correct color channel using a square ROI. The user will then be able to select an ROI with a polygon.
5.10 After the calibration, follow Steps 2.4-2.5 described above for selecting thresholds.
Step 6. Single-molecule localization for control points
This will outline the steps to fit control points in the two channels.
6.1 Click the ‘Run’ button in the ‘Localize DHPSF SMs’ panel.
6.2 Choose the frames you would like to fit, as well as whether you would like to estimate the laser profile and find true lobe sigmas.
6.3 As this step is for fitting the control points, enter how many stationary frames there are for each axial position and click ‘OK.’
6.4 If using an NHA, select 4 fiducials that form a box that outlines the field of view (Figure 8). The program will find the rest of the DHPSFs located on a grid for each axial scan. Otherwise, this step does not show up for bead fitting (Figure 9).
6.5 Once the program is finished fitting, filter and export your results. Under ‘Output DHPSF SM localization’, click ‘Filter Output.’
6.6 If using a NHA, choose ‘Yes’ when the program asks whether you would like to use spatially dependent calibrations. Doing this will reduce field-dependent aberrations by applying nearest-neighbor calibrations to your data with the NHA.
6.7 A different calibration may be used during this step. The program will prompt the user with this option.
6.8 Filter your control points as prompted by the program (for instance, filter by frame, z position, lobe distance, photons, localization precision, etc.).
6.9 Choose the region to be plotted in the scatter plot, inspect the localizations, then save your data when you are happy with the results. The filtered localizations will be in the file ‘Output.mat’, for use in the next step.
6.10 Repeat steps 5 and 6 for the other color channel. Take note of where you saved the filtered output files, as they will be needed for the next step.
Step 7. Identification of control points
This module will identify candidate control points between two channels.
KEY INPUTS: Output.mat file of GREEN and RED channels
KEY OUTPUTS: Identify_ControlPoints_3D_output.mat
7.1 Run the MATLAB function ‘Identify_ControlPoints_3D_v1.m’
7.2 Open the ‘Output.mat’ data file with the molecule fits in reflected/GREEN channel. (If you are not using a single camera, ignore “reflected” vs. “transmitted”.)
7.3 Open the ‘Output.mat’ data file with the molecule fits in transmitted/RED channel.
7.4 Open the .mat or .dat sequence log file for the control point scan.
7.5 If available, open a previous transform to use as an initial guess. Otherwise, click ‘Cancel’
7.6 Input parameters of how many stationary frames were taken at each z position, how many frames to wait before starting the averaging, and if using an old transform, how closely the initial transform should match old transform points. The program will prompt you for these values.
7.7 The program will first find control point (CP) candidates, merging localizations at given z positions.
7.8 A figure will pop up with fitting statistics for the molecules fits you loaded. Enter filtering parameters for σx, σy, σz, and number of measurements.
7.9 Inspect averaged bead positions in both channels.
7.10 If an initial transform was not given in step 3.5, the program will ask you to hand click control points. Aim to hand click at least ~15 control points. Follow the prompts in the figure (Figure 10, Figure 11). Both the color and size of each localization encodes the relative brightness (number of photons detected) of that molecule. If the program is still prompting you to select control points but you have already selected >15 and would like to stop, get a new frame then hit ‘esc’ to end.
7.11 When finished hand clicking control points, the program will run and generate a preliminary transformation file that you will use for the next step. This file will be located in the same directory where your green channel ‘Output.mat’ is saved.
Step 8. Generating and evaluating final 3D transform from control points
This module will evaluate the initial transform calculated in Step 7 above and generate a final transform you can use in the next step.
KEY INPUTS: Identify_ControlPoints_3D_output.mat
KEY OUTPUTS: 3D_Transform_lwquadratic.mat
8.1 Run the MATLAB function ‘EvaluateTransform_3D_v2.m’
8.2 Input transformation parameters (then proceed to Step 8.4) or click if you want to evaluate parameter ranges (proceed to Step 8.3).
8.3 Enter the range of parameters you would like to evaluate. The program will evaluate these parameter ranges then return the calculated target registration errors (TRE) and fiducial registration errors (FRE)9. An example result is in Figure 12. Inspect the results by clicking on the figure. Ideally, the user should aim for errors ≤ 10 nm.
8.4 Select the value of nearest neighbors, sigma, and kth nearest neighbor, and input these parameters into the dialog box that appears. The program will then calculate a transformation using the parameters you provided. For the ~1000 control point pairs in the example here, the mapping function took ~1 hour to generate using an Intel Xeon E5-1620 processor.
8.5 The program will return a histogram of TREs and FREs, as well as the spatial distribution of these metrics. The final transformation is ‘3D_Transform_lwquadratic.mat’ and will be located in the same folder as ‘Identify_ControlPoints_3D_output.mat.’
Step 9. Transforming SMACM data
This module will smooth the fiducial tracks, perform the 3D two-color registration, correct for sample drift, apply an index mismatch correction, and calculate localization precision.
KEY INPUTS: Easy-DHPSF files for each of the two color channels, transformation function (3D_Transform_lwquadratic.mat)
KEY OUTPUTS: MATLAB structure called dataSets
9.1 Run the MATLAB script ‘TransformSMACMData_v6.m’
9.2 Indicate whether the green data or red data was acquired first, or if the two-color acquisition was interleaved.
9.3 Load in the green Easy-DHPSF file. The program will perform smoothing via wavelet filtering of the fiducial tracks and apply this correction to your data. Follow the prompts that appear.
9.4 Load in the red Easy-DHPSF file, and follow prompts that appear to smooth fiducial track data.
9.5 Load in the ‘3D_Transform_lwquadratic.mat’ file generated in the previous step.
9.6 The program will prompt whether or not you would like to crop each dataset before the transformation.
9.7 Select the location and enter a file name for where to save your registered dataset.
9.8 The registered data is stored in the MATLAB structure ‘dataSets,’ with ‘dataSets(1)’ containing the green data and ‘dataSets(2)’ containing the red data. The fields xFid, yFid, and zFid_n contain the fiducial-corrected and index-corrected localizations. The rest of the fields are described in Figure 19.
9.9 Select whether you would like to export the localizations into a csv file. If yes, choose the location and file name of each color file.