Walkthrough on command line based tilt series alignment

From Dynamo
Jump to navigation Jump to search

Dynamo includes a package for automated alignment and reconstruction of tilt series. This walkthrough guides users through a series of steps on how to use it in command line based mode. The GUI based alignment walkthrough shows how to operate this procedure through the GUI. Here, we go through each command one by one (for advanced applications, all commands can also be summarized in a Matlab script and run at once).

Create the workflow

The following commands create a new alignment workflow in a separate folder. Make sure Dynamo is running and type the following commands into the Matlab command line (or the Dynamo console, if you work on the standalone version):

name = 'hivCommandLine';
folder = 'workflows';

In the Matlab workspace you should now see the variables that you just created with these commands. If you work with the standalone version you can simply type the word whos to see a list of all variables in the workspace.

Entering the data

The variable u is an object that contains several fields to interact with the workflow. They can be found through autocompletion by using the tab key (or by pressing the enter key in the standalone version). In the following, these different fields will be used to pass our inputs to the workflow.

autocompletion of user object to access different fields in matlab and standalone version

Basic data

Basic data can be entered using the enter field. Here we use a binned version of the first tilt series from the EMPIAR entry 10164, depicting a set of virus like particles (VLP). Visit the course materials to access the tilt series or download it directly from EMPIAR (you can also use your own data). The file of the tilt series can be first defined in a normale variable as

file = 'b001ts001.mrc'; 

and then passed to the workflow together with the angles:


If necessary (not in this tutorial), you can use the discardedTiltIndices field to reject tilts that are of too bad quality using the following command (e.g., tilt 1 and 40):


Acquisition settings

Here you can enter parameters such as Cs, nominal defocus, etc. For this tutorial we just provide the pixel size in Angstroms:


Computation settings

We enable the use of parallel cores



To use all available physical cores use:


Detection settings

These here are the actual design decisions when running an alignment workflow. The gold bead radius has to be known beforehand ( see GUI based alignment walkthrough on how to measure it). Binning is used internally only for quick and robust bead detection.


Changing generic parameters

You can find all parameters of the individuals steps using autocompletion on the area field and then by adding step in the end. For example, the residual threshold of the tilt gap filler can be changed as follows:


Running the workflow

After setting the input parameters, the complete workflow can be run using the following command (we skip the CTF correction here). It should take about 5 minutes to run.


Checking the results

After completion, the view field allows you to check different output items for diagnose, such as the tilt lines:

view of tilt lines

or the different reconstructions


or the aligned stacks themselves.


You can also use the autocompletion of the info field to read different logs:

>> u.info.fit;
File with info:
rms:  1.39
psi: 85.10
fit modus: normal
total markers: 78
total observations: 2590
>> u.info.markers;
Info on working markers [used during detection, indexing refinement]
  ... item saved and in memory
Item in memory:
Number of shapes          :  78
Number of frames          :  40
Number of observations    :  2590 (out of 3120)
Number of empty frames    :  2
Number of complete frames :  0
Number of complete shapes :  0
Item in disk:
Markers in disk and currently in memory contain equal coordinates
Info on final markers [used from alignment step]
  ... item saved and in memory
Item in memory:
Number of shapes          :  78
Number of frames          :  40
Number of observations    :  2590 (out of 3120)
Number of empty frames    :  2
Number of complete frames :  0
Number of complete shapes :  0
Item in disk:
Markers in disk and currently in memory contain equal coordinates

On the fly reconstruction of particles


Grep coordinates in the binned tomogram

Open the binned reconstruction with dtmslice

dtmslice 'workflows/hivCommandLine.AWF/reconstruction/binnedReconstructionWBP.mrc';

dtmslice of binned reconstruction

You will need to adjust the contrast:

dtmslice contrast control
dtmslice after contrast correction

Now we create a new model of general type

create a new model


show a full projection
full projection of binned reconstruction


right click on a point

Left clicking on it will provide a z coordinate to it

x view of clicked point
main click to fix the 3d coordinates


click around ten markers


export a table into the matlab workspace


the command line shows the variable name assigned to the created table


Cropping the gold bead particles

We can now crop the particles using the table file

tomo = 'workflows/hivCommandLine.AWF/reconstruction/binnedReconstructionWBP.mrc';
tbl  = 'binnedGoldbeads.tbl';
targetBinnedParticles = 'binnedGoldBeads.Data';
sidelengthBinned = 32;

And then we visualise a projection along z of each cropped particle

dslices on binned gold beads


Reconstruct particles on the fly


tbl = dread('binnedGoldbeads.tbl');


alignmentBinLevel = 2;


source  = 'workflows/hivCommandLine.AWF/align/alignedFullStack.mrc';


targetDirectory = 'tempCrop.Data';


angles =  'workflows/hivCommandLine.AWF/align/reconstructionTiltAngles.tlt';


visualizationTomogram =  'workflows/hivCommandLine.AWF/reconstruction/binnedReconstructionWBP.mrc';
sizeTomogram = dynamo_read_size(visualizationTomogram);
sizeTomogramFull = sizeTomogram*2^alignmentBinLevel;


shiftTomogramCenter = [0,0,0];


sidelengthFullSize = 128;




dslices on full sized gold beads