Walkthrough on GUI based tilt series alignment (SciLifeLab 2023)
This walkthrough guides users through a series of steps on how to use it in GUI-based mode.
- 1 Data
- 2 Creating an alignment workflow
- 3 GUI description
- 4 Processing
- 4.1 Detection
- 4.2 Indexing
- 4.3 Refinement
- 4.4 Alignment
- 4.5 CTF
- 4.6 Reconstruction
Here we will be using the same data as in the previous tutorial . So, if you have create a new directory (which is highly recommended), just go back to it.
Creating an alignment workflow
Start the alignment GUI by typing the command dtsa (short form of dynamo_tilt_series_alignment) into the Dynamo command line:
A pop-up window appears. Click on "create a new workflow":
Here, the input data for the workflow (tilt series, angles, ...) is introduced:
The option configuration file is used to pass information on possible tilts that should be discarded. Here, we leave this option untouched. Press on create workflow, to open the alignment GUI.
The alignment GUI guides the process of generating gold bead coordinates, aligning the tilt series, correcting the CTF and to finally reconstruct the tomogram. It has 5 parts. Starting from top to bottom, they are:
- Menu: Different tools for visualization and customization of general settings. The option Settings > edit[general] for example lets you adjust the pixel size and different acquisition parameters such as Cs etc. Here we keep the default settings.
- Icons: Quick access to tools such as dmarkers, occupancy plot, gold bead gallery, gold bead targeting, fitting and marker selection. Their functionalities will be explained later.
- Tabs: The tabs describe the 6 execution areas that are executed from left to right: detection, indexing, refinement, alignment, ctf, reconstruction. Each execution areas contains a set of processing steps.
- Steps: The processing steps of each tab are run sequentually from top to bottom. However, after execution, the steps can be revisited to change or update information. Steps need to be active (letters highlighted in black, not grey) to be executed. They are automatically activated once the previous steps have been executed or the required input is given. Input parameters are edited by clicking the plus button (+) on the left of the step button. When a step is under execution, the text of the button becomes green. After execution the text becomes bold. At the right side of each of the steps, a tool icon is located. The tool icon can be right-clicked to provide a pop-up menu with specific tools for each step. Next to the tool icon there is the View button which provides specific tools to visualize and inspect the results of each step.
- Run options: Options to run multiple steps.
We are now ready to run all the processing steps. In the following, each step is described in detail.
The goal of this step is to find the positions of the gold bead projections in the tilt series. To do that, Dynamo cross correlates each micrograph against a 2D model of the gold bead and then locate the cross correlation peaks, which provide putative positions for actual projections of gold beads. Further analysis of these peaks will determine which ones correspond to actual gold bead projection (peak feature and peak selection).
This step just creates a binned version of the tilt series stack to accelerate visualizations that will be invoked in a later point. If you click on the box standing on the left of creates a binned tilt series button with a + symbol, an option box appears, indicating the default binning factor which is 2. This parameter can be changed by users. Binning factor 2 in Dynamo is equivalent to a binning factor of 4 in IMOD. Click on creates a binned tilt series button to create a binned tilt series stack. Rightclick on View button to visualize the newly binned tilt series stack in tmshow. In the tmshow window, visualization parameters as binning, band and thickness can be adjusted if needed.
Now, we are going to measure the diameter of the gold beads precisely in tmshow in the original (unbinned) tilt series data. To do that, press the IO in the upper toolbox of the alignment workflow GUI, then go to tilt series matrix > inspect > On-the-fly view [dtmshow]. The tmshow window opens, adjust contrast if necessary for better visualization.
Zoom in a gold bead by holding the shift key and scrolling up your mouse wheel (alternatively, use the icon with the red rectangle. Avoid using the lens icons). Adjust the visualized region by holding the shift key again and dragging with right mouse click on tmshow window.
Once you have located the gold bead of interest, click on the ruler icon at the top toolbox to activate length measurements on the displayed image data. Draw a line across the gold bead, and the length of the line appears in pixels, which correspond to the gold bead diameter. In this case, the length of this line should be 32 pixel aprox.
Detection of gold beads
Here we provide the size of the gold beads. The measured diameter of the gold beads is 32 pixels in the original image, therefore its radius is 16 pixels. We introduce the bead radius and some other parameters (see screenshot) to create an accurate initial gold bead template (here, the binning is just used internally for quick and robust bead detection).
After pressing the button detect peaks, Dynamo creates a raw cross-correlation matrix based on the initial template which is binary and extracts 300 cc-peaks by default. Then, the extracted peaks are averaged to create a refined template. The refined template is used to compute a refined cc-matrix from which 300 peaks are extracted and used as initial working markers. Once the detect peaks button turns black bold, the computation is finished. Right click on the view area of the step to access the different visualisation options.
This view shows the overlaid sum of the x,y coordinates of all cc peaks from all micrographs in the tilt series.
We can also check the positions of all the detected spots on each micrograph:
This GUI does not allow for edition of the markers. Tip: enable auto option at the bottom center of the visualization GUI to facilitate tilt series visualization.
The neighbourhood of cross correlation peaks can be visualised individually as 2D patches from the tilt series image data:
This visualization is normally a good gauge on how the detection procedure has worked. The example below would be an example of detection procedure carried with wrong search parameters
Computation of observation features
At this stage, the observed cross correlation peaks are analysed. A merit figure is assigned to each peak based on a rotational merit that measures its rotational symmetry. Press the button Peak features to compute the rotational symmetry of the current working markers. The working markers that do not meet rotational symmetry will be discarded. The results can be depicted on patches representing individual gold beads:
or extracting properties of the whole data set.
Selection of best gold beads
The population with the best markers is automatically selected by clicking on Peak selection. The results can be inspected again in a plot
or in the micrographs themselves:
The goal of this execution area is to find trails of gold beads, i.e., we connect the observations from different micrographs that correspond to the same gold bead. All the steps in this area will constantly update a set of working markers.
In this step, micrographs are compared pair-wise. For each couple, we look for the relative shifts that generate the most matches of cross-correlation peaks between one micrograph and the next one. This procedure induces trails of matched pairs of observations of variable length along the tilt series. The scheme that depicts which trails have representatives in which tilts is called occupancy graph
Note that these trails are very lacunary and do not conserve the identity of a trail; whenever a trail that represents an actual 3d marker gets interrupted, the same 3d marker might generate a different trail in other tilts.
Keep long chains
Click on keep long chains to select the longest trails, which will then be used to generate a 3d model of the markers:
Note that from this step onwards, the toolbox of each step offers the possibility to revert the current markers to the output generated at that state. Thus, if further processing of the markers in a later step leads you to loose a good marker set, you can always come back to this point.
The 3d model is projected on each micrograph. Observations that are closest (and below a distance threshold) to each reprojection are assigned to the corresponding 3d marker. This refines the 3d model, and the process is iterated till no further improvement occurs (or till a maximum of ten iterations is reached). Keep the default parameters and click on iterative reindexing.
Tilt gap filling
Here, potential tilts with too few (or zero) markers can be rescued. The cloud of observations found on that micrograph will be compared to the cloud or reprojections generated by the current model. Click on fill tilts without markers.
This step aims at locating trails that have been excluded by previous steps of the alignment procedure, or that were never detected as trails because previous, lesser quality stages of the 3d model were not able to analyse the observations correctly.
Note that newly added trails have empty spaces in the central area, they are likely to be gold beads located far away from the tilt axes and which get into the field of view only for high tilts.
This area refines the positions of the gold beads. We will run all steps of this area by pressing on a single button (the run this tab option at the bottom of the GUI). The button will remain green while the different steps are computed.
Check the current refinement error:
Optionally, we can use the scissors icon to "trim" observations (or full markers) with too high residuals. Click on the scissor icon. A window pops up with options to set different thresholds. Click on Tools and then Show residuals per observation:
You get a plot with the residuals for each observation ordered by the value of the residual. You can use this plot to estimate the residual distribution and to manually adapt the residual thresholds, if necessary.
The final step of the alignment procedure is to create the aligned tilt series using the coordinates of the markers that were optimized until now.
Fix the markers
Here we freeze the final version of the working markers and create a marker file that will define all subsequent steps of alignment and reconstruction. Click on fix alignment markers.
Align the tilt series
We then proceed to the alignment task itself, generating full resolution aligned tilt series. We also have the option to generate a binned version of the aligned tilt series that can be used for quick visualization or to create binned reconstructions in the next steps. Click on Create full-size aligned stack and Create binned aligned stack. For a quick assessment, open the binned stack in tomoshow:
A quick way to gauge the quality of the alignment is by checking that the beads move nicely horizontally over all tilts.
In this GUI, CTF estimation and correction are done using CTFFIND4 and IMOD's ctfphaseflip. This part will not be used in the workshop.
Click on binned reconstruction to create a binned tomogram using the previously created binned aligned tilt series. Adapt the tomogram height if necessary (the tomogram center is automatically located at the center of the 3d reconstruction of the aligned stack). Select binned SIRT-like reconstruction to generate a high contrast tomogram. Run the step binned reconstruction and visualize the resulting binned SIRT-like tomogram:
Full sized reconstruction
The full sized reconstruction is the one you will be using for later image processing steps that require the highest resolution possible (e.g., subtomogram averaging refinements). It can be created related to a coordinate directly read from the binned tomogram. This feature is useful to create reconstructions localised on an area of interest. In this tutorial, we will focus on one of the VLPs, resulting in a tomogram containing just one VLP. First, use the pin tool to select a point on the binned reconstruction. We use the previously opened binned SIRT-like tomogram for this:
We check the size of the structure by using the measuring tool:
Before generating the final localized tomogram, we need to set some parameters. We take the measured distance of 83 pixels and compensate for the binning factor of two, leading to 83*2*2=332 pixels. For the dimensions of the tomogram we add some spare space and define the x,y and z length to be 500 pixels. Select use center of binned coordniates and enter the values we measured before with the pin tool. Select WBP reconstruction and run the step full reconstruction. Use the inspection tools to fetch the result:
As it is a WBP reconstruction, it is much noisier than the corresponding area in the SIRT-like tomogram. Adjust the contrast, lowpass filter and thickness to increase the signal: