Difference between revisions of "Walkthrough on GUI based tilt series alignment"

From Dynamo
Jump to: navigation, search
(Detection of gold beads)
(Detection of gold beads)
Line 121: Line 121:
[[ File:alignGUI_refinedCCMatrix.png |thumb|center| 600px| computing refined cc-matrix]]
[[ File:alignGUI_refinedCCMatrix.png |thumb|center| 600px| computing refined cc-matrix]]
[[ File:AlignGUI ExtractedRefinedPeaks.png |thumb|center| 600px| extracting refined peaks from refined cc-matrix]]
Right click on the <tt>view</tt> area of the step to access the different visualisation options.
Right click on the <tt>view</tt> area of the step to access the different visualisation options.

Revision as of 21:41, 18 October 2019

Dynamo includes a package for automated alignment and reconstruction of tilt series. This walkthrough guides you through the steps on how to use it in GUI-based mode. A different page in this wiki shows how to operate this procedure through the command line.


We have prepared a version of a tilt series from the EMPIAR entry 10164, containing a set of virus like particles of VLP.

wget https://wiki.dynamo.biozentrum.unibas.ch/html/w/doc/data/hiv/align/b001ts001.mrc

In a Mac:

curl -O https://wiki.dynamo.biozentrum.unibas.ch/html/w/doc/data/hiv/align/b001ts001.mrc

In the workshop, a copy should be already available on your local data folder:


In this binned version, the pixel size is 2.7 Angstrom (original was 1.35, this is bin level 1 in Dynamo or bin level 2 in IMOD)

Creating an alignment workflow

The basic function for invoking the GUI is dtsa (short form of dynamo_tilt_series_alignment:

 u = dtsa();

Here, u is an object that will reside in memory during the session and allows to interoperate with the workflow through the command line. It is not necessary when proceeding through the GUI. After running the command above, a pop-up window appears. Click on create a new workflow.

creating a workflow

The data for the workflow (tilt series, angles) could have been introduced directly when creating the workflow, we however will introduce each item explicitly in this walkthrough.

The minimal data to initiate a workflow is

  • tilt series matrix (use the file indicated above)
  • tilt angles.
  • discarded tilt angles (leave empty)
input workflow parameters

Discarded tilt angles

If you are unsure on the tilts to be discarded, you can do it in a later stage while you inspect the images in the dmarkers GUI, using the x and shift + x buttons.

GUI description

The GUI guides the process of creating and editing a set of working markers (in the areas of detection, reindexing and refinement), and then using them to create aligned stacks (alignment tab), analyse and correct their CTF (through wrappers to ctfffind4 and imod) to create 3D reconstructions of the tomographic data.

alignment GUI before completion of any step


Acquisition settings

Here you can enter pixel size (2.7 Angstroms), Cs (2.2), nominal defocus (-4.0 microns, used if the CTF area is connected).

Alignment GUI Controls

The GUI possesses different pre-defined areas. Starting from top to bottom, you can find a toolbox with the options: Tools, Help, Settings, IO, Working Markers and Fit. These tools are extremely useful to visualize and customize general settings as tilt scheme and defocus value among others. Each of the tools are briefly explained:

  • Tools
  • Help
  • Settings
  • IO
  • Working markers
  • Fit

Under the toolbox, we find several icons: dmarkers, occupancy plot, gold bead gallery, gold bead targeting, fitting and marker selection.

  • dmarkers GUI: this icon opens a GUI that displays the tilt series data and the current working markers. It allows you to check the position of the working markers in each micrograph. If you want to make editions of the GUI permanent, you need to save the current markers as explained bellow.
  • Occupancy plot: shows a scheme of which markers are present in which tilt numbers.
  • Gold bead gallery: it crops the 2D patches which are currently contained in the working markers, and therefore, treated as gold beads, and display them in gallery mode.

Execution Areas

In the GUI, right below the icons, we can find six execution areas: detection, indexing, refinement, alignment, ctf, reconstruction. Each of them comprises a sets of steps that can be executed sequentially. Sequential execution is the natural way of proceeding; but steps can be visited in any order, i.e., a step can be re-executed in a later moment after updating its information.

By passing the cursor on the GUI elements shows a help element


Each execution area has one or more steps. Steps need to be open (letters highlighted in black, not grey) to be executed. They become open when the required input(s) are ready to be processed. The required input(s) can be provided by users or computed and stored in a previous step of this alignment workflow. When a step is under execution, its pushbutton becomes green.

  • Step Toolbox

At the right side of each of the steps, a tool icon is located. The tool icon can be secondary clicked to provide a pop-up menu with specific tools for each step. There are also some common tools for all the steps which handle the inspection and listing of input and output items generated by the step.

Next to the tool icon, there is a View pushbutton. The View pushbutton provides specific tools to visualize and inspect the results of each step.


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

Visualization matrix

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.

completed steps become bold font size

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.

open unbinned tilt series data

Zoom in a gold bead by holding the shift key and scrolling up your mouse wheel. Adjust the visualized region by holding the shift key again and dragging with right mouse click on tmshow window.

open tomoshow on the full sized matrix to check the size of a gold bead

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 64 pixel aprox.

the ruler tool allows to measure in pixels the diameter of a gold bead

Detection of gold beads

This area is the one that needed some design decision on the size of the gold bead. Now, we know that the diameter of the gold bead is 64 pixel in the original image, therefore its radius is 32 pixels. We introduce the bead radius and some other parameters to create an accurate initial gold bead template in Dynamo. The appropriate parameter are:

  • bin factor during detection = 2. We are working with binx2 data to accelerate the process.
  • bead radius = 32 (pixels from the original unbinned data).
  • mask radius = 56 (pixels according to the original unbinned data).
  • template side length = 128 (pixels according to the original unbinned data).
the plus icon at corner shows the values of the parameters of a given step

After pressing the pushbutton detect peaks, Dynamo creates a raw cross-correlation matrix based on the initial template which is binary and extracts 300 cc-peaks by default.

computing raw cc-matrix
extracting peaks from raw cc-matrix

Then, the extracted peaks are average 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.

computing refined cc-matrix
extracting refined peaks from refined cc-matrix

Right click on the view area of the step to access the different visualisation options.

secondary click in the view panel opens a menu to access the different results of a step
marker sets can be viewed as cloud of points

This view shows the x,y coordinates of all cross correlation peaks on all the micrographs in the tilt series.

cloud of unindexed cc peaks

We can also check the positions of all the detected spots on each micrograph:

shows the detected spots on the video GUI

This GUI does not allow for edition of the markers.

static video annotations cannot be edited

The neighbourhood of cross correlation peaks can be visualised individually:

Each patch will be a putative gold bead
the set of cc peaks is shown as a montage

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

example of failed gold bead detection

Note that you have the option of testing your parameters against a single image before launching a full detection procedure.

toolbox option for testing the parameters on a central image
results of testing on a central image

Computation of observation features s

At this stage, the observed cross correlation peaks are analysed. In the current Dynamo' version a merit figure is assigned to each peak based on a "rotational merit" that measures its similarity to a circle. The results can be depicted on patches representing individual gold beads:

patch gallery for features
the gallery allows relating appearance of gold bead an value of the features

or extracting properties of the whole data set.

feature plotter allows checking of the feature values on the whole set
different plotting options
scatter 2d option
coloring option for scattered plots
each point represents a cc peak

Selection of best gold beads

The cluster with the best markers is then selected. The individual patches can be inspected

check observation cloud after selection or clustering

or, again the cloud of observations

observation cloud has been thinned

and the location of the observations in the micrographs:

check marker positions after clustering
marker positions after clustering


The goal of this task is to find trails of gold beads, i.e., observations in different micrographs that correspond to the same 3d gold bead. All the steps in this area will update a set of "working markers".

Rough Alignment

Here all couples of micrographs are compared. For each couple, we look for the relative shifts that generates 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

occupancy scheme of the results of a step
rough alignment selects many potential trails

Note that these trails are very lacunary and don't 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.

Selection of stable trails

We select the longest trails, which will then be used to generate a 3d model of the markers:

trails with few markers are then rejected

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.

note working markers can be restored to the result of a previous step

Iterative reindexing

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

parameters for iterative reindexing
result of iterative reindexing

Tilt gap filling

Dynamo can be directed to try to analyse those tilts that wind up not having any marker (and that have not been explicitly rejected by the user). The cloud of observations found on that micrograph will be compared to the cloud or reproductions generated by the current model.

parameters for tilt gap filler
occupancy after tilt gap filler
we have 66 traces after gap filler
results of tilt gap filler

Trail extension

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.

parameters of tilt extensor
trail extensor adds a few new trails

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.

some of the new trails have empty spaces
result of trail extensor


This area refines the positions of the gold beads. We will run all steps of this area pressing on a single button (the run this tab option at the bottom of the GUI)

tab for refinement

The Botton remains green while the succession of different steps gets computed.

all steps of refinement area are being computed
better fitting is attained

We can use the scissors icon in order to "trim" observations (or full markers) with too high residuals

trimming of markers can be accessed through the scissor icon
residuals at each observation


This area creates the aligned tilt series. It creates two version, a binned one and one with full resolution pixel size. Note that the binning level of this one is independent of the binning level used in the detection step.

Fix the markers

Here we just freeze the working markers and create a marker file that will define all subsequent steps of alignment and reconstruction.

area for creation of an aligned tilt series

Align the tilt series

We then proceed to the alignment task itself, generating the binned and the full resolution stacks.

visualization of aligned tilt stack
binned aligned tilt stack


In this GUI CTF estimation and correction are delegated to CTFFIND4 and Imod's ctfphaseflip programs respectively. This part will not be used in the workshop.'


Binned reconstruction

This version of Dynamo fixes the tomogram center at the 3d reconstruction center of the aligned stack.

reconstruction area
choose a visualization
binned weighted back projection reconstruction

Full sized reconstruction

The full sized reconstruction can be created related to a coordinate directly read in the binned tomogram, a feature useful for creating reconstructions localised on an area of interest. In this case, we will focus on one of the VLPS.

Use the pin tool to select a point on the binned reconstruction.

the pin tool is useful for locating isolated points
we put a pin in the center of an object of interest

We also check the size of a structure of interest. We measure it in the binned tomogram.

we check the distance of the object of interest
we use the option of expressing the center of the full sized tomogram in terms of a position in the binned tomogram

A viewer system is not yet connected to this step, we can however use the common inspection tools to fetch the outcome (the full sized WBP)

as an specific viewer is not available for this step we can use the toolbox of the steps items
the full size reconstruction includes only the object of interest

As it is a full resolution reconstruction, it is much noisier than the corresponding area in the binned tomogram. You probably need to use a rather deep bandpass (around 0.2 of nyquist) in order to distinguish it.

You might need to activate the bandpass to see the VLP