<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
	<id>https://www.dynamo-em.org//w/api.php?action=feedcontributions&amp;feedformat=atom&amp;user=Andr%C3%A9s+Molina</id>
	<title>Dynamo - User contributions [en]</title>
	<link rel="self" type="application/atom+xml" href="https://www.dynamo-em.org//w/api.php?action=feedcontributions&amp;feedformat=atom&amp;user=Andr%C3%A9s+Molina"/>
	<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Special:Contributions/Andr%C3%A9s_Molina"/>
	<updated>2026-11-19T03:01:29Z</updated>
	<subtitle>User contributions</subtitle>
	<generator>MediaWiki 1.43.11</generator>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_PCA_through_the_command_line&amp;diff=5657</id>
		<title>Walkthrough on PCA through the command line</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_PCA_through_the_command_line&amp;diff=5657"/>
		<updated>2025-11-24T15:38:20Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* GPU computing */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:Walkthroughs]]&lt;br /&gt;
&lt;br /&gt;
[[Principal component analysis|PCA]] computations through the command line are governed through &#039;&#039;PCA workflow&#039;&#039; objects. We describe here how to create and handle them:&lt;br /&gt;
&lt;br /&gt;
= Creation of a synthetic data set=&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtutorial ttest128 -M 64 -N 64 -linear_tags 1 -tight 1&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This generates a set of 128 particles where 64 of the, are slightly smaller than the other 64. The particle subtomogram are randomly oriented, but the alignment parameters are known.&lt;br /&gt;
&lt;br /&gt;
= Creation of a workflow=&lt;br /&gt;
&lt;br /&gt;
== Input elements ==&lt;br /&gt;
The input of a PCA workflow are:&lt;br /&gt;
* a set of particles (called &#039;&#039;[[data container]]&#039;&#039; in this article)&lt;br /&gt;
* a table that expreses the alignment&lt;br /&gt;
* a mask that indicates the area of each alignment particle that will be taken into account during the classification procedure.&lt;br /&gt;
All theree have been generated by the &amp;lt;tt&amp;gt;dtutorial&amp;lt;/tt&amp;gt; command.&lt;br /&gt;
=== Data ===&lt;br /&gt;
 &amp;lt;tt&amp;gt;dataFolder = &#039;ttest128/data&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Table ===&lt;br /&gt;
 &amp;lt;tt&amp;gt;tableFile  = &#039;ttest128/real.tbl&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Mask ===&lt;br /&gt;
We create a cylindrical mask with the dimensions of the particles (40 pixels)&lt;br /&gt;
 &amp;lt;tt&amp;gt;mask = dcylinder([20,20],40);&amp;lt;/tt&amp;gt;&lt;br /&gt;
===Syntax ===&lt;br /&gt;
We decide a name for the workflow itself, for instance&lt;br /&gt;
 &amp;lt;tt&amp;gt;name = &#039;classtest128&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
Now we are ready to create the workflow:&lt;br /&gt;
  &amp;lt;tt&amp;gt;wb = dpkpca.new(name,&#039;t&#039;,tableFile,&#039;d&#039;,dataFolder,&#039;m&#039;,mask);&amp;lt;/tt&amp;gt;&lt;br /&gt;
This creates an workflow object (arbitrarily called &amp;lt;tt&amp;gt;wb&amp;lt;/tt&amp;gt;) in the workspace during the current session). It also creates a folder called classtest128.PCA where results will be stored as they are produced.&lt;br /&gt;
&lt;br /&gt;
== Mathematical parameters ==&lt;br /&gt;
The main parameters that can be chosen in this area are:&lt;br /&gt;
* bandpass&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.setBand([0,0.5,2]); % in Nyquist.  % Third parameter is the smoothing factor in pixels&amp;lt;/tt&amp;gt;&lt;br /&gt;
* symmetry&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.setSym(&#039;c8&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
* binning level (to accelerate the computations);&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.settings.general.bin.value = 0;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==Computational parameters==&lt;br /&gt;
The main burden of the PCA computation is the creation of the cross correlation matrix.&lt;br /&gt;
=== Computing device ===&lt;br /&gt;
PCA computations can be run on GPUs of on CPUs, in both cases in parallel. In each block, two subsets of (prealigned) particles are read from disk. &lt;br /&gt;
&lt;br /&gt;
To use all the available cores in your local machine, write:&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.settings.computing.cores.value = &#039;*&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==== GPU computing ====&lt;br /&gt;
By default, the ccmatrix computation will run on the CPUs. To force computation in the GPUs you need to active them first:&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.settings.computing.useGpus.value = true;&amp;lt;/tt&amp;gt;&lt;br /&gt;
and the specify the device numbers to use:&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.settings.computing.gpus.value = [1:8];&amp;lt;/tt&amp;gt;&lt;br /&gt;
In this example, you would be using 8 GPUs, marked by the systems with numbers 1 to 8.&lt;br /&gt;
&lt;br /&gt;
Take into account that your system needs an independent CPU for each used GPU.&lt;br /&gt;
&lt;br /&gt;
=== Size of parallel blocks ===&lt;br /&gt;
The size of the blocks is controlled by the parameter &amp;lt;tt&amp;gt;batch&amp;lt;/tt&amp;gt;. You can tune it with:&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.setBatch(100);&amp;lt;/tt&amp;gt;&lt;br /&gt;
meaning that each block executed in parallel will preload two sets of 100 (prealigned) particles into memory, and then proceed to cross correlate all possible pairs. Ideally, you should tune your &amp;lt;tt&amp;gt;batch&amp;lt;/tt&amp;gt; parameters l to have as many blocks as processing units (CPU cores or GPUs).&lt;br /&gt;
IThis might not be possible, as it might crowd the memory of your device. Thus, in real applications you should aim at using the &amp;lt;tt&amp;gt;batch&amp;lt;/tt&amp;gt; parameter to enforce a tradeoff between performance and  memory usage suited to your system.&lt;br /&gt;
&lt;br /&gt;
If you get an error when running &amp;lt;tt&amp;gt;wb.setBatch(n);&amp;lt;/tt&amp;gt; this is a bug. Try unfolding the project first (&amp;lt;tt&amp;gt;wb.unfold()&amp;lt;/tt&amp;gt;), setting the batch number then unfolding again before running calculations.&lt;br /&gt;
&lt;br /&gt;
==== Utilities to set the batch number ====&lt;br /&gt;
You can get some guidance for the selection of the batch number with &lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.getBlockSize()&amp;lt;/tt&amp;gt;&lt;br /&gt;
which will return the size of each block (in Gibabytes) for the current batch parameter. &lt;br /&gt;
This number depends of the mask, as the block contains in memory only the part of each particle that is inside the mask.&lt;br /&gt;
&lt;br /&gt;
== Unfolding==&lt;br /&gt;
Before running the workflow, it needs to be &#039;&#039;unfolded&#039;&#039;. This operation checks the mutual coherence of the different elements of the workflow, and prepares the file system for runtime.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.unfold();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
= Running=&lt;br /&gt;
&lt;br /&gt;
In this workflow we run the steps one by one to discuss them. In real workflows, you can use the &amp;lt;tt&amp;gt;run&amp;lt;/tt&amp;gt; methods to just launch all steps sequentially.&lt;br /&gt;
&lt;br /&gt;
==Prealigning==&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.steps.items.prealign.compute(); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==Correlation matrix ==&lt;br /&gt;
All pairs of correlations are computed in blocks, as described above&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.steps.items.ccmatrix.compute(); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==Eigentable ==&lt;br /&gt;
The correlation matrix is diagonalised. The eigenvectors are used to expressed as  the particles as combinations of weights.&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.steps.items.eigentable.compute(); &amp;lt;/tt&amp;gt;&lt;br /&gt;
These weights are ordered in descending order relative to their impact on the variance of the set, ideally  a particle should be represented by its few components on this basis. The weights are stored in a regular &#039;&#039;Dynamo&#039;&#039; table. First eigencomponent of a particle goes into column 41.&lt;br /&gt;
&lt;br /&gt;
== Eigenvolumes ==&lt;br /&gt;
The eigenvectors are expressed as three=dimensional volumes.&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.steps.items.eigenvolumes.compute(); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== TSNE reduction ==&lt;br /&gt;
TSNE remaps the particles into 2D maps which can be visualised and operated interactively.&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.steps.items.tsne.compute(); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=Visualization=&lt;br /&gt;
&lt;br /&gt;
Computed elements have been stored in the workflow folder. Some of them ()  can be directly access through workflow tools. &lt;br /&gt;
&lt;br /&gt;
== Correlation matrix==&lt;br /&gt;
We can visualise the cross correlation matrix&lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt&amp;gt;m=wb.getCCMatrix();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt&amp;gt;figure;dshow(m);h=gca();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&amp;lt;tt&amp;gt;h.YDir = &#039;reverse&#039;; &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Eigencomponents ==&lt;br /&gt;
&lt;br /&gt;
=== Predefined exploring  tools===&lt;br /&gt;
You can use a general browser for &#039;&#039;Dynamo&#039;&#039; tables:&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.exploreGUI;&amp;lt;/tt&amp;gt;&lt;br /&gt;
[[ File:walkthroughPCACommandLine_generalToolForExploringTables.png |thumb|center| 600px|general tool for exploring tables]]&lt;br /&gt;
&lt;br /&gt;
Advanced users: This is just a wrapper to the function &amp;lt;tt&amp;gt;dpktbl.gui&amp;lt;/tt&amp;gt; applied on the eigentable produced by the workflow.&lt;br /&gt;
&lt;br /&gt;
For instance, you can check how two eigencomponents relate to each other:&lt;br /&gt;
&lt;br /&gt;
[[ File:walkthroughPCACommandLine_scatterTabTunedToShowCobehaviourOfFirstTwoEigencomponents.png |thumb|center| 600px|scatter tab tuned to show co-behaviour of first two eigencomponents]]&lt;br /&gt;
&lt;br /&gt;
Pressing the [Scatter 2D] button will create this interactive plot&lt;br /&gt;
[[ File:walkthroughPCACommandLine_scatterplotEigencomponents.png |thumb|center| 600px|scatterplot eigencomponents]]&lt;br /&gt;
Where each point represents a different particle.&lt;br /&gt;
Right-click on it to create a &amp;quot;lasso&amp;quot;, a tool to hand-draw sets of particles.&lt;br /&gt;
[[ File:walkthroughPCACommandLine_rightClickToGetTheOptionsToManuallySelectParticlesThroughALassoTool.png |thumb|center| 600px|right click to get the options to manually select particles through a lasso tool]]&lt;br /&gt;
[[ File:walkthroughPCACommandLine_lassoParticles.png |thumb|center| 200px|lasso particles]]&lt;br /&gt;
&lt;br /&gt;
Right clicking on the &amp;quot;lassoed&amp;quot; particles give you the option of saving the information on the selected set of particles.&lt;br /&gt;
[[ File:walkthroughPCACommandLine_rightClickOnTheLassoToGetOptionsOnThatSubsetOfParticles.png |thumb|center| 600px|right click on the lasso to get options on that subset of particles]]&lt;br /&gt;
&lt;br /&gt;
=== Custom approach===&lt;br /&gt;
You can use your own methods to visualize the eigencomponents. They can be accessed through:&lt;br /&gt;
 &amp;lt;tt&amp;gt;m = wb.getEigencomponents();&amp;lt;/tt&amp;gt;&lt;br /&gt;
will produce a matrix &amp;lt;tt&amp;gt;m&amp;lt;/tt&amp;gt; where each column represents an eigenvector and each row a particle. Thus, to see how a particular eigencomponent distributes among the particles, you can just write:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;plot(m(:,i),&#039;.&#039;);&amp;lt;/tt&amp;gt; &lt;br /&gt;
&lt;br /&gt;
[[ File:walkthroughPCACommandLine_firstEigencomponentOfEachParticle.png |thumb|center| 600px|first eigencomponent of each particle]]&lt;br /&gt;
&lt;br /&gt;
=== Series of plots===&lt;br /&gt;
To check all the eigencomponents, it is a good idea to do some scripting.  The script below uses a handy &#039;&#039;Dynamo&#039;&#039; trick to create several plots in the same figure.&lt;br /&gt;
 &amp;lt;nowiki&amp;gt; gui = mbgraph.montage();&lt;br /&gt;
for i=1:10&lt;br /&gt;
    plot(m(:,i),&#039;.&#039;,&#039;Parent&#039;,gui.gca);&lt;br /&gt;
    % gui.gca captures the&lt;br /&gt;
      gui.step;&lt;br /&gt;
end&lt;br /&gt;
gui.first();&lt;br /&gt;
gui.shg(); &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
this will produce ten plots (as i=1:10) collected in a single GUI. Each plot is called a &amp;quot;frame&amp;quot;, and you can view them sequentially or in sets, just play with the layout given by the rows and columns, and use the [Refresh] icon on the top left of the GUI.&lt;br /&gt;
 &lt;br /&gt;
[[ File:walkthroughPCACommandLine_slidingMontageOnTheDistributionOfSeveralEigencomponent.png |thumb|center| 600px|sliding montage on the distribution of several eigencomponent]]&lt;br /&gt;
=== Series of histograms ===&lt;br /&gt;
[[ File:walkthroughPCACommandLine_slidingMontageOfSetsOfEigencomponent.png |thumb|center| 600px|sliding montage of sets of eigencomponent]]&lt;br /&gt;
== Eigenvolumes ==&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;eigSet=wb.getEigenvolume(1:30);&amp;lt;/tt&amp;gt;&lt;br /&gt;
This creates a cell array (arbitrarily called &amp;lt;tt&amp;gt;eigSet&amp;lt;/tt&amp;gt;). We can visualise it through:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;mbvol.groups.montage(eigSet); &amp;lt;/tt&amp;gt;&lt;br /&gt;
[[ File:walkthroughPCACommandLine_eigenvolumes.png |thumb|center| 600px|eigenvolumes ]]&lt;br /&gt;
&lt;br /&gt;
This plot is showing the true relative intensity of the eigenvolumes. In order to compare them, we can show the normalised eigenvolumes instead:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;mbvol.groups.montage(dynamo_normalize_roi(eigSet)); &amp;lt;/tt&amp;gt;&lt;br /&gt;
[[ File:walkthroughPCACommandLine_eigenvolumesAfterNomrmalization.png |thumb|center| 600px|eigenvolumes after nomrmalization]]&lt;br /&gt;
==Correlation of tilts==&lt;br /&gt;
It is a good idea to check if some eigenvolumes correlate strongly with the tilt. &lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.show.correlationEigenvectorTilt(1:10) &amp;lt;/tt&amp;gt;&lt;br /&gt;
[[ File:walkthroughPCACommandLine_correlationOfEigencomponensWithTilt.png |thumb|center| 600px|correlation of eigencomponens with tilt]]&lt;br /&gt;
&lt;br /&gt;
Remember that each particle is accessible through right clicking on it.&lt;br /&gt;
[[ File:walkthroughPCACommandLine_rightClickOnEachPointToAccessTheParticle.png |thumb|center| 600px|right click on each point to access the particle]]&lt;br /&gt;
&lt;br /&gt;
In this plot, each point represents a particle in your data set. We see that in this particular experiment, eigencomponent 3 seems to have been &amp;quot;corrupted by the missing wedge&amp;quot;&lt;br /&gt;
&lt;br /&gt;
==TSNE reduction==&lt;br /&gt;
&lt;br /&gt;
We create on the fly the TSNE reduction for eigencomponents:&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.show.tsne([1,2,4,5]);&amp;lt;/tt&amp;gt;&lt;br /&gt;
will produce the graphics:&lt;br /&gt;
[[ File:walkthroughPCACommandLine_tsneClustering.png |thumb|center| 600px|tsne clustering]]&lt;br /&gt;
TSNE has created a bidimensional proximity map for the 4-dimensional distribution induced by the 4 selected eigenvectors. Note that you can enter a cell array of several sets of indices. You could then navigate through different indices to check the shape of the TSNE reduction for different selections of eigenvolumes:&lt;br /&gt;
 &amp;lt;tt&amp;gt;# wb.show.tsne({[1,2,4,5] , [1:6]});&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Automated clustering ===&lt;br /&gt;
Right clicking on a plot you get an option to automatically segment it using the &amp;lt;tt&amp;gt;dbscan&amp;lt;/tt&amp;gt; method&lt;br /&gt;
[[ File:walkthroughPCACommandLine_rightClickOnTheAxesForAnAutomatedClustering.png |thumb|center| 200px|right click on the axes for an automated clustering]]&lt;br /&gt;
This functionality is intended to let you get a feeling of the results you would get if you would use  &amp;lt;tt&amp;gt;dbscan&amp;lt;/tt&amp;gt; in an algorithm. &lt;br /&gt;
[[ File:walkthroughPCACommandLine_automatedClustering.png |thumb|center| 600px|automated clustering]]&lt;br /&gt;
The results are reasonable, but inferior to what human inspection would yield.&lt;br /&gt;
&lt;br /&gt;
=== Manual clustering ===&lt;br /&gt;
We first right click on the axis to get a lasso tool.&lt;br /&gt;
[[ File:walkthroughPCACommandLine_rightClickOnTheAxesToSelectASetOfParticles.png |thumb|center| 200px|right click on the axes to select a set of particles]]&lt;br /&gt;
Remember that you will have a different plot (depending on the random seed used in TSNE). However, you will probably have at least a well defined cluster.&lt;br /&gt;
[[ File:walkthroughPCACommandLine_useTheLassoToolToSelectAGroup.png |thumb|center| 600px|use the lasso tool to select a group]]&lt;br /&gt;
[[ File:walkthroughPCACommandLine_lassoedParticlesCanBeAveragedTogether.png |thumb|center| 600px|lassoed particles can be averaged together]]&lt;br /&gt;
[[ File:walkthroughPCACommandLine_averageOfParticlesInsideLasso.png |thumb|center| 600px|average of particles inside lasso]]&lt;br /&gt;
[[ File:walkthroughPCACommandLine_aSecondLassoCanBeCreated.png |thumb|center| 100px|a second lasso can be created]]&lt;br /&gt;
&lt;br /&gt;
After delimiting the second subset, we can create the class averages corresponding to this manual selection.&lt;br /&gt;
[[ File:walkthroughPCACommandLine_averageAllManuallySelectedClusters.png |thumb|center| 600px|average all manually selected clusters]]&lt;br /&gt;
&lt;br /&gt;
On opening, &amp;lt;tt&amp;gt;dmapview&amp;lt;/tt&amp;gt; will show all slices of a single volume:&lt;br /&gt;
[[ File:walkthroughPCACommandLine_dmapviewOnOpening.png |thumb|center| 600px|dmapview on opening]]&lt;br /&gt;
Use the &amp;quot;simultaneous view&amp;quot; icon in the toolbar to show the two volumes together.&lt;br /&gt;
[[ File:walkthroughPCACommandLine_showingSeveralVolumesInDmapview.png |thumb|center| 100px|showing several volumes in dmapview]]&lt;br /&gt;
[[ File:walkthroughPCACommandLine_correspondigSlicesOf.png |thumb|center| 600px|correspondig slices of  ]]&lt;br /&gt;
[[ File:walkthroughPCACommandLine_youCanSelectASingleSliceForDepiction.png |thumb|center| 600px|you can select a single slice for depiction]]&lt;br /&gt;
[[ File:walkthroughPCACommandLine_useKeys1And2ToSetAnchors.png |thumb|center| 600px|use keys 1 and 2 to set anchors]]&lt;br /&gt;
[[ File:walkthroughPCACommandLine_rightClickOneAnchorToShowAnIntensityProfile.png |thumb|center| 600px|right click one anchor to show an intensity profile]]&lt;br /&gt;
[[ File:walkthroughPCACommandLine_intensityProfile.png |thumb|center| 600px|intensity profile]]&lt;br /&gt;
&lt;br /&gt;
=Manipulation of PCA workflows=&lt;br /&gt;
==Reading workflows==&lt;br /&gt;
The workflow object can be recreated by reading the workflow folder.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb2 = dread(&#039;classtest128&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note that we can name the workflow with an arbitrary variable name. &lt;br /&gt;
The workflow needs to be unfolded before being used: &lt;br /&gt;
 &amp;lt;tt&amp;gt;wb2.unfold();&amp;lt;/tt&amp;gt;&lt;br /&gt;
This concerns not only recomputation of selected steps, but also use of graphical exploration options.&lt;br /&gt;
&lt;br /&gt;
==Workflow GUIs ==&lt;br /&gt;
&lt;br /&gt;
Execution of a PCA workflow can be controlled graphically through:&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.workflowGUI()&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Overview and edition of just the workflow parameters can be accessed through:&lt;br /&gt;
 &amp;lt;tt&amp;gt;wb.settings.editGUI&amp;lt;/tt&amp;gt;&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Events&amp;diff=5649</id>
		<title>Events</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Events&amp;diff=5649"/>
		<updated>2025-11-07T10:18:57Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;Presentation of Andres Molina Ribagorda. &amp;lt;/b&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Yearly report  (2025) of the Momentum project &amp;quot;Meta-learning for the automated analysis of high-resolution cryo-electron tomography images&amp;quot; &amp;lt;/b&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This public presentation will take place on the 7th of November 2025 at noon [[https://conecta.csic.es/rooms/uea-1un-58s-9om/join | in this link]].&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Main_Page&amp;diff=5624</id>
		<title>Main Page</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Main_Page&amp;diff=5624"/>
		<updated>2025-04-24T14:56:53Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: Adding logos of founding agencies&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{DISPLAYTITLE:&#039;&#039;Dynamo&#039;&#039;}}&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;Dynamo&#039;&#039; is a software environment for subtomogram averaging of cryo-EM data.&lt;br /&gt;
&lt;br /&gt;
This wiki [[Getting started|guides new &#039;&#039;Dynamo&#039;&#039; users]] all the way from tomograms to averages and classes. In a full workflow, you would  organize tomograms in [[Catalogue | catalogues]], use them to  [[Particle picking|pick particles]] and create [[Subtomogram alignment|alignment]] and  [[Classification |classification projects]] to be run on different [[computing environments]].&lt;br /&gt;
&lt;br /&gt;
= Participate =&lt;br /&gt;
&lt;br /&gt;
There is a [[https://groups.google.com/forum/#!forum/dynamo-for-cryo-electron-tomography forum in Google Groups]] where you can present your questions to developers and other users. Bear in mind that you need a Google account for this.&lt;br /&gt;
&lt;br /&gt;
= Cite =&lt;br /&gt;
Please cite these papers if &#039;&#039;Dynamo&#039;&#039; is useful in your research:&lt;br /&gt;
&lt;br /&gt;
* [http://www.sciencedirect.com/science/article/pii/S1047847711003650|&#039;&#039;Dynamo: A flexible, user-friendly development tool for subtomogram averaging of cryo-EM data in high-performance computing environments.&#039;&#039;] Castaño-Díez D, Kudryashev M, Arheit M, Stahlberg H., J. Struct. Biol. 2012.&lt;br /&gt;
&lt;br /&gt;
* [http://www.sciencedirect.com/science/article/pii/S1047847716301113| &#039;&#039;Dynamo Catalogue: Geometrical tools and data management for particle picking in subtomogram averaging of cryo-electron tomograms&#039;&#039;] Castaño-Díez D, Kudryashev M,  Stahlberg H., in J Struct Biol. 2017 Feb; 197(2):135-144&lt;br /&gt;
&lt;br /&gt;
* [https://doi.org/10.1107/S2059798317003369&#039;&#039;The Dynamo package for tomography and subtomogram averaging: components for MATLAB, GPU computing and EC2 Amazon Web Services&#039;&#039;] Castaño-Díez D. in Acta Crystallographica Section D: Structural Biology 73 (6).&lt;br /&gt;
&lt;br /&gt;
* [https://doi.org/10.3389/fmolb.2018.00082&#039;&#039;Protocols for Subtomogram Averaging of Membrane Proteins in the Dynamo Software Package&#039;&#039;] Navarro PP, Stahlberg H and Castaño-Díez D (2018). Front. Mol. Biosci. 5:82.&lt;br /&gt;
&lt;br /&gt;
* [https://journals.plos.org/plosbiology/article?id=10.1371/journal.pbio.3001318&#039;&#039;Step-by-step guide to efficient subtomogram averaging of virus-like particles with Dynamo&#039;&#039;] Scaramuzza S, Castaño-Díez D (2021). PLoS biology. 19(8):e3001318.&lt;br /&gt;
&lt;br /&gt;
* [https://doi.org/10.1016/j.str.2024.07.003 &#039;&#039;Automated fiducial-based alignment of cryo-electron tomography tilt series in Dynamo.&#039;&#039;], Coray et al. Structure, July 2024.&lt;br /&gt;
&lt;br /&gt;
= Founding Agencies = &lt;br /&gt;
&lt;br /&gt;
[[File:AE_logo.jpg|170px|left]] [[File: Snf_logo_rgb_standard_en_pos.png |400px|right]] [[File: Logo_hfsp.jpg |400px|center]]&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=File:AE_logo.jpg&amp;diff=5623</id>
		<title>File:AE logo.jpg</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=File:AE_logo.jpg&amp;diff=5623"/>
		<updated>2025-04-24T14:53:47Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: Andrés Molina reverted File:AE logo.jpg to an old version&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=File:AEI_logo.jpg&amp;diff=5622</id>
		<title>File:AEI logo.jpg</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=File:AEI_logo.jpg&amp;diff=5622"/>
		<updated>2025-04-24T14:53:13Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=File:Snf_logo_rgb_standard_en_pos.png&amp;diff=5621</id>
		<title>File:Snf logo rgb standard en pos.png</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=File:Snf_logo_rgb_standard_en_pos.png&amp;diff=5621"/>
		<updated>2025-04-24T14:46:34Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: Andrés Molina uploaded a new version of File:Snf logo rgb standard en pos.png&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=File:Snf_logo_rgb_standard_en_pos.png&amp;diff=5620</id>
		<title>File:Snf logo rgb standard en pos.png</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=File:Snf_logo_rgb_standard_en_pos.png&amp;diff=5620"/>
		<updated>2025-04-24T14:42:21Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=File:Logo_hfsp.jpg&amp;diff=5619</id>
		<title>File:Logo hfsp.jpg</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=File:Logo_hfsp.jpg&amp;diff=5619"/>
		<updated>2025-04-24T14:42:00Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=File:AE_logo.jpg&amp;diff=5618</id>
		<title>File:AE logo.jpg</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=File:AE_logo.jpg&amp;diff=5618"/>
		<updated>2025-04-24T14:41:43Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: Andrés Molina reverted File:AE logo.jpg to an old version&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=File:AE_logo.jpg&amp;diff=5617</id>
		<title>File:AE logo.jpg</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=File:AE_logo.jpg&amp;diff=5617"/>
		<updated>2025-04-24T14:40:50Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: Andrés Molina uploaded a new version of File:AE logo.jpg&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=File:AE_logo.jpg&amp;diff=5616</id>
		<title>File:AE logo.jpg</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=File:AE_logo.jpg&amp;diff=5616"/>
		<updated>2025-04-24T14:39:59Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Walkthrough_for_lattices_on_vesicles_(Tsinghua_Spring_School_2025)&amp;diff=5607</id>
		<title>Walkthrough for lattices on vesicles (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Walkthrough_for_lattices_on_vesicles_(Tsinghua_Spring_School_2025)&amp;diff=5607"/>
		<updated>2025-03-03T05:46:02Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Getting the data */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:WalkthroughsSpecific]]&lt;br /&gt;
&lt;br /&gt;
this walkthrough shows the approach to process proteins that cover spheroidal vesicles following (approximately) a structured lattice. For demonstration, we use a highly binned tomogram with several viral capsides.&lt;br /&gt;
&lt;br /&gt;
== Data ==&lt;br /&gt;
&lt;br /&gt;
The data has been made available by Florian Schur. This  single tomogram is part of the data set used for the paper &#039;&#039;An atomic model of HIV-1 capsid-SP1 reveals structures regulating assembly and maturation&#039;&#039; by  Schur FK, Obr M, Hagen WJ, Wan W, Jakobi AJ, Kirkpatrick JM, Sachse C, Kräusslich HG and Briggs JA. (2016)&lt;br /&gt;
&lt;br /&gt;
=== Getting the data ===&lt;br /&gt;
&lt;br /&gt;
Open a new local terminal and navigate to the directory where the practices are located:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkBasicHIVTomo/ &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Inside this folder, the file of interest is &amp;lt;code&amp;gt;v17.rec&amp;lt;/code&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
=== Viewing the data ===&lt;br /&gt;
&lt;br /&gt;
The tomogram is severely binned, so it will probably fit in memory without major problems. We can just use our typical tool to quick check a tomogram.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; dtmshow v17.rec &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:HivDtmshow.png |thumb|center|500px| &amp;lt;tt&amp;gt;dtmshow&amp;lt;/tt&amp;gt; on the sample tomogram. ]]&lt;br /&gt;
&lt;br /&gt;
== Annotation of a tomogram ==&lt;br /&gt;
&lt;br /&gt;
We are interested in cropping the particles between the two layers of each one of the viruses.&lt;br /&gt;
&lt;br /&gt;
[[ File:HivBox.png |thumb|center|400px| Structure to average]]&lt;br /&gt;
&lt;br /&gt;
We  open the tomogram v17.rec with &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmslice v17.rec -c hiv&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Here, the flag  &amp;lt;tt&amp;gt;-c hiv&amp;lt;/tt&amp;gt; will create a catalogue that will contain all the annotations that we perform on this volume (through the opened &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; session)&lt;br /&gt;
&lt;br /&gt;
=== DipoleSet models ===&lt;br /&gt;
&lt;br /&gt;
In our approach, we will first use a single model to manually input the approximate centers and radiuses of all the viruses. We will use the model type &amp;lt;tt&amp;gt;dipoleSet&amp;lt;/tt&amp;gt;. This model allows to describe each annotated virus as a &#039;&#039;dipole&#039;&#039;: we will mark the (approximate) center of the virus as the &amp;lt;tt&amp;gt;center&amp;lt;/tt&amp;gt; property of a dipole. The radius of the virus will be described by an annotation of the &amp;lt;tt&amp;gt;north&amp;lt;/tt&amp;gt; property of the dipole.  &lt;br /&gt;
&lt;br /&gt;
Notice that &#039;&#039;Dynamo&#039;&#039; includes several tools for [[vesicle models]], so you might be surprised that for this particular case we go instead for this (somewhat obscurely named) &#039;&#039;dipoleSet&#039;&#039; type of model. This is just a question of convenience: the &amp;lt;tt&amp;gt;dipoleSet&amp;lt;/tt&amp;gt; allows to quickly click a series of centers and radiuses and store them in a &#039;&#039;single&#039;&#039; model. That&#039;s all you need to describe vesicular geometry. Additionally, the &amp;lt;tt&amp;gt;dipoleSet&amp;lt;/tt&amp;gt; includes some tools for quickly extracting particles from a &#039;&#039;multivesicular&#039;&#039; set, and it also offers a useful on-screen representation in the &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; tomogram browser.&lt;br /&gt;
&lt;br /&gt;
[[File:HivSelectModel.png|thumb|center|600px| Selecting the &#039;&#039;dipoleSet&#039;&#039; model ]]&lt;br /&gt;
&lt;br /&gt;
When the model is active, we use the key &amp;lt;tt&amp;gt;c&amp;lt;/tt&amp;gt; to mark the &amp;lt;tt&amp;gt;center&amp;lt;/tt&amp;gt; of the current dipole, and &amp;lt;tt&amp;gt;n&amp;lt;/tt&amp;gt; to mark the north. It will create a semitransparent sphere enclosing the completed dipole.&lt;br /&gt;
&lt;br /&gt;
[[File:HivClickDipole.png |thumb|center|600px| Selecting a &#039;&#039;dipole&#039;&#039;: click on &amp;lt;tt&amp;gt;C&amp;lt;/tt&amp;gt; for the center, then &amp;lt;tt&amp;gt;N&amp;lt;/tt&amp;gt; for the north]]&lt;br /&gt;
&lt;br /&gt;
=== Corrections during picking ===&lt;br /&gt;
&lt;br /&gt;
Further clicks on &amp;lt;tt&amp;gt;c&amp;lt;/tt&amp;gt; or &amp;lt;tt&amp;gt;n&amp;lt;/tt&amp;gt; will just move the &amp;lt;tt&amp;gt;center&amp;lt;/tt&amp;gt; or the &amp;lt;tt&amp;gt;north&amp;lt;/tt&amp;gt; of the &#039;&#039;same&#039;&#039; dipole. In order to click a further dipole, you need to &#039;&#039;&#039;click on &amp;lt;tt&amp;gt;enter&amp;lt;/tt&amp;gt;&#039;&#039;&#039; and &amp;quot;open&amp;quot;  the next dipole for clicking. If you forget to click on &amp;lt;tt&amp;gt;enter&amp;lt;/tt&amp;gt; before annotating points on the next vesicle, you&#039;ll end up with situation like this: &lt;br /&gt;
&lt;br /&gt;
[[ File:HivForgetDipoleOpening.png |thumb|center|600px| Wrong input: &amp;lt;tt&amp;gt;enter&amp;lt;/tt&amp;gt; needed to be clicked between vesicles 2 and 3]]&lt;br /&gt;
&lt;br /&gt;
Here, the user probably clicked on &amp;lt;tt&amp;gt;c&amp;lt;/tt&amp;gt; for vesicle 2 in its real center, then clicked on &amp;lt;tt&amp;gt;n&amp;lt;/tt&amp;gt; for the north point, and then moved to vesicle 3, clicking on &amp;lt;tt&amp;gt;c&amp;lt;/tt&amp;gt; trying to mark the center. As a new dipole  was not opened (i.e., the &amp;lt;tt&amp;gt;enter&amp;lt;/tt&amp;gt; key was not pressed) when the vesicle 2 was finished, the center of vesicle 2 got misplaced.  When this happens, simply press on &amp;lt;tt&amp;gt;h&amp;lt;/tt&amp;gt; to hide the spheres and click the center of vesicle 2 back in its position. Then, press on &amp;lt;tt&amp;gt;enter&amp;lt;/tt&amp;gt; to start the next vesicle.&lt;br /&gt;
&lt;br /&gt;
=== Corrections after picking ===&lt;br /&gt;
&lt;br /&gt;
It is a good idea to observe your annotation from the &#039;&#039;x&#039;&#039; or &#039;&#039;y&#039;&#039;perspectives (for this, press on keys &amp;lt;tt&amp;gt;x&amp;lt;/tt&amp;gt; or  &amp;lt;tt&amp;gt;y&amp;lt;/tt&amp;gt; when the cursor is on the slide). Sometimes you might identify situations like this one:&lt;br /&gt;
&lt;br /&gt;
[[  File:HivWrongOnY.png|thumb|center|600px| Vesicle is too poorly picked]]&lt;br /&gt;
&lt;br /&gt;
In such cases, you want to remove the dipole and click it again. The easiest way to do so is to:&lt;br /&gt;
# click on &#039;h&#039; to hide the spheres, and&lt;br /&gt;
# secondary click on the wrongly created dipole (you have to click on the line itself) and select the &#039;&#039;Remove and prepare for reenter&#039;&#039; option in the menu that will popup.&lt;br /&gt;
&lt;br /&gt;
[[  File:HivWrongYReselect.png|thumb|center|600px| Remove dipole and click again]]&lt;br /&gt;
&lt;br /&gt;
When you are finished, don&#039;t forget to save the tomogram into the catalogue, using the disk icon (or the &#039;&#039;Active Model&#039;&#039; control)&lt;br /&gt;
&lt;br /&gt;
[[  File:HivFinalSelection.png |thumb|center|600px| Save model into catalogue]]&lt;br /&gt;
&lt;br /&gt;
== Cropping the particles ==&lt;br /&gt;
&lt;br /&gt;
We will describe a protocol to be carried from the command line, explaining each step. In short, we will visit each dipole in the model we just created, define a spherical vesicle centered on the dipole, use it to define a regular distribution of points on each vesicle, define positions pointing outwards and format everything as a [[table]] that can be used directly by &#039;&#039;Dynamo&#039;&#039; to operate an extraction and a subsequent alignment.&lt;br /&gt;
&lt;br /&gt;
=== Table extraction ===&lt;br /&gt;
&lt;br /&gt;
==== In Matlab  ====&lt;br /&gt;
&lt;br /&gt;
If you are working in Matlab, you can just proceed with &amp;lt;tt&amp;gt;dcmodels&amp;lt;/tt&amp;gt; to find the location of your dipole set. &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dcmodels hiv -tc dipoleSet -ws o -gm 1&lt;br /&gt;
&lt;br /&gt;
% assumes that you only have one model file &lt;br /&gt;
ds = o.models{1};&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===== Create a table for each vesicle =====&lt;br /&gt;
&lt;br /&gt;
Now we can loop on each dipole contained in the dipole set &amp;lt;tt&amp;gt;ds&amp;lt;/tt&amp;gt;.  The next lines should be copied into a text file (using matlab command &amp;lt;tt&amp;gt;edit&amp;lt;/tt&amp;gt;), and executed.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;NDipoles = length(ds.dipoles);&lt;br /&gt;
&lt;br /&gt;
for i=1:NDipoles;&lt;br /&gt;
   v =dmodels.vesicle();&lt;br /&gt;
   &lt;br /&gt;
   v.center = ds.dipoles{i}.center;&lt;br /&gt;
&lt;br /&gt;
   % defines the radius in terms of the clicked dipole &lt;br /&gt;
   v.radius = norm( ds.dipoles{i}.north - ds.dipoles{i}.center);&lt;br /&gt;
   &lt;br /&gt;
   % create a separation distance in the vesicle&lt;br /&gt;
   v.separation = 20;&lt;br /&gt;
&lt;br /&gt;
   % This parameter sets the cropping point a number of pixels away from the vesicle&lt;br /&gt;
   % this  distance in pixels  is measured in the normal direction.&lt;br /&gt;
   % here we just use the default value.&lt;br /&gt;
   v.crop_distance_from_surface =0;&lt;br /&gt;
   &lt;br /&gt;
   % creates the crop points and respective angles&lt;br /&gt;
   v.updateCrop();&lt;br /&gt;
   &lt;br /&gt;
   % extracts a table&lt;br /&gt;
   tv{i} = v.grepTable();&lt;br /&gt;
   &lt;br /&gt;
   % marks the table assigning in the column 22 (foreseen for arbitrary use)&lt;br /&gt;
   % the number of the individual dipole&lt;br /&gt;
   tv{i}(:,22) = i;&lt;br /&gt;
    &lt;br /&gt;
   % provides information on the output&lt;br /&gt;
   &lt;br /&gt;
   disp(sprintf(&#039;Dipole %d will provide %d crop points&#039;,i,size(v.crop_points,2)));&lt;br /&gt;
end &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
==== In the standalone ====&lt;br /&gt;
&lt;br /&gt;
The standalone can execute matlab scripts, with some restrictions: the scripts need to be self contained: any traffic of variables needs to be carried through writing and reading files. There is no other possibility of transferring workspace variables between your session and the script.&lt;br /&gt;
&lt;br /&gt;
===== Creating a text file =====&lt;br /&gt;
&lt;br /&gt;
Create a text file named &amp;lt;tt&amp;gt;commands.m&amp;lt;/tt&amp;gt; (arbitrary name) with any text editor available in your system. In Linux &amp;lt;tt&amp;gt;gedit&amp;lt;/tt&amp;gt; is probably available.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;gedit commands.m &amp;amp; &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Now paste the text of the commands excluding  comments (# simbols).&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;ds = dread(&amp;lt;YOUR FILE&amp;gt;);;&lt;br /&gt;
NDipoles = length(ds.dipoles);&lt;br /&gt;
&lt;br /&gt;
for i=1:NDipoles;&lt;br /&gt;
   v =dmodels.vesicle();&lt;br /&gt;
   v.center = ds.dipoles{i}.center;&lt;br /&gt;
   v.radius = norm( ds.dipoles{i}.north - ds.dipoles{i}.center);&lt;br /&gt;
   v.separation = 20;&lt;br /&gt;
   v.crop_distance_from_surface =0;&lt;br /&gt;
   v.updateCrop();&lt;br /&gt;
   tv{i} = v.grepTable();&lt;br /&gt;
   tv{i}(:,22) = i;&lt;br /&gt;
   disp(sprintf(&#039;Dipole %d will provide %d crop points&#039;,i,size(v.crop_points,1)));&lt;br /&gt;
end &lt;br /&gt;
dwrite(tv,&#039;cellOfTables.mat&#039;);&lt;br /&gt;
&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* Replace &amp;lt;tt&amp;gt;&amp;lt;YOUR FILE&amp;gt;&amp;lt;/tt&amp;gt; with the actual &amp;lt;tt&amp;gt;.omd&amp;lt;/tt&amp;gt; file that you created containing the dipoleSet model.&lt;br /&gt;
* Notice that we changed the variable input/output, by hardcoding the names of the files that need to be read and created.&lt;br /&gt;
&lt;br /&gt;
===== Executing the text file =====&lt;br /&gt;
&lt;br /&gt;
In a system shell or in &#039;&#039;Dynamo&#039;&#039;console, type:&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;tt&amp;gt;dynamo commands.m&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===== Getting the information back into the &#039;&#039;Dynamo&#039;&#039;console =====&lt;br /&gt;
In the &#039;&#039;Dynamo&#039;&#039; console, type.&lt;br /&gt;
 &amp;lt;tt&amp;gt;tv = dread(&#039;cellOfTables.mat&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Merging the tables ===&lt;br /&gt;
&lt;br /&gt;
Each dipole with number &amp;lt;tt&amp;gt;i&amp;lt;/tt&amp;gt; generated a table stored as &amp;lt;tt&amp;gt;tv{i}&amp;lt;/tt&amp;gt;, i.e., the entry &amp;lt;tt&amp;gt;i&amp;lt;/tt&amp;gt; inside the cell array &amp;lt;tt&amp;gt;t&amp;lt;/tt&amp;gt;. We want to generate a single table. Concatenating the table matrixes will not work, as it would have several particles with the same particle tags. We thus ask &#039;&#039;Dynamo&#039;&#039; to operate the table merging by itself, and renaming the particle tags. With the order:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tAll = dynamo_table_merge(tv,&#039;linear_tags&#039;,1);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
we concatenate the tables inside the cell array &amp;lt;tt&amp;gt;tv&amp;lt;/tt&amp;gt; and set the particle tags (in column 1) to be named from 1 to the maximal number of particles to be extracted from all the vesicles. You can check the result through&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtinfo(tAll);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
or graphically  through:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtplot(tAll,&#039;pf&#039;,&#039;oriented_positions&#039;);axis equal &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:HivDtplotAll.png |thumb|center|600px| &amp;lt;tt&amp;gt;dtplot&amp;lt;/tt&amp;gt; graphic of merged table]]&lt;br /&gt;
&lt;br /&gt;
There are several programs to depict tables. In this case we may find &amp;lt;tt&amp;gt;dpktbl.plot.disks&amp;lt;/tt&amp;gt; useful, as it allows to depict the particles in a table with an associated extent. This is useful to check how a given sidelength in pixels covers the vesicles for a given particle distribution.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpktbl.plots.disks(tAll,&#039;r&#039;,10);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:HivDisks.png|thumb|center|600px| &amp;lt;tt&amp;gt;dpktbl.plot.disks&amp;lt;/tt&amp;gt; graphic of merged table]]&lt;br /&gt;
&lt;br /&gt;
=== Create a data folder ===&lt;br /&gt;
&lt;br /&gt;
We can now create our typical [[data folder]] with dtcrop with a single command. &lt;br /&gt;
 &amp;lt;nowiki&amp;gt;targetFolder = &#039;testData&#039;;&lt;br /&gt;
sidelength = 40;&lt;br /&gt;
check = dtcrop(ds.cvolume.file,tAll,targetFolder,sidelength); &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note that that &amp;lt;tt&amp;gt;dtcrop&amp;lt;/tt&amp;gt; will create a new file that contains only the particles that were actually cropped from the tomogram.  Some particles were probably excluded if they were too close to the boundary of the tomogram. We can read this table file into memory.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;finalTable = dread([targetFolder,&#039;/crop.tbl&#039;]);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Checking the particles can be done with the interactive browsers &amp;lt;tt&amp;gt;ddbrowse&amp;lt;/tt&amp;gt; or &amp;lt;tt&amp;gt;dgallery&amp;lt;/tt&amp;gt;, but for a quick check we can use the &amp;lt;tt&amp;gt;dslices&amp;lt;/tt&amp;gt; command:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dslices(targetFolder,&#039;projy&#039;,&#039;*&#039;,&#039;t&#039;,finalTable,&#039;align&#039;,1,&#039;tag&#039;,1:10:700,&#039;labels&#039;,&#039;on&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Here, we selected only one every ten tags to get a general idea on what is going on. The flag &amp;lt;tt&amp;gt;&#039;projy&#039;,&#039;*&#039;&amp;lt;/tt&amp;gt; creates a projection of the aligned particles along &#039;&#039;y&#039;&#039;, projecting all the slides, so that we can check that we are indeed greping the  capsides.&lt;br /&gt;
&lt;br /&gt;
[[ File:HivDdbrowseInitial.png |thumb|center|600px| &amp;lt;tt&amp;gt;dslices&amp;lt;/tt&amp;gt; on a subset of particles, &#039;&#039;y&#039;&#039; projection view]]&lt;br /&gt;
&lt;br /&gt;
We see that there are different problems: we are not hitting the center of the region of interest in many particles, and in some particles the region is out of scope.&lt;br /&gt;
&lt;br /&gt;
=== Create a coarse average ===&lt;br /&gt;
&lt;br /&gt;
We create a &amp;quot;coarse average&amp;quot; by just averaging all the particles with the orientations from the table, i.e, just the normals.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;oa = daverage(targetFolder,&#039;t&#039;,finalTable,&#039;fc&#039;,1); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We can quickly check the result through: &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dview(oa)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:HivAverageLow.png |thumb|center|600px| &amp;lt;tt&amp;gt;view&amp;lt;/tt&amp;gt; of the coarse average]]&lt;br /&gt;
&lt;br /&gt;
In this case, the area of interest is probably too low in the direction &#039;z&#039;: the upper half of the average is occupied by buffer. We want to lift the cropping point of the particles a little bit &amp;quot;downwards&amp;quot;, that is, in the negative normal direction.&lt;br /&gt;
&lt;br /&gt;
=== Recropping the particles ===&lt;br /&gt;
&lt;br /&gt;
Well, the protocol that we have described step by step in the previous steps can actually be completed with a single command: the method  &amp;lt;tt&amp;gt;getTableFromEnclosingSpheres&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A complete syntax description can be found it: &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;help dmodels.dipoleSet.getTableFromEnclosingSpheres&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We just want to extract a data folder where the particles are better centered and have bit more of space, so that particles stamming from spheres that are poorly defined still have a chance to get driven by a posterior alignment to the center of the box.  If we initialize some variables:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;sep    = 20; % for &#039;separation&#039; flag. This is the separation between particles&lt;br /&gt;
cdfs   = -12; % for &#039;crop_distance_from_surface&#039; flag, in pixels&lt;br /&gt;
df     = &#039;centeredData&#039;; % for &#039;dataFolder&#039; flag. It is the data folder were the particles will be created.&lt;br /&gt;
sidelength = 64;&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
the full task can be completed in one step:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;[tnew,og] = ds.getTableFromEnclosingSpheres(&#039;sep&#039;,sep,&#039;cdfs&#039;,cdfs,&#039;df&#039;,df,&#039;s&#039;, sidelength,&#039;average&#039;,1,&#039;mw&#039;,2);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Here the &amp;lt;tt&amp;gt;mw&amp;lt;/tt&amp;gt; flag just calls for 2 cores to carry the average. If you don&#039;t have a license for the Parallel Toolbox, simply don&#039;t use the flag. &lt;br /&gt;
&lt;br /&gt;
Also, notice that two outputs are produced. The first one is just the table, (including also excluded particles!). The second one includes a more detailed output, including a field &amp;lt;tt&amp;gt;averageOutput&amp;lt;/tt&amp;gt; that corresponds to the output of the average operation on the newly created data folder &amp;lt;tt&amp;gt;centeredData&amp;lt;/tt&amp;gt;. You can view it with the normal &amp;lt;tt&amp;gt;dview&amp;lt;/tt&amp;gt; command:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dview(og.averageOutput.average);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:HivAverageCentered.png |thumb|center|600px| &amp;lt;tt&amp;gt;dview&amp;lt;/tt&amp;gt; on &#039;&#039;y&#039;&#039; and &#039;&#039;z&#039;&#039; of the newly computed coarse average]]&lt;br /&gt;
&lt;br /&gt;
== Alignment project ==&lt;br /&gt;
&lt;br /&gt;
The particles can now be aligned using the table and template that we just defined. We just need to write them into files&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dwrite(dread([df,&#039;/crop.tbl&#039;]),&#039;centered.tbl&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and the density map hidden in the output:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dwrite(og.averageOutput.average,&#039;centered.em&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and create a [[alignment project | project]]&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;pr = &#039;pcnt&#039;; % pr is a variable, &amp;quot;pcnt&amp;quot; is a literal string  &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We create an empty project pointing to the right data, template and table:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcp.new(pr,&#039;d&#039;,df,&#039;t&#039;,&#039;centered.tbl&#039;,&#039;template&#039;,&#039;centered.em&#039;,&#039;masks&#039;,&#039;default&#039;,&#039;show&#039;,0);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Putting the &#039;show&#039; flag to zero prevented the [[Dcp GUI | &amp;lt;tt&amp;gt;dcp&amp;lt;/tt&amp;gt; GUI]]  from popping up, as we want to use this walkthrough as an example of how to create and manage projects from the command line. The basic tool is &amp;lt;tt&amp;gt;dvput&amp;lt;/tt&amp;gt;, which is used to change one or several project parameters. A list of the parameters and their syntax can be printed with &amp;lt;tt&amp;gt;dvhelp&amp;lt;/tt&amp;gt; or consulted through the GUI &amp;lt;tt&amp;gt;dhelp&amp;lt;/tt&amp;gt;. For this particular project we suggest the set below: &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvput(pr,&#039;ite_r1&#039;,4);&lt;br /&gt;
dvput(pr,&#039;dim_r1&#039;,32);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the stage of finding general orientations and coarse centerings, we want to save computing time (without trading accuracy). Thus, we use the &amp;lt;tt&amp;gt;&#039;dim_r1&#039;&amp;lt;/tt&amp;gt; parameters tune to 32. As the particle boxes have a sidelength of 64 pixels,  here we are asking &#039;&#039;Dynamo&#039;&#039; to bin each particle on the fly, just one time. A neighboorhod of 2x2x2 voxels will collapse into one single voxel, with the averaged intensity.  By now, we are just interested in coarsely locating the particles, so that the speed-up in the alignemnt (8x) justifies the loss of accuracy. &lt;br /&gt;
&lt;br /&gt;
Next, we need angular settings reflect that we trust the normals that we have found. This will save computation time and make the alignment more robust.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvput(pr,&#039;cr_r1&#039;,40);&lt;br /&gt;
dvput(pr,&#039;cs_r1&#039;,20);&lt;br /&gt;
dvput(pr,&#039;ir_r1&#039;,360);&lt;br /&gt;
dvput(pr,&#039;is_r1&#039;,40);&lt;br /&gt;
dvput(pr,&#039;rf_r1&#039;,4);&lt;br /&gt;
dvput(pr,&#039;rff_r1&#039;,2);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We let the particles shift, but not the the edges of the box:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvput(pr,&#039;lim_r1&#039;,[20,20,20]);&lt;br /&gt;
dvput(pr,&#039;limm_r1&#039;,1);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Some parameters re provided to control the execution. For projects to be run in parallel under Matlab, we need the &amp;lt;tt&amp;gt;&#039;destination&#039;&amp;lt;/tt&amp;gt; parameter tuned to value &amp;lt;tt&amp;gt;&#039;matlab_parfor&#039;&amp;lt;/tt&amp;gt;. We also provide a value for the number of cores to be used during the alignments (parameter &amp;lt;tt&amp;gt;&#039;cores&#039;&amp;lt;/tt&amp;gt;) and the averaging steps (parameter &amp;lt;tt&amp;gt;matlab_workers_average&amp;lt;/tt&amp;gt;).&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dvput(pr,&#039;dst&#039;,&#039;matlab_parfor&#039;,&#039;cores&#039;,2,&#039;mwa&#039;,2);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Run project ===&lt;br /&gt;
&lt;br /&gt;
As we would do the  GUI, we have to check, unfold and run the project:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvcheck pcnt&lt;br /&gt;
dvunfold pcnt&lt;br /&gt;
dvrun pcnt&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==== In scripted protocols ====&lt;br /&gt;
 &#039;&#039;Advanced&#039;&#039;: A note for future projects: when your own scripts to run several projects created dynamically, you can put the name of the project into a variable (as we did above) and use the &amp;lt;tt&amp;gt;( ) &amp;lt;/tt&amp;gt; notation:&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvcheck(pr);&lt;br /&gt;
dvunfold(pr);&lt;br /&gt;
dvrun(pr);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
When used inside a script, you probably want to use the &amp;lt;tt&amp;gt;;&amp;lt;/tt&amp;gt; at the end of each line, to prevent flooding the screen with output.&lt;br /&gt;
&lt;br /&gt;
=== Check results ===&lt;br /&gt;
&lt;br /&gt;
We can check how the particles look like:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dslices(&#039;pcnt:data&#039;,&#039;projy&#039;,&#039;*&#039;,&#039;t&#039;,&#039;pcnt:rt:ite=3&#039;,&#039;align&#039;,1,&#039;tag&#039;,1:10:700,&#039;labels&#039;,&#039;on&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Here, &amp;lt;tt&amp;gt;&#039;pcnt:data&#039;&amp;lt;/tt&amp;gt; is a database query. it is just a shorthand to tell &#039;&#039;Dynamo&#039;&#039; to use the data folder associated with the project &amp;lt;tt&amp;gt;pcnt&amp;lt;/tt&amp;gt;. The same trick is used to extract the refined table (&amp;lt;tt&amp;gt;rt&amp;lt;/tt&amp;gt;) at iteration 3. Don&#039;t worry if you don&#039;t like this notation: you can just input the actual folder and file names.&lt;br /&gt;
&lt;br /&gt;
[[ File:HivDDbrowseCentered.png |thumb|center|600px| &amp;lt;tt&amp;gt; dslices &amp;lt;/tt&amp;gt; of a selection of aligned particles]]&lt;br /&gt;
&lt;br /&gt;
The averages can be consulted with &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt;. We open the averages (&amp;lt;tt&amp;gt;a&amp;lt;/tt&amp;gt; item) corresponding to iterations 0 and 4:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(&#039;pcnt:a:ite=[0,4]&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can tweak the visualization to see a depiction of how the average evolved from the first template to iteration number 4.&lt;br /&gt;
&lt;br /&gt;
[[ File:HivMapviewEvolution.png |thumb|center|600px|  Interactive slice comparison through &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt; ]]&lt;br /&gt;
&lt;br /&gt;
As a tip, when you know exactly which features you want to test visually, you can use the command line order &amp;lt;tt&amp;gt;dslices&amp;lt;/tt&amp;gt; to directly produce the scene of interest:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dslices pcnt:a:ite=[0,4] -projy 44 -ns 1&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[  File:HivSlicesEvolution.png|thumb|center|600px| Programatic slice comparison through &amp;lt;tt&amp;gt;dslices&amp;lt;/tt&amp;gt; ]]&lt;br /&gt;
&lt;br /&gt;
== Recropping the particles ==&lt;br /&gt;
&lt;br /&gt;
You can create a new table excluding particles that are too close to each other:&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;tt&amp;gt;tc = dpktbl.exclusionPerVolume(&#039;pcnt:rt:ite=4&#039;,15,22);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
where 15 is a distance in pixels. The third parameter denotes the column in the table that denotes particles in the same objects. In this case, we have marked each virus with a different integer in column 22 of the table, and we pass this information to &amp;lt;tt&amp;gt;dpktbl.exclusionPerVolume&amp;lt;/tt&amp;gt;.&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Getting_a_Structure_from_Multiple_Tomograms_of_HIV_Capsids_(Tsinghua_Spring_School_2025)&amp;diff=5606</id>
		<title>Getting a Structure from Multiple Tomograms of HIV Capsids (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Getting_a_Structure_from_Multiple_Tomograms_of_HIV_Capsids_(Tsinghua_Spring_School_2025)&amp;diff=5606"/>
		<updated>2025-03-03T05:45:31Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Data */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:WalkthroughsSpecific]]&lt;br /&gt;
&lt;br /&gt;
In this walkthrough you will get familiar with managing multiple tomograms through the &#039;&#039;Dynamo&#039;&#039; catalogue and developing strategies for alignment projects to reach a reasonable structure from a set of tomograms. You will make use of the knowledge that you acquired during the workshop and apply it to a more realistic case. It is recommended to get familiar with the [[ Complete walkthrough on FHV virus (Copenhagen 2024) | advanced starters guide]] and the [[Walkthrough for lattices on vesicles (Copenhagen 2024)| walkthrough for lattices on vesicles]] before starting this walkthrough. &lt;br /&gt;
&lt;br /&gt;
== Data ==&lt;br /&gt;
We prepared a set of 6 tomograms, each containing one Immature HIV-1 virus like particle (VLP) with a layer formed by a lattice of capsid proteins. The capsid proteins have a C6 symmetry, a diameter of roughly 15nm and a molecular weight of about 150kDa. The pixelsize of the tomograms is 2.7 angstrom. You can find the tomograms in:&lt;br /&gt;
 &amp;lt;tt&amp;gt; /mnt/fs/2025workshop/Users/user**/Data/DownloadLindVLPs/ &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The tomograms are part of the data that was used in the publication &#039;&#039;An atomic model of HIV-1 capsid-SP1 reveals structures regulating assembly and maturation&#039;&#039; by  Schur FK, Obr M, Hagen WJ, Wan W, Jakobi AJ, Kirkpatrick JM, Sachse C, Kräusslich HG and Briggs JA. (2016). The full dataset can be found on the Electron Microscopy Public Image Archive (EMPIAR) under [https://www.ebi.ac.uk/pdbe/emdb/empiar/entry/10164/ EMPIAR-10164]. The 6 tomograms were extracted from the tilt series TS_03 and TS_43.&lt;br /&gt;
&lt;br /&gt;
== Goal==&lt;br /&gt;
From the data given you should be able to get a final average in which you start seeing hints of alpha helices, i.e., it should be possible to reach a resolution close to roughly 10 angstroms. &lt;br /&gt;
&lt;br /&gt;
== Walkthrough  ==&lt;br /&gt;
=== Set up a catalogue ===&lt;br /&gt;
Create a new [[catalogue|catalogue]]&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcm -create catVLP&amp;lt;/tt&amp;gt;&lt;br /&gt;
and open it in the catalogue manager&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcm catVLP&amp;lt;/tt&amp;gt;&lt;br /&gt;
You can add each volume manually to the catalogue under &#039;&#039;Catalogue -&amp;gt; Browse for new volume&#039;&#039; or you can make use of a [[volume list file|volume file]] and add all tomograms at once under &#039;&#039;Catalogue -&amp;gt; Input list of tomograms -&amp;gt; Browse for text file (.vll file)&#039;&#039;. The volume file should be created beforehand by opening a blank text file named for example &amp;lt;code&amp;gt;VLPtomograms.vll&amp;lt;/code&amp;gt; and copy the paths of all tomograms into it:&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;vlp_1.mrc&lt;br /&gt;
vlp_2.mrc&lt;br /&gt;
vlp_3.mrc&lt;br /&gt;
vlp_4.mrc&lt;br /&gt;
vlp_5.mrc&lt;br /&gt;
vlp_6.mrc&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In case you imported the tomograms using a volume file you have to click the button &#039;&#039;list volumes&#039;&#039; to refresh the tomogram list in the catalogue manager. Now you should see the 6 tomograms in the catalogue manager. [[Prebinned_tomograms|Prebin]] the tomograms once (1x) under &#039;&#039;Catalogue -&amp;gt; Create binned versions -&amp;gt; with factor 1&#039;&#039;. You can now look at single tomograms in [[dtmslice|tomoslice]] by selecting a tomogram of choice in the catalogue manager and then go under &#039;&#039;View volume -&amp;gt; Load full prebinned Volume [if available] -&amp;gt; open in tomoslice&#039;&#039;. If needed, adjust the lowpass level and contrast in tomoslice to improve the depiction.&lt;br /&gt;
&lt;br /&gt;
=== Annotate tomograms ===&lt;br /&gt;
To know where we want to later extract the subvolumes we have to first annotate the surfaces of the VLPs inside the tomograms. We do this by opening a tomogram inside tomoslice where a so called dipole Set model is defined. How to do that is described in detail in the section &#039;&#039;DipoleSet models&#039;&#039;, &#039;&#039;Corrections during picking&#039;&#039; and &#039;&#039;Corrections after picking&#039;&#039; of the [[Walkthrough_for_lattices_on_vesicles | walkthrough for lattices on vesicles]]. A new dipole set model has to be made for each tomogram. Save each model before closing tomoslice and when opening a new tomogram in tomoslice select &#039;&#039;Delete from memory&#039;&#039; if asked. In case you see markers of the previously defined dipole set inside the newly opened tomogram make sure the model pool is empty and click on &#039;&#039;reset scene&#039;&#039; before defining the new dipole set. Once you went through all tomograms click on the button &#039;&#039;list volumes&#039;&#039; inside the catalogue manager to refresh the list of tomograms. In the column &#039;&#039;model files&#039;&#039; of the tomogram list of the catalogue manager you should now see that you have one defined model per tomogram.&lt;br /&gt;
&lt;br /&gt;
=== Define crop points ===&lt;br /&gt;
To extract subvolumes (crop particles) we need to first define the crop points on the surface of the VLPs using the previously defined models. The crop points are then stored in a table. This is all done with the following script which is an extended version of the one found in the [[Walkthrough_for_lattices_on_vesicles | walkthrough for lattices on vesicles]]. Note that we [[Seed_oversampling|oversample]] the VLPs, i.e., we define enough crop points such that every protein has the chance to end up in at least one subvolume. We will take care of proteins that end up in more than subvolume in a later step. Note that this script assumes that there are exactly 6 tomograms with only one model for each tomogram. In cases where a different number of tomograms or models is used, the script has to be adapted accordingly.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;% read dipole from catalogue into workspace&lt;br /&gt;
dcmodels catVLP -tc dipoleSet -ws o -gm 1&lt;br /&gt;
&lt;br /&gt;
c=1; % counter for table&lt;br /&gt;
for tomo = 1:6 % loop over tomograms&lt;br /&gt;
    ds = o.models{tomo};                  % read models&lt;br /&gt;
    NDipoles = length(ds.dipoles);&lt;br /&gt;
    for i=1:NDipoles                      % loop over models (in our case just one per tomogram)&lt;br /&gt;
        v = dmodels.vesicle();            % create empty vesicle model&lt;br /&gt;
        v.center = ds.dipoles{i}.center;  % add center from dipole to vesicle model&lt;br /&gt;
        v.radius = norm( ds.dipoles{i}.north - ds.dipoles{i}.center); % add radius&lt;br /&gt;
        v.separation = 60;                % separation of crop points (in px)&lt;br /&gt;
        v.crop_distance_from_surface =0;&lt;br /&gt;
        v.updateCrop();                   % update vesicle model&lt;br /&gt;
&lt;br /&gt;
        tv{c} = v.grepTable(); % create crop table from using vesicle model&lt;br /&gt;
        tv{c}(:,22) = i;       % add model number to table&lt;br /&gt;
        tv{c}(:,20) = tomo;    % add tomogram number to table&lt;br /&gt;
        c=c+1;&lt;br /&gt;
    end&lt;br /&gt;
end&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
In the &#039;&#039;&#039;standalone version&#039;&#039;&#039; you need to proceed as follows:&lt;br /&gt;
&lt;br /&gt;
1.) Open a text file named &amp;lt;code&amp;gt;commands.m&amp;lt;/code&amp;gt; and copy the following into the file (avoid commenting with % or #):&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;o=dcmodels(&#039;catVLP&#039;,&#039;tc&#039;,&#039;dipoleSet&#039;,&#039;gm&#039;,1);&lt;br /&gt;
c=1;&lt;br /&gt;
for tomo = 1:6&lt;br /&gt;
    ds = dread(o{tomo});&lt;br /&gt;
    NDipoles = length(ds.dipoles);&lt;br /&gt;
    for i=1:NDipoles&lt;br /&gt;
        v = dmodels.vesicle();&lt;br /&gt;
        v.center = ds.dipoles{i}.center;&lt;br /&gt;
        v.radius = norm( ds.dipoles{i}.north - ds.dipoles{i}.center);&lt;br /&gt;
        v.separation = 60;&lt;br /&gt;
        v.crop_distance_from_surface =0;&lt;br /&gt;
        v.updateCrop();&lt;br /&gt;
        tv{c} = v.grepTable();&lt;br /&gt;
        tv{c}(:,22) = i;&lt;br /&gt;
        tv{c}(:,20) = tomo;&lt;br /&gt;
        c=c+1;&lt;br /&gt;
        disp(sprintf(&#039;Dipole %d will provide %d crop points&#039;,i,size(v.crop_points,2)));&lt;br /&gt;
    end&lt;br /&gt;
end&lt;br /&gt;
dwrite(tv,&#039;cellOfTables.mat&#039;);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
2.) Execute the text file in a system shell or in the &#039;&#039;Dynamo&#039;&#039; console:&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;tt&amp;gt;dynamo commands.m&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
3.) When you are back in the &#039;&#039;Dynamo&#039;&#039; console, you can load the results from the script into the workspace with&lt;br /&gt;
 &amp;lt;tt&amp;gt;tv = dread(&#039;cellOfTables.mat&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Type &#039;&#039;whos&#039;&#039; to display the actual matlab workspace and to check if the variable &#039;&#039;tv&#039;&#039; was loaded correctly.&lt;br /&gt;
&lt;br /&gt;
=== Write table with crop points ===&lt;br /&gt;
&lt;br /&gt;
The tables beloning to each dipole model are stored in the cell array &#039;&#039;tv&#039;&#039;. To create one single table containing all crop points we merge all tables into one with the command&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tAll = dynamo_table_merge(tv,&#039;linear_tags&#039;,1); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and visualize the table to see the crop points and their orientations (when visualizing actual results of an alignment project use option &#039;&#039; &#039;corrected_oriented_positions&#039;&#039; &#039; instead of the one shown here).&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtplot(tAll,&#039;pf&#039;,&#039;oriented_positions&#039;); axis equal&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You should get something like:&lt;br /&gt;
&lt;br /&gt;
 [[File:Result_table_vlp.png|thumb|center|400px| Crop points in table.]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
=== Extract subvolumes ===&lt;br /&gt;
&lt;br /&gt;
Before extracting the subvolumes (cropping particles) using the previously generated table we have to define a so called [[Tomogram-table map file|tomogram table map file]] which links the tomogram identification number in column 20 of the previously created table to an actual tomogram on the disk. Create a file named &amp;lt;code&amp;gt;VLPtomograms.doc&amp;lt;/code&amp;gt; and copy the tomogram numbers and full paths of the tomograms into it:&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;1 vlp_1.mrc&lt;br /&gt;
2 vlp_2.mrc&lt;br /&gt;
3 vlp_3.mrc&lt;br /&gt;
4 vlp_4.mrc&lt;br /&gt;
5 vlp_5.mrc&lt;br /&gt;
6 vlp_6.mrc&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Define a destination for the cropped particles:&lt;br /&gt;
 &amp;lt;tt&amp;gt;targetFolder = &#039;./particlesSize128&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Now we can crop the particles with sidelength 128 pixels from the tomograms using the table previously defined.&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtcrop(&#039;VLPtomograms.doc&#039;,tAll,targetFolder,128);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The cropping on one core should not take longer than 5 minutes. &lt;br /&gt;
&lt;br /&gt;
We create a plain average of all cropped particles to asses the quality of the cropped particles. First we read the table of the cropped particles:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;finalTable = dread([targetFolder &#039;/crop.tbl&#039;]);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We can also visualise the particles:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dslices(targetFolder,&#039;projy&#039;,&#039;*&#039;,&#039;t&#039;,finalTable,&#039;align&#039;,1,&#039;tag&#039;,1:10:500,&#039;labels&#039;,&#039;on&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Then we form the average&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;oa = daverage(targetFolder,&#039;t&#039;,finalTable,&#039;fc&#039;,1);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and inspect the average with&lt;br /&gt;
 &amp;lt;tt&amp;gt;dview(oa.average)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You should see a faint and noisy curvature of a thick membrane-like structure in the X and Y view.&lt;br /&gt;
&lt;br /&gt;
 [[File:VLP_raw128_x.png|thumb|center|170px| Average of cropped particles (X view).]]&lt;br /&gt;
&lt;br /&gt;
We will use this average as a first reference (template) in the next alignment project. We therefore save the average with&lt;br /&gt;
 &amp;lt;tt&amp;gt;dwrite(oa.average,[targetFolder &#039;/template.em&#039;]);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Hint: When dealing with preferred orientations, randomizing the azimuth of the particles bevore averaging can help (in this tutorial this is not needed):&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tRandAz = dynamo_table_randomize_azimuth(t);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== First alignment project ===&lt;br /&gt;
Now we create our first [[alignment project | alignment project]] through the command line in a similar way as described in detail in the [[Walkthrough_for_lattices_on_vesicles | walkthrough for lattices on vesicles]]. First we define a project name&lt;br /&gt;
 &amp;lt;tt&amp;gt;pr = &#039;aliVLP&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Then we create the alignment project with the particles, template and table that we defined before. The masks are set to default.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcp.new(pr,&#039;d&#039;,targetFolder,&#039;t&#039;,[targetFolder &#039;/crop.tbl&#039;],&#039;template&#039;,[targetFolder &#039;/template.em&#039;],&#039;masks&#039;,&#039;default&#039;,&#039;show&#039;,0);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Next we set up the numerical parameters for the project and the computing environment (type &#039;&#039;dvhelp&#039;&#039;  in the console for an overview of all parameters). We use 2x binned particles and a rather coarse angular search. The shift limits are very generous in order to make sure all particles have the chance to &#039;see&#039; each other.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvput(pr,&#039;ite_r1&#039;,4);&lt;br /&gt;
dvput(pr,&#039;dim_r1&#039;,32);&lt;br /&gt;
dvput(pr,&#039;cr_r1&#039;,40);&lt;br /&gt;
dvput(pr,&#039;cs_r1&#039;,20);&lt;br /&gt;
dvput(pr,&#039;ir_r1&#039;,360);&lt;br /&gt;
dvput(pr,&#039;is_r1&#039;,40);&lt;br /&gt;
dvput(pr,&#039;rf_r1&#039;,4);&lt;br /&gt;
dvput(pr,&#039;rff_r1&#039;,2);&lt;br /&gt;
dvput(pr,&#039;lim_r1&#039;,[40,40,40]);&lt;br /&gt;
dvput(pr,&#039;limm_r1&#039;,1);&lt;br /&gt;
dvput(pr,&#039;dst&#039;,&#039;standalone_gpu&#039;,&#039;cores&#039;,1,&#039;mwa&#039;,2);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Everything can of course also be set up through the alignment project GUI. The numerical parameters would correspond to:&lt;br /&gt;
&lt;br /&gt;
 [[File:VLP_first_parameters.png|thumb|center|400px| Alignment parameters for first alignment project.]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Check, unfold and run the project through the alignment project GUI or through the command line:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvcheck aliVLP&lt;br /&gt;
dvunfold aliVLP&lt;br /&gt;
dvrun aliVLP&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
On one GPU (and 2 cores for averaging) the alignment project should not take longer than half an hour. Check the status of the alignment project with&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dvstatus aliVLP&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can also see the average of the last computed iteration in &#039;&#039;dmapview&#039;&#039; with the command. If needed, adjust the lowpass and contrast to improve the depiction.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(&#039;aliVLP:a&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Recenter and recrop ===&lt;br /&gt;
After the alignment project finished successfully we can inspect the last computed average with the same command introduced before:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(&#039;aliVLP:a&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The command can be extended to see the averages of all iterations including the starting reference. Once in &#039;&#039;dmapview&#039;&#039;, press the button &#039;&#039;norm&#039;&#039; to properly compare the averages.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(&#039;aliVLP:a:ite=0:last&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the last average, you should already start to see a hexagonal lattice. We now want to make sure that the center of one C6 subunit of the lattice coincides with the center of the subvolume and that the subunits symmetry axis is parallel to the Z axis of the subvolume. This will allow us to later recrop the subvolumes with a smaller box size and to choose finer alignment parameters in the next alignment project. The recentering and realigning can be done in two steps. First, we subbox the particles using a new, manually defined box center and recrop the particles with a smaller boxsize. Second, we align the symmetry axis using a synthetic template. Both procedures are described in detail in the [[Advanced_starters_guide | advanced starters guide]] in the section &#039;&#039;Aligning the axis of symmetry&#039;&#039; and &#039;&#039;Subboxing &#039;&#039; and are now applied here.&lt;br /&gt;
&lt;br /&gt;
====Step 1: Subboxing====&lt;br /&gt;
&lt;br /&gt;
Open the last computed average in &#039;&#039;dmapview&#039;&#039; as previously described. Activate the radio buttons for the &#039;&#039;Center/North&#039;&#039; tools under &#039;&#039;Clicks&#039;&#039;. You can now click anywhere on the average and see the corresponding coordinates. Find the coordinates of the center of one subunit of the lattice. Switch between X,Y and Z view to make sure the center is correct. In our case we found the center of a subunit at [88,75,72]. For you these coordinates might be different.&lt;br /&gt;
&lt;br /&gt;
 [[File:VLP_center_xy.jpg|thumb|center|600px| Finding the coordinates of the center of a lattice subunit.]]&lt;br /&gt;
&lt;br /&gt;
Copy the found coordinates of the center of the subunit into the first vector of the command below. To compute the vector from the center of the subvolume to the center of a subunit we need to subtract the coordinates of the center of the subvolume. The [[Volume_center|center of a subvolume]] with a sidelength of 128 pixels is defined as [65,65,65].&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;rSubunitFromCenter = [88,75,72] - [65,65,65];&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This vector will now be used to shift (or recenter) all particles in the table. Read the last computed table of the alignment project&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;ddb aliVLP:rt -ws t&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and apply the new center to the table&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;ts = dynamo_subboxing_table(t,rSubunitFromCenter);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The table now contains the coordinates of the recentered particles. We use this new table to recrop the particles. We first define a new target folder:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;targetFolder = &#039;./particlesSize96r&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Then we recrop the new particles. Since the particles are centered now, we can also choose a smaller boxsize of 96 pixels. This will save space and speed up the following processes. &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtcrop(&#039;VLPtomograms.doc&#039;,ts,targetFolder,96);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Again we average and visualize the cropping results:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;finalTable = dread([targetFolder,&#039;/crop.tbl&#039;]);&lt;br /&gt;
oa = daverage(targetFolder,&#039;t&#039;,finalTable,&#039;fc&#039;,1);&lt;br /&gt;
dwrite(oa.average,[targetFolder &#039;/template.em&#039;]);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==== Step 2: Align symmetry axis ====&lt;br /&gt;
We see that the new average is niceley centered (there is one subunit of the lattice in the center of the volume). However, the symmetry axis is not aligned with the Z axis (the whole average looks a bit &#039;tilted&#039;).&lt;br /&gt;
&lt;br /&gt;
 [[File:VLP_tilted.png|thumb|center|170px| Centered subunit but tilted symmetry axis (X view).]]&lt;br /&gt;
&lt;br /&gt;
We can fix that by aligning the last computed average to a synthetic template and then apply the found transformation to the table, resulting in a new and correct orientation for all particles. First we create a synthetic template using the mask tools of &#039;&#039;Dynamo&#039;&#039;. We choose a curved membrane with a hole in the center, representing the &#039;hollow&#039; central subunit of the lattice.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;mr = dpktomo.examples.motiveTypes.Membrane();   % create membrane object&lt;br /&gt;
mr.thickness  = 22;       % choose thickness of membrane&lt;br /&gt;
mr.sidelength = 96;       % choose sidelength of box&lt;br /&gt;
mr.getMask();             % compute mask &lt;br /&gt;
mem  = (mr.mask)*(-1)+1;  % invert contrast&lt;br /&gt;
cyl = dynamo_cylinder(7,96,[48,48,48]);  % create a cylinder (this will be the &#039;hole&#039;)&lt;br /&gt;
templateSum = mem+cyl;    % sum the two masks&lt;br /&gt;
template = templateSum;&lt;br /&gt;
template(template&amp;gt;0) = 1; % binarize the new mask&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We look at the newly created template to make sure it was computed correctly.&lt;br /&gt;
 &amp;lt;tt&amp;gt;dview(template)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 [[File:VLP_template.png|thumb|center|170px| Template for axis alignment (X view).]]&lt;br /&gt;
&lt;br /&gt;
Now we align the last computed average of the previous alignment project to the newly created template. We save the computed transformation parameters in the matlab object &#039;&#039;sal&#039;&#039;.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;sal = dalign(oa.average,template,&#039;cr&#039;,30,&#039;cs&#039;,5,&#039;ir&#039;,0,&#039;dim&#039;,48,&#039;limm&#039;,1,&#039;lim&#039;,[15,15,15]);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A quick look at the newly aligned average should show a nicely centered particle with the symmetry axis aligned to the Z axis.&lt;br /&gt;
 &amp;lt;tt&amp;gt;dmapview(sal.aligned_particle);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 [[File:VLP_centered_xz.png|thumb|center|300px| Centered and aligned symmetry axis (X/Z view).]]&lt;br /&gt;
&lt;br /&gt;
The transformation parameters that have been saved in the matlab object &#039;&#039;sal&#039;&#039; can now be applied to the table&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tr =  dynamo_table_rigid(finalTable,sal.Tp);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We now have an up-to-date table with nicely centered and aligned particles. This new table can be used in a new, finer alignment project.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
=== Dealing with oversampling ===&lt;br /&gt;
Before starting the new alignment project we apply one more operation on the table. Since we oversampled the VLP surfaces in the beginning we might have ended up with some proteins being in more than one subvolume. Using the following function we can exclude subvolumes that are closer than 20 pixels to each other. In case the distance between two (or more) subvolumes is below this threshold, only the volume with the highest cross correlation (resulting from the previous alignment project) is kept. Read more about how to deal with oversampling [[Seed oversampling| here]].&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;trEx = dpktbl.exclusionPerVolume(tr,20);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We save the new table and use it to create a new reference, which will be used in the next alignment project.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;targetFolder = &#039;./particlesSize96r&#039;;&lt;br /&gt;
dwrite(trEx,[targetFolder &#039;/crop_trEx.tbl&#039;]);&lt;br /&gt;
oa = daverage(targetFolder,&#039;t&#039;,trEx,&#039;fc&#039;,1);&lt;br /&gt;
dwrite(oa.average,[targetFolder &#039;/template_trEx.em&#039;]);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Second aligment project ===&lt;br /&gt;
We now have particles which are centered and aligned. We dealt with the oversampling and recropped them to a smaller box size. These are good conditions to run one more alignment project with finer alignment parameters. We will narrow down the angular search, use a finer angular sampling, impose a C6 symmetry and use a tighter alignment mask. We begin by creating an alignment mask which is tighter than the previously used default one. Through the following commands we create a mask that looks like a thick curved membrane.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;mr = dpktomo.examples.motiveTypes.Membrane();&lt;br /&gt;
mr.thickness  = 55;&lt;br /&gt;
mr.sidelength = 96;&lt;br /&gt;
mr.getMask();&lt;br /&gt;
mem_mask  = mr.mask;&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We save the alignment mask&lt;br /&gt;
 &amp;lt;tt&amp;gt;dwrite(mem_mask,&#039;mem_mask_thick.em&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and inspect it in &#039;&#039;dmapview&#039;&#039;. We open first the previously created template&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dmapview(oa.average)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and then in the mask section we activate &#039;&#039;file&#039;&#039;, put the path of the mask in it (&#039;&#039;mem_mask_thick.em&#039;&#039;) and then click &#039;&#039;layer&#039;&#039;. You should see the mask overlaid to the average. The mask should contain all the signal of the sample. If this is not the case create a new mask with adjusted parameters.&lt;br /&gt;
&lt;br /&gt;
 [[File:VLP_ali_mask_x.png|thumb|center|170px| Alignment mask overlaid to reference (X view).]]&lt;br /&gt;
&lt;br /&gt;
We have now all the material to set up a new alignment project in the same way as done before. We define a new project name:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;pr = &#039;aliVLP_fine&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We create the new alignment project with the newly cropped particles of 96 pixles sidelength, the new template and the new table. The masks are set to default for now. The new alignment mask is added in the next step.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcp.new(pr,&#039;d&#039;,targetFolder,&#039;t&#039;,[targetFolder &#039;/crop_trEx.tbl&#039;],&#039;template&#039;,[targetFolder &#039;/template_trEx.em&#039;],&#039;masks&#039;,&#039;default&#039;,&#039;show&#039;,0);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Adding the new tight alignment mask:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dvput(pr,&#039;file_mask&#039;,&#039;mem_mask_thick.em&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Next we set up the numerical parameters for the project. In this case we define two rounds. The first round has 2 iterations and works with 1x binned particles and a more restricted and finer angular search than the first alignment project. The second round has only 1 iteration but is using the full size particles and even finer angular search parameters. We use C6 symmetry in both rounds.&lt;br /&gt;
&lt;br /&gt;
Parameters round 1:&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvput(pr,&#039;ite_r1&#039;,2);&lt;br /&gt;
dvput(pr,&#039;dim_r1&#039;,48);&lt;br /&gt;
dvput(pr,&#039;cr_r1&#039;,30);&lt;br /&gt;
dvput(pr,&#039;cs_r1&#039;,10);&lt;br /&gt;
dvput(pr,&#039;ir_r1&#039;,30);&lt;br /&gt;
dvput(pr,&#039;is_r1&#039;,10);&lt;br /&gt;
dvput(pr,&#039;rf_r1&#039;,4);&lt;br /&gt;
dvput(pr,&#039;rff_r1&#039;,2);&lt;br /&gt;
dvput(pr,&#039;lim_r1&#039;,[15,15,15]);&lt;br /&gt;
dvput(pr,&#039;limm_r1&#039;,1);&lt;br /&gt;
dvput(pr,&#039;sym_r1&#039;,&#039;c6&#039;);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Parameters round 2:&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvput(pr,&#039;ite_r2&#039;,1);&lt;br /&gt;
dvput(pr,&#039;dim_r2&#039;,96);&lt;br /&gt;
dvput(pr,&#039;cr_r2&#039;,12);&lt;br /&gt;
dvput(pr,&#039;cs_r2&#039;,4);&lt;br /&gt;
dvput(pr,&#039;ir_r2&#039;,12);&lt;br /&gt;
dvput(pr,&#039;is_r2&#039;,4);&lt;br /&gt;
dvput(pr,&#039;rf_r2&#039;,4);&lt;br /&gt;
dvput(pr,&#039;rff_r2&#039;,2);&lt;br /&gt;
dvput(pr,&#039;lim_r2&#039;,[5,5,5]);&lt;br /&gt;
dvput(pr,&#039;limm_r2&#039;,2);&lt;br /&gt;
dvput(pr,&#039;sym_r2&#039;,&#039;c6&#039;);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We set the computing environement:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dvput(pr,&#039;dst&#039;,&#039;standalone_gpu&#039;,&#039;cores&#039;,1,&#039;mwa&#039;,2);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Check, unfold and run the project:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvcheck aliVLP_fine&lt;br /&gt;
dvunfold aliVLP_fine&lt;br /&gt;
dvrun aliVLP_fine &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
While the project is running, we can monitor the results in the same way as we did for the first alignment project. This project should again take no longer than half an hour on one GPU (and 2 cores for averaging). If you are under time pressure you can skip the second round. You should have already nice results after the first round.&lt;br /&gt;
&lt;br /&gt;
=== Result ===&lt;br /&gt;
After the second alignment and without any postprocessing or elaborate refinement your final average may look similar to the one shown below. If not, it may need one more refinement round, adjustments to the mask or one more step of recentering and recropping. This representation was lowpass filtered to ~8 angstroms (or 32px in fourier space).&lt;br /&gt;
&lt;br /&gt;
 [[File:Average_hiv.jpg|thumb|center|400px| Possible outcome of the exercise.]]&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_hexagonal_lattice_coherence_through_neighborhood_analysis_(Tsinghua_Spring_School_2025)&amp;diff=5605</id>
		<title>Walkthrough on hexagonal lattice coherence through neighborhood analysis (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_hexagonal_lattice_coherence_through_neighborhood_analysis_(Tsinghua_Spring_School_2025)&amp;diff=5605"/>
		<updated>2025-03-03T05:44:56Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Data */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:WalkthroughsSpecific]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
==Neighborhood analysis==&lt;br /&gt;
&lt;br /&gt;
Neighbourhood analysis stands at the forefront of methods used to investigate geometrical lattice parameters and offers a wide spectrum of visualization tools. This technique is precise, targeting specific elements, yet broad enough to facilitate overarching interpretive analysis. At its core, the method constructs a latent space of connections by mapping the relative positions of neighbouring particles onto a reference framework. This mapping involves a reorientation process, wherein the &#039;N&#039; closest neighbours are repositioned within the reference particle&#039;s coordinate system, adjusted for its orientation. The richness of the latent space—characterized by the number and nature of these repositioned features—is dictated by a defined distance threshold. This threshold ranges from a minimal couple, representing the closest inter-particle distance, to the maximal extent, linking every particle within the neighbourhood to the reference point.&lt;br /&gt;
&lt;br /&gt;
For additional insights into neighborhood analysis, visit [https://www.dynamo-em.org//w/index.php?title=Neighborhood_analysis this page.]  &lt;br /&gt;
&lt;br /&gt;
==Data==&lt;br /&gt;
&lt;br /&gt;
We will use data from the initial gold standard alignment derived from five tomograms of immature HIV-1 virus-like particles.&lt;br /&gt;
&lt;br /&gt;
In this course, the data for this walkthrough is in:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkNeighborhoodData/&amp;lt;/tt&amp;gt;&lt;br /&gt;
the tomogram with the data is in the link:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkNeighborhoodData/template.em &amp;lt;/tt&amp;gt;&lt;br /&gt;
the table linked with the data is in the link:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkNeighborhoodData/table.tbl &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===Inspecting data===&lt;br /&gt;
&lt;br /&gt;
First, open a new local terminal and navigate to the directory containing the tutorial dataset and project.&lt;br /&gt;
&lt;br /&gt;
Let&#039;s inspect the contents:&lt;br /&gt;
&lt;br /&gt;
 &amp;gt;&amp;gt; dfile template.em&lt;br /&gt;
    &lt;br /&gt;
    filetype: volume&lt;br /&gt;
    &lt;br /&gt;
    size: 192 x 192 x 192 &lt;br /&gt;
&lt;br /&gt;
 &amp;gt;&amp;gt; dfile table.tbl&lt;br /&gt;
  &lt;br /&gt;
    filetype: table&lt;br /&gt;
    &lt;br /&gt;
    size: 7068  x 35, aligns: 7068, averages: 7068 &lt;br /&gt;
&lt;br /&gt;
These files represent an average as a template and its associated metadata (i.e., table). We will focus on the table data.&lt;br /&gt;
&lt;br /&gt;
To visualize the particles along with their normals:&lt;br /&gt;
&lt;br /&gt;
 tbl = dread(&#039;table.tbl&#039;);&lt;br /&gt;
 figure;&lt;br /&gt;
 h = dpktbl.plots.sketch(tbl,&#039;haxis&#039;,gca());&lt;br /&gt;
 h.zlength.value=100;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
[[File:tbl-positions-normals-vlps.png|centre|thumb|450px| VLPs particle positions and normals.]]&lt;br /&gt;
&lt;br /&gt;
== Prepare (meta)data ==&lt;br /&gt;
&lt;br /&gt;
Let&#039;s select a couple of Virus-Like Particles (VLPs):&lt;br /&gt;
&lt;br /&gt;
 tblT2V2 = tbl(tbl(:,20) == 2 &amp;amp; tbl(:,22) == 2, :);&lt;br /&gt;
 tblT2V5 = tbl(tbl(:,20) == 2 &amp;amp; tbl(:,22) == 5, :);&lt;br /&gt;
 tblT2V3 = tbl(tbl(:,20) == 2 &amp;amp; tbl(:,22) == 3, :);&lt;br /&gt;
&lt;br /&gt;
To visualize:&lt;br /&gt;
&lt;br /&gt;
 figure;&lt;br /&gt;
 &lt;br /&gt;
 subplot(1, 3, 1);&lt;br /&gt;
 dpktbl.plots.sketch(tblT2V5);&lt;br /&gt;
 title(&#039;Ideal&#039;);&lt;br /&gt;
 pbaspect([1 1 1]);&lt;br /&gt;
 &lt;br /&gt;
 subplot(1, 3, 2);&lt;br /&gt;
 dpktbl.plots.sketch(tblT2V2); &lt;br /&gt;
 title(&#039;Slightly flat surface&#039;);&lt;br /&gt;
 pbaspect([1 1 1]); &lt;br /&gt;
 &lt;br /&gt;
 subplot(1, 3, 3);&lt;br /&gt;
 dpktbl.plots.sketch(tblT2V3); &lt;br /&gt;
 title(&#039;1/4 missing, flat top&#039;);&lt;br /&gt;
 pbaspect([1 1 1]); &lt;br /&gt;
&lt;br /&gt;
[[File:selected-vlps.png|centre|thumb|800px|  Selected VLPs. From left to right: ideal, medium, and low quality instances.]]&lt;br /&gt;
&lt;br /&gt;
Indeed, we will analyze three different VLP quality instances.&lt;br /&gt;
&lt;br /&gt;
== Get mean distance to closest neighbor ==&lt;br /&gt;
&lt;br /&gt;
To find the optimal distance threshold, we will use the following function to calculate the mean distance to the closest neighbor:&lt;br /&gt;
&lt;br /&gt;
 function [meanDst, stdDsts] = mean_distance_to_closest_neighbor(pts);&lt;br /&gt;
 numPts = size(pts, 1);&lt;br /&gt;
 minDsts = zeros(numPts, 1);&lt;br /&gt;
 &lt;br /&gt;
 for i = 1:numPts&lt;br /&gt;
    dsts = pdist2(pts(i,:), pts);&lt;br /&gt;
    dsts(i) = Inf;&lt;br /&gt;
    minDsts(i) = min(dsts);&lt;br /&gt;
 end&lt;br /&gt;
 &lt;br /&gt;
 meanDst = mean(minDsts);&lt;br /&gt;
 stdDsts = std(minDsts);&lt;br /&gt;
 fprintf(&#039;Mean distance: %.4f\nStandard deviation: %.4f \n&#039;, meanDst, stdDsts);&lt;br /&gt;
 end&lt;br /&gt;
&lt;br /&gt;
Invoke the function like so: &lt;br /&gt;
&lt;br /&gt;
 [meanDst, stdDsts] =   mean_distance_to_closest_neighbor(tbl(:,24:26)+tbl(:,4:6));&lt;br /&gt;
&lt;br /&gt;
The mean distance to the closest neighbor is around 50-60 pixels.&lt;br /&gt;
 Mean distance: 50.42&lt;br /&gt;
 Standard deviation: 12.23&lt;br /&gt;
&lt;br /&gt;
For a sanity check, you might also measure the lattice directly on the average volume:&lt;br /&gt;
&lt;br /&gt;
 dshow template.em&lt;br /&gt;
&lt;br /&gt;
[[File:average-overplot-hexagonal-lattice-measurements.png|centre|thumb|400px|  Overplot average and hexagonal lattice measurements.]]&lt;br /&gt;
&lt;br /&gt;
== Neighborhood analysis computation ==&lt;br /&gt;
&lt;br /&gt;
Here, we conduct the neighborhood analysis with a distance threshold set as the mean distance plus the standard deviation:&lt;br /&gt;
&lt;br /&gt;
 tblT2V3N = dpktbl.neighborhood.analize(tblT2V3,&#039;distance&#039;,meanDst+stdDsts,&#039;modelColumn&#039;,22);&lt;br /&gt;
 tblT2V2N = dpktbl.neighborhood.analize(tblT2V2,&#039;distance&#039;,meanDst+stdDsts,&#039;modelColumn&#039;,22);&lt;br /&gt;
 tblT2V5N = dpktbl.neighborhood.analize(tblT2V5,&#039;distance&#039;,meanDst+stdDsts,&#039;modelColumn&#039;,22);&lt;br /&gt;
&lt;br /&gt;
Then, we will need the couple table since it is our new representation (i.e., latent space):&lt;br /&gt;
&lt;br /&gt;
 tblT2V3NC = real(tblT2V3N.coupleTable);&lt;br /&gt;
 tblT2V2NC = real(tblT2V2N.coupleTable);&lt;br /&gt;
 tblT2V5NC = real(tblT2V5N.coupleTable);&lt;br /&gt;
&lt;br /&gt;
Now, let&#039;s visualize first-order distance clusters with synchronized viewing:&lt;br /&gt;
&lt;br /&gt;
 datasets = {tblT2V3NC, tblT2V2NC, tblT2V5NC};&lt;br /&gt;
 titles = {&amp;quot;Incomplete + flat surface&amp;quot;, &amp;quot;Slightly flat surface&amp;quot;, &amp;quot;Ideal&amp;quot;};&lt;br /&gt;
 &lt;br /&gt;
 fig = figure;&lt;br /&gt;
 ax = gobjects(1, length(datasets));&lt;br /&gt;
 &lt;br /&gt;
 for i = 1:length(datasets)&lt;br /&gt;
    ax(i) = subplot(1, length(datasets), i, &#039;Parent&#039;, fig);&lt;br /&gt;
    pcshow(datasets{i}(:, 24:26), &#039;Parent&#039;, ax(i));&lt;br /&gt;
    pbaspect(ax(i), [1 1 1]);&lt;br /&gt;
    % Set titles using text, since the title function was not working&lt;br /&gt;
    xl = xlim(ax(i));&lt;br /&gt;
    yl = ylim(ax(i));&lt;br /&gt;
    zl = zlim(ax(i));&lt;br /&gt;
    titlePos = [mean(xl), yl(2), zl(2)];&lt;br /&gt;
    text(ax(i), titlePos(1), titlePos(2), titlePos(3), titles{i}, ...&lt;br /&gt;
        &#039;HorizontalAlignment&#039;, &#039;center&#039;, &#039;Color&#039;, &#039;white&#039;, ...&lt;br /&gt;
        &#039;FontSize&#039;, 14, &#039;FontWeight&#039;, &#039;bold&#039;, &#039;BackgroundColor&#039;, &#039;black&#039;);&lt;br /&gt;
 end&lt;br /&gt;
 &lt;br /&gt;
 link = linkprop(ax, {&#039;CameraUpVector&#039;, &#039;CameraPosition&#039;, &#039;CameraTarget&#039;, &#039;CameraViewAngle&#039;, &#039;XLim&#039;, &#039;YLim&#039;, &#039;ZLim&#039;});&lt;br /&gt;
 setappdata(gcf, &#039;StoreTheLink&#039;, link);&lt;br /&gt;
 &lt;br /&gt;
 for a = ax&lt;br /&gt;
    rotate3d(a, &#039;on&#039;);&lt;br /&gt;
 end&lt;br /&gt;
&lt;br /&gt;
[[File:first-order-distance-clusters-three-different-vlps.png|centre|thumb|800px|   First-order distance clusters obtained vía neighborhood analysis. From left to right: low, medium, and high quality instances.]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
The color, by default, represents the Z-axis. Notice that the better the quality of the VLP, the less sparse each cluster is.&lt;br /&gt;
&lt;br /&gt;
== Local analysis - lattice coherence ==&lt;br /&gt;
&lt;br /&gt;
To quantify lattice coherence, we apply [https://www.youtube.com/watch?v=R2e3Ls9H_fc k-means clustering] and calculate the Euclidean norms for each centroid. The standard deviation of these norms provides a measure of cluster sparsity and hence, lattice coherence.&lt;br /&gt;
&lt;br /&gt;
We encapsulate this process in a function:&lt;br /&gt;
&lt;br /&gt;
 function [idx, cc_final, results, results_std] = perform_lattice_analysis(data, symm)&lt;br /&gt;
    [idx, cc_final] = kmeans(data, symm);&lt;br /&gt;
    results = vecnorm(cc_final, 2, 2); &lt;br /&gt;
    results_std = std(results); &lt;br /&gt;
 end&lt;br /&gt;
&lt;br /&gt;
Then, execute the analysis:&lt;br /&gt;
&lt;br /&gt;
 symm = 6; &lt;br /&gt;
 [idx_ideal, cc_ideal_final, results_ideal, std_ideal] = perform_lattice_analysis(tblT2V5NC(:,24:26),symm);&lt;br /&gt;
 [idx_slightly_flat, cc_sf_final, results_sf, std_sf] = perform_lattice_analysis(tblT2V2NC(:,24:26),symm);&lt;br /&gt;
 [idx_incomplete_and_flat, cc_implt_final, results_implt, std_implt] = perform_lattice_analysis(tblT2V3NC(:,24:26),symm);&lt;br /&gt;
&lt;br /&gt;
Display results neatly in a table&lt;br /&gt;
&lt;br /&gt;
 resultsTable = table(std_ideal, std_sf, std_implt, &#039;VariableNames&#039;, {&#039;Ideal&#039;, &#039;SlightlyFlat&#039;, &#039;IncompleteFlat&#039;}, &#039;RowNames&#039;, {&#039;StandardDeviation&#039;});&lt;br /&gt;
 &lt;br /&gt;
 disp(resultsTable);&lt;br /&gt;
&lt;br /&gt;
This will output:&lt;br /&gt;
        &lt;br /&gt;
                               Ideal             SlightlyFlat        IncompleteFlat                       &lt;br /&gt;
                         __________________    _________________    _________________&lt;br /&gt;
                           &lt;br /&gt;
    Standard deviation    0.0933777687916592    0.321031652546273    0.574732108201886&lt;br /&gt;
&lt;br /&gt;
As demonstrated, the qualitative degree of imperfection correlates with our lattice coherence measurements.&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Walkthrough_for_GUI-based_template_matching_(Tsinghua_Spring_School_2025)&amp;diff=5604</id>
		<title>Walkthrough for GUI-based template matching (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Walkthrough_for_GUI-based_template_matching_(Tsinghua_Spring_School_2025)&amp;diff=5604"/>
		<updated>2025-03-03T05:43:54Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Data set */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:Walkthroughs]]&lt;br /&gt;
&lt;br /&gt;
== Template matching ==&lt;br /&gt;
&lt;br /&gt;
In this technique, a template representing a molecule of interest is systematically cross-correlated against a tomogram, producing a &#039;&#039;cross-correlation map&#039;&#039; of the tomogram. Each pixel in this map represents a score assigned the corresponding pixel in the tomogram map. This score measures the similarity of the neighbourhood of the tomogram pixel to the used template.&lt;br /&gt;
This similarity is measured exclusively inside a mask.&lt;br /&gt;
&lt;br /&gt;
Model-aware template matching is meant as an extension of the normal template matching algorithm in Dynamo. The main change introduced in model-aware template matching is that the tomogram is split in chunks that are meant to be meaningful from the point of view of the tomogram models. This allows for the reduction of needed computation by restricting the angular combinations of the template to be scanned. &lt;br /&gt;
&lt;br /&gt;
In this walkthrough, the methods to manually manipulate these chunk is introduced.&lt;br /&gt;
&lt;br /&gt;
Walkthroughs on [[Walkthrough for template matching | basic TM]] in Dynamo and [[Walkthrough for model-aware template matching | model-aware TM]] are also available.&lt;br /&gt;
&lt;br /&gt;
== Data set ==&lt;br /&gt;
&lt;br /&gt;
In this course, the data for this walkthrough is in:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkTemplateMCP/&amp;lt;/tt&amp;gt;&lt;br /&gt;
and the tomogram with the data is in the link:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkTemplateMCP/fullReconstructionWBPCTFDW.mrc &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Getting the data ===&lt;br /&gt;
Currently the data necessary to tun this walkthrough can be downloaded using the link:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;!--https://drive.google.com/file/d/1ME2r6cDw6_sJVtFPTFTgOVBWIuQn44Wl/view?usp=drive_link--&amp;gt;&lt;br /&gt;
{{Template:DownloadLinkTemplateMCP}}&lt;br /&gt;
&lt;br /&gt;
It consists in: a tomogram fullReconstructionWBPCTFDW.mrc, a template templateMCP.mrc, a mask maskMCP.mrc and a fourier mask fmaskMCP.mrc.&lt;br /&gt;
&lt;br /&gt;
=== Tomogram description ===&lt;br /&gt;
&lt;br /&gt;
The tomogram contains Bdellovibrio bacteriovorus acquired by fast-incremental method. The tomogram has been generated using the tilt series from EMPIAR dataset entry 10226. The pixel size is 2.743 Å. The tomogram has been generated around an area of the bacteria presenting methyl-accepting chemotaxis protein (MCP) arrays. The template an average of MCP array.&lt;br /&gt;
&lt;br /&gt;
=== Acknowledgements ===&lt;br /&gt;
&lt;br /&gt;
The tomogram has been generated using the tilt series from EMPIAR dataset entry 10226 described in the paper &amp;quot;Chreifi, G., Chen, S., Metskas, L. A., Kaplan, M., &amp;amp; Jensen, G. J. (2019b). Rapid tilt-series acquisition for electron cryotomography. Journal of Structural Biology, 205(2), 163–169. https://doi.org/10.1016/j.jsb.2018.12.008&amp;quot;. The alignment and reconstruction was done using the [[Walkthrough on GUI based tilt series alignment | Dynamo AWF procedure]] as detailed in &amp;quot;Coray, R., Navarro, P., Scaramuzza, S., Stahlberg, H., &amp;amp; Castaño-Díez, D. (2024). Automated fiducial-based alignment of cryo-electron tomography tilt series in Dynamo. Structure, 32(10), 1808-1819.e4. https://doi.org/10.1016/j.str.2024.07.003&amp;quot;. The template has been generated by STA as described in the same paper.&lt;br /&gt;
&lt;br /&gt;
=== Visualizing the tomogram ===&lt;br /&gt;
&lt;br /&gt;
The tomogram can be found in the path with:&amp;lt;br&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tomofile = &#039;fullReconstructionWBPCTFDW.mrc&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We can get a first glance on how the tomogram looks like:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dshow(tomofile);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The tomogram should appear like the following figure. Note the MCP arrays on the inner membrane of the bacteria.&lt;br /&gt;
[[ File:tomogram_dshow_TM_MCP.png |thumb|center|500px| &amp;lt;tt&amp;gt;dshow&amp;lt;/tt&amp;gt; on the tomogram, View along &#039;&#039;z&#039;&#039; ]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
==== Estimation of the missing wedge ====&lt;br /&gt;
&lt;br /&gt;
We can quickly check the extent of the missing wedge in the tomogram. We extract a sample of the tomogram:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;fragment = dynamo_read_subtomogram(tomofile, &#039;r&#039;,128,&#039;c&#039;,[450,450,450]); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and plot a map of the distribution of the Fourier coefficients:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dynamo_wedge_estimate(fragment,&#039;show&#039;,1); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&amp;lt;br&amp;gt;&lt;br /&gt;
The wedge estimation will show a bi-directional tilt-series acquisition by fast-incremental from around -60 to 60 degrees. &lt;br /&gt;
[[ File:missing_wedge_MCP.png |thumb|center|500px| Estimation of the missing wedge]]&lt;br /&gt;
&lt;br /&gt;
=== Inspecting the template and mask ===&lt;br /&gt;
&lt;br /&gt;
In this walkthrough, a template and its mask are already provided. The template was generated by averaging ~50000 particles aligned with Dynamo. &lt;br /&gt;
&lt;br /&gt;
The template can be loaded by:&lt;br /&gt;
 &amp;lt;tt&amp;gt;av = dread(&#039;templateMCP.mrc&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
And the mask can be loaded by:&lt;br /&gt;
 &amp;lt;tt&amp;gt;mask = dread(&#039;maskMCP.mrc&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The template and mask positioning can be inspected with:&lt;br /&gt;
 &amp;lt;tt&amp;gt;dshow(av+mask); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:template_mask_MCP.png |thumb|center|500px| Template with its mask, View along &#039;&#039;Z&#039;&#039; ]]&lt;br /&gt;
&lt;br /&gt;
[[ File:template_mask_MCP_Y.png |thumb|center|500px| Template with its mask, View along &#039;&#039;Y&#039;&#039; ]]&lt;br /&gt;
&lt;br /&gt;
Note the membrane bilayer on which the MCP array is present is at the bottom of the template. The bacterial cytoplasm would be at the top of the template.&lt;br /&gt;
&lt;br /&gt;
== Description of basic chunk manipulations ==&lt;br /&gt;
&lt;br /&gt;
The GUI for chunk manipulation is &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; with a tomogram as input. It has a tab called Template Matching in the top bar of the GUI.&lt;br /&gt;
It is through this tab that general attributes of chunks distributions and TM processes can be manipulated.&lt;br /&gt;
Additionally, each chunk has its own attributes (such as position and size) that can be manipulated after they are created.&lt;br /&gt;
&lt;br /&gt;
[[ File:general_GUI_MCP.png |thumb|center|500px| &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; and template match tab.]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
=== Chunk creation ===&lt;br /&gt;
&lt;br /&gt;
Create a chunk by pointing the cursor on the tomogram and pressing the &amp;quot;B&amp;quot; key.&lt;br /&gt;
[[ File:newchunk_GUI_MCP.png |thumb|center|500px| Newly created chunk.]]&lt;br /&gt;
&lt;br /&gt;
Multiple chunks can be created by pressing the &amp;quot;B&amp;quot; key again. A chunk can be deleted by right-clicking it and selecting &amp;quot;Delete box&amp;quot;. This will also update the number of existing chunks noted in the Template Matching tab.&lt;br /&gt;
&lt;br /&gt;
[[ File:delete_chunk_MCP.png |thumb|center|500px| Delete options for chunks.]]&lt;br /&gt;
&lt;br /&gt;
Each created chunk is represented with a colored box indicating its position, size and orientation in the tomogram. The coordinate system defined by each chunk is noted by the colored axis. The X axis is magenta, the Y axis is green and the Z axis is black.&lt;br /&gt;
[[ File:chunk_axis_MCP.png |thumb|center|500px| Close-up of a new chunk.]]&lt;br /&gt;
&lt;br /&gt;
=== Basic chunk manipulations ===&lt;br /&gt;
&lt;br /&gt;
Resize a chunk by clicking an edge and dragging it with the cursor. The figure shows the chunk being increased in size along all directions.&lt;br /&gt;
[[ File:chunk_resizing_MCP.png |thumb|center|500px| Chunk during resizing operation.]]&lt;br /&gt;
&lt;br /&gt;
Move a chunk by shift-clicking an edge and dragging it with the cursor.  The figure shows the chunk being moved along its Z direction.&lt;br /&gt;
[[ File:chunk_moving_MCP.png |thumb|center|500px| Chunk during moving operation.]]&lt;br /&gt;
&lt;br /&gt;
Rotate a chunk by alt-clicking an edge and dragging it with the cursor.&lt;br /&gt;
[[ File:chunk_rotating_method1_MCP.png |thumb|center|500px| Chunk during change of chunk orientation by alt-click.]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
This can also be done by right-clicking the chunk and then selection the option &amp;quot;Change chunk orientation (into an oblique view)&amp;quot;. This will spawn a interactable lever that can rotate the chunk in any direction.&lt;br /&gt;
[[ File:chunk_rotating_method2_before_MCP.png |thumb|center|500px| Selection of chunk orientation by lever.]]&lt;br /&gt;
[[ File:chunk_rotating_method2_after_MCP.png |thumb|center|500px| Chunk during change of chunk orientation by lever.]]&lt;br /&gt;
&lt;br /&gt;
=== Chunk inspection ===&lt;br /&gt;
&lt;br /&gt;
The tomogram data included in a chunk can be inspected by right-clicking the chunk and selecting &amp;quot;show chunk (in tomoshow)&amp;quot;.&lt;br /&gt;
&lt;br /&gt;
The data can also be inspected through a chunk-specific template match process that will be described in the following sections&lt;br /&gt;
&lt;br /&gt;
=== Chunk cone setting ===&lt;br /&gt;
The chunk cone orientation is the direction around which a template would be oriented during template match. It can be seen as the most probable direction that copies of the template present in the volume defined by the chunk. The graphical object allowing changes in the cone orientation is accessible by right-clicking a chunk as in the next figure.&lt;br /&gt;
&lt;br /&gt;
[[ File:cone_rotating_before_MCP.png |thumb|center|500px| Selection of cone orientation.]]&lt;br /&gt;
&lt;br /&gt;
The graphical object has some functionalities that can be accessed by right-clicking it as in the next figure.&lt;br /&gt;
&lt;br /&gt;
[[ File:cone_rotating_options_MCP.png |thumb|center|500px| Option for cone orientation.]]&lt;br /&gt;
&lt;br /&gt;
The cone orientation is changed by dragging the lever as in the following figure. Once the cone orientation is satisfactory, the lever graphical object should be removed by pressing the &amp;quot;Delete rotation frame&amp;quot; option shown in the previous figure.&lt;br /&gt;
&lt;br /&gt;
[[ File:cone_rotating_after_MCP.png |thumb|center|500px| Change of cone orientation.]]&lt;br /&gt;
&lt;br /&gt;
=== Per-chunk TM ===&lt;br /&gt;
&lt;br /&gt;
As mentioned before, it is possible to run a TM project on a chunk directly from the GUI. This can be done by right-click the chunk and select &amp;quot;Launch TM process for this chunk&amp;quot;. However, more parameters are necessary than only the chunk positions, size, orientation and cone orientation. These parameter can be accessed by selecting the &amp;quot;Template Matching&amp;quot; option on the top bar of the GUI and clicking &amp;quot;Settings for template match process&amp;quot; as in the next figure.&lt;br /&gt;
&lt;br /&gt;
[[ File:access_TM_setting_GUI.png |thumb|center|500px| How to access the TM parameters GUI.]]&lt;br /&gt;
&lt;br /&gt;
The TM parameter GUI is initially blank and need to be filled to be able to run a per-chunk TM. The main advantage of per-chunk TM is that it can be done directly from the GUI and on any type of chunk, including oblique chunks.&lt;br /&gt;
[[ File:blank_TM_setting_GUI.png |thumb|center|500px| Blank TM parameter GUI.]]&lt;br /&gt;
&lt;br /&gt;
It should be noted that the area of the chunk that will generate valid cross-correlation scores is reduced by half of the size of the template in all directions.&lt;br /&gt;
&lt;br /&gt;
== Relationship between GUI models and tessellations ==&lt;br /&gt;
&lt;br /&gt;
The GUI allows the creation and manipulation of tessellation with the tool mentioned in the previous section. However, these tessellations will be saved or loaded from .omd files. This can be done from the &amp;quot;Template Matching&amp;quot; tab in the GUI with the options &amp;quot;Save chunk distribution&amp;quot; and &amp;quot;Load chunk distribution from .omd file&amp;quot;.&amp;lt;br&amp;gt;&lt;br /&gt;
However, TM processes require a tessellation in either table or dStar format as described in the tutorial [[Walkthrough for model-aware template matching | on model-aware template matching]]. This difference in format exists because .omd file tessellations are simplified so that their representations in the GUI would not be cumbersome. As such two converting functions are available in the Dynamo TM package:&lt;br /&gt;
&lt;br /&gt;
The function &amp;lt;tt&amp;gt;dpktomo.match.modelling.createTesselationFromGUIomd&amp;lt;/tt&amp;gt; converts an .omd tessellation into a dStar tessellation ready for &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt;.&amp;lt;br&amp;gt;&lt;br /&gt;
The function &amp;lt;tt&amp;gt;dpktomo.match.modelling.saveTesselationAsGUIomd&amp;lt;/tt&amp;gt; converts a dStar tessellation into an object that can be saved as a .omd file with &amp;lt;tt&amp;gt;dwrite&amp;lt;/tt&amp;gt;.&amp;lt;br&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Walkthrough on chunk manipulation ==&lt;br /&gt;
&lt;br /&gt;
In this walkthrough the basic function described before will be used to create a tesselation and run a model-aware TM project. Additionally, on per-chunk TM will be tested with different cones.&lt;br /&gt;
&lt;br /&gt;
=== Chunk setup ===&lt;br /&gt;
&lt;br /&gt;
First, if not done already, open the &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; GUI with the tomogram.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmslice(&#039;fullReconstructionWBPCTFDW.mrc&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Then, create a single chunk in the top area of the bacteria presenting an MCP array. For now, do not use oblique chunks.&amp;lt;br&amp;gt;&lt;br /&gt;
Ensure the chunk is thick enough to include the MCP array area even considering the template size.&amp;lt;br&amp;gt;&lt;br /&gt;
Rescale and shift the chunk until a configuration similar to the following figure is reached. The cone orientation will be left as the default one for now (that is, collinear to the Z axis of the tomogram).&lt;br /&gt;
[[ File:first_chunk_position_MCP.png |thumb|center|500px| Position of first chunk.]]&lt;br /&gt;
&lt;br /&gt;
=== Global TM ===&lt;br /&gt;
&lt;br /&gt;
In this first experiment, an per-chunk TM with isotropic angular scanning will be used.&amp;lt;br&amp;gt;&lt;br /&gt;
Howver, first it is necessary to set up the global TM parameters from the GUI. Update the GUI as in the following figure.&lt;br /&gt;
[[ File:settings_TM_GUI_360_MCP.png |thumb|center|500px| TM parameters for isotropic angular scans.]]&lt;br /&gt;
&lt;br /&gt;
This setup will allow the GUI to access template, mask and missing wedge mask. The scanning ranges are 360 degrees to ensure isotropic angular scans. The angular scanning steps are set to 10 to allow fine enough sampling to achieve good cross-correlation maps. The binning is set to 2 to speed up calculations.&amp;lt;br&amp;gt;&lt;br /&gt;
It is preferable to compute using GPUs for computing speed. Only one GPU is required. If more than one GPU are accessible by MATLAB, their corresponding id numbers can be checked with the MATLAB command:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;gpuDeviceTable&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The per-chunk TM can then by launched. Right-click the chunk and select &amp;quot;Launch TM process for this chunk&amp;quot;. This will automatically create a folder called &amp;quot;chunkTM.CTM&amp;quot; containing the oblique chunk and its resulting TM process.&amp;lt;br&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Finally, inspect the resulting cross-correlation map. In the created folder this can be done by:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dshow(&#039;process.TM/cc.mrc&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:CC_first_chunk_360_MCP.png |thumb|center|500px| Resulting CC map.]]&lt;br /&gt;
&lt;br /&gt;
=== Cone-restricted TM ===&lt;br /&gt;
&lt;br /&gt;
One of the main advantages of tesselation is that each chunk can limit the number of scanning angles by exploiting the know general orientation of the particle of interest present in the chunk area. This information is encoded in the cone orientation of each chunk. In this case, we know that the chunk is positioned on the top of the bacteria presenting the MCP arrays. This means that the MCP template is expected to identify the MCP array when it is oriented towards the bottom of the chunk. As such, updated the chunk orientation appropriately like in the following figure.&lt;br /&gt;
[[ File:first_chunk_correct_cone_MCP.png |thumb|center|500px| Position of first chunk with proper cone orientation.]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
The general TM parameters must be updated as well. In particular the cone range should be reduced from 360 degrees to 60 degrees.&lt;br /&gt;
&lt;br /&gt;
[[ File:settings_TM_GUI_60_MCP.png |thumb|center|500px| TM parameters for cone-limited angular scans.]]&lt;br /&gt;
&lt;br /&gt;
The per-chunk TM can then by launched and inspect the resulting cross-correlation map. In the created folder this can be done as before:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dshow(&#039;process.TM/cc.mrc&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The map will look similar to the previous per-chunk TM, but the computing time will be reduced by a factor of 10.&lt;br /&gt;
&lt;br /&gt;
[[ File:CC_first_chunk_correct_cone_MCP.png |thumb|center|500px| Resulting CC map with limited angular cone.]]&lt;br /&gt;
&lt;br /&gt;
It must be noted that cone orientation can be used to test if sets of template orientations are not present. For example, we it is not expected that the MCP array on top of the bacteria will be horizontal. Update the chunk orientation like in the following figure. &lt;br /&gt;
[[ File:first_chunk_wrong_cone_MCP.png |thumb|center|500px| Position of first chunk with incorrect cone orientation.]]&lt;br /&gt;
&lt;br /&gt;
The per-chunk TM can then by launched and inspect the resulting cross-correlation map. The cross-correlation map shows a lack of matches for the scanned orientations, as expected.&lt;br /&gt;
[[ File:CC_first_chunk_wrong_cone_MCP.png |thumb|center|500px| Resulting CC map with limited angular cone oriented incorrectly.]]&lt;br /&gt;
&lt;br /&gt;
== Walkthrough on tessellation generation ==&lt;br /&gt;
&lt;br /&gt;
Tessellation are sets of chunks an cone orientations designed to be used by &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt; for advantageous TM. Here, the process to create and uses tesselations by GUI is shown.&lt;br /&gt;
&lt;br /&gt;
=== Add more chunks ===&lt;br /&gt;
&lt;br /&gt;
Firstly, add two new chunks with their cone orientations with the GUI as in the following figure. In total three non-oblique chunks are created.&lt;br /&gt;
&lt;br /&gt;
[[ File:full_tesselation_MCP.png |thumb|center|500px| Positions of multiple chunks with their cones.]]&lt;br /&gt;
&lt;br /&gt;
Now, save the tesselation to disk by pressing the &amp;quot;Save chunk distribution&amp;quot; in the &amp;quot;Template Match&amp;quot; tab. This will create a file &amp;lt;tt&amp;gt;tesselation.omd&amp;lt;/tt&amp;gt; to disk.&lt;br /&gt;
&lt;br /&gt;
=== Generate a tesselation ===&lt;br /&gt;
&lt;br /&gt;
As mentioned before, a .omd file need ot be converted to a star object to be an accepted input of &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt;.&amp;lt;br&amp;gt;&lt;br /&gt;
The conversion can be done by:&lt;br /&gt;
 &amp;lt;tt&amp;gt;star = dpktomo.match.modelling.createTesselationFromGUIomd(&#039;tesselation.omd&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The values encoded in the star object cen be inspected with:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;star.tbl&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The properties will look similar to the following:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
    index     tdrot      tilt       narot      posX      posY      posZ     sizeX     sizeY     sizeZ     coneRange    inplaneRange&lt;br /&gt;
    _____    _______    _______    _______    ______    ______    ______    ______    ______    ______    _________    ____________&lt;br /&gt;
&lt;br /&gt;
      1      -156.91    -160.25     156.91    702.55    743.66    564.27    515.44     397.2     270.9       60            360     &lt;br /&gt;
      2       147.92    -97.808    -147.92    912.01    455.29    326.33    414.75    387.03    242.75       60            360     &lt;br /&gt;
      3      -51.289    -78.113     51.289     486.3       883    322.65    455.65    549.42    282.14       60            360&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Run model-aware TM with manual tessellation ===&lt;br /&gt;
&lt;br /&gt;
Finally, a full model-aware TM process can be run.&lt;br /&gt;
 &amp;lt;tt&amp;gt;pts_GPU = dynamo_match(&#039;fullReconstructionWBPCTFDW.mrc&#039;,&#039;templateMCP.mrc&#039;,&#039;mask&#039;,&#039;maskMCP.mrc&#039;,...&lt;br /&gt;
 &#039;outputFolder&#039;,&#039;MCP_tesselation&#039;,...&lt;br /&gt;
 &#039;ytilt&#039;,[-60,60],&#039;is&#039;,10,&#039;cs&#039;,10,&#039;bin&#039;,2,&#039;mw&#039;,10,&#039;gpus&#039;,1,&#039;tilingTable&#039;,star);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The resulting TM object pts_GPU can be then used as in the tutorials [[Walkthrough for template matching | on basic TM]] and [[Walkthrough for model-aware template matching | model-aware TM]].&lt;br /&gt;
&lt;br /&gt;
== Additional functionalities ==&lt;br /&gt;
&lt;br /&gt;
Two other functionalities will be introduced in this section. First, an per-chunk TM with an oblique chunk and then a conversion of &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt; tesselation into an .omd file ready to be loaded in the GUI.&lt;br /&gt;
&lt;br /&gt;
=== Oblique chunks ===&lt;br /&gt;
&lt;br /&gt;
Oblique chunks are currently not supported by &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt;. However, per-chunk TM can be done on oblique chunks.&lt;br /&gt;
First, create an oblique chunk with appropriate cone orientation like in the following figure.&lt;br /&gt;
&lt;br /&gt;
[[ File:oblique_chunk_position_MCP.png |thumb|center|500px| Oblique chunk with correct cone.]]&lt;br /&gt;
&lt;br /&gt;
Per-chunk TM can then by run as in the previous sections.&lt;br /&gt;
&lt;br /&gt;
[[ File:CC_oblique_chunk_correct_cone_MCP.png |thumb|center|500px| Resulting CC map with limited angular cone on oblique chunk.]]&lt;br /&gt;
&lt;br /&gt;
=== Manipulation a tessellation with the GUI ===&lt;br /&gt;
&lt;br /&gt;
The GUI can save and load .omd files, allowing of their manipulation and as such, the manipulations of tesselations.&amp;lt;br&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
If a tesselation is available as a star object, it can be converted in a .omd object with:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;newomd = dpktomo.match.modelling.saveTesselationAsGUIomd(star);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Which can be save to disk as usual:&lt;br /&gt;
 &amp;lt;tt&amp;gt;dwrite(newomd,&#039;tesselation_back.omd&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The new .omd file can then be loaded by the GUI.&amp;lt;br&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Note that tesselations can be generated automatically with the functions: &amp;lt;br&amp;gt;&lt;br /&gt;
&amp;lt;tt&amp;gt;dpktomo.match.modelling.estimateTesselationForFilament&amp;lt;/tt&amp;gt;&amp;lt;br&amp;gt; &lt;br /&gt;
&amp;lt;tt&amp;gt;dpktomo.match.modelling.estimateTesselationForMembrane&amp;lt;/tt&amp;gt;&amp;lt;br&amp;gt; &lt;br /&gt;
&amp;lt;tt&amp;gt;dpktomo.match.modelling.estimateTesselationForDipole&amp;lt;/tt&amp;gt;&amp;lt;br&amp;gt; &lt;br /&gt;
and the creator of tesselation star objects:&lt;br /&gt;
&amp;lt;tt&amp;gt;dpktomo.match.modelling.setUpTilingTable&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
More information on this can be found in the tutorial [[Walkthrough for model-aware template matching | on model-aware template matching]].&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
=== Programmatic GUI customization for template matching ===&lt;br /&gt;
&lt;br /&gt;
It is possible to add custom functionalities to the GUI as described in the [[Programmatic GUI customization for template matching | corresponding tutorial]].&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Walkthrough_for_template_matching_(Tsinghua_Spring_School_2025)&amp;diff=5603</id>
		<title>Walkthrough for template matching (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Walkthrough_for_template_matching_(Tsinghua_Spring_School_2025)&amp;diff=5603"/>
		<updated>2025-03-03T05:42:41Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Data set */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:WalkthroughsSpecific]]&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;Dynamo&#039;&#039; includes a set of tools for location of particles inside tomograms. The most simple one is &#039;&#039;template matching&#039;&#039;.&lt;br /&gt;
&lt;br /&gt;
== Template matching ==&lt;br /&gt;
In this technique, a template representing a molecule of interest is systematically cross-correlated against a tomogram, producing a &#039;&#039;cross-correlation map&#039;&#039; of the tomogram. Each pixel in this map represents a score assigned the corresponding pixel in the tomogram map. This score measures the similarity of the neighbourhood of the tomogram pixel to the used template.&lt;br /&gt;
This similarity is measured exclusively inside a mask.&lt;br /&gt;
&lt;br /&gt;
==Data set ==&lt;br /&gt;
&lt;br /&gt;
In this course, the data for this walkthrough is in:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkTemplateMatchingBasic/&amp;lt;/tt&amp;gt;&lt;br /&gt;
and the tomogram with the data is in the link:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkTemplateMatchingBasic/t20s.mrc &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Tomogram description ===&lt;br /&gt;
&lt;br /&gt;
The tomogram contains a buffer with T20S proteasome on a holey carbon grid collected on a Krios + K2. Original pixelsize was 1.76 angstroms. The tomogram provided here has bin binned twice (yielding thus 7.04 ang), defocus is 4.4 microns, no CTF correction, no energy filter.&lt;br /&gt;
&lt;br /&gt;
=== Acknowledgements ===&lt;br /&gt;
The tomogram has been kindly provided by Alex Noble, from the New York Structural Biology Center. Data collection was performed using Leginon and Appion-Protomo at the Simons Electron Microscopy Center and National Resource for Automated Molecular Microscopy located at the New York Structural Biology Center, supported by grants from the Simons Foundation (349247), NYSTAR, and the NIH National Institute of General Medical Sciences (GM103310) with additional support from Agouron Institute [Grant Number: F00316].&lt;br /&gt;
&lt;br /&gt;
=== Getting the tomogram ===&lt;br /&gt;
You should have already a local version of the data. Therefore, navigate to the directory where you just created the tutorial dataset and project.&lt;br /&gt;
&lt;br /&gt;
=== Visualizing the tomogram ===&lt;br /&gt;
&lt;br /&gt;
We can get a first glance on how the tomogram looks like:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmshow -otf t20s.mrc &amp;lt;/tt&amp;gt; &lt;br /&gt;
&lt;br /&gt;
to use the &#039;&#039;on-the-fly&#039;&#039; access to the slice shown at each given moment, or &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;v = dread(&#039;t20s.mrc&#039;);dtmshow(v);&amp;lt;/tt&amp;gt; &lt;br /&gt;
&lt;br /&gt;
to preload the full tomogram into a memory variable (arbitrarily called &amp;lt;tt&amp;gt;v&amp;lt;/tt&amp;gt;). In either option, you will see, the proteasomes are densely packed in an layer. The layer is slightly oblique, what can be seen browsing through &#039;&#039;z&#039;&#039; or &#039;&#039;y&#039;&#039;. &lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingTomoshowZ.png |thumb|center|500px| &amp;lt;tt&amp;gt;dtmshow&amp;lt;/tt&amp;gt; on the pt20s tomogram, View along &#039;&#039;z&#039;&#039; ]]&lt;br /&gt;
&lt;br /&gt;
Navigating on-the-fly you&#039;ll see that transitions in &#039;&#039;y&#039;&#039; are slower than transitions in &#039;&#039;z&#039;&#039;, because all the pixels of the same slice are stored sequentially in the disk. &lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingTomoshowY.png |thumb|center|500px| &amp;lt;tt&amp;gt;dtmshow&amp;lt;/tt&amp;gt; on the pt20s tomogram, View along &#039;&#039;y&#039;&#039; ]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
==== Estimation of the missing wedge ====&lt;br /&gt;
&lt;br /&gt;
We can quickly check the extent of the missing wedge in the tomogram. We extract a sample of the tomogram:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;fragment = dynamo_read_subtomogram(&#039;t20s.mrc&#039;, &#039;r&#039;,64,&#039;c&#039;,[450,450,100]); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and plot a map of the distribution of the Fourier coefficients:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dynamo_wedge_estimate(fragment,&#039;show&#039;,1); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingWedgeEstimation.png |thumb|center|500px| Estimation of the missing wedge&#039; ]]&lt;br /&gt;
&lt;br /&gt;
== Creating a template ==&lt;br /&gt;
&lt;br /&gt;
There are different strategies to create the first template. In the case where the general shape of each protein is roughly recognisable by eye, it is not difficult to just crop and align manually some of the particles. When this is not possible, you have the option of using a density map that mimics the general topology of your protein.&lt;br /&gt;
&lt;br /&gt;
=== Through manual alignment ===&lt;br /&gt;
&lt;br /&gt;
We will use a model inside [[Dtmslice | &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt;]] to pick a set of ~10 particles. We will then crop them, and align them manually using &amp;lt;tt&amp;gt;dgallery&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
====Manual selection of some particles ====&lt;br /&gt;
&lt;br /&gt;
We use for this our tool &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt;. As the tomogram is provided is fairly small you can probably just open it without any further binning.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmslice t20s.mrc -c ct20s&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingTomosliceGeneral.png |thumb|center|500px| &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; on tomogram ]]&lt;br /&gt;
&lt;br /&gt;
Use the &amp;lt;tt&amp;gt;model pool&amp;lt;/tt&amp;gt; menu to add a new model of type &amp;lt;tt&amp;gt;General&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingTomosliceModel.png |thumb|center|500px| Opening a model ]]&lt;br /&gt;
&lt;br /&gt;
Try to pick particles on different orientations, both in top and side views.  Particles are picked with the key &amp;lt;tt&amp;gt;C&amp;lt;/tt&amp;gt;, use &amp;lt;tt&amp;gt;backspace&amp;lt;/tt&amp;gt; to clear the latest selection.&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingTomoslicePick.png |thumb|center|500px| Pick particles with the &amp;lt;tt&amp;gt;C&amp;lt;/tt&amp;gt; key ]]&lt;br /&gt;
&lt;br /&gt;
You can move the slice with the &#039;&#039;z&#039;&#039; slidebar in the control panel, or dragging it while the mouse button is pressed. Top views are more abundant below the crowded accumulation of side views in the central slice.&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingTomoslicePickTop.png |thumb|center|500px| Use the wheel to go up and down in the tomogram to locate top views ]]&lt;br /&gt;
&lt;br /&gt;
When you have clicked around ten, we will prepare to crop them out of the tomogram. For this, we first need to get an approximative idea of how big should be  the box. With the keys [1] and [2] you can place anchor points in the scene. Auxiliary click in the bar between them shows the distance (in pixels of the unbinned tomogram). In view of the measured distance of around 32, we will use a cropping box  size of 48 pixels, in order to ensure that the particles will comfortably fit inside the boxes, as our clicks will not be very precise. &lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingMeasure.png |thumb|center|500px| Measure distances with the [1] and [2] anchors  ]]&lt;br /&gt;
&lt;br /&gt;
Now we can open the &amp;lt;tt&amp;gt;dtcrop&amp;lt;/tt&amp;gt; utility for this model, by visiting the &#039;&#039;Active model&#039;&#039; menu.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingMenuForDtcrop.png |thumb|center|500px | invoking the &amp;lt;tt&amp;gt;dtcrop&amp;lt;/tt&amp;gt; GUI for the active model. ]]&lt;br /&gt;
&lt;br /&gt;
In the GUI that pops up we can fix the sidelength to the value 48. &lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingDtcrop.png |thumb|center|500px  | &amp;lt;tt&amp;gt;dtcrop&amp;lt;/tt&amp;gt; GUI ]]&lt;br /&gt;
&lt;br /&gt;
After completion of the cropping process, you will get a [[data folder]] called  &amp;lt;tt&amp;gt;t20s_Particles.Data&amp;lt;/tt&amp;gt;, which will also contain a [[table]] file called &amp;lt;tt&amp;gt;t20s_Particles.Data/crop.tbl&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
====Manual alignment of some particles ====&lt;br /&gt;
&lt;br /&gt;
Now we want to align the particles. We open them inside the &amp;lt;tt&amp;gt;dgallery&amp;lt;/tt&amp;gt; browser:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dgallery -d t20s_Particles.Data -t t20s_Particles.Data/crop.tbl &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This GUI has several functionalities. We will focus in using it to quickly get an alignment of the particles.  For this, we first load the particles expressed in the table into the internal memory of the &amp;lt;tt&amp;gt;gallery&amp;lt;/tt&amp;gt; by clicking into &#039;&#039;Load&#039;&#039;.&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingGalleryLoad.png |thumb|center|500px | Preload all the particles into memory ]]&lt;br /&gt;
&lt;br /&gt;
This seems not to have any effect in the depiction: you need to fix the range of the depicted particles moving the slider bar. When you do so, each particle will appear in the scene as  a single red box.&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingGalleryShowAll.png |thumb|center|500px  | Adjust the scene to show all the particles ]]&lt;br /&gt;
&lt;br /&gt;
You can play with different settings for viewing, like the direction (&#039;&#039;x&#039;&#039;, &#039;&#039;y&#039;&#039; or &#039;&#039;z&#039;&#039;)&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingControlViewing.png |thumb|center|500px| viewing direction controls  ]]&lt;br /&gt;
&lt;br /&gt;
or the number of slices that are projected into the depicted image for each particle.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingControlThickness.png |thumb|center|500px | Thickness controls  ]]&lt;br /&gt;
&lt;br /&gt;
Then, you go through each particle and indicate a point that you considere that could lay in the central axis of the particle by clicking on &amp;lt;tt&amp;gt;[N]&amp;lt;/tt&amp;gt;. The particle will rotate on screen to match this direction.  The center of the particle can also be set by clicking on &amp;lt;tt&amp;gt;[C]&amp;lt;/tt&amp;gt;. In this case, the particle will not rotate, but will shift to put its center on the spot where the click was operated.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingClickNorth.png |thumb|center|500px| Select the north direction with &amp;lt;tt&amp;gt;N&amp;lt;/tt&amp;gt;  ]]&lt;br /&gt;
&lt;br /&gt;
Top views viewed along &#039;&#039;z&#039;&#039; should not be changed with the &amp;lt;tt&amp;gt;N&amp;lt;/tt&amp;gt; click, only with the &amp;lt;tt&amp;gt;C&amp;lt;/tt&amp;gt; to recenter them if necessary.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingClickNorthTopViewX.png |thumb|center|500px |  Select the north direction with &amp;lt;tt&amp;gt;N&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
You may need to complete two rounds of operating on the particles, changing the viewing direction (first in &#039;&#039;x&#039;&#039;, then in &#039;&#039;y&#039;&#039;).&lt;br /&gt;
&lt;br /&gt;
==== Averaging manually aligned particles ====&lt;br /&gt;
&lt;br /&gt;
We export the table we have computed &lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingQuickSave.png  |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
Now we can use the table (saved as file &amp;lt;tt&amp;gt;quickbuffer.tbl&amp;lt;/tt&amp;gt; by default) to create an average of the manually aligned particles:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;oa = daverage(&#039;t20s_Particles.Data&#039;,&#039;t&#039;,&#039;quickbuffer.tbl&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
which can be visualized in &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(oa.average);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingAverageManual.png |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
==== Creating a tight mask  ====&lt;br /&gt;
===== Measure distances =====&lt;br /&gt;
&lt;br /&gt;
Open the computed average in &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt;,&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(oa.average); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
set the view to the XZ or YZ planes, &lt;br /&gt;
&lt;br /&gt;
Hit the buttons next to the anchors [C] and [N] then place them with left and right click respectively. This is to measure the semiaxis of the average. Here, we want to click well outside of the signal, as we are measuring the distances that define a mask that needs to contain the average.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingMarkZaxis.png |thumb|center|500px| Measuring the semiaxis in the longitudinal direction in &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt; ]]&lt;br /&gt;
&lt;br /&gt;
Use the &#039;&#039;solid&#039;&#039; button to make the points more visible (as solid circles instead of rings). Now, move the [N] anchor to move the radius of the average in the xy plane,&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingMarkXYPlane.png |thumb|center|500px| Measuring the semiaxis in the transversal direction in &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt;  ]]&lt;br /&gt;
&lt;br /&gt;
===== Create mask =====&lt;br /&gt;
&lt;br /&gt;
We now symmetrize the density map. Use an arbitrary high value, we have use 17 in our example. The goal is simply to have a strong representation of the signal and to check how the template fits inside the mask that we will create later. &lt;br /&gt;
&lt;br /&gt;
Now, we create a cylindrical mask using the lengths of the semiaxes that we have measured using the anchor points.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingMaskOptions.png |thumb|center|500px  | Creating a cylindrical mask inside  &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
We save the created mask into a file&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingMaskSave.png |thumb|center|500px | exporting the created mask into file inside &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt; ]]&lt;br /&gt;
&lt;br /&gt;
====Cropping the borders of a template====&lt;br /&gt;
&lt;br /&gt;
We check how the mask looks like on the template&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;shifted =circshift(dsym(oa.average,&#039;c17&#039;),[0,0,-1]);dslices(shifted,&#039;y&#039;,&#039;overlay&#039;,&#039;maskTight.em&#039;,&#039;overlay_as&#039;,&#039;mask&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The &amp;lt;tt&amp;gt;circshift&amp;lt;/tt&amp;gt; operation is just shifting the template, as it seems that it is not well centered. It&#039;s normal: it&#039;s difficult to catch a perfect centering in a manual alignment. Probably in your own data set things will look slightly different. If necessary, you should try with different parameters, and stick with the one that looks like the best alignment. Then save it into a variable in the memory space:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;shifted = circshift(dsym(oa.average,&#039;c17&#039;),[0,0,-1]); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingCircshiftTemplate.png |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
Now  we can extract the part of the created template where we actually have signal:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;cropped = dynamo_crop(shifted ,32);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
which can be visualized with: &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dslices(cropped,&#039;y&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingTemplateInterior.png |thumb|center|500px| Template cropped to 32 pixels ]]&lt;br /&gt;
&lt;br /&gt;
We create a file to contain this cropped template:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; dwrite(cropped,&#039;average32.em&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and proceed similarly with the mask:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; dwrite(dcrop(dread(&#039;maskTight.em&#039;),32),&#039;maskTight32.em&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Through geometrical shapes ===&lt;br /&gt;
Alternatively, you can use &amp;lt;tt&amp;gt;dynamo_mask&amp;lt;/tt&amp;gt; or &amp;lt;tt&amp;gt;dynamo_tube&amp;lt;/tt&amp;gt; to create a synthetic model.&lt;br /&gt;
&lt;br /&gt;
== Creating a template matching process==&lt;br /&gt;
&lt;br /&gt;
The main function is &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;pts = dynamo_match(&#039;t20s.mrc&#039;,&#039;average32.em&#039;,&#039;mask&#039;,&#039;maskTight32.em&#039;,...&lt;br /&gt;
    &#039;outputFolder&#039;,&#039;cs30&#039;,...&lt;br /&gt;
    &#039;ytilt&#039;,[-39,36],&#039;sc&#039;,[256,256,256],&#039;cr&#039;,360,&#039;cs&#039;,30,&#039;bin&#039;,1);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note: when working in the [[standalone]], you cannot write the &amp;lt;tt&amp;gt;...&amp;lt;/tt&amp;gt; to break the lines, so you&#039;ll need to write in one single line.&lt;br /&gt;
&lt;br /&gt;
* &#039;bin&#039; &amp;lt;br/&amp;gt;  allows binning on the fly. Template, mask and tomograms are input in original size.&lt;br /&gt;
* &#039;sc&#039; : size of chunk &amp;lt;br/&amp;gt; This is the maximum extent of a block in the unbinned tomogram that will be kept in memory by each one of the processors working in parallel (only one in this experiment). We need to be careful not to crowd the available memory.&lt;br /&gt;
* &#039;cr&#039; : cone range &amp;lt;br/&amp;gt; orientations will be looked for inside a cone. In this context, the most usual values are 360 (sample the full sphere) or 0 (do not scan orientations)&lt;br /&gt;
* &#039;cs&#039; : cone sampling &amp;lt;br/&amp;gt; Determines the scanning density inside the sphere.&lt;br /&gt;
* &#039;ir&#039; : in plane range &amp;lt;br/&amp;gt; in plane rotation range&lt;br /&gt;
* &#039;is&#039; : in plane sampling &amp;lt;br/&amp;gt; determines the scanning density for in plane rotations&lt;br /&gt;
* &#039;mw&#039; : number of matlab workers for parallel computation&lt;br /&gt;
&lt;br /&gt;
&#039;ir&#039; and &#039;is&#039; are not used here to speed up computation and because the proteasome has a high rotational symmetry.&lt;br /&gt;
&lt;br /&gt;
&#039;mw&#039; is not used here for compatibility with all systems.&lt;br /&gt;
&lt;br /&gt;
You should get the following response on the screen (will take around 5 minutes to complete)&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;------------------------------------------------------------&lt;br /&gt;
 &lt;br /&gt;
 Template matching process.&lt;br /&gt;
 computing in CPU&lt;br /&gt;
 Output folder: cs30.TM&lt;br /&gt;
A total of 1 tiles have been created&lt;br /&gt;
  - Mb per tile (reading)   : 724.19&lt;br /&gt;
  - Mb per tile (operation) : 663.84&lt;br /&gt;
 ... initializing output elements&lt;br /&gt;
Preparing to run on 25 blocks&lt;br /&gt;
Running on single processor&lt;br /&gt;
 Computing tile 1&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;Information for each block&amp;gt;&lt;br /&gt;
&lt;br /&gt;
  ... tile 1 finished in 387 seconds (8 for setup;  7.73 per triplet)&lt;br /&gt;
  [ok] ... template matching process completed upto creation of cross correlation&lt;br /&gt;
       you can proceed to peak location and particle extraction.&lt;br /&gt;
------------------------------------------------------------&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The main result of &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt; is  a volume (&#039;&#039;cross correlation&#039;&#039; volume) that assigns a score to each pixel. This tomogram is written in the file &amp;lt;tt&amp;gt;cs30/CC.mrc&amp;lt;/tt&amp;gt;. Some auxiliary outputs are other volumes that store the angles [tdrot,tilt,narot] that maximize the cross-correlation for each pixel in the volume. It also creates a binned version of the tomogram, which will be useful to quickly crop particles for the purpose of evaluating the quality of the template matching. &amp;lt;br&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;b&amp;gt;Performance note &amp;lt;/b&amp;gt;: it is possible to run &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt; with several CPU cores in parallel, or with several GPUs. Both options increase the performance of the computation.&lt;br /&gt;
* The use of several CPUs can be called by the flag &amp;lt;tt&amp;gt;&#039;matlabWorkers&#039;&amp;lt;/tt&amp;gt; or &amp;lt;tt&amp;gt;&#039;mw&#039;&amp;lt;/tt&amp;gt; . The value &amp;lt;tt&amp;gt;&#039;*&#039;&amp;lt;/tt&amp;gt;  will instruct Matlab to use all available cores.&lt;br /&gt;
* You can activate the GPUs by the flag &amp;lt;tt&amp;gt;&#039;gpus&#039;&amp;lt;/tt&amp;gt;. For this, take into account that in this command, the numbers that identify each GPU device are the ones assigned by Matlab; they typically start with 1. This is in opposition to the device counting that you would get from the system, for instance through &amp;lt;tt&amp;gt;nvidia-smi&amp;lt;/tt&amp;gt;, where the counting starts typically with 0. &lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
=== The &amp;lt;tt&amp;gt;Process&amp;lt;/tt&amp;gt; object ===&lt;br /&gt;
The return &amp;lt;tt&amp;gt;pts&amp;lt;/tt&amp;gt; of the function &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt; is an object that keeps track of the location of all the created output, and is used in the subsequent steps that extract the actual location of the peaks&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
if you need to reload this object after closing a matlab shell, simply use dynamo_read() on the process.mat file in the template matching directory&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;pts = dread(&#039;cs30.TM/process.mat&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Locating cross correlation peaks  ==&lt;br /&gt;
&lt;br /&gt;
Now we need to identify which peaks of the cross correlation correspond to actual particles.&lt;br /&gt;
&lt;br /&gt;
=== Looking at the cross correlation map ===&lt;br /&gt;
&lt;br /&gt;
We first examine the cross correlation map.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;pts.showCC&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingCCRaw.png |thumb|center|500px| &amp;lt;tt&amp;gt;tmshow&amp;lt;/tt&amp;gt; on the CC volume  ]]&lt;br /&gt;
&lt;br /&gt;
It is possible to operate on the map (through bandpassing or gaussian filtering) to smoothen the volume and get rid of many spurious peaks, but  we won&#039;t do it like thtr in this exercise.&lt;br /&gt;
&lt;br /&gt;
=== Looking at the cross correlation profile ===&lt;br /&gt;
&lt;br /&gt;
We can get a plot of the cross-correlation value found on the local maxima of the cc volume wiith the order&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;pts.peaks.plotCCPeaks(&#039;sidelength&#039;,32);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The cross-correlation values of the peaks appear in ascending order. We can check the quality of the peaks by auxiliary clicking on the curve to select one particle and then selecting some visualization option. &lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingPeakGood.png |thumb|center|500px|  auxiliary click on the area of good peaks ]]&lt;br /&gt;
&lt;br /&gt;
The &amp;lt;tt&amp;gt;sidelength&amp;lt;/tt&amp;gt; that we pass will be used for this visualization options to crop the particle around the peak.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingPeakGoodVolume.png |thumb|center|500px  |  particle cropped around the selected correlation peak]]&lt;br /&gt;
&lt;br /&gt;
We click on a couple of particles in the area of kink in the cross-correlation to roughly estimate the cross-correlation threshold. In our case, it seems to be around 0.37 (being rather conservative)&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingPeakKink.png |thumb|center|500px |  Looking for an area of transition between good and bad peaks]]&lt;br /&gt;
&lt;br /&gt;
In the gaussian distribution below this ara , the peaks do not correspond to particles&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingPeakBad.png |thumb|center|500px | false positives ]]&lt;br /&gt;
&lt;br /&gt;
=== Extracting a table ===&lt;br /&gt;
A table can be extracted through:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;myTable = pts.peaks.computeTable(&#039;mcc&#039;,0.38);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In this procedure, the template is first placed back in the position of highest correlation, using the alignment parameters. Then the next correlation maximum is considered, and the template is placed in its location. If the second placement overlaps with the previous one, the second one is considered an spurious maximum and skipped. This procedure is repeated till a threshold of cross correlation is attained (0.38 in this case).&lt;br /&gt;
&lt;br /&gt;
This order creates the variable &amp;lt;tt&amp;gt;myTable&amp;lt;/tt&amp;gt; in the workspace, and stores a copy of it inside the &amp;lt;tt&amp;gt;pts&amp;lt;/tt&amp;gt; objects, so that we can use it to invoke some axiliary functions to evaluate the result of our experiment.&lt;br /&gt;
&lt;br /&gt;
== Visual evaluation of results ==&lt;br /&gt;
&lt;br /&gt;
=== Looking at  table positions===&lt;br /&gt;
&lt;br /&gt;
A sketch of the 3d positions of the particles can be created through&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtplot(myTable,&#039;pf&#039;,&#039;oriented_positions&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
where &amp;lt;tt&amp;gt;&#039;pf&#039;&amp;lt;/tt&amp;gt; stands for &#039;&#039;profile&#039;&#039;. There are different predefined visualization profiles that can be passed to &amp;lt;tt&amp;gt;dtplot&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[   File:TemplateMatchingTable3d.png |thumb|center|500px | Particle positions ]]&lt;br /&gt;
&lt;br /&gt;
When rotated to show the YZ plane we see the shape of the layer were proteosomes are packing. This indicates that we don&#039;t have too many false positives.&lt;br /&gt;
&lt;br /&gt;
[[   File:TemplateMatchingTable3dSide.png |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
=== Looking at cropped particles ===&lt;br /&gt;
We can check how the individual particles look like on a gallery modus:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;pts.peaks.browse();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This order just opens &amp;lt;tt&amp;gt;ddbrowse&amp;lt;/tt&amp;gt;. We are using here the support object &amp;lt;tt&amp;gt;peaks&amp;lt;/tt&amp;gt;, but this command is equivalent to just invoking &amp;lt;tt&amp;gt;ddbrowse&amp;lt;/tt&amp;gt; as &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;ddbrowse(&#039;d&#039;,&#039;cs30.TM/binnedTomogram.mrc&#039;,&#039;t&#039;,myTable); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingDDBrowseNoTable.png |thumb|center|500px| &amp;lt;tt&amp;gt;ddbrowse&amp;lt;/tt&amp;gt; with a tomogram as a data source, needing the input of a sidelength in pixels]]&lt;br /&gt;
&lt;br /&gt;
We check the first 100 particles, as they appear inside the tomogram (i.e., without aligning them). We use the &#039;&#039;z&#039;&#039; direction (corresponding to the direction of the electron beam)&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingDDBrowseZ.png |thumb|center|500px| Result launched by &amp;lt;tt&amp;gt;ddbrowse&amp;lt;/tt&amp;gt;  without a connected table  ]]&lt;br /&gt;
&lt;br /&gt;
Now we look at them along the &#039;&#039;z&#039;&#039; direction of the aligned particles.&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingDDBrowseWithTable.png |thumb|center|500px| The table must be connected to align the particles   ]]&lt;br /&gt;
&lt;br /&gt;
Along the z direction we can only recognize particles that were already in a top view/&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingDDBrowseZAligned.png|thumb|center|500px|  &#039;&#039;z&#039;&#039;-view of aligned particles ]]&lt;br /&gt;
&lt;br /&gt;
Note the different appearance of the particles along the &#039;&#039;x&#039;&#039; and &#039;&#039;y&#039;&#039; direction.&lt;br /&gt;
&lt;br /&gt;
{|style=&amp;quot;margin: 0 auto;&amp;quot;&lt;br /&gt;
| [[ File:TemplateMatchingDDBrowseXAligned.png |thumb|center|350px| &#039;&#039;x&#039;&#039;-view of aligned particles   ]]&lt;br /&gt;
| [[ File:TemplateMatchingDDBrowseYAligned.png |thumb|center|350px|  &#039;&#039;y&#039;&#039;-view of aligned particles  ]]&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
This different behaviour occurs because we haven&#039;t used any rotational search during the template matching procedure. Thus, the azimuthal angle is initialized to zero, creating this bias.&lt;br /&gt;
&lt;br /&gt;
=== Looking at averages ===&lt;br /&gt;
&lt;br /&gt;
The bias visualized in the aligned particles is not important for the purpose of locating the particles, but we need to take it into account if we want to produce a new template on the results we just computed. A simple averaging&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;oap = pts.peaks.average(48);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
will produce a density map showing this different behaviour along &#039;&#039;x&#039;&#039; and &#039;&#039;y&#039;&#039;. Note that we need to introduce a sidelength (48), as the particles have never been cropped to this point, we are extracting them continuously from the binned tomogram.&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;dview(oap);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingAverageRaw.png |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
We should randomize the azimuthal angle &lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;oapRandomized = pts.peaks.average(48,&#039;ra&#039;,1);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
in order to get a well balanced template&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingAverageRandomized.png |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
== Getting the tables back into the catalogue ==&lt;br /&gt;
&lt;br /&gt;
You don&#039;t need to operate with the catalogue: you could just use &amp;lt;tt&amp;gt;dtcrop&amp;lt;/tt&amp;gt; on the just computed table  to extract particles from the original tomogram into a [[data folder]]. However, cataloguing has to advantages:&lt;br /&gt;
* Eases keeping track of all the steps you&#039;ve performed, specially if you are going to use several tomograms, and..&lt;br /&gt;
*allows you to visualize the peaks on the tomogram interactively, so that you can delete false positives or add peaks that were not located by the template matching.&lt;br /&gt;
&lt;br /&gt;
===Rescaling the table ===&lt;br /&gt;
&lt;br /&gt;
Remember that the table that we are working with has the scale of the auxiliary binned volume that has been created along with the CC matrix. In the catalogue, we want to work with the particles in their original scale.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tableOriginalScale = dynamo_table_rescale(myTable,&#039;factor&#039;,2);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the syntax of &amp;lt;tt&amp;gt; dynamo_table_rescale&amp;lt;/tt&amp;gt;, the &amp;lt;tt&amp;gt;factor&amp;lt;/tt&amp;gt; is expressed in terms of how many times is the apix in the original table bigger than in the target table to be computed. In our case, the target table was computed with an apix of 14 Angstrom (one time binned in relation to the tomogram &amp;lt;tt&amp;gt;t20s.rec&amp;lt;/tt&amp;gt;, with an apix of 7.04A). The factor is thus 2. In case of doubt, it is convenient to just run &lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;dtinfo(tableOriginalScale);&amp;lt;/tt&amp;gt; &lt;br /&gt;
&lt;br /&gt;
to check the extent of the entries in the columns 24, 25 and 26, which are positions (in pixels) of the particles indexed by the table.  &lt;br /&gt;
Now, if we write the upscaled table into a file&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;dwrite(tableOriginalScale,&#039;peaks.tbl&#039;);&amp;lt;/tt&amp;gt; &lt;br /&gt;
&lt;br /&gt;
===Entering result in catalogue ===&lt;br /&gt;
we can just put this table back into the catalogue through:&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;dmimport -t peaks.tbl -c ct20s -i 1 -mn ccpeaks&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
which will create a model called &amp;lt;tt&amp;gt;ccpeaks&amp;lt;/tt&amp;gt; and assign it to the first volume (&amp;lt;tt&amp;gt;-i 1&amp;lt;/tt&amp;gt;) in the catalogue &amp;lt;tt&amp;gt;ct20s&amp;lt;/tt&amp;gt;. You can check it by writing:&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;dcm -c ct20s -i 1 -l m&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
which asks for a listing of models (&amp;lt;tt&amp;gt;-l m&amp;lt;/tt&amp;gt;) in the first volume of the catalogue.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingIntoCatalogue.png |thumb|center|500px  ]]&lt;br /&gt;
[[  File:TemplateMatchingIntoCatalogueZoom.png |thumb|center|500px | Zooming inside &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; with &amp;lt;tt&amp;gt;Ctrl+ mouse wheell&amp;lt;/tt&amp;gt; ]]&lt;br /&gt;
&lt;br /&gt;
The model is editable and you can add or remove individual points.&lt;br /&gt;
&lt;br /&gt;
== Discarding regions ==&lt;br /&gt;
&lt;br /&gt;
Below the planar area that contains the most proteosomes, we see several false positives. Some false positives insist in having high correlation peaks and cannot be discarded  by thresholding. In order to remove them, we can inspect and remove them individually. If they are too many, we will probably prefer to mark regions in the tomogram where we want to keep of discard peaks. In this case we will mark a polygon in the XZ plane, and keep those peaks that fall inside (indepently of the y coordinate). &lt;br /&gt;
&lt;br /&gt;
To to this, press [Y] to get a slice orthogonal to this direction, and adjust the transparence in order to see the points behind the slice.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingDiscardTransparence.png |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
Now, we create a surface model, and change its name to &amp;lt;tt&amp;gt;boundary&amp;lt;/tt&amp;gt; for future reference.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingSurfaceMenu.png |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
Use  the mouse while keeping CTRL pressed to adjust the view and see along the &#039;&#039;direction&#039;&#039;. Then, use C to draw a line that enclose the area where we see valid peaks.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingSurface.png |thumb|center|600px  ]]&lt;br /&gt;
&lt;br /&gt;
Don&#039;t forget to save the model when you are done.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingSurfaceSave.png |thumb|center|200px  ]]&lt;br /&gt;
&lt;br /&gt;
=== Keeping peaks inside the selected polygon ===&lt;br /&gt;
&lt;br /&gt;
Now, we can read both models into memory&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dcmodels ct20s -nc peaks -ws output&lt;br /&gt;
p = dread(output.files{1});&lt;br /&gt;
dcmodels ct20s -nc bound -ws output&lt;br /&gt;
b = dread(output.files{1});&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Consider only the XZ coordinates in both&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;pXZ = p.points(:,[1,3]);&lt;br /&gt;
bXZ = b.points(:,[1,3]);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and compute the indices of the points in the &amp;lt;tt&amp;gt;peaks&amp;lt;/tt&amp;gt; model that are enclosed inside the &amp;lt;tt&amp;gt;boundary&amp;lt;/tt&amp;gt; model (in the xz plane).&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;indicesOfPInsideB = inpolygon(pXZ(:,1),pXZ(:,2),bXZ(:,1),bXZ(:,2));&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Plotting the kept peaks ===&lt;br /&gt;
  &amp;lt;nowiki&amp;gt;f = figure();&lt;br /&gt;
hs1 = subplot(2,1,1);&lt;br /&gt;
h = dpkgeom.plotCloud(p.points); axis equal&lt;br /&gt;
h.Marker = &#039;.&#039;;&lt;br /&gt;
view([0,1,0]);&lt;br /&gt;
hs1.ZLim = [0,200];&lt;br /&gt;
hs1.XLim = [0,1000];&lt;br /&gt;
title(&#039;Original peaks&#039;);&lt;br /&gt;
&lt;br /&gt;
hs2 = subplot(2,1,2);&lt;br /&gt;
h = dpkgeom.plotCloud(p.points(indicesOfPInsideB,:)); axis equal; &lt;br /&gt;
h.Marker = &#039;.&#039;;&lt;br /&gt;
hold on;&lt;br /&gt;
hB = dpkgeom.plotCloud(b.points); axis equal&lt;br /&gt;
hB.Marker = &#039;o&#039;;&lt;br /&gt;
hB.LineStyle = &#039;--&#039;;&lt;br /&gt;
hB.MarkerFaceColor = &#039;b&#039;;&lt;br /&gt;
hB.Color = &#039;k&#039;;&lt;br /&gt;
title(&#039;Peaks inside boundary&#039;);&lt;br /&gt;
view([0,1,0]);&lt;br /&gt;
axis(hs2,axis(hs1)); &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingDiscardTPlot.png  |thumb|center|500px  ]]&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_command_line_based_tilt_series_alignment_(Tsinghua_Spring_School_2025)&amp;diff=5602</id>
		<title>Walkthrough on command line based tilt series alignment (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_command_line_based_tilt_series_alignment_(Tsinghua_Spring_School_2025)&amp;diff=5602"/>
		<updated>2025-03-03T05:41:57Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Data */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:WalkthroughsSpecific]]&lt;br /&gt;
&lt;br /&gt;
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 [[Walkthrough on GUI based tilt series alignment | 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).&lt;br /&gt;
&lt;br /&gt;
= Data =&lt;br /&gt;
&lt;br /&gt;
We use a binned version of the first tilt series from the EMPIAR entry 10164, depicting a set of virus like particles (VLP). You can download it directly from EMPIAR, then bin it,   &amp;lt;!--[https://drive.google.com/file/d/1EsnKBvbFuWD1njk8dRVLc3SlhdsTHIpY/view?usp=drive_link or simply follow this link]--&amp;gt;[{{Template:DownloadLinkAWFHIV1TS}} or simply follow this link] to download a 600Mb file. You can also follow this tutorial using your own data.&lt;br /&gt;
&lt;br /&gt;
In this course, the data for this walkthrough is in:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkAWFHIV1TS/&amp;lt;/tt&amp;gt;&lt;br /&gt;
and the tomogram with the data is in the link:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkAWFHIV1TS/b001ts001.mrc &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
= Create the workflow =&lt;br /&gt;
The following commands create a new alignment workflow in a separate folder. Make sure &#039;&#039;Dynamo&#039;&#039; is running and type the following commands into the Matlab command line (or the &#039;&#039;Dynamo&#039;&#039; console, if you work on the standalone version):&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;nowiki&amp;gt;name = &#039;hivCommandLine&#039;;&lt;br /&gt;
folder = &#039;workflows&#039;;&lt;br /&gt;
u = dtsa(name,&#039;--nogui&#039;,&#039;-path&#039;,folder,&#039;fp&#039;,1); &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
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 &amp;lt;tt&amp;gt;whos&amp;lt;/tt&amp;gt; to see a list of all variables in the workspace.&lt;br /&gt;
&lt;br /&gt;
= Entering the data =&lt;br /&gt;
&lt;br /&gt;
The variable &amp;lt;tt&amp;gt;u&amp;lt;/tt&amp;gt; is an object that contains several &#039;&#039;fields&#039;&#039; to interact with the workflow. They can be found through autocompletion by using the &amp;lt;tt&amp;gt;tab&amp;lt;/tt&amp;gt; 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.&lt;br /&gt;
&lt;br /&gt;
[[ File:alignCommandLine_autocompletionOfUserObject.png |thumb|center| 700px|autocompletion of user object to access different fields in matlab and standalone version]]&lt;br /&gt;
&lt;br /&gt;
== Basic data==&lt;br /&gt;
Basic data can be entered using the &#039;&#039;enter&#039;&#039; 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 and the angles are passed to the workflow:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;u.enter.tiltSeries(&#039;b001ts001.mrc&#039;);&lt;br /&gt;
u.enter.tiltAngles(-57:3:60); &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If necessary (not in this tutorial), you can use the &#039;&#039;discardedTiltIndices&#039;&#039; field to reject tilts that are of too bad quality using the following command (e.g., tilt 1 and 40):&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.enter.discardedTiltIndices([1,40]); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Acquisition settings==&lt;br /&gt;
Here you can enter parameters such as &amp;lt;tt&amp;gt;Cs&amp;lt;/tt&amp;gt;, nominal defocus, etc. For this tutorial we just provide the pixel size in Angstroms:&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.enter.settingAcquisition.apix(2.7);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Computation settings==&lt;br /&gt;
We enable the use of parallel cores&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.enter.settingComputing.parallelCPUUse(1); &amp;lt;/tt&amp;gt;&lt;br /&gt;
This will be using mainly for gold bead detection (cc computation) and reconstruction.&lt;br /&gt;
&lt;br /&gt;
To use all available physical cores use:&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.enter.settingComputing.cpus(&#039;*&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Detection settings==&lt;br /&gt;
These here are the actual design decisions when running an alignment workflow. The gold bead radius has to be known beforehand ( see [[Walkthrough on GUI based tilt series alignment | GUI based alignment walkthrough]] on how to measure it). Binning is used internally only for quick and robust bead detection.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;u.enter.settingDetection.detectionBinningFactor(1);&lt;br /&gt;
u.enter.settingDetection.beadRadius(16);&lt;br /&gt;
u.enter.settingDetection.maskRadius(28);&lt;br /&gt;
u.enter.templateSidelength(64);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Changing generic parameters ==&lt;br /&gt;
You can find all parameters of the individuals steps using autocompletion on the &amp;lt;tt&amp;gt;area&amp;lt;/tt&amp;gt; field and then by adding &amp;lt;tt&amp;gt;step&amp;lt;/tt&amp;gt; in the end. For example, the residual threshold of the tilt gap filler can be changed as follows:&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.area.indexing.step.tiltGapFiller.parameterSet.residualsThreshold(8);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
= Running the workflow =&lt;br /&gt;
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.&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.run.all(&#039;noctf&#039;,1);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Checking the results ==&lt;br /&gt;
After completion, the &amp;lt;tt&amp;gt;view&amp;lt;/tt&amp;gt; field allows you to check different output items for diagnose, such as the tilt lines:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.view.tiltLines.unaligned();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:alignCommandLine_viewOfTiltLines.png |thumb|center| 600px|view of tilt lines]]&lt;br /&gt;
&lt;br /&gt;
or the different reconstructions &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;u.view.reconstruction.binnedWBP();&lt;br /&gt;
u.view.reconstruction.binnedSIRT();&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
or the aligned stacks themselves.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.view.stack.alignedFull();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can also use the autocompletion of the &amp;lt;tt&amp;gt;info&amp;lt;/tt&amp;gt; field (as shown in the beginning) to find and display different logs:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;&amp;gt;&amp;gt; u.info.fit;&lt;br /&gt;
------------------------------------------------------------&lt;br /&gt;
File with info:&lt;br /&gt;
  workflows/hivCommandLine.AWF/info/fitting.doc&lt;br /&gt;
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - &lt;br /&gt;
rms:  1.41&lt;br /&gt;
psi: 85.20&lt;br /&gt;
fit modus: normal&lt;br /&gt;
total markers: 79&lt;br /&gt;
total observations: 2702&lt;br /&gt;
fit created at: 11-Aug-2021 10:56:24&lt;br /&gt;
------------------------------------------------------------&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;&amp;gt;&amp;gt; u.info.markers;&lt;br /&gt;
------------------------------------------------------------&lt;br /&gt;
Info on working markers [used during detection, indexing refinement]&lt;br /&gt;
  ... item saved and in memory&lt;br /&gt;
Item in memory:&lt;br /&gt;
Number of shapes          :  79&lt;br /&gt;
Number of frames          :  40&lt;br /&gt;
Number of observations    :  2702 (out of 3160)&lt;br /&gt;
Number of empty frames    :  1&lt;br /&gt;
Number of complete frames :  0&lt;br /&gt;
Number of complete shapes :  0&lt;br /&gt;
 &lt;br /&gt;
Item in disk:&lt;br /&gt;
Markers in disk and currently in memory contain equal coordinates&lt;br /&gt;
 &lt;br /&gt;
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - &lt;br /&gt;
 &lt;br /&gt;
Info on final markers [used from alignment step]&lt;br /&gt;
  ... item saved and in memory&lt;br /&gt;
Item in memory:&lt;br /&gt;
Number of shapes          :  79&lt;br /&gt;
Number of frames          :  40&lt;br /&gt;
Number of observations    :  2702 (out of 3160)&lt;br /&gt;
Number of empty frames    :  1&lt;br /&gt;
Number of complete frames :  0&lt;br /&gt;
Number of complete shapes :  0&lt;br /&gt;
 &lt;br /&gt;
Item in disk:&lt;br /&gt;
Markers in disk and currently in memory contain equal coordinates&lt;br /&gt;
------------------------------------------------------------&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If you are following this tutorial during a &#039;&#039;Dynamo&#039;&#039; workshop, the exercise ends here.&lt;br /&gt;
&lt;br /&gt;
= On the fly reconstruction of particles=&lt;br /&gt;
&lt;br /&gt;
In this section we show how to avoid having to reconstruct a &#039;&#039;&#039;full&#039;&#039;&#039; tomogram at &#039;&#039;&#039;full&#039;&#039;&#039; resolution for the case where only a set of subtomograms are need. For this exercise we will use the gold beads as proxies that represent any particles of interest. We will first locate a few of them in the &#039;&#039;&#039;binned&#039;&#039;&#039; tomogram, and then use those coordinates to directly reconstruct the subtomograms in full resolution and skipping the need to reconstruct the whole full sized tomogram..&lt;br /&gt;
&lt;br /&gt;
== Define coordinates in the binned tomogram==&lt;br /&gt;
&lt;br /&gt;
First, we open the binned reconstruction tht we created before using the visualization tool &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; and adjust the contrast if necessary (arrow):&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmslice &#039;workflows/hivCommandLine.AWF/reconstruction/binnedReconstructionWBP.mrc&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:alignCommandLine_dtmsliceOfBinnedReconstruction.png |thumb|center| 600px|dtmslice of binned reconstruction]]&lt;br /&gt;
[[ File:alignCommandLine_dtmsliceAfterContrastCorrection.png |thumb|center| 600px|dtmslice after contrast correction]]&lt;br /&gt;
To manually define the particle coordinates, we first open a new model of type &amp;lt;tt&amp;gt;general&amp;lt;/tt&amp;gt;:&lt;br /&gt;
[[ File:alignCommandLine_createANewModel.png |thumb|center| 600px|create a new model]]&lt;br /&gt;
To quickly find the 3d positions of a set of particles, we use a projection of the tomogram:&lt;br /&gt;
[[ File:alignCommandLine_showAFullProjection.png |thumb|center| 600px|show a full projection]]&lt;br /&gt;
[[ File:alignCommandLine_fullProjectionOfBinnedReconstruction.png |thumb|center| 600px|full projection of binned reconstruction]]&lt;br /&gt;
Right click on the (x,y) position of a particle opens two small windows showing the x-z and y-z planes:&lt;br /&gt;
[[ File:alignCommandLine_rightClickOnAPoint.png |thumb|center| 600px|right click on a point]]&lt;br /&gt;
Use the y-z depiction to left clicking on the marker. After clicking, the marker coordinates are saved in the model:&lt;br /&gt;
[[ File:alignCommandLine_xViewOfClickedPoint.png |thumb|center| 600px|x view of clicked point]]&lt;br /&gt;
[[ File:alignCommandLine_mainClickToFixThe3dCoordinates.png |thumb|center| 600px|main click to fix the 3d coordinates]]&lt;br /&gt;
Go back to the projection view and repeat the procedure until you have a few more markers (but no more than ten in this exercise). The x-z and y-z planes will be updated automatically when clicking on new markers on the projection and do not need to be closed every time. When you are done, you can close all the plane views and also the projection view.&lt;br /&gt;
[[ File:alignCommandLine_clickAroundTenMarkers.png |thumb|center| 600px|click around ten markers]]&lt;br /&gt;
To save the coordinates we first export them into the Matlab workspace in table format:&lt;br /&gt;
[[ File:alignCommandLine_exportATableIntoTheMatlabWorkspace.png |thumb|center| 600px|export a table into the matlab workspace]]&lt;br /&gt;
The Matlab shell should report the variable name used to store the table:&lt;br /&gt;
[[ File:alignCommandLine_theCommandLineShowsTheVariableNameAssignedToTheCreatedTable.png |thumb|center| 400px|the command line shows the variable name assigned to the created table]]&lt;br /&gt;
&lt;br /&gt;
Now we can save the table with the coordinates as a file in the current directory (this table will be used to crop the subtomograms in the next steps):&lt;br /&gt;
 &amp;lt;tt&amp;gt;dwrite(temp_table,&#039;binnedGoldbeads.tbl&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Cropping the gold bead particles ===&lt;br /&gt;
&lt;br /&gt;
We can now crop the particles using the table file that we generated before:&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;tomo = &#039;workflows/hivCommandLine.AWF/reconstruction/binnedReconstructionWBP.mrc&#039;;&lt;br /&gt;
tbl  = &#039;binnedGoldbeads.tbl&#039;;&lt;br /&gt;
targetBinnedParticles = &#039;binnedGoldBeads.Data&#039;;&lt;br /&gt;
sidelengthBinned = 32;&lt;br /&gt;
o = dtcrop(tomo,tbl, targetBinnedParticles, sidelengthBinned);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
To monitor if everything worked correctly, we visualize a projection along &amp;lt;tt&amp;gt;z&amp;lt;/tt&amp;gt; of each cropped particle using the command:&lt;br /&gt;
 &amp;lt;tt&amp;gt;dslices(targetBinnedParticles,&#039;proj&#039;,&#039;c&#039;);shg;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:alignCommandLine_dslicesOnBinnedGoldBeads.png |thumb|center| 600px|dslices on binned gold beads]]&lt;br /&gt;
== Reconstruct particles on the fly ==&lt;br /&gt;
&lt;br /&gt;
The command that reconstructs full sized particles from an aligned stack is &amp;lt;tt&amp;gt;dynamo_table_trec&amp;lt;/tt&amp;gt;. This is an independent function, not part of the workflow, implying that we will need to perform some format conversion.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tbl     = dread(&#039;binnedGoldbeads.tbl&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We scale the table. &amp;quot;Bin level 2&amp;quot; means that each pixel in the binned tomogram is 2 times twice its size in the full resolution tomogram. This is the factor that we input into &amp;lt;tt&amp;gt;dynamo_table_rescale&amp;lt;/tt&amp;gt;:&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;alignmentBinLevel = 2;&lt;br /&gt;
tblFull = dynamo_table_rescale(tbl,&#039;factor&#039;,2^alignmentBinLevel); &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Now we fetch the full sized aligned stack stored inside the alignment folder:&lt;br /&gt;
 &amp;lt;tt&amp;gt;source  = &#039;workflows/hivCommandLine.AWF/align/alignedFullStack.mrc&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We create a data folder to contain the particles to be reconstructed on the fly:&lt;br /&gt;
 &amp;lt;tt&amp;gt;targetDirectory = &#039;tempCrop.Data&#039;&amp;lt;/tt&amp;gt;;&lt;br /&gt;
&lt;br /&gt;
Angles &#039;&#039;actually&#039;&#039; used during the reconstruction are contained in the &#039;&#039;reconstructionTiltAngles&#039; item of the output folder. Note that they might differ from the nominal angles, as some views might have been eliminated, both explicitely by the user, of by the program not being able to align all tilts.&lt;br /&gt;
 &amp;lt;tt&amp;gt;angles =  &#039;workflows/hivCommandLine.AWF/align/reconstructionTiltAngles.tlt&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The (binned) coordinates were measured in a binned tomogram, whose dimensionality is requested by &amp;lt;tt&amp;gt;dynamo_table_rec&amp;lt;/tt&amp;gt;. We need to provide &amp;lt;tt&amp;gt;dynamo_table_rec&amp;lt;/tt&amp;gt; with &lt;br /&gt;
 &amp;lt;nowiki&amp;gt;visualizationTomogram =  &#039;workflows/hivCommandLine.AWF/reconstruction/binnedReconstructionWBP.mrc&#039;;&lt;br /&gt;
sizeTomogram = dynamo_read_size(visualizationTomogram);&lt;br /&gt;
sizeTomogramFull = sizeTomogram*2^alignmentBinLevel;&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The tomogram center can be shifted in order to account for a possible shift in the centre in the binned reconstruction that was used to crop the particles.&lt;br /&gt;
 &amp;lt;tt&amp;gt;shiftTomogramCenter = [0,0,0];&amp;lt;/tt&amp;gt;&lt;br /&gt;
We proceed now to the reconstruction. Our sid length should be 4 times the size we used before:&lt;br /&gt;
 &amp;lt;tt&amp;gt;sidelengthFullSize = 128;&amp;lt;/tt&amp;gt;&lt;br /&gt;
We use the &amp;lt;tt&amp;gt;applyRampFilter&amp;lt;/tt&amp;gt; option in order to explicitely estate the kind of filter that we want during the back projection.&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dynamo_table_rec(tblFull,source,angles,targetDirectory, sidelengthFullSize, &#039;applyRampFilter&#039;,1, &#039;sizeTomogram&#039;,sizeTomogramFull, &#039;shiftTomogramCenter&#039;,shiftTomogramCenter);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We can now check that the particles have been reconstructed in full size:&lt;br /&gt;
 &amp;lt;tt&amp;gt;figure;dslices(targetDirectory,&#039;proj&#039;,&#039;c&#039;);shg;&amp;lt;/tt&amp;gt;&lt;br /&gt;
[[ File:alignCommandLine_dslicesOnFullSizedGoldBeads.png |thumb|center| 600px|dslices on full sized gold beads]]&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_GUI_based_tilt_series_alignment_(Tsinghua_Spring_School_2025)&amp;diff=5601</id>
		<title>Walkthrough on GUI based tilt series alignment (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_GUI_based_tilt_series_alignment_(Tsinghua_Spring_School_2025)&amp;diff=5601"/>
		<updated>2025-03-03T05:41:21Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Data */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:WalkthroughsSpecific]]&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;Dynamo&#039;&#039; 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 GUI-based mode. The [[Walkthrough on command line based tilt series alignment | walkthrough on command line based tilt series alignment]] shows how to operate this procedure through the command line.&lt;br /&gt;
&lt;br /&gt;
= Data =&lt;br /&gt;
&lt;br /&gt;
We use a binned version of the first tilt series from the EMPIAR entry 10164, depicting a set of virus like particles (VLP). You can download it directly from EMPIAR, then bin it,   &amp;lt;!--[https://drive.google.com/file/d/1EsnKBvbFuWD1njk8dRVLc3SlhdsTHIpY/view?usp=drive_link or simply follow this link]--&amp;gt;[{{Template:DownloadLinkAWFHIV1TS}} or simply follow this link] to download a 600Mb file. You can also follow this tutorial using your own data.&lt;br /&gt;
&lt;br /&gt;
In this course, the data for this walkthrough is in:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkAWFHIV1TS/&amp;lt;/tt&amp;gt;&lt;br /&gt;
and the tomogram with the data is in the link:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkAWFHIV1TS/b001ts001.mrc &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
= Creating an alignment workflow= &lt;br /&gt;
&lt;br /&gt;
Start the alignment GUI by typing the command &amp;lt;tt&amp;gt;dtsa&amp;lt;/tt&amp;gt; (short form of &amp;lt;tt&amp;gt;dynamo_tilt_series_alignment&amp;lt;/tt&amp;gt;) into the &#039;&#039;Dynamo&#039;&#039; command line: &lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt&amp;gt;dtsa&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A pop-up window appears. Click on &amp;quot;create a new workflow&amp;quot;:&lt;br /&gt;
&lt;br /&gt;
[[ File:alignGUI_creatingAWorkflow.png |thumb|center| 600px|creating a workflow]]&lt;br /&gt;
&lt;br /&gt;
Here, the input data for the workflow (tilt series, angles, ...) is introduced:&lt;br /&gt;
&lt;br /&gt;
[[ File:alignGUI_inputWorkflowParameters.png |thumb|center| 600px|input workflow parameters]]&lt;br /&gt;
&lt;br /&gt;
The option &amp;lt;tt&amp;gt;configuration file&amp;lt;/tt&amp;gt; is used to pass information on possible tilts that should be discarded. Here, we leave this option untouched. Press on &#039;&#039;create workflow&#039;&#039;, to open the alignment GUI.&lt;br /&gt;
&lt;br /&gt;
= GUI description =&lt;br /&gt;
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:&lt;br /&gt;
# &#039;&#039;&#039;Menu:&#039;&#039;&#039; Different tools for visualization and customization of general settings. The option &#039;&#039;Settings&#039;&#039; &amp;gt; &#039;&#039;edit[general]&#039;&#039; for example lets you adjust the pixel size and different acquisition parameters such as Cs etc. Here we keep the default settings.&lt;br /&gt;
# &#039;&#039;&#039;Icons:&#039;&#039;&#039; Quick access to tools such as &#039;&#039;dmarkers&#039;&#039;, &#039;&#039;occupancy plot&#039;&#039;, &#039;&#039;gold bead gallery&#039;&#039;, &#039;&#039;gold bead targeting&#039;&#039;, &#039;&#039;fitting&#039;&#039; and &#039;&#039;marker selection&#039;&#039;. Their functionalities will be explained later.&lt;br /&gt;
# &#039;&#039;&#039;Tabs:&#039;&#039;&#039; The tabs describe the 6 &#039;&#039;execution areas&#039;&#039; that are executed from left to right: &#039;&#039;detection&#039;&#039;, &#039;&#039;indexing&#039;&#039;, &#039;&#039;refinement&#039;&#039;, &#039;&#039;alignment&#039;&#039;, &#039;&#039;ctf&#039;&#039;, &#039;&#039;reconstruction&#039;&#039;. Each execution areas contains a set of processing steps.&lt;br /&gt;
# &#039;&#039;&#039;Steps:&#039;&#039;&#039; 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 &#039;&#039;View&#039;&#039; button which provides specific tools to visualize and inspect the results of each step.&lt;br /&gt;
# &#039;&#039;&#039;Run options:&#039;&#039;&#039; Options to run multiple steps.&lt;br /&gt;
&lt;br /&gt;
[[ File:alignGUI_alignmentGUIBeforeCompletionOfAnyStep.png |thumb|center| 600px|alignment GUI before completion of any step]]&lt;br /&gt;
&lt;br /&gt;
= Processing =&lt;br /&gt;
We are now ready to run all the processing steps. In the following, each step is described in detail.&lt;br /&gt;
== Detection ==&lt;br /&gt;
The goal of this step is to find the positions of the gold bead projections in the tilt series.  To do that, &#039;&#039;Dynamo&#039;&#039; 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 (&#039;&#039;peak feature&#039;&#039; and &#039;&#039;peak selection&#039;&#039;).&lt;br /&gt;
&lt;br /&gt;
=== Visualization matrix ===&lt;br /&gt;
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 &#039;&#039;creates a binned tilt series&#039;&#039; button with a &#039;&#039;+&#039;&#039; symbol, an option box appears, indicating the default binning factor which is 2. This parameter can be changed by users. Binning factor 2 in &#039;&#039;Dynamo&#039;&#039; is equivalent to a binning factor of 4 in &#039;&#039;IMOD&#039;&#039;.&lt;br /&gt;
Click on &#039;&#039;creates a binned tilt series&#039;&#039; button to create a binned tilt series stack.&lt;br /&gt;
Rightclick on &#039;&#039;View&#039;&#039; button to visualize the newly binned tilt series stack in &amp;lt;tt&amp;gt;tmshow&amp;lt;/tt&amp;gt;. In the &amp;lt;tt&amp;gt;tmshow&amp;lt;/tt&amp;gt; window, visualization parameters as binning, band and thickness can be adjusted if needed.&lt;br /&gt;
&lt;br /&gt;
Now, we are going to measure the diameter of the gold beads precisely in &amp;lt;tt&amp;gt;tmshow&amp;lt;/tt&amp;gt; in the original (unbinned) tilt series data. To do that, press the &#039;&#039;IO&#039;&#039; in the upper toolbox of the &#039;&#039;alignment workflow GUI&#039;&#039;, then go to &#039;&#039;tilt series matrix &amp;gt; inspect &amp;gt; On-the-fly view [dtmshow]&#039;&#039;. The &amp;lt;tt&amp;gt;tmshow&amp;lt;/tt&amp;gt; window opens, adjust contrast if necessary for better visualization.&lt;br /&gt;
[[ File:openOriginalTiltSeriesDataGUI.png |thumb|center| 600px| open unbinned tilt series data to measure gold bead diameter]]&lt;br /&gt;
&lt;br /&gt;
Zoom in a gold bead by holding the &amp;lt;tt&amp;gt;shift&amp;lt;/tt&amp;gt; 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 &amp;lt;tt&amp;gt;shift&amp;lt;/tt&amp;gt; key again and dragging with right mouse click on &amp;lt;tt&amp;gt;tmshow&amp;lt;/tt&amp;gt; window.&lt;br /&gt;
&lt;br /&gt;
[[ File:alignGUI_openTomoshowOnTheFullSizedMatrixToCheckTheSizeOfAGoldBead.png |thumb|center| 600px|open tomoshow on the full sized matrix to check the size of a gold bead]]&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
[[ File:OriginalGoldBeadDiameter.png |thumb|center| 600px|the ruler tool allows to measure in pixels the diameter of a gold bead]]&lt;br /&gt;
&lt;br /&gt;
=== Detection of gold beads ===&lt;br /&gt;
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).&lt;br /&gt;
&lt;br /&gt;
[[ File:alignGUI_DetectionParameters.png |thumb|center| 600px|the plus icon at corner reveals the values of the parameters of a given step.]]&lt;br /&gt;
&lt;br /&gt;
After pressing the button &#039;&#039;detect peaks&#039;&#039;, &#039;&#039;Dynamo&#039;&#039; 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 &#039;&#039;detect peaks&#039;&#039; button turns black bold, the computation is finished. Right click on the &amp;lt;tt&amp;gt;view&amp;lt;/tt&amp;gt; area of the step to access the different visualisation options.&lt;br /&gt;
&lt;br /&gt;
[[ File:alignGUI_markerSetsCanBeViewedAsCloudOfPoints.png |thumb|center| 600px| Secondary click the view panel to open a menu to access different results of a step. Marker sets can be viewed as cloud of points.]]&lt;br /&gt;
&lt;br /&gt;
This view shows the overlaid sum of the x,y coordinates of &#039;&#039;all&#039;&#039; cc peaks from &#039;&#039;all&#039;&#039; micrographs in the tilt series.&lt;br /&gt;
[[ File:alignGUI_cloudOfUnindexedCcPeaks.png |thumb|center| 600px|cloud of unindexed cc peaks]]&lt;br /&gt;
We can also check the positions of all the detected spots on each micrograph:&lt;br /&gt;
[[ File:alignGUI_showsTheDetectedSpotsOnTheVideoGUI.png |thumb|center| 600px|shows the detected spots on the video GUI]]&lt;br /&gt;
This GUI does not allow for edition of the markers. &#039;&#039;&#039;Tip:&#039;&#039;&#039; enable &#039;&#039;auto&#039;&#039; option at the bottom center of the visualization GUI to facilitate tilt series visualization.&lt;br /&gt;
[[ File:alignGUI_staticVideoAnnotationsCannotBeEdited.png |thumb|center| 600px|static video annotations cannot be edited]]&lt;br /&gt;
The neighbourhood of cross correlation peaks can be visualised individually as 2D patches from the tilt series image data:&lt;br /&gt;
[[ File:alignGUI_EachPatchWillBeAPutativeGoldBead.png |thumb|center| 600px|Each patch will be a putative gold bead]]&lt;br /&gt;
[[ File:alignGUI_theSetOfCcPeaksIsShownAsAMontage.png |thumb|center| 600px|the set of cc peaks is shown as a montage]]&lt;br /&gt;
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&lt;br /&gt;
[[ File:alignGUI_exampleOfFailedSearch.png |thumb|center| 600px|example of failed gold bead detection]]&lt;br /&gt;
Note that you have the option of testing your parameters against a single image before launching a full detection procedure. Right-click on the tool icon on the right side of &#039;&#039;detect peaks&#039;&#039; pushbutton.&lt;br /&gt;
[[ File:alignGUI_toolboxOptionForTestingTheParametersOnACentralImage.png |thumb|center| 600px|toolbox option for testing the parameters on a central image]]&lt;br /&gt;
[[ File:alignGUI_resultsOfTestingOnACentralImage.png |thumb|center| 600px|results of testing on a central image]]&lt;br /&gt;
&lt;br /&gt;
=== Computation of observation features ===&lt;br /&gt;
At this stage, the observed cross correlation peaks are analysed. A merit figure is assigned to each peak based on a &#039;&#039;rotational merit&#039;&#039; that measures its rotational symmetry. Press the button &#039;&#039;Peak features&#039;&#039; 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:&lt;br /&gt;
[[ File:alignGUI_patchGalleryForFeatures.png |thumb|center| 600px|patch gallery for features]]&lt;br /&gt;
[[ File:alignGUI_theGalleryAllowsRelatingAppearanceOfGoldBeadAnValueOfTheFeatures.png |thumb|center| 600px|the gallery shows the detected gold beads, the CC score (yellow) and the rotational merit (red). Tilt number is purple.]]&lt;br /&gt;
or extracting properties of the whole data set.&lt;br /&gt;
[[ File:alignGUI_featurePlotterAllowsCheckingOfTheFeatureValuesOnTheWholeSet.png |thumb|center| 600px|feature plotter allows checking of the feature values on the whole set]]&lt;br /&gt;
[[ File:alignGUI_scatter2dOption.png |thumb|center| 600px| We select &#039;&#039;scatter&#039;&#039;, set the y axis to &#039;&#039;rotationaMerit&#039;&#039; and then press &#039;&#039;Scatter 2d.]]&lt;br /&gt;
[[ File:alignGUI_eachPointRepresentsACcPeak.png |thumb|center| 600px| We get a scatter plot of each peak and its relation to the CC and rotational merit score. Seeing two distinct populations means that the majority of the gold beads are distinguishable from other signal such as background.]]&lt;br /&gt;
&lt;br /&gt;
=== Selection of best gold beads===&lt;br /&gt;
The population with the best markers is automatically selected by clicking on &#039;&#039;Peak selection&#039;&#039;. The results can be inspected again in a plot&lt;br /&gt;
[[ File:alignGUI_checkObservationCloudAfterSelectionOrClustering.png |thumb|center| 600px|check observation cloud after selection or clustering ]]&lt;br /&gt;
[[ File:alignGUI_observationCloudHasBeenThinned.png |thumb|center| 600px|observation cloud has been thinned]]&lt;br /&gt;
or in the micrographs themselves:&lt;br /&gt;
[[ File:alignGUI_checkMarkerPositionsAfterClustering.png |thumb|center| 600px|check marker positions after clustering]]&lt;br /&gt;
[[ File:alignGUI_markerPositionsAfterClustering.png |thumb|center| 600px|marker positions after clustering]]&lt;br /&gt;
&lt;br /&gt;
== Indexing == &lt;br /&gt;
The goal of this execution area is to find &#039;&#039;trails&#039;&#039; 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 &#039;&#039;working markers&#039;&#039;.&lt;br /&gt;
&lt;br /&gt;
=== Rough Alignment ===&lt;br /&gt;
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 &#039;&#039;occupancy graph&#039;&#039;&lt;br /&gt;
[[ File:alignGUI_occupancySchemeOfTheResultsOfAStep.png |thumb|center| 600px|occupancy scheme of the results of a step]]&lt;br /&gt;
[[ File:alignGUI_roughAlignmentSelectsManyPotentialTrails.png |thumb|center| 600px| The rough alignment selects many potential trails. On the x-axis is the tilt number, on the y-axis the trail number and each red dot marks the presence of a marker.]]&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
=== Keep long chains ===&lt;br /&gt;
Click on &#039;&#039;keep long chains&#039;&#039; to select the longest trails, which will then be used to generate a 3d model of the markers:&lt;br /&gt;
[[ File:alignGUI_trailsWithFewMarkersAreThenRejected.png |thumb|center| 600px|short trails have been rejected]]&lt;br /&gt;
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.&lt;br /&gt;
[[ File:alignGUI_noteWorkingMarkersCanBeRestoredToTheResultOfAPreviousStep.png |thumb|center| 600px|working markers can be restored to the result of a previous step]]&lt;br /&gt;
&lt;br /&gt;
=== Iterative reindexing ===&lt;br /&gt;
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 &#039;&#039;iterative reindexing&#039;&#039;.&lt;br /&gt;
[[ File:alignGUI_parametersForIterativeReindexing.png |thumb|center| 600px|parameters for iterative reindexing]]&lt;br /&gt;
[[ File:alignGUI_resultOfIterativeReindexing.png |thumb|center| 600px|Result of iterative reindexing. Missing markers have been added to the trails]]&lt;br /&gt;
&lt;br /&gt;
===Tilt gap filling ===&lt;br /&gt;
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 &#039;&#039;fill tilts without markers&#039;&#039;.&lt;br /&gt;
[[ File:alignGUI_parametersForTiltGapFiller.png |thumb|center| 600px|parameters for tilt gap filler]]&lt;br /&gt;
[[ File:alignGUI_occupancyAfterTiltGapFiller.png |thumb|center| 600px|Results of tilt gap filler. Note how (in this example) a lot of markers have been rescued on the first tilt.]]&lt;br /&gt;
[[ File:alignGUI_weHave66TracesAfterGapFiller.png |thumb|center| 600px|Click on &#039;&#039;working markers&#039;&#039; to see that (in this example) we have 66 traces after tilt gap filling.]]&lt;br /&gt;
[[ File:alignGUI_resultsOfTiltGapFiller.png |thumb|center| 600px|results of tilt gap filler (&#039;&#039;show markers created by this step on tilt series&#039;&#039;)]]&lt;br /&gt;
&lt;br /&gt;
===Trail extension===&lt;br /&gt;
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.&lt;br /&gt;
&amp;lt;!--[[ File:alignGUI_parametersOfTiltExtensor.png |thumb|center| 600px|parameters of tilt extensor]]--&amp;gt;&lt;br /&gt;
[[ File:align_gui_parameters_tilt_extensor.png |thumb|center| 600px|parameters of tilt extensor]]&lt;br /&gt;
[[ File:alignGUI_trailExtensorAddsAFewNewTrails.png |thumb|center| 600px|trail extensor adds a few new trails]]&lt;br /&gt;
&lt;br /&gt;
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. &lt;br /&gt;
[[ File:alignGUI_someOfTheNewTrailsHaveEmptySpaces.png |thumb|center| 600px|some of the new trails may have empty spaces]]&lt;br /&gt;
[[ File:alignGUI_resultOfTrailExtensor.png |thumb|center| 600px|result of trail extensor]]&lt;br /&gt;
&lt;br /&gt;
==Refinement ==&lt;br /&gt;
This area refines the positions of the gold beads. We will run all steps of this area by pressing on a single button (the &#039;&#039;run this tab&#039;&#039; option at the bottom of the GUI). The button will remain green while the different steps are computed.&lt;br /&gt;
[[ File:alignGUI_tabForRefinement.png |thumb|center| 600px|tab for refinement]]&lt;br /&gt;
Check the current refinement error:&lt;br /&gt;
[[ File:alignGUI_betterFiitingIsAttained.png |thumb|center| 600px|better fitting is attained]]&lt;br /&gt;
Optionally, we can use the scissors icon to &amp;quot;trim&amp;quot; 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 &#039;&#039;Tools&#039;&#039; and then &#039;&#039;Show residuals per observation&#039;&#039;:&lt;br /&gt;
[[ File:alignGUI_trimmingOfMarkersCanBeAccessedThroughTheScissorIcon.png |thumb|center| 600px|trimming of markers can be accessed through the scissor icon]]&lt;br /&gt;
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.&lt;br /&gt;
[[ File:alignGUI_residualsAtEachObservation.png |thumb|center| 600px|residuals at each observation]]&lt;br /&gt;
&lt;br /&gt;
== Alignment ==&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
=== Fix the markers ===&lt;br /&gt;
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 &#039;&#039;fix alignment markers&#039;&#039;.&lt;br /&gt;
&lt;br /&gt;
[[ File:alignGUI_areaForCreationOfAnAlignedTiltSeries.png |thumb|center| 600px|area for creation of an aligned tilt series]]&lt;br /&gt;
&lt;br /&gt;
=== Align the tilt series ===&lt;br /&gt;
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 &#039;&#039;Create full-size aligned stack&#039;&#039; and &#039;&#039;Create binned aligned stack&#039;&#039;. For a quick assessment, open the binned stack in tomoshow:&lt;br /&gt;
[[ File:alignGUI_visualizationOfAlignedTiltStack.png |thumb|center| 600px|visualization of aligned tilt stack]]&lt;br /&gt;
[[ File:alignGUI_binnedAlignedTiltStack.png |thumb|center| 600px|binned aligned tilt stack]]&lt;br /&gt;
A quick way to gauge the quality of the alignment is by checking that the beads move nicely horizontally over all tilts.&lt;br /&gt;
&lt;br /&gt;
== CTF  ==&lt;br /&gt;
In this GUI, CTF estimation and correction are done using CTFFIND4 and IMOD&#039;s ctfphaseflip. This part will not be used in the workshop.&lt;br /&gt;
&lt;br /&gt;
== Reconstruction ==&lt;br /&gt;
&lt;br /&gt;
=== Binned reconstruction ===&lt;br /&gt;
Click on &#039;&#039;binned reconstruction&#039;&#039; 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 &#039;&#039;binned SIRT-like reconstruction&#039;&#039; to generate a high contrast tomogram. Run the step &#039;&#039;binned reconstruction&#039;&#039; and visualize the resulting binned SIRT-like tomogram: &lt;br /&gt;
[[ File:alignGUI_chooseAVisualization.png |thumb|center| 700px|choose a visualization]]&lt;br /&gt;
[[ File:alignGUI_binnedWeightedBackProjectionReconstruction.png |thumb|center| 600px|binned SIRT-like reconstruction]]&lt;br /&gt;
&lt;br /&gt;
=== Full sized reconstruction ===&lt;br /&gt;
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:&lt;br /&gt;
[[ File:alignGUI_thePinToolIsUsefulForLocatingIsolatedPoints.png |thumb|center| 600px|Click in the center of an object of interest using the pin tool.]]&lt;br /&gt;
&lt;br /&gt;
We check the size of the structure by using the measuring tool:&lt;br /&gt;
[[ File:alignGUI_weCheckTheDistanceOfTheObjectOfInterest.png |thumb|center| 600px|we check the distance of the object of interest]]&lt;br /&gt;
&lt;br /&gt;
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 &#039;&#039;use center of binned coordniates&#039;&#039; and enter the values we measured before with the pin tool. Select &#039;&#039;WBP reconstruction&#039;&#039; and run the step &#039;&#039;full reconstruction&#039;&#039;. Use the inspection tools to fetch the result:&lt;br /&gt;
[[ File:alignGUI_asAnSpecificViewerIsNotAvailableForThisStepWeCanUseTheToolboxOfTheStepsItems.png |thumb|center| 700px|as an specific viewer is not available for this step we can use the toolbox of the steps items]]&lt;br /&gt;
&lt;br /&gt;
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:&lt;br /&gt;
[[ File:alignGUI_theFullSizeReconstructionIncludesOnlyTheObjectOfInterest.png |thumb|center| 600px|the full size WBP reconstruction includes only the object of interest]]&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_manual_marker_clicking_(Tsinghua_Spring_School_2025)&amp;diff=5600</id>
		<title>Walkthrough on manual marker clicking (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_manual_marker_clicking_(Tsinghua_Spring_School_2025)&amp;diff=5600"/>
		<updated>2025-03-03T05:40:32Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Loading the data */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:WalkthroughsSpecific]]&lt;br /&gt;
&lt;br /&gt;
This walkthrough describes the tools to &#039;&#039;manually&#039;&#039; locate fiducial markers for tilt series alignment using different graphical tools. &#039;&#039;Automatic&#039;&#039; alignment is described in [[Walkthrough on GUI based tilt series alignment]] and [[Walkthrough on command line based tilt series alignment ]].&lt;br /&gt;
&lt;br /&gt;
= Data set =&lt;br /&gt;
We use a binned version of the first tilt series from the EMPIAR entry 10164, depicting a set of virus like particles (VLP). You can download it directly from EMPIAR, then bin it,   &amp;lt;!--[https://drive.google.com/file/d/1EsnKBvbFuWD1njk8dRVLc3SlhdsTHIpY/view?usp=drive_link or simply follow this link]--&amp;gt;[{{Template:DownloadLinkAWFHIV1TS}} or simply follow this link] to download a 600Mb file. You can also follow this tutorial using your own data.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;!--This tutorial uses the tilt series VPP_tomo4.mrc from the EMPIAR database entry 10064. You can download it directly from the website: https://www.ebi.ac.uk/pdbe/emdb/empiar/entry/10064/{{Template:DownloadLinkAWFmanualEMPIAR}}&lt;br /&gt;
&lt;br /&gt;
The tilt series has already been prepared and can be found by following the next steps.--&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note that this tilt series has the following tilt angles: &amp;lt;code&amp;gt;-57:3:60&amp;lt;/code&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
= The &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt; GUI =&lt;br /&gt;
&lt;br /&gt;
This GUI is the basic tool for exploring tilt series and annotating on it  using  &#039;&#039;Dynamo&#039;&#039;. It allows to edit manually positions of markers, to fit them to a projection model, and to create an aligned data stack and a reconstruction based on this fitting.&lt;br /&gt;
&lt;br /&gt;
== Loading the data ==&lt;br /&gt;
&lt;br /&gt;
In this course, the data for this walkthrough is in:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkAWFHIV1TS/&amp;lt;/tt&amp;gt;&lt;br /&gt;
and the tomogram with the data is in the link:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkAWFHIV1TS/b001ts001.mrc &amp;lt;/tt&amp;gt;&lt;br /&gt;
Opening the &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt; GUI on a tilt series:&lt;br /&gt;
&lt;br /&gt;
It is convenient to first read the tilt series: &amp;lt;br/&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;ts = dread(&#039;b001ts001.mrc&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and then pass the variable to the gui &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt;:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; gui = dmarkers(ts,&#039;tiltAngles&#039;,-57:3:60);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
here, &amp;lt;tt&amp;gt;gui&amp;lt;/tt&amp;gt; is just a handle to the GUI. This handle can be used on a later point to operate on it. Note that we also need to pass the tilt angles, as they will be needed for fitting a projection model. &lt;br /&gt;
&lt;br /&gt;
[[File:manual_marker_HIV_TS.png|thumb|center|600px| &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt; GUI ]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&amp;lt;!--Opening the &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt; GUI on a tilt series:&lt;br /&gt;
&lt;br /&gt;
It is convenient to first read the tilt series: &amp;lt;br/&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the &#039;&#039;&#039;local version&#039;&#039;&#039; that was distributed yesterday: &amp;lt;br/&amp;gt;&lt;br /&gt;
 &amp;lt;tt&amp;gt;ts = dread(&#039;b001ts001.mrc&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the remote version: &amp;lt;br/&amp;gt;&lt;br /&gt;
 &amp;lt;tt&amp;gt;ts = dread(&#039;b001ts001_15_08_2023.mrc&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and then pass the variable to the gui &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt;:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; gui = dmarkers(ts,&#039;tiltAngles&#039;,-57:3:60);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
here, &amp;lt;tt&amp;gt;gui&amp;lt;/tt&amp;gt; is just a handle to the GUI. This handle can be used on a later point to operate on it. Note that we also need to pass the tilt angles, as they will be needed for fitting a projection model. &lt;br /&gt;
&lt;br /&gt;
[[File:ManualAlignmentDmarkers.png|thumb|center|600px| &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt; GUI ]]--&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Basic visualization controls ==&lt;br /&gt;
&lt;br /&gt;
=== Slide on micrographs ===&lt;br /&gt;
* Use the slide bar to view a transition of the micrographs (lower resolution images will be shown during the transition, full resolution images will be shown )&lt;br /&gt;
* left and right arrows move the  previous or next micrograph in the tilt series.&lt;br /&gt;
&lt;br /&gt;
===Zoom=== &lt;br /&gt;
* You can zoom into a point by using the wheel. &lt;br /&gt;
* The small red  window in the tool bar can be used as magnifying-glass to zoom in into a  hand-draw a region.&lt;br /&gt;
* The tool with the four arrows pointing into the corners zooms out of the scene totally.&lt;br /&gt;
&lt;br /&gt;
[[File:ManualAlignmentControls.png|thumb|center|400px|  Basic controls inn &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt; GUI ]]&lt;br /&gt;
&lt;br /&gt;
=== Dragging ===&lt;br /&gt;
The scene gets dragged by moving the mouse while keeping pressed the right mouse button.&lt;br /&gt;
&lt;br /&gt;
=== Elimination of defective tilts ===&lt;br /&gt;
&lt;br /&gt;
Some micrographs may be defective because of errors during acquisition. They can be markers as invalid by the key  &amp;lt;tt&amp;gt;x&amp;lt;/tt&amp;gt;. If you want to undo the marking of a micrograph as invalid, use &amp;lt;tt&amp;gt;shift+x&amp;lt;/tt&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
== Initiating a trace ==&lt;br /&gt;
A  three-dimensional gold bead is represented by a &#039;&#039;trace&#039;&#039;. A trace is a set of &#039;&#039;observations&#039;&#039;, where we call observation to the location of the projection of a gold bead in a given micrograph.&lt;br /&gt;
&lt;br /&gt;
The tool with a black point and a red edge starts the trace initiator. The cursor in the GUI becomes a cross; while this cursor is active, clicking on the screen will create a new gold bead.&lt;br /&gt;
&lt;br /&gt;
== Following a trace ==&lt;br /&gt;
To select a gold bead, click on it with the mouse, a green box will appear on the observation corresponding to the selected markers  in the current micrograph. &#039;&#039;&#039;Important&#039;&#039;&#039;:  to add observations into a trace that you have just created, you need to select it, otherwise your next clicks on the screen will be assigned to the trace that is currently under selection.&lt;br /&gt;
&lt;br /&gt;
Once you have selected a gold bead, you should switch off the tool for adding gold beads, and switch on the tool for adding observations to the gold bead currently under selection. The icon represents a point being tracked  across  several micrographs.&lt;br /&gt;
&lt;br /&gt;
You can use the arrows to move to the next or previous micrograph after clicking the gold bead.&lt;br /&gt;
&lt;br /&gt;
Additionally, you can connect the &#039;&#039;click and right&#039;&#039; or &#039;&#039;click and left&#039;&#039; tools. When they are switched on, after a click on the screen, the GUI will automatically move to the next micrograph.&lt;br /&gt;
&lt;br /&gt;
[[File:ManualAlignmentSetGoldBead.png |thumb|center|400px|  The gold bead click tools sets new traces, the track tool allows adding new observations to the currently selected trace ]]&lt;br /&gt;
&lt;br /&gt;
=== Key controls during clicking ===&lt;br /&gt;
&lt;br /&gt;
* &amp;lt;tt&amp;gt;d&amp;lt;/tt&amp;gt; will delete the closest observation (point in currently shown  micrograph).&lt;br /&gt;
* &amp;lt;tt&amp;gt;shift&amp;lt;/tt&amp;gt; + &amp;lt;tt&amp;gt;d&amp;lt;/tt&amp;gt; will delete a full trace.&lt;br /&gt;
*  &amp;lt;tt&amp;gt;m&amp;lt;/tt&amp;gt; will move the observation of the currently selected shape to the location of the cursor.&lt;br /&gt;
&lt;br /&gt;
=== Auxiliar views during clicking ===&lt;br /&gt;
There are two auxiliary GUIs that can be used to control the growth of the traces based as you click the points. The &#039;&#039;occupancy&#039;&#039; window updates as a new observation is added into a gold bead, showing the current content of each trace. And additional control shows the content of each trace as new points are clicked inside.&lt;br /&gt;
&lt;br /&gt;
[[File:ManualAlignmentControlViewers.png |thumb|center|400px|  Tools to follow the traces across the micrographs ]]&lt;br /&gt;
&lt;br /&gt;
== Saving the marker set ==&lt;br /&gt;
We want to save current set of markers into disk, by using the &amp;lt;tt&amp;gt;save to disk&amp;lt;/tt&amp;gt; option in the &amp;lt;tt&amp;gt;Tracks&amp;lt;/tt&amp;gt; menu. This will create the file &amp;lt;tt&amp;gt;Tracks.dms&amp;lt;/tt&amp;gt; in disk.&lt;br /&gt;
&lt;br /&gt;
= Fitting to an alignment model =&lt;br /&gt;
&lt;br /&gt;
When you have enough observations, you can proceed to fitting the location of your gold beads to a projection model. The tool with the icon &amp;lt;tt&amp;gt;Fit&amp;lt;/tt&amp;gt; will compute a set of shifts and a single angle &amp;lt;tt&amp;gt;psi&amp;lt;/tt&amp;gt; of rotation for the tilt axis. &lt;br /&gt;
&lt;br /&gt;
In the &#039;&#039;Fit&#039;&#039; menu on the GUI, you can find the current error, i.e., the mean residual between each observation and the projection estimated by the fitting model.&lt;br /&gt;
&lt;br /&gt;
[[File:ManualAlignmentFitting.png |thumb|center|400px| Fitting menu in &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
== Extended fitting models ==&lt;br /&gt;
In a coarse fitting, &#039;&#039;Dynamo&#039;&#039; only tries to solve for shifts and a single rotation angle for all micrographs. It is possible to refine this fitting allowing a different rotation of the tilt axis for each micrograph. You can select for a richer model that computes for one different rotation angle on each micrograph by checking the option &amp;lt;tt&amp;gt;eachTilt&amp;lt;/tt&amp;gt;  on the parameter &amp;lt;tt&amp;gt;psi&amp;lt;/tt&amp;gt; (default is &amp;lt;tt&amp;gt;single&amp;lt;/tt&amp;gt;). &lt;br /&gt;
&lt;br /&gt;
Although you will get a lower error value, this might be due to overfitting. Thus, richer parametric models should not be used if you don&#039;t have enough markers on each micrograph (in the order of the tens.)&lt;br /&gt;
&lt;br /&gt;
= Reconstruction through the command line =&lt;br /&gt;
&lt;br /&gt;
Creating reconstructions through the command line is convenient when organizing the processing of  batches of tilt series. Automatic selection of markers is explored in a different walkthrough, here we describe the command line tools for creating reconstructions once a marker set is available. The steps are:&lt;br /&gt;
* Fitting of the available markers (using a &#039;&#039;fitter&#039;&#039; object).&lt;br /&gt;
* Extraction of alignment  parameters (using an &#039;&#039;aligner&#039;&#039; object).&lt;br /&gt;
* Creation of an aligned tilt series.&lt;br /&gt;
* Weighting the tilt series appropriately for a weighted-back-projection or Sirt-like reconstruction.&lt;br /&gt;
* Creation of the tomogram through back projecting the filtered aligned stack.&lt;br /&gt;
&lt;br /&gt;
If you have a set of markers saved  in a file in disk, you can load it to memory through:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;markers = dread(&#039;Tracks.dms&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Then, you can create a fitter object:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;fitter = dfitter(markers);&amp;lt;/tt&amp;gt;&lt;br /&gt;
 &lt;br /&gt;
This object needs to know where to put the rotation center of the aligned tilt series. &lt;br /&gt;
 &amp;lt;tt&amp;gt;fitter.setCenter(ts);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and prepare it to run with standard parameters:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;fitter.physical.defaultInitialization();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The command&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;fitter.linearScan();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
will then compute the best &amp;lt;tt&amp;gt;psi&amp;lt;/tt&amp;gt; angle for the rotation of the tilt axis together with the shifts.  They can be gathered into an stack alignment object&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;stackAligner = fitter.getStackAligner();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
that gets then applied onto the original tilt series in the variable &amp;lt;tt&amp;gt;ts&amp;lt;/tt&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tsAligned  = stackAligner.applyOnStack(ts);&amp;lt;/tt&amp;gt; &lt;br /&gt;
&lt;br /&gt;
This aligned stack can be visualized through:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmshow(tsAligned);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Binned reconstruction  ==&lt;br /&gt;
&lt;br /&gt;
A reconstruction with a bigger pixel size can be computed by resizing both tilt series and markers. A marker object can be resized through:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;markersBinned = markers.math.bin(2);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Here, the factor 2 indicates that the coordinates of the markers get halved twice. This factor needs to be applied also to the tilt series:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tsBinned = dpktilt.bin(ts,2);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Now, we can refit the binned markers, proceeding as above:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;pre&amp;gt;binnedFitter = dfitter(markersBinned);&lt;br /&gt;
binnedFitter.setCenter(tsBinned);&lt;br /&gt;
binnedFitter.physical.defaultInitialization();&lt;br /&gt;
binnedFitter.linearScan();&lt;br /&gt;
binnedAligner = binnedFitter.getStackAligner();&lt;br /&gt;
tsBinnedAligned = binnedAligner.applyOnStack(tsBinned);&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
To create a weighted back projection reconstruction, this stack needs to be weighted with a ramp function in the Fourier space.&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;tt&amp;gt; tsBinnedRamp = dpktomo.rec.applyRampFilter(tsBinnedAligned);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Then, we can use the command &amp;lt;tt&amp;gt;dpktilt.math.backproject&amp;lt;/tt&amp;gt; to create a reconstruction.&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;fbp = dpktilt.math.backproject([400,400,400],tsBinnedRamp,-57:3:60,&#039;mw&#039;,&#039;*&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Here, the flag &amp;lt;tt&amp;gt;&#039;mw&#039;&amp;lt;/tt&amp;gt; is merely instructing &#039;&#039;Dynamo&#039;&#039; to use all available cores.&lt;br /&gt;
&lt;br /&gt;
In case you did not mark a bead on every tilt you might get an error message at this point. Ideally you would go back and either mark at least one bead on the corresponding tilt or, if there are no good beads, you would exclude the tilt. Alternatively (but not recommended) you can use the following command to exclude the tilts without marked beads from the reconstruction:&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;fbp = dpktilt.math.backproject([400,400,400],tsBinnedRamp,fitter.physical.thetas(fitter.physical.indicesActiveTilts),&#039;mw&#039;,&#039;*&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
The reconstruction object &amp;lt;tt&amp;gt;fbp&amp;lt;/tt&amp;gt; contains the reconstructed tomogram in its property &amp;lt;tt&amp;gt;.rec&amp;lt;/tt&amp;gt;, which can be visualized through:&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmshow(fbp.rec);&amp;lt;/tt&amp;gt;&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Complete_walkthrough_on_FHV_virus_(Tsinghua_Spring_School_2025)&amp;diff=5599</id>
		<title>Complete walkthrough on FHV virus (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Complete_walkthrough_on_FHV_virus_(Tsinghua_Spring_School_2025)&amp;diff=5599"/>
		<updated>2025-03-03T05:39:19Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Downloading */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:WalkthroughsSpecific]]&lt;br /&gt;
&lt;br /&gt;
This walkthrough uses a small size example based on a real tomogram to cover several tasks.&lt;br /&gt;
&lt;br /&gt;
== The example data set ==&lt;br /&gt;
&lt;br /&gt;
The data is a fraction of a tomogram.  The full tomogram was used in &amp;quot;Cryo-electron tomography reveals novel features of a viral RNA replication compartment.&amp;quot;  (Ertel et al.), and represents several FHV viruses docked in the outer membrane of a mitochondrion.&lt;br /&gt;
&lt;br /&gt;
 [[File:FhvDefinitionCrown.png|thumb|center|500px| Average for several hundreds of particles. The &amp;quot;crown&amp;quot; area is shown under a red shadow.]]&lt;br /&gt;
&lt;br /&gt;
== Downloading ==&lt;br /&gt;
&lt;br /&gt;
In this course, the data for this walkthrough is in:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/Users/user**/Data/FHV/&amp;lt;/tt&amp;gt;&lt;br /&gt;
and the tomogram with the data is in the link:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/Users/user**/Data/FHV/DownloadLinkFHVDrive/crop.rec &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===Size check of a file===&lt;br /&gt;
&lt;br /&gt;
In order to work, you can copy it to the working folder in which you are operating now.:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt &amp;gt; cp /mnt/fs/2025workshop/Data/FHV/DownloadLinkFHVDrive/crop.rec . &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Ok, you just brought the tomogram file to your current folder. You&#039;re probably curious to see what&#039;s inside, so that let&#039;s write first:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dfile crop.rec&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
to let &#039;&#039;Dynamo&#039;&#039; check the dimensions of the file. The header of a &amp;lt;tt&amp;gt;.rec&amp;lt;/tt&amp;gt; file is readed as a regular &amp;lt;tt&amp;gt;.mrc&amp;lt;/tt&amp;gt;, yielding:&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;nowiki&amp;gt;filetype: volume&lt;br /&gt;
 size: 1285 x 956 x 786&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
So, it&#039;s a tomogram.&lt;br /&gt;
&lt;br /&gt;
===Lightweight visualization===&lt;br /&gt;
We can inspect quickly its contents with [[Viewing_tomograms#dtmshow | dtmshow]]&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmshow -otf crop.rec&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Hereby, the flag &amp;lt;tt&amp;gt;-otf&amp;lt;/tt&amp;gt; means &amp;quot;on the fly&amp;quot;, telling &amp;lt;tt&amp;gt;dtmshow&amp;lt;/tt&amp;gt; to &#039;&#039;not&#039;&#039; preload the full tomogram, but to access in disk the individual slices that are needed when inspecting a particular area.&lt;br /&gt;
&lt;br /&gt;
 [[File:FhvTomoshowOnTheFly.png|thumb|center|500px|Basic controls of &amp;lt;tt&amp;gt;dtmshow&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
Go up and down. We want to select the locations were the vesicles intersect the mitochondrion membrane and average them together. For this, we need to &#039;&#039;catalogue&#039;&#039; the tomogram, so that our annotations are stored with a clear relationship with the tomogram.&lt;br /&gt;
&lt;br /&gt;
== Cataloguing the tomogram ==&lt;br /&gt;
&lt;br /&gt;
We can create catalogues just to contain a single tomogram. They are useful to keep track of all annotations, and of the typical transforms (binning, cropping of fractions) that we usually perform on a larged size tomogram of interest. In this case, we can create the catalogue directly from the command line: &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; dcm -create fhv &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
where &amp;lt;tt&amp;gt;dcm&amp;lt;/tt&amp;gt; is the short form of &amp;lt;tt&amp;gt;dynamo_catalogue_manager&amp;lt;/tt&amp;gt; and &amp;lt;tt&amp;gt;fhv&amp;lt;/tt&amp;gt; is just an arbitrary name. The just created catalogue is empty, and we can add our tomogram with:&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;dcm -c fhv -at crop.rec&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We can check that the tomogram is in the catalogue by asking &#039;&#039;Dynamo&#039;&#039; to show the contents of the catalogue&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcm -c fhv -l tomograms&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
or &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcm -c fhv -l t&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The flag &amp;lt;tt&amp;gt;-l&amp;lt;/tt&amp;gt; asks &#039;&#039;Dynamo&#039;&#039; to list items of a given category of catalogue contents, in this case &amp;lt;tt&amp;gt;tomograms&amp;lt;/tt&amp;gt; &lt;br /&gt;
&lt;br /&gt;
=== Prebinning the tomograms ===&lt;br /&gt;
&lt;br /&gt;
We typically want to [[prebinned tomograms | prebin]] the tomogram, i.e., have a version of |smaller size that is known to the catalogue. This version will be useful in some operations that require a full tomogram in memory, an operation that can consume much memory and need a long time. In this example, this would not be necessary: a tomogram with a sidelength on x and y of ~1000 pixels shouldn&#039;t pose any visualization problem. We do it anyway for the exercise with the command:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dynamo_catalogue_bin(&#039;fhv&#039;, 1, &#039;zchunk&#039;, 300); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
where the parameter &amp;lt;tt&amp;gt;zchunk&amp;lt;/tt&amp;gt; represents the maximum number of z slices that are kept simultaneously in the memory during the binning process. This parameter might be important for larger size tomograms.&lt;br /&gt;
&lt;br /&gt;
=== Operation with GUI===&lt;br /&gt;
&lt;br /&gt;
These steps could have been performed thorough the &amp;lt;tt&amp;gt;dcm&amp;lt;/tt&amp;gt; GUI&lt;br /&gt;
&lt;br /&gt;
== Annotation of particle positions ==&lt;br /&gt;
Now we can open the tomogram through the catalogue:&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmslice crop.rec -c fhv  -prebinned 1 &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 [[File:FhvTomosliceOpen.png|thumb|center|500px|dtmslice opened on the FHV example tomogram&amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
Probably you don&#039;t like the initial contrast, change it with the button in the toolbar.&lt;br /&gt;
&lt;br /&gt;
 [[File:FhvTomosliceContrast.png|thumb|center|500px|contrast adjustment options inside &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
=== Navigating the tomogram ===&lt;br /&gt;
&lt;br /&gt;
* left click and drag the slice with your mouse to move it up and down&lt;br /&gt;
* this can also be achieved with the controls on the left hand side&lt;br /&gt;
* ctrl + left click and drag will change your viewpoint of the 3d scene&lt;br /&gt;
* shift + left click and drag will move the center of rotation&lt;br /&gt;
* ctrl + mouse wheel up/down will zoom in or out of the scene&lt;br /&gt;
&lt;br /&gt;
Other [[Dtmslice#Viewing controls | axiliary tools]] are the keys x,y,z to change the slice orientation, the number of projected slices (called &amp;quot;thickness&amp;quot; in the GUI controls), the transparency of the slice.&lt;br /&gt;
&lt;br /&gt;
You can reset the scene at any time by hitting the reset button.&lt;br /&gt;
&lt;br /&gt;
You can save slices for viewing later with the s key.&lt;br /&gt;
&lt;br /&gt;
=== Creation of models to contain annotations===&lt;br /&gt;
&lt;br /&gt;
In this example we just want to manually pick some particles. This can be done creating a general or box [[models|model]], which will [[model pool | reside in memory  ]] till we save it into the catalogue. &lt;br /&gt;
&lt;br /&gt;
 [[File:FhvBoxesModel.png|thumb|center|500px|Creating a new model in the scene. Each annotation is represented by a box]]&lt;br /&gt;
&lt;br /&gt;
After creating the model, it will be only model currently active in the &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; scene.  You can add new points pressing on [c].  The idea is to mark on the positions where you see the &amp;quot;neck&amp;quot; of a vesicle (what we called &amp;quot;crowns&amp;quot;) in contact with the outer mitochondrial membrane.&lt;br /&gt;
&lt;br /&gt;
[[File:FhvCloseUp.png|thumb|center|500px|Clicking the crowns on screen]]&lt;br /&gt;
&lt;br /&gt;
The last marked point can be deleted by pressing [delete]. An arbitrary point can be deleted by clicking on it with the auxiliary mouse button. This will open a menu that includes the option of deleting the point (through Ctrl+X in Linux or Cmmd+X in Mac).&lt;br /&gt;
&lt;br /&gt;
At this stage you probably want to change the transparence of the depicted slice, so that you can control which objects have been already clicked below the depicted slide.&lt;br /&gt;
&lt;br /&gt;
 [[File:FhvSelectedPoints.png|thumb|center|500px|Selection of points. Transparency of slide was set to 0.8]].&lt;br /&gt;
&lt;br /&gt;
When you are done, remember to save the model, using the menu options on active model or simply clicking on the disk icon in tomoslice.&lt;br /&gt;
&lt;br /&gt;
== Cropping particles ==&lt;br /&gt;
&lt;br /&gt;
Now we want to use the positions that we have marked to extract the subtomograms and format them as a [[data folder]]. The first thing we need is an estimation of the sidelength in pixels of each of the subtomograms. In [[dtmslice]] We can use the keys [1] and [2] to define two anchor points that appear as rombohedra. Clicking (with the right button) onto the black dashed that links the will show on screen both coordinates and the distance between them. All distances are reported in pixels of the non-binned tomogram: even if you are using a binned version, &#039;&#039;Dynamo&#039;&#039; keeps track of it.&lt;br /&gt;
&lt;br /&gt;
 [[File:FhvMeasureDistance.png|thumb|center|500px|Measuring distances with [1] , [2] and right-click]].&lt;br /&gt;
&lt;br /&gt;
We will thus choose to create a datafolder with a cubic sidelength of 128 pixels (remember that the particles will be cropped in the &#039;&#039;unbinned&#039;&#039; tomogram). This will ensure that the crowns fit comfortably inside the physical box, even if our manual picking imposes an error of several pixels. If you were using, say, a &#039;&#039;thickness&#039;&#039; parameter of 10 pixles in &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt;, you have to count with at least this inaccuracy in the location of the particles.&lt;br /&gt;
&lt;br /&gt;
Now, we check that the  catalogued tomogram contains the model that we manually picked before:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;&amp;gt;&amp;gt; dcmodels fhv&lt;br /&gt;
Volume 1 contains 1 models in total&lt;br /&gt;
/Users/casdanie//fhv/tomograms/volume_1/models/mboxes.omd&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In your system, instead of &amp;lt;tt&amp;gt;/Users/casdanie/&amp;lt;/tt&amp;gt; you will see the path to the  folder where you created the catalogue &amp;lt;tt&amp;gt;fhv&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Creating a table ===&lt;br /&gt;
We could just use  the catalogue GUI to extract the particles, be it is also possible to proceed directly  with the command line. We will use the  &amp;lt;tt&amp;gt;dtcrop&amp;lt;/tt&amp;gt; command, .which requires preparing a [[table]] with the information of the model. &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;m = dread(&#039;/Users/casdanie/fhv/tomograms/volume_1/models/mboxes.omd&#039;);&lt;br /&gt;
t = m.grepTable();&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Here, you read the file into a model object (which we arbitrarily choose to call &amp;lt;tt&amp;gt;m&amp;lt;/tt&amp;gt;), and then you use the &amp;lt;tt&amp;gt;grepTable&amp;lt;/tt&amp;gt; method on this object to extract a variable into your workspace. We arbitrarily call it &amp;lt;tt&amp;gt;t&amp;lt;/tt&amp;gt;. &lt;br /&gt;
&lt;br /&gt;
Note that we can extract models directly from the output of &amp;lt;tt&amp;gt;dcmodels&amp;lt;/tt&amp;gt;&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dcmodels fhv -i 1 -ws o;&lt;br /&gt;
m = dread(o.files{1});&lt;br /&gt;
t = m.grepTable();&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
i.e., we load the answer of &amp;lt;tt&amp;gt;dcmodels&amp;lt;/tt&amp;gt; for volume index &amp;lt;tt&amp;gt;-i 1&amp;lt;/tt&amp;gt; in the output variable &amp;lt;tt&amp;gt;o&amp;lt;/tt&amp;gt;.  Inside it, there is a field called &amp;lt;tt&amp;gt;&#039;files&#039;&amp;lt;/tt&amp;gt; which contains a [[matlab cell array| cell array]] of files containing models.  Then we read the first entry &amp;lt;tt&amp;gt;o.files{1}&amp;lt;/tt&amp;gt;. &lt;br /&gt;
&lt;br /&gt;
Whichever way you create the table variable &amp;lt;tt&amp;gt;t&amp;lt;/tt&amp;gt;, it is just a matrix with a row for each particle, and a summary of the information coded inside can be created through:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;&amp;gt;&amp;gt; dtinfo(t);&lt;br /&gt;
 &lt;br /&gt;
        size                :  22 35 &lt;br /&gt;
        NaNs                :  0&lt;br /&gt;
 &lt;br /&gt;
 COLUMN &lt;br /&gt;
[  2  ] marked for alignment:  22&lt;br /&gt;
[  3  ] included in average :  22&lt;br /&gt;
[ 4-6 ] shifts              :  all zero&lt;br /&gt;
[ 7-9 ] angles              :  all zero&lt;br /&gt;
[  10 ] cross correlation   :  min: 0.00  max: 0.00  mean: 0.00  std: 0.00&lt;br /&gt;
[  13 ] Fourier sampling    :  1 (single tilt around y) &lt;br /&gt;
[  13 ] fsampling types     :  all of the same type &lt;br /&gt;
[14-15] ytilt range         :  min:120.00   max:120.00&lt;br /&gt;
[16-17] xtilt range         :  min:120.00   max:120.00&lt;br /&gt;
[  20 ] linked volumes      :  total 1 (labels: [1])&lt;br /&gt;
[  21 ] regions inside tomograms :  total 1 (labels: [0])&lt;br /&gt;
[  22 ] user-defined classes:  total 1 (labels: [0])&lt;br /&gt;
[  23 ] annotation types    :  total 1 (labels: [0])&lt;br /&gt;
[24-26] spatial locations   :  initialized: 22&lt;br /&gt;
[  24 ]   *  x              :  min: 645.21  max: 1001.92  mean: 799.05  std: 109.44&lt;br /&gt;
[  25 ]   *  y              :  min: 23.78  max: 917.51  mean: 484.07  std: 271.28&lt;br /&gt;
[  26 ]   *  z              :  min: 198.00  max: 563.00  mean: 415.55  std: 114.03&lt;br /&gt;
[  31 ] original tags       :  total 1 (labels: [0])&lt;br /&gt;
[  32 ] compacted particles :  total 1 (labels: [1])&lt;br /&gt;
[  34 ] references          :  total 1 (labels: [0])&lt;br /&gt;
[  35 ] subreferences       :  total 1 (labels: [0])&lt;br /&gt;
[  36 ] apix                :  Warning: column not available in this table&lt;br /&gt;
[  37 ] defocus             :  Warning: column not available in this table&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Using &amp;lt;tt&amp;gt;dtcrop&amp;lt;/tt&amp;gt; ===&lt;br /&gt;
 &lt;br /&gt;
The simplest  syntax of &amp;lt;tt&amp;gt;dtcrop&amp;lt;/tt&amp;gt; requires passing the name of the tomogram from which we want to crop (syntax varies for [[ Particle extraction#Extract from different tomograms| cropping from multiple tomograms]]). We know that the file is &amp;lt;tt&amp;gt;crop.rec&amp;lt;/tt&amp;gt;, and we could directly insert this name in the command. But a catalogued model already contains information about its source tomogram (inside its property &amp;lt;tt&amp;gt;cvolume&amp;lt;/tt&amp;gt;), so that we can always track it back. We could then define a variable &amp;lt;tt&amp;gt;tomogramFile&amp;lt;/tt&amp;gt; by accessing this information inside the model variable &amp;lt;tt&amp;gt;m&amp;lt;/tt&amp;gt;:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tomogramFile = m.cvolume.file();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
if you get a warning at this stage, don&#039;t worry, the command still worked.&lt;br /&gt;
&lt;br /&gt;
You can then launch the cropping order:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;o = dtcrop(tomogramFile,t,&#039;particlesData&#039;,128);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
where you could add the &amp;lt;tt&amp;gt;mw&amp;lt;/tt&amp;gt; flag to let &#039;&#039;Dynamo&#039;&#039; use several cores. In any case, for this number or particles the cropping should take some seconds. The last part of the final output into screen should look like this:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;21 [read_subtomogram] Volume has size 1285 956 786&lt;br /&gt;
[read_subtomogram] Accessing subvolume x: 713:840; y: 339:466; z: 160:287  totalling ~ 16.0Mb&lt;br /&gt;
Elapsed time is 0.191014 seconds.&lt;br /&gt;
22 &lt;br /&gt;
Total time invested in cropping: 7s&lt;br /&gt;
[table_crop] Done extracting 20 particles&lt;br /&gt;
             from tomogram      :&amp;quot;/Users/casdanie/dynamo/devmac/workplace/paris/crop.rec&amp;quot; &lt;br /&gt;
             destination folder :&amp;quot;particlesData&amp;quot; &lt;br /&gt;
             excluded particles : 2   &lt;br /&gt;
 &lt;br /&gt;
 [ok] table_crop &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
informing you that some of the particles where excluded, as they were probably too close to the boundary of the tomogram, given the sidelength we asked for.  Inside the created data folder,&lt;br /&gt;
you will find the table &amp;lt;tt&amp;gt;particlesData/crop.tbl&amp;lt;/tt&amp;gt;, which only indexes the actually cropped particles.&lt;br /&gt;
&lt;br /&gt;
=== Creating an average ===&lt;br /&gt;
 &lt;br /&gt;
The particles can now be averaged together. They have different orientations, but in this tomogram we only have a fraction of the membrane. &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;oa = daverage(&#039;particlesData&#039;,&#039;t&#039;,&#039;particlesData/crop.tbl&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If you want to let &#039;&#039;Dynamo&#039;&#039; pass maps into Chimera, you have to inform &#039;&#039;Dynamo&#039;&#039;  on the location of Chimera. For instance: &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dchimera -setPath  /usr/local/bin/ &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Please adapt it to the location of Chimera in your file system.&lt;br /&gt;
&lt;br /&gt;
To open your average in chimera&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;tt&amp;gt; dchimera(oa.average) &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Project to find membrane orientations==&lt;br /&gt;
&lt;br /&gt;
We first need to create files with the average and the table that we have till now in memory:&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dwrite(t,&#039;raw.tbl&#039;);&lt;br /&gt;
dwrite(oa.average,&#039;rawTemplate.em&#039;);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We can create a project directly thorugh the command line:&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcp.new(&#039;first&#039;,&#039;d&#039;,&#039;particlesData&#039;,&#039;template&#039;,&#039;rawTemplate.em&#039;,&#039;masks&#039;,&#039;default&#039;,&#039;t&#039;,&#039;particlesData/crop.tbl&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
...and go directly to the panel of numerical parameters to create a project adapted for catching the general orientation of the membrane:&lt;br /&gt;
 [[File:FhvFirstParameters.png|thumb|center|500px| Numerical parameters for just membrane orientation]]&lt;br /&gt;
&lt;br /&gt;
Also, remember to visit the window for execution environment, and select the appropriate settings. If you are working with Matlab, select &#039;&#039;Matlab&#039;&#039;(for one single core) or &amp;quot;Matlab_parfor&amp;quot; (if you are going to several cores. Be aware that it requires the parallel computing toolbox.). If working with the standalone, use the [[standalone]]  option.  In both cases, select the number of cores for alignment (green box in the picture below) and averaging (blue and green arrow) .  &lt;br /&gt;
&lt;br /&gt;
 [[File:fhv_any_computing_enviroment.png|thumb|center|500px| Selecting the execution modus]]&lt;br /&gt;
&lt;br /&gt;
You can operate the project management operations from the GUI or the command line. First checking:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dvcheck first&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
then unfolding &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dvunfold first&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and finally running it by invoking the name of the execution script.&lt;br /&gt;
&lt;br /&gt;
* If you are running in Matlab use: &amp;lt;code&amp;gt;run first.m &amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* For the standalone, first opening a new terminal (in a new tab), loading &#039;&#039;Dynamo&#039;&#039; but not running it and starting the alignment project by typing: &amp;lt;code&amp;gt;./first.exe&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
After running the project, we check the created average:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;ddb first:a -v &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This command asks the  database (hence &amp;lt;tt&amp;gt;db&amp;lt;/tt&amp;gt;) of the project &amp;lt;tt&amp;gt;first&amp;lt;/tt&amp;gt; to look for the item of type &amp;lt;tt&amp;gt;average&amp;lt;/tt&amp;gt;, by default accessing  the last computed one. The flag &amp;lt;tt&amp;gt;-v&amp;lt;/tt&amp;gt; sends the output of the database query to the depiction GUI called &amp;lt;tt&amp;gt;dview&amp;lt;/tt&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
 [[File:FhvFirstAverage.png|thumb|center|500px|First average, no azimuthal rotation was tested. Shown in &amp;lt;tt&amp;gt; dview&amp;lt;/tt&amp;gt; program]]&lt;br /&gt;
&lt;br /&gt;
Apparently, the project finds the membranes and centers the particles correctly.  If you show the volume in Chimera (by clicking in the &#039;&#039;Export&amp;gt;Send to Chimera&#039;&#039; option in the &amp;lt;tt&amp;gt;dview&amp;lt;/tt&amp;gt; window ).&lt;br /&gt;
&lt;br /&gt;
[[File:FhvFirstChimera.png|thumb|center|500px|First average, no azimuthal rotation was tested ]]&lt;br /&gt;
&lt;br /&gt;
We can check the individual particles:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;ddbrowse -d first:data -t first:rt &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FhvDdbrowseFirstZ.png|thumb|center|700px| ddbrowse explores the aligned particles, each one represented as a projection. ]].&lt;br /&gt;
&lt;br /&gt;
== Aligning  the axis of symmetry ==&lt;br /&gt;
&lt;br /&gt;
We would like to bring the axis of symmetry to the &#039;&#039;z&#039;&#039;direction. This will create an intuitive separation between the two first euler angles that represent &amp;quot;change of orientation of the main axis&amp;quot;, and the third one that represents &amp;quot;azimuthal rotation about the new axis&amp;quot;.  We want that azimuthal rotations occur about an axis of possible symmetry, which by convention is located along z. There are several ways to achieve this. A simple one is to create a model of the membrane/crown geometry, align our average to it (with &amp;lt;tt&amp;gt;dalign&amp;lt;/tt&amp;gt;), and use the alignment parameters to create a new table. With this new table and average we will be able study possible symmetries with a new project.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
=== Creating a template aligned with z ===&lt;br /&gt;
&lt;br /&gt;
Geometrical shapes of many types can be created with &amp;lt;tt&amp;gt;dmask,dsphere,dcylinder,dshell&amp;lt;/tt&amp;gt; and &amp;lt;tt&amp;gt;dtube&amp;lt;/tt&amp;gt;, and combined with &amp;lt;tt&amp;gt;dynamo_mask_combine&amp;lt;/tt&amp;gt;. However, there are also some available utilities to create templates representing frequently occurring membraneous geometries:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;mr = dpktomo.examples.motiveTypes.MembraneWithRod();&lt;br /&gt;
mr.sidelength = 128;&lt;br /&gt;
mr.rodRadius = 20; mr.rodShift = [0,0,10]; mr.rodHeight= 20;&lt;br /&gt;
mr.getMask();&lt;br /&gt;
template  = mr.mask;&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note that you can check the list of properties inside the object &amp;lt;tt&amp;gt;mr&amp;lt;/tt&amp;gt; just by typing it without the semicolon and pressing [Return]&lt;br /&gt;
&lt;br /&gt;
We can check the result with:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;mr.viewMask();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FhvTemplateZ.png|thumb|center|700px| A simple template with rotational symmetry axis aligned along z]]&lt;br /&gt;
&lt;br /&gt;
=== Aligning the previous average along z ===&lt;br /&gt;
The mask is white on black by definition. The tomogram data in this case represents bright protein on dark background, so that in this case we want to align the previously computed average to the mask of the &amp;lt;tt&amp;gt;mr&amp;lt;/tt&amp;gt; object. &lt;br /&gt;
&lt;br /&gt;
The alignment does not need to scan azimuthal rotations, so that our &#039;inplane_range&#039; will be 0. The &#039;cone_range&#039; will be the full sphere, and we take and spacing of 30 degrees. As we are looking for coarse orientations, we can bin the two volumes twice (yielding volumes with a sidelength of 32 pixels). We will also &amp;quot;nail&amp;quot; the new center to the physical center of the box (parameter &amp;lt;tt&amp;gt;limm&amp;lt;/tt&amp;gt; set to 1 below).&lt;br /&gt;
&lt;br /&gt;
Now we read the average computed by the project &amp;lt;tt&amp;gt;first&amp;lt;/tt&amp;gt; into a workspace variable which we arbitrarily call &amp;lt;tt&amp;gt;previousAverage&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;ddb first:a -r previousAverage;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Here, the volume &amp;lt;tt&amp;gt;previousAverage&amp;lt;/tt&amp;gt; will be treated as a &amp;quot;particle&amp;quot; to be aligned onto a &#039;&#039;template&#039;&#039;, which in this case is the volume contained in &amp;lt;tt&amp;gt;mr.mask&amp;lt;/tt&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;sal = dalign(previousAverage,mr.mask,&#039;cr&#039;,360,&#039;cs&#039;,30,&#039;ir&#039;,0,&#039;dim&#039;,32,&#039;limm&#039;,1,&#039;lim&#039;,[10,10,10]); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The flags are the same parameters that would be used in an alignment project. You can check the shorthands with &amp;lt;tt&amp;gt;dvhelp&amp;lt;/tt&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
The output result &amp;lt;tt&amp;gt;sal&amp;lt;/tt&amp;gt; contains many fields. We can, for instance directly visualize how the previous average looks like when transformed through the results of this &amp;lt;tt&amp;gt;dalign&amp;lt;/tt&amp;gt; operation.  For this, use the field &amp;lt;tt&amp;gt;aligned_particle&amp;lt;/tt&amp;gt; in the output &amp;lt;tt&amp;gt;sal&amp;lt;/tt&amp;gt;:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dview(sal.aligned_particle);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
[[File:ZAlignedAverage.png|thumb|center|700px| A simple template with rotational symmetry axis aligned along z]]&lt;br /&gt;
&lt;br /&gt;
=== Applying the z-alignment to the table ===&lt;br /&gt;
&lt;br /&gt;
We don&#039;t want just to get a z-oriented average: we also want to convert the table yield by the &amp;lt;tt&amp;gt;first&amp;lt;/tt&amp;gt; project into a table that, when applied onto the original data, produces a correct, z-aligned average. For this, we use the alignment parameters coded inside the output &amp;lt;tt&amp;gt;sal&amp;lt;/tt&amp;gt;  (as field &amp;lt;tt&amp;gt;.Tp&amp;lt;/tt&amp;gt;) and apply them onto the table.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;ddb first:rt -r tf&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The variable &amp;lt;tt&amp;gt;tf &amp;lt;/tt&amp;gt; contains now the original table, which is now rotated and shifted according with the rigid body transform &amp;lt;tt&amp;gt;Tp&amp;lt;/tt&amp;gt; inside &amp;lt;tt&amp;gt;sal&amp;lt;/tt&amp;gt;&lt;br /&gt;
  &amp;lt;tt&amp;gt;tr =  dynamo_table_rigid(tf,sal.Tp); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
now the &#039;&#039;rectified &#039;&#039;table &amp;lt;tt&amp;gt;tr&amp;lt;/tt&amp;gt;   should contain the metadata that makes the particles &amp;quot;point upward&amp;quot;. We use now the typical sanity check to assess that a table behave as expected: we apply it to the particles in its paired [[data folder]] and check the average:&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;tt&amp;gt;oz = daverage(&#039;first:data&#039;,&#039;t&#039;,tr,&#039;fc&#039;,1); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
whose results can be checked by:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dview(oz); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSanityCheckZ.png|thumb|center|700px| Particles aligned with rectified table &amp;lt;tt&amp;gt;tr&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
We can visualize this operation by plotting a sketch with the orientation of the particles. We first show the results for the table computed in the project &amp;lt;tt&amp;gt;first&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;figure;&lt;br /&gt;
dtplot(&#039;first:rt&#039;,&#039;m&#039;,&#039;sketch&#039;,&#039;sketch_length&#039;,100,&#039;sm&#039;,30);&lt;br /&gt;
view(-230,30);axis equal;&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSketchFirst.png|thumb|center|400px| sketch of orientations after computation of the the project &amp;lt;tt&amp;gt;first&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
Here, the &#039;z&#039; orientation computed for each particle is represented by the longest semiaxis. Note that with the original definition of the template, the &#039;z&#039; points -approximately- along the direction of the &#039;z&#039; in the tomogram. If we depict the same plot with the table we just computed:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;figure;&lt;br /&gt;
dtplot(tr,&#039;m&#039;,&#039;sketch&#039;,&#039;sketch_length&#039;,100,&#039;sm&#039;,30);&lt;br /&gt;
view(-230,30);axis equal;&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSketchZ.png|thumb|center|400px| sketch of orientations in the rectified table]]&lt;br /&gt;
&lt;br /&gt;
we see that now the &#039;z&#039; axis in each particle is pointing orthogonally(-ish) to the membrane. A different quick check would be to show the projections of the particles along &#039;&#039;y&#039;&#039;. Instead of using the GUI &amp;lt;tt&amp;gt;ddbrowse&amp;lt;/tt&amp;gt;, we can create this depiction with a single command: &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;figure;dslices(&#039;particlesData&#039;,&#039;t&#039;,tr,&#039;projy&#039;,&#039;*&#039;,&#039;align&#039;,1,&#039;labels&#039;,&#039;on&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:fhvOrientedSlicesX.png|thumb|center|400px|  full &#039;&#039;y&#039;&#039;projection of the particles according to the orientations in the rectified table ]]&lt;br /&gt;
&lt;br /&gt;
Lets look at the &#039;&#039;z&#039;&#039;-projection. In this case we project only the central slices around the crown and the aperture in the viral vesicle, chosing thus slices 60 to 70. if project the full particle, we won&#039;t distinguish any features.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;figure;dslices(&#039;particlesData&#039;,&#039;t&#039;,tr,&#039;projz&#039;,60:80,&#039;align&#039;,1,&#039;labels&#039;,&#039;on&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:fhvOrientedSlicesZ.png|thumb|center|400px|  &#039;&#039;z&#039;&#039;projection of the central slices in the rectified table ]]&lt;br /&gt;
&lt;br /&gt;
The depiction clearly shows the missing wedge of the particles. Incidentally, it also shows that averaging all the particles should produce an average that covers all the orientaions  in the Fourier space.&lt;br /&gt;
&lt;br /&gt;
== Using the membrane to impart an orientation ==&lt;br /&gt;
&lt;br /&gt;
This section describes an &#039;&#039;&#039;alternative&#039;&#039;&#039; method to compute:&lt;br /&gt;
* a rough orientation of the particles, and&lt;br /&gt;
* a rough first template&lt;br /&gt;
&lt;br /&gt;
In this section we will use the membrane of the mithocondrion to assign a roughly orientation to each of the points in the table. This orientation will be defined by the normal of the closest point in the membrane. The membrane will be defined as a a triangulation, to be constructed based on a set of manually picked points.&lt;br /&gt;
&lt;br /&gt;
=== Pick membrane points===&lt;br /&gt;
&lt;br /&gt;
We open our tomogram in &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmslice @{fhv}1 -prebin 1&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
or, if you are working with the [[standalone]] version, please prepend a &amp;quot;\&amp;quot; symbol:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;\dtmslice @{fhv}1 -prebin 1&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In this variant of the syntax of &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt;, the string &amp;lt;tt&amp;gt;@{fhv}1&amp;lt;/tt&amp;gt; just means &amp;quot;tomogram number 1 inside catalogue &amp;lt;tt&amp;gt;fhv&amp;lt;/tt&amp;gt;.  On the opened scene, we will use a [[Montage viewer for membrane picking | montage ]] to manually click on a set of membrane points.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Note! (08/06/21) - the montage viewer was recently updated and no longer provides the ability to easily add points, please define your surface model on sequential z-slices in dtmslice directly by annotating points every 20 or so slices.&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
[[ File:FhvMontage.png |thumb|center|400px|   Opening a montage view]]&lt;br /&gt;
&lt;br /&gt;
By default, this &amp;lt;tt&amp;gt;montage&amp;lt;/tt&amp;gt; represents slices taken orthogonally to &#039;&#039;z&#039;&#039; every 20 pixels of the unbinned tomogram. This can be changed in the settings &#039;&#039;before&#039;&#039; opening the montage GUI. Now, we can create a model of type &amp;lt;tt&amp;gt;Surface&amp;lt;/tt&amp;gt;, which we will use to store a set of points in the membrane to be picked manually (or semiautomatically). To do this, go to &#039;&#039;Model pool&amp;gt; Create new model in pool (choose type) &amp;gt; surface &#039;&#039;&lt;br /&gt;
&lt;br /&gt;
[[ File:FhvCreateSurfaceModel.png |thumb|center|400px|  Creating a surface model]]&lt;br /&gt;
&lt;br /&gt;
You need to click on the point switcher (the control in the toolbar with a &#039;&#039;c&#039;&#039; and an &#039;&#039;i&#039;&#039;) to allow entering points. The basic controls are: &lt;br /&gt;
* Mouse click to enter a point. &lt;br /&gt;
* &amp;lt;tt&amp;gt;d&amp;lt;/tt&amp;gt; to delete a point.&lt;br /&gt;
* &amp;lt;tt&amp;gt;i&amp;lt;/tt&amp;gt; to insert a point.&lt;br /&gt;
&lt;br /&gt;
[[File:FhvMontageActiveClick.png |thumb|center|400px|  Point switcher  must be toggle on to pick points into the model]]&lt;br /&gt;
&lt;br /&gt;
Use the &#039;&#039;&amp;gt;&amp;gt;&#039;&#039; button in the bottom of the GUI to go to next set of orthoslices.&lt;br /&gt;
&lt;br /&gt;
[[File:FhvMontageControls.png |thumb|center|400px|   Controls of the montage GUI]]&lt;br /&gt;
&lt;br /&gt;
Note that the points that you click in the Montage GUI are assigned to a model in the pool, and as such, they appear automatically in the dtmslice GUI&lt;br /&gt;
[[ File:FhvTmsliceUpdates.png |thumb|center|600px|   Points clicked in the montage GUI reflect in the &amp;lt;tt&amp;gt;tmslice&amp;lt;/tt&amp;gt; GUI]]&lt;br /&gt;
&lt;br /&gt;
You also need &amp;lt;tt&amp;gt;shift + C &amp;lt;/tt&amp;gt; in order to place a center inside the mithocondrion. This point is just used to tell &#039;&#039;Dynamo&#039;&#039; what is the inside and what is the outside face of the surface that we are building.&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSurfaceMarkCenter.png |thumb|center|400px|   &amp;lt;tt&amp;gt;shift + C &amp;lt;/tt&amp;gt; marks an arbitrary interior point]]&lt;br /&gt;
&lt;br /&gt;
==== Automatic detection ====&lt;br /&gt;
&lt;br /&gt;
Once you have clicked points on a level, you can try and check if the automatic tracker can locate them in the next one. To do so, activate the next slice (i.e., secondary click it, so that its frame becomes red), and press &amp;lt;tt&amp;gt;o&amp;lt;/tt&amp;gt;. You can edit the points with &amp;lt;tt&amp;gt;d&amp;lt;/tt&amp;gt; to delete the closest point, &amp;lt;tt&amp;gt;m&amp;lt;/tt&amp;gt; to move the closest point to the position currently under the cursor, or &amp;lt;tt&amp;gt;l&amp;lt;/tt&amp;gt; to delete all the points detected in the slice... in such a case, you probably want to check the tracking parameters before using &amp;lt;tt&amp;gt;o&amp;lt;/tt&amp;gt; again!&lt;br /&gt;
&lt;br /&gt;
=== Create a surface ===&lt;br /&gt;
&lt;br /&gt;
Now, we want to convert the points that we have introduced into a triangulation. This is a part of the [[Membrane Models#Workflow description| workflow]] used to crop particles from [[membrane models]], so we open the workflow GUI for this model in the &#039;&#039;Active Model&#039;&#039; menu tab. &lt;br /&gt;
&lt;br /&gt;
[[ File:FhvSurfaceWorkflowCreate.png |thumb|center|400px|  Invoking the workflow editor of active model ]]&lt;br /&gt;
&lt;br /&gt;
We can first check the points currently contained in the model, by auxiliary clicking on the first viewing option and choosing the &#039;&#039;User points&#039;&#039; option. They will be depicted in a graphic window which will update with the new graphical elements that we depict there.&lt;br /&gt;
&lt;br /&gt;
[[ File:FhvSurfacePlotPoints.png|thumb|center|600px|  Showing original points in the model workflow GUI ]]&lt;br /&gt;
&lt;br /&gt;
We first need to create a spline interpolation on each of the levels of our point cloud.&lt;br /&gt;
&lt;br /&gt;
[[ File:FhvSurfaceControlPoints.png|thumb|center|600px|  Control points are created by spline interpolation. ]]&lt;br /&gt;
&lt;br /&gt;
Now we define a triangulation on  this control points.&lt;br /&gt;
&lt;br /&gt;
[[ File:FhvSurfaceCreateTriangulation.png |thumb|center|600px|  Creating a triangulation on the control points ]]&lt;br /&gt;
&lt;br /&gt;
Which can be subdivided to get a smoother appearance, and also a more accurate representation of the geometry.&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSurfaceSubdivisionMinimum.png |thumb|center|400px|  A single round of subdivision smoothens the appearance of the lattice ]]&lt;br /&gt;
&lt;br /&gt;
Then, we can change the name of the model for clarity, and then save it into the catalogue (with the disk icon in &amp;lt;tt&amp;gt;tmslice&amp;lt;/tt&amp;gt; or the &#039;&#039;Save into catalogue&#039;&#039; options under the &#039;&#039;Active model&#039;&#039; menu)&lt;br /&gt;
[[ File:FhvSurfaceSaveModel.png |thumb|center|600px|  Renaming a saving a model into the catalogue ]]&lt;br /&gt;
&lt;br /&gt;
=== Use a surface to impart orientation ===&lt;br /&gt;
&lt;br /&gt;
We bring the model into our workspace. We search for it in the catalogue:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcmodels fhv -nc mySurface -ws output&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
which will prompt the response &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;Volume 1. Matching models: 1 (total: 1)&lt;br /&gt;
/Users/casdanie/dynamo/examples/fhvParis/fhv/tomograms/volume_1/models/mySurface.omd&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
now, we can read the model file into our memory space to operate with it:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;m = dread(output.files{1});&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Now the model &amp;lt;tt&amp;gt;m&amp;lt;/tt&amp;gt; is in our space of memory and can be used to impart an orientation to the points in our table.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tOrientedBySurface = dpktbl.triangulation.fillTable(m,&#039;raw.tbl&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In this table, orientations are orthogonal to the membrane (or more precisely, orthogonal to the closest triangle in the mesh that represents the membrane)&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; figure;dslices(&#039;particlesData&#039;,&#039;t&#039;, tOrientedBySurface,&#039;projy&#039;,&#039;c20&#039;,&#039;align&#039;,1,&#039;labels&#039;,&#039;on&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:FhvMembraneSlicesPreflipping.png|thumb|center|400px|   Slices along the xz plane as seen by the table]]&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tConsistent = dynamo_table_flip_normals(tOrientedBySurface,&#039;center&#039;,m.center)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We can check the effect of this table on the particles through:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;figure;dslices(&#039;particlesData&#039;,&#039;t&#039;, tConsistent,&#039;projy&#039;,&#039;c20&#039;,&#039;align&#039;,1,&#039;labels&#039;,&#039;on&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:FhvMembraneSlicesPostflipping.png |thumb|center|400px|  Slices along the xz plane as seen by the table, after using the center point to establish the interior side of the surface ]]&lt;br /&gt;
&lt;br /&gt;
To get a better graphical impression, we can depict our surface (contained in the model &amp;lt;tt&amp;gt;m&amp;lt;/tt&amp;gt;)  with:&lt;br /&gt;
  &lt;br /&gt;
 &amp;lt;tt&amp;gt;m.ezplot&amp;lt;/tt&amp;gt; &lt;br /&gt;
&lt;br /&gt;
and choose the &amp;lt;tt&amp;gt;Surface&amp;lt;/tt&amp;gt;option&lt;br /&gt;
&lt;br /&gt;
[[ File:FhvMembraneSurfaceEzplot.png |thumb|center|400px| Easy way to get all defined plots of a model object.  ]]&lt;br /&gt;
&lt;br /&gt;
Then, we just plot the positions of the particles on the same graphical figure:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtplot(tConsistent,&#039;m&#039;,&#039;sketch&#039;,&#039;sketch_length&#039;,100,&#039;sm&#039;,30);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:FhvMembraneSketchDtplot.png |thumb|center|400px|  &amp;lt;tt&amp;gt;dtplot&amp;lt;/tt&amp;gt; directs its output on the last active figure ]]&lt;br /&gt;
&lt;br /&gt;
==== Management of the missing wedge ====&lt;br /&gt;
&lt;br /&gt;
When we create a table considering only the orientations of the points with relation to a membrane, there is no particular preference for rotations of the particles about the normal direction (i.e., azimuthal directions).  The &amp;lt;tt&amp;gt;narot&amp;lt;/tt&amp;gt; angle in this table is initialized to zero&lt;br /&gt;
&lt;br /&gt;
Thus, take into account that an average created on these particles will have a strong missing wedge, especially in our case, where we have a preferential direction. This can be checked by averaging the particles against this table:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;oa=daverage(&#039;particlesData&#039;,&#039;t&#039;, tConsistent,&#039;fc&#039;,1);&amp;lt;/tt&amp;gt;&lt;br /&gt;
Here, we ask (&amp;lt;tt&amp;gt;&#039;fc&#039;,1&amp;lt;/tt&amp;gt;) to run a Fourier compensation step, so that we can check in the output &amp;lt;tt&amp;gt;oa&amp;lt;/tt&amp;gt; the property &amp;lt;tt&amp;gt;fweight&amp;lt;/tt&amp;gt;, which contains the number of times a Fourier component is represented in the average. Bright values mean that the Fourier component is present in many particles (yielding thus an average of better quality for the involved frequencies).&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dview(oa.fweight);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[  File:FhvMembraneMissingWedge.png|thumb|center|400px|   Fourier component presence without azimuthal randomization ]]&lt;br /&gt;
&lt;br /&gt;
We can atenuate this effect by randomizing the rotational angle:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tConsistentRandomized = dynamo_table_randomize_azimuth( tConsistent);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and averaging again.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;oaRandomized=daverage(&#039;particlesData&#039;,&#039;t&#039;, tConsistentRandomized,&#039;fc&#039;,1);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Now, the &amp;lt;tt&amp;gt;fweight&amp;lt;/tt&amp;gt; map doesn&#039;t show such a strongly preferential orientation:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dview(oaRandomized.fweight);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[  File:FhvMembraneMissingRandomized.png |thumb|center|400px|   Fourier component presence with azimuthal randomization ]]&lt;br /&gt;
&lt;br /&gt;
The effect in direct space can be shown by depicting both averages (with and without randomization side to side)&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview({oa.average,oaRandomized.average});&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[  File:FhvMembraneCompareWedges.png |thumb|center|400px| The map on the left shows a worse definition and clear traces of missing Fourier components  ]]&lt;br /&gt;
&lt;br /&gt;
== Project for rotational alignment ==&lt;br /&gt;
&lt;br /&gt;
We have now a template and a coherently defined metadata (i.e. table) that align the particles coarsely along the right direction. We write  them into disk: &lt;br /&gt;
&amp;lt;nowiki&amp;gt;Insert non-formatted text here&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
If you did not create a membrane model, use the results of the alignment project:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dwrite(tr,&#039;zOriented.tbl&#039;);&lt;br /&gt;
dwrite(oz.average,&#039;zOriented.em&#039;);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If you did create a membrane model, used the corresponding table and average:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dwrite(tConsistentRandomized,&#039;zOriented.tbl&#039;);&lt;br /&gt;
dwrite(oaRandomized.average,&#039;zOriented.em&#039;);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
and create a project with these files. Note that the [[data folder]] remains unchanged.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcp.new(&#039;zOriented&#039;,&#039;d&#039;,&#039;particlesData&#039;,&#039;template&#039;,&#039;zOriented.em&#039;,&#039;masks&#039;,&#039;default&#039;,&#039;t&#039;,&#039;zOriented.tbl&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In this project, we will ask for a symmetrization &#039;c57&#039;.. this is just to simulate fully rotational symmetry.  We are not assuming that this symmetry is physical: we just want to force any possible symmetry axis in the data along the &#039;&#039;z&#039;&#039; axis. We also keep binning twice the particles, in order to get the computation times short.&lt;br /&gt;
&lt;br /&gt;
[[File:FhvZOrientedParameters.png|thumb|center|500px| Alignment parameters in &amp;lt;tt&amp;gt;zOriented&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
The result shown an incipient formation of the crown... however, the presence of  suspicious striations in a preferential direction might be an indication of the effect of the missing wedge.&lt;br /&gt;
&lt;br /&gt;
[[File:FhvZOrientedMapview.png|thumb|center|500px| Result in  &amp;lt;tt&amp;gt;zOriented&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
== Project with rotational randomization ==&lt;br /&gt;
&lt;br /&gt;
We can create a template that does not have a prefererential orintation, by just randomizing the azimuthal rotations in our table, We extract the last refined table into the variable &amp;lt;tt&amp;gt;tns&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;ddb zOriented:rt -r tns &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and impose a perturbation that keeps all other parameters constant but randomly rotates the particles around their axis&lt;br /&gt;
 &amp;lt;tt&amp;gt;tr = dynamo_table_perturbation(tns,&#039;pshift&#039;,0,&#039;paxis&#039;,0,&#039;pnarot&#039;,360);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We can use this table to average again the particles and check the average.&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;oar = daverage(&#039;particlesData&#039;,&#039;t&#039;,tr,&#039;fc&#039;,1);&lt;br /&gt;
dview(oar)&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Now, we can write these files in disk and create a project:&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dwrite(oar.average,&#039;randomizedAverage.em&#039;);&lt;br /&gt;
dwrite(tr,&#039;randomized.tbl&#039;);&lt;br /&gt;
dcp.new(&#039;zRandomized&#039;,&#039;d&#039;,&#039;particlesData&#039;,&#039;template&#039;,&#039;randomizedAverage.em&#039;,&#039;masks&#039;,&#039;default&#039;,&#039;t&#039;,&#039;randomized.tbl&#039;);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FHV zRandomized Parameters.png|thumb|center|600px| Alignment parameters in &amp;lt;tt&amp;gt;zRandomized&amp;lt;/tt&amp;gt; project]]&lt;br /&gt;
&lt;br /&gt;
After running this projects, the presence of a crown-like is very, very faintly hinted in mapview:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(&#039;zRandomized:a&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FhvRandomizedFaintHintsMapview.png|thumb|center|500px| Result from  &amp;lt;tt&amp;gt;zRandomized&amp;lt;/tt&amp;gt; project]]&lt;br /&gt;
&lt;br /&gt;
and barely identifialble in Chimera:&lt;br /&gt;
&lt;br /&gt;
[[File:FhvZRandomizedChimera.png|thumb|center|500px| Alignment parameters in &amp;lt;tt&amp;gt;localized&amp;lt;/tt&amp;gt; project]]&lt;br /&gt;
&lt;br /&gt;
== Project for localized alignment ==&lt;br /&gt;
&lt;br /&gt;
We don&#039;t see clearly what is happening on the area of interest... On one hand we know that we are using a very reduced number of particles ( which on top of it are too similarly oriented). But there is still some room to improve in the approach: we can focus the refinement in the area of interest.&lt;br /&gt;
&lt;br /&gt;
=== Creating a tight mask ===&lt;br /&gt;
We want to create a mask that encloses the area of interest. To do this, we open the average in &amp;lt;tt&amp;gt;dmapview&amp;lt;/tt&amp;gt;:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(&#039;zRandomized:a&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We tune the browser for viewing along &#039;&#039;y&#039;&#039;, and we select one of the central slices. We can use a thickness of several pixels to have a better view.&lt;br /&gt;
&lt;br /&gt;
Then, we select the area that we want to use as seed in this plane to create a revolution solid. We press on &amp;lt;tt&amp;gt;[shift] + [s] &amp;lt;/tt&amp;gt; on the selected slide, letting a new window pop up. In this window, you handdraw an area on the XZ plane (main click to start drawing, auxiliary click to stop). &#039;&#039;Dynamo&#039;&#039; will rotate the region about the &#039;&#039;z&#039;&#039; axis, creating a revolution solid into the &amp;lt;tt&amp;gt;file temp_drawn_revolution_mask.em&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:fhvHandDrawn.png|thumb|center|500px|  Drawing a revolution mask.]]&lt;br /&gt;
&lt;br /&gt;
We have to change the default name given by &#039;&#039;Dynamo&#039;&#039; to a relevant one:&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;tt&amp;gt;!mv temp_drawn_revolution_mask.em teethMask.em&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and now continue the previous project by transferring the results of &amp;lt;tt&amp;gt;zRandomized&amp;lt;/tt&amp;gt; to a fresh project (lets call  it &amp;lt;tt&amp;gt;localized&amp;lt;/tt&amp;gt;)&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dynamo_vpr_branch zRandomized localized -b 1 -noise 0&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
where we insert the tight mask &amp;lt;tt&amp;gt;teethMask.em&amp;lt;/tt&amp;gt; that we just created as alignment mask of the project. Note that we do &#039;&#039;&#039;not&#039;&#039;&#039; want impose any symmetry in our parameters:&lt;br /&gt;
[[File:FhvParametersLocalized.png|thumb|center|500px| Alignment parameters in &amp;lt;tt&amp;gt;localized&amp;lt;/tt&amp;gt; project]]&lt;br /&gt;
&lt;br /&gt;
Let&#039;s inspect the output in &amp;lt;tt&amp;gt;dview&amp;lt;/tt&amp;gt;&lt;br /&gt;
[[File:fhvLocalizedDview.png|thumb|center|800px| Last average in project &amp;lt;tt&amp;gt;localized&amp;lt;/tt&amp;gt; as shown by &amp;lt;tt&amp;gt;dview&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
There are different things that we like in this average&lt;br /&gt;
# The localized masking worked well, producing a clearer insight into the region of relevance&lt;br /&gt;
# Although we are using signal only inside the mask, the material outside of the mask does &#039;&#039;&#039;not&#039;&#039; become smeared. This is clear mark that the alignment is real and non artifactual. That&#039;s an important point to check when we use small masks.&lt;br /&gt;
# The symmetry in the area becomes apparent on the bare eye. They can be distinguished clearly with mapview and even in Chimera.&lt;br /&gt;
&lt;br /&gt;
[[File:FhvLocalizedMapview.png|thumb|center|500px| Last average in project &amp;lt;tt&amp;gt;localized&amp;lt;/tt&amp;gt; as shown by &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
[[File:FhvLocalizedChimera.png|thumb|center|500px| Last average in project &amp;lt;tt&amp;gt;localized&amp;lt;/tt&amp;gt; as shown by &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
=== Testing the symmetry ===&lt;br /&gt;
&lt;br /&gt;
We can check for different symmetry operators to confirm the presence of symmetry. &lt;br /&gt;
&lt;br /&gt;
==== Basic command ====&lt;br /&gt;
&lt;br /&gt;
The basic command for this task is &amp;lt;tt&amp;gt;dynamo_symmetry_scan&amp;lt;/tt&amp;gt;. In its fundamental syntax, you need to state the type  of symmetry operator to be tested, and a set of operator.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; stm = dynamo_symmetry_scan(&#039;localized:a&#039;,&#039;c&#039;,&#039;order&#039;,3:15,&#039;type&#039;,&#039;pearson&#039;,&#039;nfig&#039;,3); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSymmetryGlobal.png|thumb|center|500px| Symmetry detected for different masks]]&lt;br /&gt;
&lt;br /&gt;
With a more localized mask:&lt;br /&gt;
 &amp;lt;tt&amp;gt; slm = dynamo_symmetry_scan(&#039;localized:a&#039;,&#039;c&#039;,&#039;order&#039;,3:15,&#039;type&#039;,&#039;pearson&#039;,&#039;mask&#039;,&#039;teethMask.em&#039;,&#039;nfig&#039;,4);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSymmetryLocal.png|thumb|center|500px| Symmetry detected for different masks]]&lt;br /&gt;
&lt;br /&gt;
==== Interpretation of results ====&lt;br /&gt;
&lt;br /&gt;
If you got the results above, you might have jumped to the conclusion that they already constitute an objective hint at a real C12 symmetry. This is, however, not true. The fact is that,  with a slightly different picking of particles, you could have obtained the profiles in these pictures:&lt;br /&gt;
&lt;br /&gt;
{|style=&amp;quot;margin: 0 auto;&amp;quot;&lt;br /&gt;
| [[File:FhvSymmetryGlobalWrong.png|thumb|upright|400px| Symmetry merit plot (global mask) ]]&lt;br /&gt;
| [[File:FhvSymmetryLocalWrong.png|thumb|upright|400px| Symmetry merit plot (local mask) ]]&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
These images represent the result of the two symmetry-exploring commands described above obtained by a different user. . Surprisingly, they point at possible symmetry orders of 11 and 13.&lt;br /&gt;
So, what is going on here? How is it possible that two different users that operate exactly the same walkthrough get contradictory symmetry estimations? The reason is that different users will pick manually slightly different particle centers, and this have a direct impact on the symmetry estimation. In short, the problem is that the density map &amp;lt;tt&amp;gt;localized:a&amp;lt;/tt&amp;gt; is not garanteed to have its possible symmetry axis located along the center of the box, and this misleads &amp;lt;tt&amp;gt; dynamo_symmetry_scan&amp;lt;/tt&amp;gt;. This can bechecked by opening the average in &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt; and overlaying the file &amp;lt;tt&amp;gt;&#039;teethMask.em&#039;&amp;lt;/tt&amp;gt; on it.&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSymmetryDecentered.png|thumb|center|500px| Mapview map n file &amp;lt;tt&amp;gt;localized:a &amp;lt;/tt&amp;gt; overlayed with file &amp;lt;tt&amp;gt;&#039;teethMask.em&#039;&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
In this non-centered density map, any symmetry determination can only be an artifact. To solve this, we create a centered version: &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;ddb zOriented:a -r zo % extract average of zOriented as the ws variable zo&lt;br /&gt;
ddb localized:a –r localizedAverage % extract average of localized as the ws variable localized Average&lt;br /&gt;
sal = dalign(localizedAverage,zo,&#039;cr&#039;,0,&#039;cs&#039;,30,&#039;ir&#039;,0,&#039;dim&#039;,64,&#039;limm&#039;,1,&#039;lim&#039;,[20,20,20]); % aligns localizedAverage against zo (like that localizedAverage is centered)&lt;br /&gt;
centerLocalized = sal.aligned_particle;&lt;br /&gt;
dview(centerLocalized); &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSymmetryRecenteredView.png|thumb|center|500px| Recentered average (x and y views) ]]&lt;br /&gt;
&lt;br /&gt;
We can scan again the symmetry operators on the recentered volume.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; slmCentered = dynamo_symmetry_scan(centerLocalized,&#039;c&#039;,&#039;order&#039;,3:15,&#039;type&#039;,&#039;pearson&#039;,&#039;mask&#039;,&#039;teethMask.em&#039;,&#039;nfig&#039;,4);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
{|style=&amp;quot;margin: 0 auto;&amp;quot;&lt;br /&gt;
| [[File:FHVsymmetryRecenteringOldMaskSlice.png|thumb|upright|400px| &amp;lt;tt&amp;gt;&#039;teethMask.em&#039;&amp;lt;/tt&amp;gt; overlayed on the recentered average ]]&lt;br /&gt;
| [[File:FHVsymmetryRecenteringOldMaskPlot.png|thumb|upright|400px| Symmetry merit plot after recentering using &amp;lt;tt&amp;gt;&#039;teethMask.em&#039;&amp;lt;/tt&amp;gt; ]]&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
Now the peaks located that at 6 and 12 are trustworthy.  You can even create a new mask on the recentered average, carefully excluding intensities from the central ring structure to completely rule out any artefact. &lt;br /&gt;
&lt;br /&gt;
{|style=&amp;quot;margin: 0 auto;&amp;quot;&lt;br /&gt;
| [[File:FHVSymmetryAdhocMaskOverlay.png|thumb|upright|400px| Mask constructed &#039;&#039;ad hoc&#039;&#039; on the recentered average ]]&lt;br /&gt;
| [[File:FHVSymmetryAdhocMaskPlot.png |thumb|upright|400px| Symmetry merit plot using  &#039;&#039;ad hoc&#039;&#039; constructed mask]]&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== Subboxing ==&lt;br /&gt;
&lt;br /&gt;
The &#039;&#039;subboxing&#039;&#039; technique consists in redefining the area of interest inside a previously defined average. In this example, we have use the full crowns as the subject of alignment and averaging. This has allowed us to use the whole signal carried by the full crown on each of the particles to drive the alignment robustly. This approach, however, will not allow us to identify heterogeneity and flexibility inside the individual crowns. Additionally, the possible hetereogeneity inside the crown will decrease the quality of the alignment when the crown is treated as a whole. &lt;br /&gt;
&lt;br /&gt;
With the &#039;&#039;subboxing&#039;&#039; technique, we can use our previous results to setup an approach that centers the alignment on the individual teeth. Each one the particles in our new data set will be a &#039;&#039;subbox&#039;&#039; (a tooth) extracted from the previos &#039;&#039;box&#039;&#039; (the crown) using the alignment parametes for the full boxes gained by the projects that we have ran so far. &lt;br /&gt;
&lt;br /&gt;
=== Defining a subboxed subunit ===&lt;br /&gt;
&lt;br /&gt;
First, we need to define the location that we want to subbox. We use &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(&#039;localized:a&#039;) &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
to show the last average in the project &amp;lt;tt&amp;gt;localized&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSubboxSelectZ.png|thumb|center|500px| Selecting the center of the tooth subunit with &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
You probably want to explore several views in mapviews (&#039;&#039;x&#039;/&#039;y&#039; and &#039;z&#039;) to make sure you (roughtly) hit the center of the subunit of interest. Guiding yourself only for a view on &#039;&#039;z&#039;&#039; can be misleading.&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSubboxSelectY.png|thumb|center|500px| Selecting the center of the tooth subunit with &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt; on the &#039;&#039;y&#039;&#039; view]].&lt;br /&gt;
&lt;br /&gt;
As we are in this browser, we can check the size of the subunit that we want to &#039;&#039;subbox&#039;&#039;, using the two markers C and N. This will be useful later when we want to actually crop physical particles using &amp;lt;tt&amp;gt;dtcrop&amp;lt;/tt&amp;gt;, when we will be required to input a sidelength for the subboxed data folder.&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSubboxSelectDistance.png|thumb|center|500px| Measuring distances in mapview]].&lt;br /&gt;
&lt;br /&gt;
We define a variable to contain the position that we read in mapview for the blue (North) anchor. &lt;br /&gt;
 &amp;lt;tt&amp;gt;rSubunitFromCenter = [88,80,53 ] - [64,64,64]; &amp;lt;/tt&amp;gt;&lt;br /&gt;
We subtract the half sidelength of the full box, because the next command will need the position of the asymmetrical unit expressed in relation to center of the box.&lt;br /&gt;
&lt;br /&gt;
=== Creating a subboxing table ===&lt;br /&gt;
&lt;br /&gt;
We extract the last refined table: &lt;br /&gt;
 &amp;lt;tt&amp;gt;ddb localized:rt -r t&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and define positions related by C12 symmetry along the axis&lt;br /&gt;
 &amp;lt;tt&amp;gt;ts = dynamo_subboxing_table(t,rSubunitFromCenter,&#039;sym&#039;,&#039;c12&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The new subboxed table &amp;lt;tt&amp;gt;ts&amp;lt;/tt&amp;gt; will have 12 times as many rows as the original one. The system of reference on each particle will point &#039;&#039;z&#039;&#039; in the direction of its original box, but the &#039;&#039;x&#039;&#039; and &#039;&#039;y&#039;&#039; orientations of each tooth will be symmetrically related in the same crown. We can depict this geometrical relationship by plotting a sketch of all the particles in the table:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;figure;dtplot(ts,&#039;m&#039;,&#039;sketch&#039;,&#039;sketch_length&#039;,100,&#039;sm&#039;,30);view(-151,12);axis equal;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSubboxSketch.png|thumb|center|500px| Sketch of orientations of the new subboxed table &amp;lt;tt&amp;gt;ts&amp;lt;/tt&amp;gt;]].&lt;br /&gt;
&lt;br /&gt;
=== Creating a subboxed data folder ===&lt;br /&gt;
&lt;br /&gt;
Now we have all we need to go back to the original tomogram and crop the subboxed particles into a new data folder using the sidelength that we checked with &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt;:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtcrop(&#039;crop.rec&#039;,ts,&#039;subboxData&#039;,32);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We can run our typical sanity check to ensure that everything ran correctly&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;osb = daverage(&#039;subboxData&#039;,&#039;t&#039;,ts,&#039;fc&#039;,1);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
To visualize it you can write: &lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;dview(osb.average);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSubboxAverage.png|thumb|center|700px| Density map of the average of subboxed teeth]].&lt;br /&gt;
&lt;br /&gt;
As it looks like we expected, we just write it into a file, which we will use to define a new project.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dwrite(osb.average,&#039;subboxRaw.em&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Defining masks ===&lt;br /&gt;
&lt;br /&gt;
There are some tools to quickly format masks for project. If we want to check a reasonable radius for our mask, we can use the &amp;lt;tt&amp;gt;dsphere&amp;lt;/tt&amp;gt; command and overlay the created mask on the template &lt;br /&gt;
 &amp;lt;nowiki&amp;gt;cs = dynamo_sphere(10,32);&lt;br /&gt;
figure;dslices(osb.average,&#039;y&#039;,&#039;ov&#039;,cs,&#039;ovas&#039;,&#039;mask&#039;);&lt;br /&gt;
figure;dslices(osb.average,&#039;ov&#039;,cs,&#039;ovas&#039;,&#039;mask&#039;); &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSubboxOverlay.png|thumb|center|700px| Testing the radius of created masks by overlay on template]].&lt;br /&gt;
In fact, this mask is probably too risky: we need a minimum of signal to drive the alignment &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dwrite(cs,&#039;maskTooth32.em&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Subboxing project ===&lt;br /&gt;
&lt;br /&gt;
We create the project through:&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcp.new(&#039;subboxBig&#039;,&#039;d&#039;,&#039;subboxData&#039;,&#039;template&#039;,&#039;subboxRaw.em&#039;,&#039;masks&#039;,&#039;default&#039;,&#039;t&#039;,&#039;subboxData/crop.tbl&#039;,&#039;show&#039;,0);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In this case, we use  &amp;lt;tt&amp;gt;&#039;show&#039; 0&amp;lt;/tt&amp;gt; would suppress the [[dcm]] GUI. We use typically this option when we want to enter project parameters through the command line. This is exactly equivalent to entering parameters through the GUI. &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvput subboxBig mask maskTooth32.em&lt;br /&gt;
dvput subboxBig ite_r1 3&lt;br /&gt;
dvput subboxBig cr_r1 4&lt;br /&gt;
dvput subboxBig cs_r1 2&lt;br /&gt;
dvput subboxBig ir_r1 4&lt;br /&gt;
dvput subboxBig is_r1 2&lt;br /&gt;
dvput subboxBig rf_r1 2&lt;br /&gt;
dvput subboxBig rff_r1 2&lt;br /&gt;
dvput subboxBig dim_r1 32&lt;br /&gt;
dvput subboxBig lim_r1 [4,4,4]&lt;br /&gt;
dvput subboxBig limm_r1 1 &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A list of the names of the parameters can be displayed through the command &amp;lt;tt&amp;gt;dvhelp&amp;lt;/tt&amp;gt;. The computing environment is set using the &amp;lt;tt&amp;gt;destination&amp;lt;/tt&amp;gt; parameter, shortnamed &amp;lt;tt&amp;gt;dst&amp;lt;/tt&amp;gt;. To run it in matlab use:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; dvput -dst matlab&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
For standalone running, use:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; dvput -dst standalone&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
After running the project, we can check the effect of the independent refinement of the &amp;quot;tooth&amp;quot; units:&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(&#039;subboxBig:a:ite=[0,3]&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSubboxRefimentMapview.png|thumb|center|800px| Slice-to-slice comparison of initial template and final average of the subboxing project]].&lt;br /&gt;
&lt;br /&gt;
or send the average to Chimera through:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;ddb subboxBig:a -c &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:FhvSubboxRefimentChimera.png|thumb|center|600px| Density map of the average of subboxed teeth after refinement]].&lt;br /&gt;
&lt;br /&gt;
== Visualization ==&lt;br /&gt;
&lt;br /&gt;
You can continue working on this data in the [[Walkthrough on creation of 3d scenes]], where you will learn to depict tomgraphic slices, place templates in table positions, and depict graphical elements  representing model geometries.&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Walkthrough_for_lattices_on_vesicles_(Tsinghua_Spring_School_2025)&amp;diff=5598</id>
		<title>Walkthrough for lattices on vesicles (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Walkthrough_for_lattices_on_vesicles_(Tsinghua_Spring_School_2025)&amp;diff=5598"/>
		<updated>2025-03-03T05:30:32Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Getting the data */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:WalkthroughsSpecific]]&lt;br /&gt;
&lt;br /&gt;
this walkthrough shows the approach to process proteins that cover spheroidal vesicles following (approximately) a structured lattice. For demonstration, we use a highly binned tomogram with several viral capsides.&lt;br /&gt;
&lt;br /&gt;
== Data ==&lt;br /&gt;
&lt;br /&gt;
The data has been made available by Florian Schur. This  single tomogram is part of the data set used for the paper &#039;&#039;An atomic model of HIV-1 capsid-SP1 reveals structures regulating assembly and maturation&#039;&#039; by  Schur FK, Obr M, Hagen WJ, Wan W, Jakobi AJ, Kirkpatrick JM, Sachse C, Kräusslich HG and Briggs JA. (2016)&lt;br /&gt;
&lt;br /&gt;
=== Getting the data ===&lt;br /&gt;
&lt;br /&gt;
Open a new local terminal and navigate to the directory where the practices are located:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; /mnt/fs/2025workshop/data/DownloadLinkBasicHIVTomo/ &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Inside this folder, the file of interest is &amp;lt;code&amp;gt;v17.rec&amp;lt;/code&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
=== Viewing the data ===&lt;br /&gt;
&lt;br /&gt;
The tomogram is severely binned, so it will probably fit in memory without major problems. We can just use our typical tool to quick check a tomogram.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; dtmshow v17.rec &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:HivDtmshow.png |thumb|center|500px| &amp;lt;tt&amp;gt;dtmshow&amp;lt;/tt&amp;gt; on the sample tomogram. ]]&lt;br /&gt;
&lt;br /&gt;
== Annotation of a tomogram ==&lt;br /&gt;
&lt;br /&gt;
We are interested in cropping the particles between the two layers of each one of the viruses.&lt;br /&gt;
&lt;br /&gt;
[[ File:HivBox.png |thumb|center|400px| Structure to average]]&lt;br /&gt;
&lt;br /&gt;
We  open the tomogram v17.rec with &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmslice v17.rec -c hiv&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Here, the flag  &amp;lt;tt&amp;gt;-c hiv&amp;lt;/tt&amp;gt; will create a catalogue that will contain all the annotations that we perform on this volume (through the opened &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; session)&lt;br /&gt;
&lt;br /&gt;
=== DipoleSet models ===&lt;br /&gt;
&lt;br /&gt;
In our approach, we will first use a single model to manually input the approximate centers and radiuses of all the viruses. We will use the model type &amp;lt;tt&amp;gt;dipoleSet&amp;lt;/tt&amp;gt;. This model allows to describe each annotated virus as a &#039;&#039;dipole&#039;&#039;: we will mark the (approximate) center of the virus as the &amp;lt;tt&amp;gt;center&amp;lt;/tt&amp;gt; property of a dipole. The radius of the virus will be described by an annotation of the &amp;lt;tt&amp;gt;north&amp;lt;/tt&amp;gt; property of the dipole.  &lt;br /&gt;
&lt;br /&gt;
Notice that &#039;&#039;Dynamo&#039;&#039; includes several tools for [[vesicle models]], so you might be surprised that for this particular case we go instead for this (somewhat obscurely named) &#039;&#039;dipoleSet&#039;&#039; type of model. This is just a question of convenience: the &amp;lt;tt&amp;gt;dipoleSet&amp;lt;/tt&amp;gt; allows to quickly click a series of centers and radiuses and store them in a &#039;&#039;single&#039;&#039; model. That&#039;s all you need to describe vesicular geometry. Additionally, the &amp;lt;tt&amp;gt;dipoleSet&amp;lt;/tt&amp;gt; includes some tools for quickly extracting particles from a &#039;&#039;multivesicular&#039;&#039; set, and it also offers a useful on-screen representation in the &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; tomogram browser.&lt;br /&gt;
&lt;br /&gt;
[[File:HivSelectModel.png|thumb|center|600px| Selecting the &#039;&#039;dipoleSet&#039;&#039; model ]]&lt;br /&gt;
&lt;br /&gt;
When the model is active, we use the key &amp;lt;tt&amp;gt;c&amp;lt;/tt&amp;gt; to mark the &amp;lt;tt&amp;gt;center&amp;lt;/tt&amp;gt; of the current dipole, and &amp;lt;tt&amp;gt;n&amp;lt;/tt&amp;gt; to mark the north. It will create a semitransparent sphere enclosing the completed dipole.&lt;br /&gt;
&lt;br /&gt;
[[File:HivClickDipole.png |thumb|center|600px| Selecting a &#039;&#039;dipole&#039;&#039;: click on &amp;lt;tt&amp;gt;C&amp;lt;/tt&amp;gt; for the center, then &amp;lt;tt&amp;gt;N&amp;lt;/tt&amp;gt; for the north]]&lt;br /&gt;
&lt;br /&gt;
=== Corrections during picking ===&lt;br /&gt;
&lt;br /&gt;
Further clicks on &amp;lt;tt&amp;gt;c&amp;lt;/tt&amp;gt; or &amp;lt;tt&amp;gt;n&amp;lt;/tt&amp;gt; will just move the &amp;lt;tt&amp;gt;center&amp;lt;/tt&amp;gt; or the &amp;lt;tt&amp;gt;north&amp;lt;/tt&amp;gt; of the &#039;&#039;same&#039;&#039; dipole. In order to click a further dipole, you need to &#039;&#039;&#039;click on &amp;lt;tt&amp;gt;enter&amp;lt;/tt&amp;gt;&#039;&#039;&#039; and &amp;quot;open&amp;quot;  the next dipole for clicking. If you forget to click on &amp;lt;tt&amp;gt;enter&amp;lt;/tt&amp;gt; before annotating points on the next vesicle, you&#039;ll end up with situation like this: &lt;br /&gt;
&lt;br /&gt;
[[ File:HivForgetDipoleOpening.png |thumb|center|600px| Wrong input: &amp;lt;tt&amp;gt;enter&amp;lt;/tt&amp;gt; needed to be clicked between vesicles 2 and 3]]&lt;br /&gt;
&lt;br /&gt;
Here, the user probably clicked on &amp;lt;tt&amp;gt;c&amp;lt;/tt&amp;gt; for vesicle 2 in its real center, then clicked on &amp;lt;tt&amp;gt;n&amp;lt;/tt&amp;gt; for the north point, and then moved to vesicle 3, clicking on &amp;lt;tt&amp;gt;c&amp;lt;/tt&amp;gt; trying to mark the center. As a new dipole  was not opened (i.e., the &amp;lt;tt&amp;gt;enter&amp;lt;/tt&amp;gt; key was not pressed) when the vesicle 2 was finished, the center of vesicle 2 got misplaced.  When this happens, simply press on &amp;lt;tt&amp;gt;h&amp;lt;/tt&amp;gt; to hide the spheres and click the center of vesicle 2 back in its position. Then, press on &amp;lt;tt&amp;gt;enter&amp;lt;/tt&amp;gt; to start the next vesicle.&lt;br /&gt;
&lt;br /&gt;
=== Corrections after picking ===&lt;br /&gt;
&lt;br /&gt;
It is a good idea to observe your annotation from the &#039;&#039;x&#039;&#039; or &#039;&#039;y&#039;&#039;perspectives (for this, press on keys &amp;lt;tt&amp;gt;x&amp;lt;/tt&amp;gt; or  &amp;lt;tt&amp;gt;y&amp;lt;/tt&amp;gt; when the cursor is on the slide). Sometimes you might identify situations like this one:&lt;br /&gt;
&lt;br /&gt;
[[  File:HivWrongOnY.png|thumb|center|600px| Vesicle is too poorly picked]]&lt;br /&gt;
&lt;br /&gt;
In such cases, you want to remove the dipole and click it again. The easiest way to do so is to:&lt;br /&gt;
# click on &#039;h&#039; to hide the spheres, and&lt;br /&gt;
# secondary click on the wrongly created dipole (you have to click on the line itself) and select the &#039;&#039;Remove and prepare for reenter&#039;&#039; option in the menu that will popup.&lt;br /&gt;
&lt;br /&gt;
[[  File:HivWrongYReselect.png|thumb|center|600px| Remove dipole and click again]]&lt;br /&gt;
&lt;br /&gt;
When you are finished, don&#039;t forget to save the tomogram into the catalogue, using the disk icon (or the &#039;&#039;Active Model&#039;&#039; control)&lt;br /&gt;
&lt;br /&gt;
[[  File:HivFinalSelection.png |thumb|center|600px| Save model into catalogue]]&lt;br /&gt;
&lt;br /&gt;
== Cropping the particles ==&lt;br /&gt;
&lt;br /&gt;
We will describe a protocol to be carried from the command line, explaining each step. In short, we will visit each dipole in the model we just created, define a spherical vesicle centered on the dipole, use it to define a regular distribution of points on each vesicle, define positions pointing outwards and format everything as a [[table]] that can be used directly by &#039;&#039;Dynamo&#039;&#039; to operate an extraction and a subsequent alignment.&lt;br /&gt;
&lt;br /&gt;
=== Table extraction ===&lt;br /&gt;
&lt;br /&gt;
==== In Matlab  ====&lt;br /&gt;
&lt;br /&gt;
If you are working in Matlab, you can just proceed with &amp;lt;tt&amp;gt;dcmodels&amp;lt;/tt&amp;gt; to find the location of your dipole set. &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dcmodels hiv -tc dipoleSet -ws o -gm 1&lt;br /&gt;
&lt;br /&gt;
% assumes that you only have one model file &lt;br /&gt;
ds = o.models{1};&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===== Create a table for each vesicle =====&lt;br /&gt;
&lt;br /&gt;
Now we can loop on each dipole contained in the dipole set &amp;lt;tt&amp;gt;ds&amp;lt;/tt&amp;gt;.  The next lines should be copied into a text file (using matlab command &amp;lt;tt&amp;gt;edit&amp;lt;/tt&amp;gt;), and executed.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;NDipoles = length(ds.dipoles);&lt;br /&gt;
&lt;br /&gt;
for i=1:NDipoles;&lt;br /&gt;
   v =dmodels.vesicle();&lt;br /&gt;
   &lt;br /&gt;
   v.center = ds.dipoles{i}.center;&lt;br /&gt;
&lt;br /&gt;
   % defines the radius in terms of the clicked dipole &lt;br /&gt;
   v.radius = norm( ds.dipoles{i}.north - ds.dipoles{i}.center);&lt;br /&gt;
   &lt;br /&gt;
   % create a separation distance in the vesicle&lt;br /&gt;
   v.separation = 20;&lt;br /&gt;
&lt;br /&gt;
   % This parameter sets the cropping point a number of pixels away from the vesicle&lt;br /&gt;
   % this  distance in pixels  is measured in the normal direction.&lt;br /&gt;
   % here we just use the default value.&lt;br /&gt;
   v.crop_distance_from_surface =0;&lt;br /&gt;
   &lt;br /&gt;
   % creates the crop points and respective angles&lt;br /&gt;
   v.updateCrop();&lt;br /&gt;
   &lt;br /&gt;
   % extracts a table&lt;br /&gt;
   tv{i} = v.grepTable();&lt;br /&gt;
   &lt;br /&gt;
   % marks the table assigning in the column 22 (foreseen for arbitrary use)&lt;br /&gt;
   % the number of the individual dipole&lt;br /&gt;
   tv{i}(:,22) = i;&lt;br /&gt;
    &lt;br /&gt;
   % provides information on the output&lt;br /&gt;
   &lt;br /&gt;
   disp(sprintf(&#039;Dipole %d will provide %d crop points&#039;,i,size(v.crop_points,2)));&lt;br /&gt;
end &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
==== In the standalone ====&lt;br /&gt;
&lt;br /&gt;
The standalone can execute matlab scripts, with some restrictions: the scripts need to be self contained: any traffic of variables needs to be carried through writing and reading files. There is no other possibility of transferring workspace variables between your session and the script.&lt;br /&gt;
&lt;br /&gt;
===== Creating a text file =====&lt;br /&gt;
&lt;br /&gt;
Create a text file named &amp;lt;tt&amp;gt;commands.m&amp;lt;/tt&amp;gt; (arbitrary name) with any text editor available in your system. In Linux &amp;lt;tt&amp;gt;gedit&amp;lt;/tt&amp;gt; is probably available.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;gedit commands.m &amp;amp; &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Now paste the text of the commands excluding  comments (# simbols).&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;ds = dread(&amp;lt;YOUR FILE&amp;gt;);;&lt;br /&gt;
NDipoles = length(ds.dipoles);&lt;br /&gt;
&lt;br /&gt;
for i=1:NDipoles;&lt;br /&gt;
   v =dmodels.vesicle();&lt;br /&gt;
   v.center = ds.dipoles{i}.center;&lt;br /&gt;
   v.radius = norm( ds.dipoles{i}.north - ds.dipoles{i}.center);&lt;br /&gt;
   v.separation = 20;&lt;br /&gt;
   v.crop_distance_from_surface =0;&lt;br /&gt;
   v.updateCrop();&lt;br /&gt;
   tv{i} = v.grepTable();&lt;br /&gt;
   tv{i}(:,22) = i;&lt;br /&gt;
   disp(sprintf(&#039;Dipole %d will provide %d crop points&#039;,i,size(v.crop_points,1)));&lt;br /&gt;
end &lt;br /&gt;
dwrite(tv,&#039;cellOfTables.mat&#039;);&lt;br /&gt;
&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* Replace &amp;lt;tt&amp;gt;&amp;lt;YOUR FILE&amp;gt;&amp;lt;/tt&amp;gt; with the actual &amp;lt;tt&amp;gt;.omd&amp;lt;/tt&amp;gt; file that you created containing the dipoleSet model.&lt;br /&gt;
* Notice that we changed the variable input/output, by hardcoding the names of the files that need to be read and created.&lt;br /&gt;
&lt;br /&gt;
===== Executing the text file =====&lt;br /&gt;
&lt;br /&gt;
In a system shell or in &#039;&#039;Dynamo&#039;&#039;console, type:&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;tt&amp;gt;dynamo commands.m&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===== Getting the information back into the &#039;&#039;Dynamo&#039;&#039;console =====&lt;br /&gt;
In the &#039;&#039;Dynamo&#039;&#039; console, type.&lt;br /&gt;
 &amp;lt;tt&amp;gt;tv = dread(&#039;cellOfTables.mat&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Merging the tables ===&lt;br /&gt;
&lt;br /&gt;
Each dipole with number &amp;lt;tt&amp;gt;i&amp;lt;/tt&amp;gt; generated a table stored as &amp;lt;tt&amp;gt;tv{i}&amp;lt;/tt&amp;gt;, i.e., the entry &amp;lt;tt&amp;gt;i&amp;lt;/tt&amp;gt; inside the cell array &amp;lt;tt&amp;gt;t&amp;lt;/tt&amp;gt;. We want to generate a single table. Concatenating the table matrixes will not work, as it would have several particles with the same particle tags. We thus ask &#039;&#039;Dynamo&#039;&#039; to operate the table merging by itself, and renaming the particle tags. With the order:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tAll = dynamo_table_merge(tv,&#039;linear_tags&#039;,1);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
we concatenate the tables inside the cell array &amp;lt;tt&amp;gt;tv&amp;lt;/tt&amp;gt; and set the particle tags (in column 1) to be named from 1 to the maximal number of particles to be extracted from all the vesicles. You can check the result through&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtinfo(tAll);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
or graphically  through:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtplot(tAll,&#039;pf&#039;,&#039;oriented_positions&#039;);axis equal &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[File:HivDtplotAll.png |thumb|center|600px| &amp;lt;tt&amp;gt;dtplot&amp;lt;/tt&amp;gt; graphic of merged table]]&lt;br /&gt;
&lt;br /&gt;
There are several programs to depict tables. In this case we may find &amp;lt;tt&amp;gt;dpktbl.plot.disks&amp;lt;/tt&amp;gt; useful, as it allows to depict the particles in a table with an associated extent. This is useful to check how a given sidelength in pixels covers the vesicles for a given particle distribution.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpktbl.plots.disks(tAll,&#039;r&#039;,10);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:HivDisks.png|thumb|center|600px| &amp;lt;tt&amp;gt;dpktbl.plot.disks&amp;lt;/tt&amp;gt; graphic of merged table]]&lt;br /&gt;
&lt;br /&gt;
=== Create a data folder ===&lt;br /&gt;
&lt;br /&gt;
We can now create our typical [[data folder]] with dtcrop with a single command. &lt;br /&gt;
 &amp;lt;nowiki&amp;gt;targetFolder = &#039;testData&#039;;&lt;br /&gt;
sidelength = 40;&lt;br /&gt;
check = dtcrop(ds.cvolume.file,tAll,targetFolder,sidelength); &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note that that &amp;lt;tt&amp;gt;dtcrop&amp;lt;/tt&amp;gt; will create a new file that contains only the particles that were actually cropped from the tomogram.  Some particles were probably excluded if they were too close to the boundary of the tomogram. We can read this table file into memory.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;finalTable = dread([targetFolder,&#039;/crop.tbl&#039;]);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Checking the particles can be done with the interactive browsers &amp;lt;tt&amp;gt;ddbrowse&amp;lt;/tt&amp;gt; or &amp;lt;tt&amp;gt;dgallery&amp;lt;/tt&amp;gt;, but for a quick check we can use the &amp;lt;tt&amp;gt;dslices&amp;lt;/tt&amp;gt; command:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dslices(targetFolder,&#039;projy&#039;,&#039;*&#039;,&#039;t&#039;,finalTable,&#039;align&#039;,1,&#039;tag&#039;,1:10:700,&#039;labels&#039;,&#039;on&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Here, we selected only one every ten tags to get a general idea on what is going on. The flag &amp;lt;tt&amp;gt;&#039;projy&#039;,&#039;*&#039;&amp;lt;/tt&amp;gt; creates a projection of the aligned particles along &#039;&#039;y&#039;&#039;, projecting all the slides, so that we can check that we are indeed greping the  capsides.&lt;br /&gt;
&lt;br /&gt;
[[ File:HivDdbrowseInitial.png |thumb|center|600px| &amp;lt;tt&amp;gt;dslices&amp;lt;/tt&amp;gt; on a subset of particles, &#039;&#039;y&#039;&#039; projection view]]&lt;br /&gt;
&lt;br /&gt;
We see that there are different problems: we are not hitting the center of the region of interest in many particles, and in some particles the region is out of scope.&lt;br /&gt;
&lt;br /&gt;
=== Create a coarse average ===&lt;br /&gt;
&lt;br /&gt;
We create a &amp;quot;coarse average&amp;quot; by just averaging all the particles with the orientations from the table, i.e, just the normals.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;oa = daverage(targetFolder,&#039;t&#039;,finalTable,&#039;fc&#039;,1); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We can quickly check the result through: &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dview(oa)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:HivAverageLow.png |thumb|center|600px| &amp;lt;tt&amp;gt;view&amp;lt;/tt&amp;gt; of the coarse average]]&lt;br /&gt;
&lt;br /&gt;
In this case, the area of interest is probably too low in the direction &#039;z&#039;: the upper half of the average is occupied by buffer. We want to lift the cropping point of the particles a little bit &amp;quot;downwards&amp;quot;, that is, in the negative normal direction.&lt;br /&gt;
&lt;br /&gt;
=== Recropping the particles ===&lt;br /&gt;
&lt;br /&gt;
Well, the protocol that we have described step by step in the previous steps can actually be completed with a single command: the method  &amp;lt;tt&amp;gt;getTableFromEnclosingSpheres&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A complete syntax description can be found it: &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;help dmodels.dipoleSet.getTableFromEnclosingSpheres&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We just want to extract a data folder where the particles are better centered and have bit more of space, so that particles stamming from spheres that are poorly defined still have a chance to get driven by a posterior alignment to the center of the box.  If we initialize some variables:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;sep    = 20; % for &#039;separation&#039; flag. This is the separation between particles&lt;br /&gt;
cdfs   = -12; % for &#039;crop_distance_from_surface&#039; flag, in pixels&lt;br /&gt;
df     = &#039;centeredData&#039;; % for &#039;dataFolder&#039; flag. It is the data folder were the particles will be created.&lt;br /&gt;
sidelength = 64;&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
the full task can be completed in one step:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;[tnew,og] = ds.getTableFromEnclosingSpheres(&#039;sep&#039;,sep,&#039;cdfs&#039;,cdfs,&#039;df&#039;,df,&#039;s&#039;, sidelength,&#039;average&#039;,1,&#039;mw&#039;,2);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Here the &amp;lt;tt&amp;gt;mw&amp;lt;/tt&amp;gt; flag just calls for 2 cores to carry the average. If you don&#039;t have a license for the Parallel Toolbox, simply don&#039;t use the flag. &lt;br /&gt;
&lt;br /&gt;
Also, notice that two outputs are produced. The first one is just the table, (including also excluded particles!). The second one includes a more detailed output, including a field &amp;lt;tt&amp;gt;averageOutput&amp;lt;/tt&amp;gt; that corresponds to the output of the average operation on the newly created data folder &amp;lt;tt&amp;gt;centeredData&amp;lt;/tt&amp;gt;. You can view it with the normal &amp;lt;tt&amp;gt;dview&amp;lt;/tt&amp;gt; command:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dview(og.averageOutput.average);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:HivAverageCentered.png |thumb|center|600px| &amp;lt;tt&amp;gt;dview&amp;lt;/tt&amp;gt; on &#039;&#039;y&#039;&#039; and &#039;&#039;z&#039;&#039; of the newly computed coarse average]]&lt;br /&gt;
&lt;br /&gt;
== Alignment project ==&lt;br /&gt;
&lt;br /&gt;
The particles can now be aligned using the table and template that we just defined. We just need to write them into files&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dwrite(dread([df,&#039;/crop.tbl&#039;]),&#039;centered.tbl&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and the density map hidden in the output:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dwrite(og.averageOutput.average,&#039;centered.em&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and create a [[alignment project | project]]&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;pr = &#039;pcnt&#039;; % pr is a variable, &amp;quot;pcnt&amp;quot; is a literal string  &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We create an empty project pointing to the right data, template and table:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcp.new(pr,&#039;d&#039;,df,&#039;t&#039;,&#039;centered.tbl&#039;,&#039;template&#039;,&#039;centered.em&#039;,&#039;masks&#039;,&#039;default&#039;,&#039;show&#039;,0);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Putting the &#039;show&#039; flag to zero prevented the [[Dcp GUI | &amp;lt;tt&amp;gt;dcp&amp;lt;/tt&amp;gt; GUI]]  from popping up, as we want to use this walkthrough as an example of how to create and manage projects from the command line. The basic tool is &amp;lt;tt&amp;gt;dvput&amp;lt;/tt&amp;gt;, which is used to change one or several project parameters. A list of the parameters and their syntax can be printed with &amp;lt;tt&amp;gt;dvhelp&amp;lt;/tt&amp;gt; or consulted through the GUI &amp;lt;tt&amp;gt;dhelp&amp;lt;/tt&amp;gt;. For this particular project we suggest the set below: &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvput(pr,&#039;ite_r1&#039;,4);&lt;br /&gt;
dvput(pr,&#039;dim_r1&#039;,32);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the stage of finding general orientations and coarse centerings, we want to save computing time (without trading accuracy). Thus, we use the &amp;lt;tt&amp;gt;&#039;dim_r1&#039;&amp;lt;/tt&amp;gt; parameters tune to 32. As the particle boxes have a sidelength of 64 pixels,  here we are asking &#039;&#039;Dynamo&#039;&#039; to bin each particle on the fly, just one time. A neighboorhod of 2x2x2 voxels will collapse into one single voxel, with the averaged intensity.  By now, we are just interested in coarsely locating the particles, so that the speed-up in the alignemnt (8x) justifies the loss of accuracy. &lt;br /&gt;
&lt;br /&gt;
Next, we need angular settings reflect that we trust the normals that we have found. This will save computation time and make the alignment more robust.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvput(pr,&#039;cr_r1&#039;,40);&lt;br /&gt;
dvput(pr,&#039;cs_r1&#039;,20);&lt;br /&gt;
dvput(pr,&#039;ir_r1&#039;,360);&lt;br /&gt;
dvput(pr,&#039;is_r1&#039;,40);&lt;br /&gt;
dvput(pr,&#039;rf_r1&#039;,4);&lt;br /&gt;
dvput(pr,&#039;rff_r1&#039;,2);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We let the particles shift, but not the the edges of the box:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvput(pr,&#039;lim_r1&#039;,[20,20,20]);&lt;br /&gt;
dvput(pr,&#039;limm_r1&#039;,1);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Some parameters re provided to control the execution. For projects to be run in parallel under Matlab, we need the &amp;lt;tt&amp;gt;&#039;destination&#039;&amp;lt;/tt&amp;gt; parameter tuned to value &amp;lt;tt&amp;gt;&#039;matlab_parfor&#039;&amp;lt;/tt&amp;gt;. We also provide a value for the number of cores to be used during the alignments (parameter &amp;lt;tt&amp;gt;&#039;cores&#039;&amp;lt;/tt&amp;gt;) and the averaging steps (parameter &amp;lt;tt&amp;gt;matlab_workers_average&amp;lt;/tt&amp;gt;).&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dvput(pr,&#039;dst&#039;,&#039;matlab_parfor&#039;,&#039;cores&#039;,2,&#039;mwa&#039;,2);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Run project ===&lt;br /&gt;
&lt;br /&gt;
As we would do the  GUI, we have to check, unfold and run the project:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvcheck pcnt&lt;br /&gt;
dvunfold pcnt&lt;br /&gt;
dvrun pcnt&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==== In scripted protocols ====&lt;br /&gt;
 &#039;&#039;Advanced&#039;&#039;: A note for future projects: when your own scripts to run several projects created dynamically, you can put the name of the project into a variable (as we did above) and use the &amp;lt;tt&amp;gt;( ) &amp;lt;/tt&amp;gt; notation:&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvcheck(pr);&lt;br /&gt;
dvunfold(pr);&lt;br /&gt;
dvrun(pr);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
When used inside a script, you probably want to use the &amp;lt;tt&amp;gt;;&amp;lt;/tt&amp;gt; at the end of each line, to prevent flooding the screen with output.&lt;br /&gt;
&lt;br /&gt;
=== Check results ===&lt;br /&gt;
&lt;br /&gt;
We can check how the particles look like:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dslices(&#039;pcnt:data&#039;,&#039;projy&#039;,&#039;*&#039;,&#039;t&#039;,&#039;pcnt:rt:ite=3&#039;,&#039;align&#039;,1,&#039;tag&#039;,1:10:700,&#039;labels&#039;,&#039;on&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Here, &amp;lt;tt&amp;gt;&#039;pcnt:data&#039;&amp;lt;/tt&amp;gt; is a database query. it is just a shorthand to tell &#039;&#039;Dynamo&#039;&#039; to use the data folder associated with the project &amp;lt;tt&amp;gt;pcnt&amp;lt;/tt&amp;gt;. The same trick is used to extract the refined table (&amp;lt;tt&amp;gt;rt&amp;lt;/tt&amp;gt;) at iteration 3. Don&#039;t worry if you don&#039;t like this notation: you can just input the actual folder and file names.&lt;br /&gt;
&lt;br /&gt;
[[ File:HivDDbrowseCentered.png |thumb|center|600px| &amp;lt;tt&amp;gt; dslices &amp;lt;/tt&amp;gt; of a selection of aligned particles]]&lt;br /&gt;
&lt;br /&gt;
The averages can be consulted with &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt;. We open the averages (&amp;lt;tt&amp;gt;a&amp;lt;/tt&amp;gt; item) corresponding to iterations 0 and 4:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(&#039;pcnt:a:ite=[0,4]&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can tweak the visualization to see a depiction of how the average evolved from the first template to iteration number 4.&lt;br /&gt;
&lt;br /&gt;
[[ File:HivMapviewEvolution.png |thumb|center|600px|  Interactive slice comparison through &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt; ]]&lt;br /&gt;
&lt;br /&gt;
As a tip, when you know exactly which features you want to test visually, you can use the command line order &amp;lt;tt&amp;gt;dslices&amp;lt;/tt&amp;gt; to directly produce the scene of interest:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dslices pcnt:a:ite=[0,4] -projy 44 -ns 1&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[  File:HivSlicesEvolution.png|thumb|center|600px| Programatic slice comparison through &amp;lt;tt&amp;gt;dslices&amp;lt;/tt&amp;gt; ]]&lt;br /&gt;
&lt;br /&gt;
== Recropping the particles ==&lt;br /&gt;
&lt;br /&gt;
You can create a new table excluding particles that are too close to each other:&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;tt&amp;gt;tc = dpktbl.exclusionPerVolume(&#039;pcnt:rt:ite=4&#039;,15,22);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
where 15 is a distance in pixels. The third parameter denotes the column in the table that denotes particles in the same objects. In this case, we have marked each virus with a different integer in column 22 of the table, and we pass this information to &amp;lt;tt&amp;gt;dpktbl.exclusionPerVolume&amp;lt;/tt&amp;gt;.&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Getting_a_Structure_from_Multiple_Tomograms_of_HIV_Capsids_(Tsinghua_Spring_School_2025)&amp;diff=5597</id>
		<title>Getting a Structure from Multiple Tomograms of HIV Capsids (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Getting_a_Structure_from_Multiple_Tomograms_of_HIV_Capsids_(Tsinghua_Spring_School_2025)&amp;diff=5597"/>
		<updated>2025-03-01T08:34:14Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Data */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:WalkthroughsSpecific]]&lt;br /&gt;
&lt;br /&gt;
In this walkthrough you will get familiar with managing multiple tomograms through the &#039;&#039;Dynamo&#039;&#039; catalogue and developing strategies for alignment projects to reach a reasonable structure from a set of tomograms. You will make use of the knowledge that you acquired during the workshop and apply it to a more realistic case. It is recommended to get familiar with the [[ Complete walkthrough on FHV virus (Copenhagen 2024) | advanced starters guide]] and the [[Walkthrough for lattices on vesicles (Copenhagen 2024)| walkthrough for lattices on vesicles]] before starting this walkthrough. &lt;br /&gt;
&lt;br /&gt;
== Data ==&lt;br /&gt;
We prepared a set of 6 tomograms, each containing one Immature HIV-1 virus like particle (VLP) with a layer formed by a lattice of capsid proteins. The capsid proteins have a C6 symmetry, a diameter of roughly 15nm and a molecular weight of about 150kDa. The pixelsize of the tomograms is 2.7 angstrom. You can find the tomograms in:&lt;br /&gt;
 &amp;lt;tt&amp;gt; /mnt/fs/2025workshop/data/DownloadLindVLPs/ &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The tomograms are part of the data that was used in the publication &#039;&#039;An atomic model of HIV-1 capsid-SP1 reveals structures regulating assembly and maturation&#039;&#039; by  Schur FK, Obr M, Hagen WJ, Wan W, Jakobi AJ, Kirkpatrick JM, Sachse C, Kräusslich HG and Briggs JA. (2016). The full dataset can be found on the Electron Microscopy Public Image Archive (EMPIAR) under [https://www.ebi.ac.uk/pdbe/emdb/empiar/entry/10164/ EMPIAR-10164]. The 6 tomograms were extracted from the tilt series TS_03 and TS_43.&lt;br /&gt;
&lt;br /&gt;
== Goal==&lt;br /&gt;
From the data given you should be able to get a final average in which you start seeing hints of alpha helices, i.e., it should be possible to reach a resolution close to roughly 10 angstroms. &lt;br /&gt;
&lt;br /&gt;
== Walkthrough  ==&lt;br /&gt;
=== Set up a catalogue ===&lt;br /&gt;
Create a new [[catalogue|catalogue]]&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcm -create catVLP&amp;lt;/tt&amp;gt;&lt;br /&gt;
and open it in the catalogue manager&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcm catVLP&amp;lt;/tt&amp;gt;&lt;br /&gt;
You can add each volume manually to the catalogue under &#039;&#039;Catalogue -&amp;gt; Browse for new volume&#039;&#039; or you can make use of a [[volume list file|volume file]] and add all tomograms at once under &#039;&#039;Catalogue -&amp;gt; Input list of tomograms -&amp;gt; Browse for text file (.vll file)&#039;&#039;. The volume file should be created beforehand by opening a blank text file named for example &amp;lt;code&amp;gt;VLPtomograms.vll&amp;lt;/code&amp;gt; and copy the paths of all tomograms into it:&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;vlp_1.mrc&lt;br /&gt;
vlp_2.mrc&lt;br /&gt;
vlp_3.mrc&lt;br /&gt;
vlp_4.mrc&lt;br /&gt;
vlp_5.mrc&lt;br /&gt;
vlp_6.mrc&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In case you imported the tomograms using a volume file you have to click the button &#039;&#039;list volumes&#039;&#039; to refresh the tomogram list in the catalogue manager. Now you should see the 6 tomograms in the catalogue manager. [[Prebinned_tomograms|Prebin]] the tomograms once (1x) under &#039;&#039;Catalogue -&amp;gt; Create binned versions -&amp;gt; with factor 1&#039;&#039;. You can now look at single tomograms in [[dtmslice|tomoslice]] by selecting a tomogram of choice in the catalogue manager and then go under &#039;&#039;View volume -&amp;gt; Load full prebinned Volume [if available] -&amp;gt; open in tomoslice&#039;&#039;. If needed, adjust the lowpass level and contrast in tomoslice to improve the depiction.&lt;br /&gt;
&lt;br /&gt;
=== Annotate tomograms ===&lt;br /&gt;
To know where we want to later extract the subvolumes we have to first annotate the surfaces of the VLPs inside the tomograms. We do this by opening a tomogram inside tomoslice where a so called dipole Set model is defined. How to do that is described in detail in the section &#039;&#039;DipoleSet models&#039;&#039;, &#039;&#039;Corrections during picking&#039;&#039; and &#039;&#039;Corrections after picking&#039;&#039; of the [[Walkthrough_for_lattices_on_vesicles | walkthrough for lattices on vesicles]]. A new dipole set model has to be made for each tomogram. Save each model before closing tomoslice and when opening a new tomogram in tomoslice select &#039;&#039;Delete from memory&#039;&#039; if asked. In case you see markers of the previously defined dipole set inside the newly opened tomogram make sure the model pool is empty and click on &#039;&#039;reset scene&#039;&#039; before defining the new dipole set. Once you went through all tomograms click on the button &#039;&#039;list volumes&#039;&#039; inside the catalogue manager to refresh the list of tomograms. In the column &#039;&#039;model files&#039;&#039; of the tomogram list of the catalogue manager you should now see that you have one defined model per tomogram.&lt;br /&gt;
&lt;br /&gt;
=== Define crop points ===&lt;br /&gt;
To extract subvolumes (crop particles) we need to first define the crop points on the surface of the VLPs using the previously defined models. The crop points are then stored in a table. This is all done with the following script which is an extended version of the one found in the [[Walkthrough_for_lattices_on_vesicles | walkthrough for lattices on vesicles]]. Note that we [[Seed_oversampling|oversample]] the VLPs, i.e., we define enough crop points such that every protein has the chance to end up in at least one subvolume. We will take care of proteins that end up in more than subvolume in a later step. Note that this script assumes that there are exactly 6 tomograms with only one model for each tomogram. In cases where a different number of tomograms or models is used, the script has to be adapted accordingly.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;% read dipole from catalogue into workspace&lt;br /&gt;
dcmodels catVLP -tc dipoleSet -ws o -gm 1&lt;br /&gt;
&lt;br /&gt;
c=1; % counter for table&lt;br /&gt;
for tomo = 1:6 % loop over tomograms&lt;br /&gt;
    ds = o.models{tomo};                  % read models&lt;br /&gt;
    NDipoles = length(ds.dipoles);&lt;br /&gt;
    for i=1:NDipoles                      % loop over models (in our case just one per tomogram)&lt;br /&gt;
        v = dmodels.vesicle();            % create empty vesicle model&lt;br /&gt;
        v.center = ds.dipoles{i}.center;  % add center from dipole to vesicle model&lt;br /&gt;
        v.radius = norm( ds.dipoles{i}.north - ds.dipoles{i}.center); % add radius&lt;br /&gt;
        v.separation = 60;                % separation of crop points (in px)&lt;br /&gt;
        v.crop_distance_from_surface =0;&lt;br /&gt;
        v.updateCrop();                   % update vesicle model&lt;br /&gt;
&lt;br /&gt;
        tv{c} = v.grepTable(); % create crop table from using vesicle model&lt;br /&gt;
        tv{c}(:,22) = i;       % add model number to table&lt;br /&gt;
        tv{c}(:,20) = tomo;    % add tomogram number to table&lt;br /&gt;
        c=c+1;&lt;br /&gt;
    end&lt;br /&gt;
end&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
In the &#039;&#039;&#039;standalone version&#039;&#039;&#039; you need to proceed as follows:&lt;br /&gt;
&lt;br /&gt;
1.) Open a text file named &amp;lt;code&amp;gt;commands.m&amp;lt;/code&amp;gt; and copy the following into the file (avoid commenting with % or #):&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;o=dcmodels(&#039;catVLP&#039;,&#039;tc&#039;,&#039;dipoleSet&#039;,&#039;gm&#039;,1);&lt;br /&gt;
c=1;&lt;br /&gt;
for tomo = 1:6&lt;br /&gt;
    ds = dread(o{tomo});&lt;br /&gt;
    NDipoles = length(ds.dipoles);&lt;br /&gt;
    for i=1:NDipoles&lt;br /&gt;
        v = dmodels.vesicle();&lt;br /&gt;
        v.center = ds.dipoles{i}.center;&lt;br /&gt;
        v.radius = norm( ds.dipoles{i}.north - ds.dipoles{i}.center);&lt;br /&gt;
        v.separation = 60;&lt;br /&gt;
        v.crop_distance_from_surface =0;&lt;br /&gt;
        v.updateCrop();&lt;br /&gt;
        tv{c} = v.grepTable();&lt;br /&gt;
        tv{c}(:,22) = i;&lt;br /&gt;
        tv{c}(:,20) = tomo;&lt;br /&gt;
        c=c+1;&lt;br /&gt;
        disp(sprintf(&#039;Dipole %d will provide %d crop points&#039;,i,size(v.crop_points,2)));&lt;br /&gt;
    end&lt;br /&gt;
end&lt;br /&gt;
dwrite(tv,&#039;cellOfTables.mat&#039;);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
2.) Execute the text file in a system shell or in the &#039;&#039;Dynamo&#039;&#039; console:&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;tt&amp;gt;dynamo commands.m&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
3.) When you are back in the &#039;&#039;Dynamo&#039;&#039; console, you can load the results from the script into the workspace with&lt;br /&gt;
 &amp;lt;tt&amp;gt;tv = dread(&#039;cellOfTables.mat&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Type &#039;&#039;whos&#039;&#039; to display the actual matlab workspace and to check if the variable &#039;&#039;tv&#039;&#039; was loaded correctly.&lt;br /&gt;
&lt;br /&gt;
=== Write table with crop points ===&lt;br /&gt;
&lt;br /&gt;
The tables beloning to each dipole model are stored in the cell array &#039;&#039;tv&#039;&#039;. To create one single table containing all crop points we merge all tables into one with the command&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tAll = dynamo_table_merge(tv,&#039;linear_tags&#039;,1); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and visualize the table to see the crop points and their orientations (when visualizing actual results of an alignment project use option &#039;&#039; &#039;corrected_oriented_positions&#039;&#039; &#039; instead of the one shown here).&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtplot(tAll,&#039;pf&#039;,&#039;oriented_positions&#039;); axis equal&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You should get something like:&lt;br /&gt;
&lt;br /&gt;
 [[File:Result_table_vlp.png|thumb|center|400px| Crop points in table.]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
=== Extract subvolumes ===&lt;br /&gt;
&lt;br /&gt;
Before extracting the subvolumes (cropping particles) using the previously generated table we have to define a so called [[Tomogram-table map file|tomogram table map file]] which links the tomogram identification number in column 20 of the previously created table to an actual tomogram on the disk. Create a file named &amp;lt;code&amp;gt;VLPtomograms.doc&amp;lt;/code&amp;gt; and copy the tomogram numbers and full paths of the tomograms into it:&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;1 vlp_1.mrc&lt;br /&gt;
2 vlp_2.mrc&lt;br /&gt;
3 vlp_3.mrc&lt;br /&gt;
4 vlp_4.mrc&lt;br /&gt;
5 vlp_5.mrc&lt;br /&gt;
6 vlp_6.mrc&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Define a destination for the cropped particles:&lt;br /&gt;
 &amp;lt;tt&amp;gt;targetFolder = &#039;./particlesSize128&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Now we can crop the particles with sidelength 128 pixels from the tomograms using the table previously defined.&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtcrop(&#039;VLPtomograms.doc&#039;,tAll,targetFolder,128);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The cropping on one core should not take longer than 5 minutes. &lt;br /&gt;
&lt;br /&gt;
We create a plain average of all cropped particles to asses the quality of the cropped particles. First we read the table of the cropped particles:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;finalTable = dread([targetFolder &#039;/crop.tbl&#039;]);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We can also visualise the particles:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dslices(targetFolder,&#039;projy&#039;,&#039;*&#039;,&#039;t&#039;,finalTable,&#039;align&#039;,1,&#039;tag&#039;,1:10:500,&#039;labels&#039;,&#039;on&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Then we form the average&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;oa = daverage(targetFolder,&#039;t&#039;,finalTable,&#039;fc&#039;,1);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and inspect the average with&lt;br /&gt;
 &amp;lt;tt&amp;gt;dview(oa.average)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You should see a faint and noisy curvature of a thick membrane-like structure in the X and Y view.&lt;br /&gt;
&lt;br /&gt;
 [[File:VLP_raw128_x.png|thumb|center|170px| Average of cropped particles (X view).]]&lt;br /&gt;
&lt;br /&gt;
We will use this average as a first reference (template) in the next alignment project. We therefore save the average with&lt;br /&gt;
 &amp;lt;tt&amp;gt;dwrite(oa.average,[targetFolder &#039;/template.em&#039;]);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Hint: When dealing with preferred orientations, randomizing the azimuth of the particles bevore averaging can help (in this tutorial this is not needed):&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tRandAz = dynamo_table_randomize_azimuth(t);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== First alignment project ===&lt;br /&gt;
Now we create our first [[alignment project | alignment project]] through the command line in a similar way as described in detail in the [[Walkthrough_for_lattices_on_vesicles | walkthrough for lattices on vesicles]]. First we define a project name&lt;br /&gt;
 &amp;lt;tt&amp;gt;pr = &#039;aliVLP&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Then we create the alignment project with the particles, template and table that we defined before. The masks are set to default.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcp.new(pr,&#039;d&#039;,targetFolder,&#039;t&#039;,[targetFolder &#039;/crop.tbl&#039;],&#039;template&#039;,[targetFolder &#039;/template.em&#039;],&#039;masks&#039;,&#039;default&#039;,&#039;show&#039;,0);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Next we set up the numerical parameters for the project and the computing environment (type &#039;&#039;dvhelp&#039;&#039;  in the console for an overview of all parameters). We use 2x binned particles and a rather coarse angular search. The shift limits are very generous in order to make sure all particles have the chance to &#039;see&#039; each other.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvput(pr,&#039;ite_r1&#039;,4);&lt;br /&gt;
dvput(pr,&#039;dim_r1&#039;,32);&lt;br /&gt;
dvput(pr,&#039;cr_r1&#039;,40);&lt;br /&gt;
dvput(pr,&#039;cs_r1&#039;,20);&lt;br /&gt;
dvput(pr,&#039;ir_r1&#039;,360);&lt;br /&gt;
dvput(pr,&#039;is_r1&#039;,40);&lt;br /&gt;
dvput(pr,&#039;rf_r1&#039;,4);&lt;br /&gt;
dvput(pr,&#039;rff_r1&#039;,2);&lt;br /&gt;
dvput(pr,&#039;lim_r1&#039;,[40,40,40]);&lt;br /&gt;
dvput(pr,&#039;limm_r1&#039;,1);&lt;br /&gt;
dvput(pr,&#039;dst&#039;,&#039;standalone_gpu&#039;,&#039;cores&#039;,1,&#039;mwa&#039;,2);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Everything can of course also be set up through the alignment project GUI. The numerical parameters would correspond to:&lt;br /&gt;
&lt;br /&gt;
 [[File:VLP_first_parameters.png|thumb|center|400px| Alignment parameters for first alignment project.]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Check, unfold and run the project through the alignment project GUI or through the command line:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvcheck aliVLP&lt;br /&gt;
dvunfold aliVLP&lt;br /&gt;
dvrun aliVLP&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
On one GPU (and 2 cores for averaging) the alignment project should not take longer than half an hour. Check the status of the alignment project with&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dvstatus aliVLP&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can also see the average of the last computed iteration in &#039;&#039;dmapview&#039;&#039; with the command. If needed, adjust the lowpass and contrast to improve the depiction.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(&#039;aliVLP:a&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Recenter and recrop ===&lt;br /&gt;
After the alignment project finished successfully we can inspect the last computed average with the same command introduced before:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(&#039;aliVLP:a&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The command can be extended to see the averages of all iterations including the starting reference. Once in &#039;&#039;dmapview&#039;&#039;, press the button &#039;&#039;norm&#039;&#039; to properly compare the averages.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(&#039;aliVLP:a:ite=0:last&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the last average, you should already start to see a hexagonal lattice. We now want to make sure that the center of one C6 subunit of the lattice coincides with the center of the subvolume and that the subunits symmetry axis is parallel to the Z axis of the subvolume. This will allow us to later recrop the subvolumes with a smaller box size and to choose finer alignment parameters in the next alignment project. The recentering and realigning can be done in two steps. First, we subbox the particles using a new, manually defined box center and recrop the particles with a smaller boxsize. Second, we align the symmetry axis using a synthetic template. Both procedures are described in detail in the [[Advanced_starters_guide | advanced starters guide]] in the section &#039;&#039;Aligning the axis of symmetry&#039;&#039; and &#039;&#039;Subboxing &#039;&#039; and are now applied here.&lt;br /&gt;
&lt;br /&gt;
====Step 1: Subboxing====&lt;br /&gt;
&lt;br /&gt;
Open the last computed average in &#039;&#039;dmapview&#039;&#039; as previously described. Activate the radio buttons for the &#039;&#039;Center/North&#039;&#039; tools under &#039;&#039;Clicks&#039;&#039;. You can now click anywhere on the average and see the corresponding coordinates. Find the coordinates of the center of one subunit of the lattice. Switch between X,Y and Z view to make sure the center is correct. In our case we found the center of a subunit at [88,75,72]. For you these coordinates might be different.&lt;br /&gt;
&lt;br /&gt;
 [[File:VLP_center_xy.jpg|thumb|center|600px| Finding the coordinates of the center of a lattice subunit.]]&lt;br /&gt;
&lt;br /&gt;
Copy the found coordinates of the center of the subunit into the first vector of the command below. To compute the vector from the center of the subvolume to the center of a subunit we need to subtract the coordinates of the center of the subvolume. The [[Volume_center|center of a subvolume]] with a sidelength of 128 pixels is defined as [65,65,65].&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;rSubunitFromCenter = [88,75,72] - [65,65,65];&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This vector will now be used to shift (or recenter) all particles in the table. Read the last computed table of the alignment project&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;ddb aliVLP:rt -ws t&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and apply the new center to the table&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;ts = dynamo_subboxing_table(t,rSubunitFromCenter);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The table now contains the coordinates of the recentered particles. We use this new table to recrop the particles. We first define a new target folder:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;targetFolder = &#039;./particlesSize96r&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Then we recrop the new particles. Since the particles are centered now, we can also choose a smaller boxsize of 96 pixels. This will save space and speed up the following processes. &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtcrop(&#039;VLPtomograms.doc&#039;,ts,targetFolder,96);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Again we average and visualize the cropping results:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;finalTable = dread([targetFolder,&#039;/crop.tbl&#039;]);&lt;br /&gt;
oa = daverage(targetFolder,&#039;t&#039;,finalTable,&#039;fc&#039;,1);&lt;br /&gt;
dwrite(oa.average,[targetFolder &#039;/template.em&#039;]);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==== Step 2: Align symmetry axis ====&lt;br /&gt;
We see that the new average is niceley centered (there is one subunit of the lattice in the center of the volume). However, the symmetry axis is not aligned with the Z axis (the whole average looks a bit &#039;tilted&#039;).&lt;br /&gt;
&lt;br /&gt;
 [[File:VLP_tilted.png|thumb|center|170px| Centered subunit but tilted symmetry axis (X view).]]&lt;br /&gt;
&lt;br /&gt;
We can fix that by aligning the last computed average to a synthetic template and then apply the found transformation to the table, resulting in a new and correct orientation for all particles. First we create a synthetic template using the mask tools of &#039;&#039;Dynamo&#039;&#039;. We choose a curved membrane with a hole in the center, representing the &#039;hollow&#039; central subunit of the lattice.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;mr = dpktomo.examples.motiveTypes.Membrane();   % create membrane object&lt;br /&gt;
mr.thickness  = 22;       % choose thickness of membrane&lt;br /&gt;
mr.sidelength = 96;       % choose sidelength of box&lt;br /&gt;
mr.getMask();             % compute mask &lt;br /&gt;
mem  = (mr.mask)*(-1)+1;  % invert contrast&lt;br /&gt;
cyl = dynamo_cylinder(7,96,[48,48,48]);  % create a cylinder (this will be the &#039;hole&#039;)&lt;br /&gt;
templateSum = mem+cyl;    % sum the two masks&lt;br /&gt;
template = templateSum;&lt;br /&gt;
template(template&amp;gt;0) = 1; % binarize the new mask&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We look at the newly created template to make sure it was computed correctly.&lt;br /&gt;
 &amp;lt;tt&amp;gt;dview(template)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 [[File:VLP_template.png|thumb|center|170px| Template for axis alignment (X view).]]&lt;br /&gt;
&lt;br /&gt;
Now we align the last computed average of the previous alignment project to the newly created template. We save the computed transformation parameters in the matlab object &#039;&#039;sal&#039;&#039;.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;sal = dalign(oa.average,template,&#039;cr&#039;,30,&#039;cs&#039;,5,&#039;ir&#039;,0,&#039;dim&#039;,48,&#039;limm&#039;,1,&#039;lim&#039;,[15,15,15]);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A quick look at the newly aligned average should show a nicely centered particle with the symmetry axis aligned to the Z axis.&lt;br /&gt;
 &amp;lt;tt&amp;gt;dmapview(sal.aligned_particle);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 [[File:VLP_centered_xz.png|thumb|center|300px| Centered and aligned symmetry axis (X/Z view).]]&lt;br /&gt;
&lt;br /&gt;
The transformation parameters that have been saved in the matlab object &#039;&#039;sal&#039;&#039; can now be applied to the table&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tr =  dynamo_table_rigid(finalTable,sal.Tp);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We now have an up-to-date table with nicely centered and aligned particles. This new table can be used in a new, finer alignment project.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
=== Dealing with oversampling ===&lt;br /&gt;
Before starting the new alignment project we apply one more operation on the table. Since we oversampled the VLP surfaces in the beginning we might have ended up with some proteins being in more than one subvolume. Using the following function we can exclude subvolumes that are closer than 20 pixels to each other. In case the distance between two (or more) subvolumes is below this threshold, only the volume with the highest cross correlation (resulting from the previous alignment project) is kept. Read more about how to deal with oversampling [[Seed oversampling| here]].&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;trEx = dpktbl.exclusionPerVolume(tr,20);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We save the new table and use it to create a new reference, which will be used in the next alignment project.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;targetFolder = &#039;./particlesSize96r&#039;;&lt;br /&gt;
dwrite(trEx,[targetFolder &#039;/crop_trEx.tbl&#039;]);&lt;br /&gt;
oa = daverage(targetFolder,&#039;t&#039;,trEx,&#039;fc&#039;,1);&lt;br /&gt;
dwrite(oa.average,[targetFolder &#039;/template_trEx.em&#039;]);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Second aligment project ===&lt;br /&gt;
We now have particles which are centered and aligned. We dealt with the oversampling and recropped them to a smaller box size. These are good conditions to run one more alignment project with finer alignment parameters. We will narrow down the angular search, use a finer angular sampling, impose a C6 symmetry and use a tighter alignment mask. We begin by creating an alignment mask which is tighter than the previously used default one. Through the following commands we create a mask that looks like a thick curved membrane.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;mr = dpktomo.examples.motiveTypes.Membrane();&lt;br /&gt;
mr.thickness  = 55;&lt;br /&gt;
mr.sidelength = 96;&lt;br /&gt;
mr.getMask();&lt;br /&gt;
mem_mask  = mr.mask;&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We save the alignment mask&lt;br /&gt;
 &amp;lt;tt&amp;gt;dwrite(mem_mask,&#039;mem_mask_thick.em&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and inspect it in &#039;&#039;dmapview&#039;&#039;. We open first the previously created template&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dmapview(oa.average)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and then in the mask section we activate &#039;&#039;file&#039;&#039;, put the path of the mask in it (&#039;&#039;mem_mask_thick.em&#039;&#039;) and then click &#039;&#039;layer&#039;&#039;. You should see the mask overlaid to the average. The mask should contain all the signal of the sample. If this is not the case create a new mask with adjusted parameters.&lt;br /&gt;
&lt;br /&gt;
 [[File:VLP_ali_mask_x.png|thumb|center|170px| Alignment mask overlaid to reference (X view).]]&lt;br /&gt;
&lt;br /&gt;
We have now all the material to set up a new alignment project in the same way as done before. We define a new project name:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;pr = &#039;aliVLP_fine&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We create the new alignment project with the newly cropped particles of 96 pixles sidelength, the new template and the new table. The masks are set to default for now. The new alignment mask is added in the next step.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dcp.new(pr,&#039;d&#039;,targetFolder,&#039;t&#039;,[targetFolder &#039;/crop_trEx.tbl&#039;],&#039;template&#039;,[targetFolder &#039;/template_trEx.em&#039;],&#039;masks&#039;,&#039;default&#039;,&#039;show&#039;,0);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Adding the new tight alignment mask:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dvput(pr,&#039;file_mask&#039;,&#039;mem_mask_thick.em&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Next we set up the numerical parameters for the project. In this case we define two rounds. The first round has 2 iterations and works with 1x binned particles and a more restricted and finer angular search than the first alignment project. The second round has only 1 iteration but is using the full size particles and even finer angular search parameters. We use C6 symmetry in both rounds.&lt;br /&gt;
&lt;br /&gt;
Parameters round 1:&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvput(pr,&#039;ite_r1&#039;,2);&lt;br /&gt;
dvput(pr,&#039;dim_r1&#039;,48);&lt;br /&gt;
dvput(pr,&#039;cr_r1&#039;,30);&lt;br /&gt;
dvput(pr,&#039;cs_r1&#039;,10);&lt;br /&gt;
dvput(pr,&#039;ir_r1&#039;,30);&lt;br /&gt;
dvput(pr,&#039;is_r1&#039;,10);&lt;br /&gt;
dvput(pr,&#039;rf_r1&#039;,4);&lt;br /&gt;
dvput(pr,&#039;rff_r1&#039;,2);&lt;br /&gt;
dvput(pr,&#039;lim_r1&#039;,[15,15,15]);&lt;br /&gt;
dvput(pr,&#039;limm_r1&#039;,1);&lt;br /&gt;
dvput(pr,&#039;sym_r1&#039;,&#039;c6&#039;);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Parameters round 2:&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvput(pr,&#039;ite_r2&#039;,1);&lt;br /&gt;
dvput(pr,&#039;dim_r2&#039;,96);&lt;br /&gt;
dvput(pr,&#039;cr_r2&#039;,12);&lt;br /&gt;
dvput(pr,&#039;cs_r2&#039;,4);&lt;br /&gt;
dvput(pr,&#039;ir_r2&#039;,12);&lt;br /&gt;
dvput(pr,&#039;is_r2&#039;,4);&lt;br /&gt;
dvput(pr,&#039;rf_r2&#039;,4);&lt;br /&gt;
dvput(pr,&#039;rff_r2&#039;,2);&lt;br /&gt;
dvput(pr,&#039;lim_r2&#039;,[5,5,5]);&lt;br /&gt;
dvput(pr,&#039;limm_r2&#039;,2);&lt;br /&gt;
dvput(pr,&#039;sym_r2&#039;,&#039;c6&#039;);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We set the computing environement:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dvput(pr,&#039;dst&#039;,&#039;standalone_gpu&#039;,&#039;cores&#039;,1,&#039;mwa&#039;,2);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Check, unfold and run the project:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dvcheck aliVLP_fine&lt;br /&gt;
dvunfold aliVLP_fine&lt;br /&gt;
dvrun aliVLP_fine &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
While the project is running, we can monitor the results in the same way as we did for the first alignment project. This project should again take no longer than half an hour on one GPU (and 2 cores for averaging). If you are under time pressure you can skip the second round. You should have already nice results after the first round.&lt;br /&gt;
&lt;br /&gt;
=== Result ===&lt;br /&gt;
After the second alignment and without any postprocessing or elaborate refinement your final average may look similar to the one shown below. If not, it may need one more refinement round, adjustments to the mask or one more step of recentering and recropping. This representation was lowpass filtered to ~8 angstroms (or 32px in fourier space).&lt;br /&gt;
&lt;br /&gt;
 [[File:Average_hiv.jpg|thumb|center|400px| Possible outcome of the exercise.]]&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_hexagonal_lattice_coherence_through_neighborhood_analysis_(Tsinghua_Spring_School_2025)&amp;diff=5596</id>
		<title>Walkthrough on hexagonal lattice coherence through neighborhood analysis (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_hexagonal_lattice_coherence_through_neighborhood_analysis_(Tsinghua_Spring_School_2025)&amp;diff=5596"/>
		<updated>2025-03-01T08:31:32Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Data */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:WalkthroughsSpecific]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
==Neighborhood analysis==&lt;br /&gt;
&lt;br /&gt;
Neighbourhood analysis stands at the forefront of methods used to investigate geometrical lattice parameters and offers a wide spectrum of visualization tools. This technique is precise, targeting specific elements, yet broad enough to facilitate overarching interpretive analysis. At its core, the method constructs a latent space of connections by mapping the relative positions of neighbouring particles onto a reference framework. This mapping involves a reorientation process, wherein the &#039;N&#039; closest neighbours are repositioned within the reference particle&#039;s coordinate system, adjusted for its orientation. The richness of the latent space—characterized by the number and nature of these repositioned features—is dictated by a defined distance threshold. This threshold ranges from a minimal couple, representing the closest inter-particle distance, to the maximal extent, linking every particle within the neighbourhood to the reference point.&lt;br /&gt;
&lt;br /&gt;
For additional insights into neighborhood analysis, visit [https://www.dynamo-em.org//w/index.php?title=Neighborhood_analysis this page.]  &lt;br /&gt;
&lt;br /&gt;
==Data==&lt;br /&gt;
&lt;br /&gt;
We will use data from the initial gold standard alignment derived from five tomograms of immature HIV-1 virus-like particles.&lt;br /&gt;
&lt;br /&gt;
In this course, the data for this walkthrough is in:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/data/DownloadLinkNeighborhoodData/&amp;lt;/tt&amp;gt;&lt;br /&gt;
the tomogram with the data is in the link:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/data/DownloadLinkNeighborhoodData/template.em &amp;lt;/tt&amp;gt;&lt;br /&gt;
the table linked with the data is in the link:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/data/DownloadLinkNeighborhoodData/table.tbl &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===Inspecting data===&lt;br /&gt;
&lt;br /&gt;
First, open a new local terminal and navigate to the directory containing the tutorial dataset and project.&lt;br /&gt;
&lt;br /&gt;
Let&#039;s inspect the contents:&lt;br /&gt;
&lt;br /&gt;
 &amp;gt;&amp;gt; dfile template.em&lt;br /&gt;
    &lt;br /&gt;
    filetype: volume&lt;br /&gt;
    &lt;br /&gt;
    size: 192 x 192 x 192 &lt;br /&gt;
&lt;br /&gt;
 &amp;gt;&amp;gt; dfile table.tbl&lt;br /&gt;
  &lt;br /&gt;
    filetype: table&lt;br /&gt;
    &lt;br /&gt;
    size: 7068  x 35, aligns: 7068, averages: 7068 &lt;br /&gt;
&lt;br /&gt;
These files represent an average as a template and its associated metadata (i.e., table). We will focus on the table data.&lt;br /&gt;
&lt;br /&gt;
To visualize the particles along with their normals:&lt;br /&gt;
&lt;br /&gt;
 tbl = dread(&#039;table.tbl&#039;);&lt;br /&gt;
 figure;&lt;br /&gt;
 h = dpktbl.plots.sketch(tbl,&#039;haxis&#039;,gca());&lt;br /&gt;
 h.zlength.value=100;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
[[File:tbl-positions-normals-vlps.png|centre|thumb|450px| VLPs particle positions and normals.]]&lt;br /&gt;
&lt;br /&gt;
== Prepare (meta)data ==&lt;br /&gt;
&lt;br /&gt;
Let&#039;s select a couple of Virus-Like Particles (VLPs):&lt;br /&gt;
&lt;br /&gt;
 tblT2V2 = tbl(tbl(:,20) == 2 &amp;amp; tbl(:,22) == 2, :);&lt;br /&gt;
 tblT2V5 = tbl(tbl(:,20) == 2 &amp;amp; tbl(:,22) == 5, :);&lt;br /&gt;
 tblT2V3 = tbl(tbl(:,20) == 2 &amp;amp; tbl(:,22) == 3, :);&lt;br /&gt;
&lt;br /&gt;
To visualize:&lt;br /&gt;
&lt;br /&gt;
 figure;&lt;br /&gt;
 &lt;br /&gt;
 subplot(1, 3, 1);&lt;br /&gt;
 dpktbl.plots.sketch(tblT2V5);&lt;br /&gt;
 title(&#039;Ideal&#039;);&lt;br /&gt;
 pbaspect([1 1 1]);&lt;br /&gt;
 &lt;br /&gt;
 subplot(1, 3, 2);&lt;br /&gt;
 dpktbl.plots.sketch(tblT2V2); &lt;br /&gt;
 title(&#039;Slightly flat surface&#039;);&lt;br /&gt;
 pbaspect([1 1 1]); &lt;br /&gt;
 &lt;br /&gt;
 subplot(1, 3, 3);&lt;br /&gt;
 dpktbl.plots.sketch(tblT2V3); &lt;br /&gt;
 title(&#039;1/4 missing, flat top&#039;);&lt;br /&gt;
 pbaspect([1 1 1]); &lt;br /&gt;
&lt;br /&gt;
[[File:selected-vlps.png|centre|thumb|800px|  Selected VLPs. From left to right: ideal, medium, and low quality instances.]]&lt;br /&gt;
&lt;br /&gt;
Indeed, we will analyze three different VLP quality instances.&lt;br /&gt;
&lt;br /&gt;
== Get mean distance to closest neighbor ==&lt;br /&gt;
&lt;br /&gt;
To find the optimal distance threshold, we will use the following function to calculate the mean distance to the closest neighbor:&lt;br /&gt;
&lt;br /&gt;
 function [meanDst, stdDsts] = mean_distance_to_closest_neighbor(pts);&lt;br /&gt;
 numPts = size(pts, 1);&lt;br /&gt;
 minDsts = zeros(numPts, 1);&lt;br /&gt;
 &lt;br /&gt;
 for i = 1:numPts&lt;br /&gt;
    dsts = pdist2(pts(i,:), pts);&lt;br /&gt;
    dsts(i) = Inf;&lt;br /&gt;
    minDsts(i) = min(dsts);&lt;br /&gt;
 end&lt;br /&gt;
 &lt;br /&gt;
 meanDst = mean(minDsts);&lt;br /&gt;
 stdDsts = std(minDsts);&lt;br /&gt;
 fprintf(&#039;Mean distance: %.4f\nStandard deviation: %.4f \n&#039;, meanDst, stdDsts);&lt;br /&gt;
 end&lt;br /&gt;
&lt;br /&gt;
Invoke the function like so: &lt;br /&gt;
&lt;br /&gt;
 [meanDst, stdDsts] =   mean_distance_to_closest_neighbor(tbl(:,24:26)+tbl(:,4:6));&lt;br /&gt;
&lt;br /&gt;
The mean distance to the closest neighbor is around 50-60 pixels.&lt;br /&gt;
 Mean distance: 50.42&lt;br /&gt;
 Standard deviation: 12.23&lt;br /&gt;
&lt;br /&gt;
For a sanity check, you might also measure the lattice directly on the average volume:&lt;br /&gt;
&lt;br /&gt;
 dshow template.em&lt;br /&gt;
&lt;br /&gt;
[[File:average-overplot-hexagonal-lattice-measurements.png|centre|thumb|400px|  Overplot average and hexagonal lattice measurements.]]&lt;br /&gt;
&lt;br /&gt;
== Neighborhood analysis computation ==&lt;br /&gt;
&lt;br /&gt;
Here, we conduct the neighborhood analysis with a distance threshold set as the mean distance plus the standard deviation:&lt;br /&gt;
&lt;br /&gt;
 tblT2V3N = dpktbl.neighborhood.analize(tblT2V3,&#039;distance&#039;,meanDst+stdDsts,&#039;modelColumn&#039;,22);&lt;br /&gt;
 tblT2V2N = dpktbl.neighborhood.analize(tblT2V2,&#039;distance&#039;,meanDst+stdDsts,&#039;modelColumn&#039;,22);&lt;br /&gt;
 tblT2V5N = dpktbl.neighborhood.analize(tblT2V5,&#039;distance&#039;,meanDst+stdDsts,&#039;modelColumn&#039;,22);&lt;br /&gt;
&lt;br /&gt;
Then, we will need the couple table since it is our new representation (i.e., latent space):&lt;br /&gt;
&lt;br /&gt;
 tblT2V3NC = real(tblT2V3N.coupleTable);&lt;br /&gt;
 tblT2V2NC = real(tblT2V2N.coupleTable);&lt;br /&gt;
 tblT2V5NC = real(tblT2V5N.coupleTable);&lt;br /&gt;
&lt;br /&gt;
Now, let&#039;s visualize first-order distance clusters with synchronized viewing:&lt;br /&gt;
&lt;br /&gt;
 datasets = {tblT2V3NC, tblT2V2NC, tblT2V5NC};&lt;br /&gt;
 titles = {&amp;quot;Incomplete + flat surface&amp;quot;, &amp;quot;Slightly flat surface&amp;quot;, &amp;quot;Ideal&amp;quot;};&lt;br /&gt;
 &lt;br /&gt;
 fig = figure;&lt;br /&gt;
 ax = gobjects(1, length(datasets));&lt;br /&gt;
 &lt;br /&gt;
 for i = 1:length(datasets)&lt;br /&gt;
    ax(i) = subplot(1, length(datasets), i, &#039;Parent&#039;, fig);&lt;br /&gt;
    pcshow(datasets{i}(:, 24:26), &#039;Parent&#039;, ax(i));&lt;br /&gt;
    pbaspect(ax(i), [1 1 1]);&lt;br /&gt;
    % Set titles using text, since the title function was not working&lt;br /&gt;
    xl = xlim(ax(i));&lt;br /&gt;
    yl = ylim(ax(i));&lt;br /&gt;
    zl = zlim(ax(i));&lt;br /&gt;
    titlePos = [mean(xl), yl(2), zl(2)];&lt;br /&gt;
    text(ax(i), titlePos(1), titlePos(2), titlePos(3), titles{i}, ...&lt;br /&gt;
        &#039;HorizontalAlignment&#039;, &#039;center&#039;, &#039;Color&#039;, &#039;white&#039;, ...&lt;br /&gt;
        &#039;FontSize&#039;, 14, &#039;FontWeight&#039;, &#039;bold&#039;, &#039;BackgroundColor&#039;, &#039;black&#039;);&lt;br /&gt;
 end&lt;br /&gt;
 &lt;br /&gt;
 link = linkprop(ax, {&#039;CameraUpVector&#039;, &#039;CameraPosition&#039;, &#039;CameraTarget&#039;, &#039;CameraViewAngle&#039;, &#039;XLim&#039;, &#039;YLim&#039;, &#039;ZLim&#039;});&lt;br /&gt;
 setappdata(gcf, &#039;StoreTheLink&#039;, link);&lt;br /&gt;
 &lt;br /&gt;
 for a = ax&lt;br /&gt;
    rotate3d(a, &#039;on&#039;);&lt;br /&gt;
 end&lt;br /&gt;
&lt;br /&gt;
[[File:first-order-distance-clusters-three-different-vlps.png|centre|thumb|800px|   First-order distance clusters obtained vía neighborhood analysis. From left to right: low, medium, and high quality instances.]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
The color, by default, represents the Z-axis. Notice that the better the quality of the VLP, the less sparse each cluster is.&lt;br /&gt;
&lt;br /&gt;
== Local analysis - lattice coherence ==&lt;br /&gt;
&lt;br /&gt;
To quantify lattice coherence, we apply [https://www.youtube.com/watch?v=R2e3Ls9H_fc k-means clustering] and calculate the Euclidean norms for each centroid. The standard deviation of these norms provides a measure of cluster sparsity and hence, lattice coherence.&lt;br /&gt;
&lt;br /&gt;
We encapsulate this process in a function:&lt;br /&gt;
&lt;br /&gt;
 function [idx, cc_final, results, results_std] = perform_lattice_analysis(data, symm)&lt;br /&gt;
    [idx, cc_final] = kmeans(data, symm);&lt;br /&gt;
    results = vecnorm(cc_final, 2, 2); &lt;br /&gt;
    results_std = std(results); &lt;br /&gt;
 end&lt;br /&gt;
&lt;br /&gt;
Then, execute the analysis:&lt;br /&gt;
&lt;br /&gt;
 symm = 6; &lt;br /&gt;
 [idx_ideal, cc_ideal_final, results_ideal, std_ideal] = perform_lattice_analysis(tblT2V5NC(:,24:26),symm);&lt;br /&gt;
 [idx_slightly_flat, cc_sf_final, results_sf, std_sf] = perform_lattice_analysis(tblT2V2NC(:,24:26),symm);&lt;br /&gt;
 [idx_incomplete_and_flat, cc_implt_final, results_implt, std_implt] = perform_lattice_analysis(tblT2V3NC(:,24:26),symm);&lt;br /&gt;
&lt;br /&gt;
Display results neatly in a table&lt;br /&gt;
&lt;br /&gt;
 resultsTable = table(std_ideal, std_sf, std_implt, &#039;VariableNames&#039;, {&#039;Ideal&#039;, &#039;SlightlyFlat&#039;, &#039;IncompleteFlat&#039;}, &#039;RowNames&#039;, {&#039;StandardDeviation&#039;});&lt;br /&gt;
 &lt;br /&gt;
 disp(resultsTable);&lt;br /&gt;
&lt;br /&gt;
This will output:&lt;br /&gt;
        &lt;br /&gt;
                               Ideal             SlightlyFlat        IncompleteFlat                       &lt;br /&gt;
                         __________________    _________________    _________________&lt;br /&gt;
                           &lt;br /&gt;
    Standard deviation    0.0933777687916592    0.321031652546273    0.574732108201886&lt;br /&gt;
&lt;br /&gt;
As demonstrated, the qualitative degree of imperfection correlates with our lattice coherence measurements.&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Walkthrough_for_GUI-based_template_matching_(Tsinghua_Spring_School_2025)&amp;diff=5595</id>
		<title>Walkthrough for GUI-based template matching (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Walkthrough_for_GUI-based_template_matching_(Tsinghua_Spring_School_2025)&amp;diff=5595"/>
		<updated>2025-03-01T08:28:31Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Data set */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:Walkthroughs]]&lt;br /&gt;
&lt;br /&gt;
== Template matching ==&lt;br /&gt;
&lt;br /&gt;
In this technique, a template representing a molecule of interest is systematically cross-correlated against a tomogram, producing a &#039;&#039;cross-correlation map&#039;&#039; of the tomogram. Each pixel in this map represents a score assigned the corresponding pixel in the tomogram map. This score measures the similarity of the neighbourhood of the tomogram pixel to the used template.&lt;br /&gt;
This similarity is measured exclusively inside a mask.&lt;br /&gt;
&lt;br /&gt;
Model-aware template matching is meant as an extension of the normal template matching algorithm in Dynamo. The main change introduced in model-aware template matching is that the tomogram is split in chunks that are meant to be meaningful from the point of view of the tomogram models. This allows for the reduction of needed computation by restricting the angular combinations of the template to be scanned. &lt;br /&gt;
&lt;br /&gt;
In this walkthrough, the methods to manually manipulate these chunk is introduced.&lt;br /&gt;
&lt;br /&gt;
Walkthroughs on [[Walkthrough for template matching | basic TM]] in Dynamo and [[Walkthrough for model-aware template matching | model-aware TM]] are also available.&lt;br /&gt;
&lt;br /&gt;
== Data set ==&lt;br /&gt;
&lt;br /&gt;
In this course, the data for this walkthrough is in:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/data/DownloadLinkTemplateMCP/&amp;lt;/tt&amp;gt;&lt;br /&gt;
and the tomogram with the data is in the link:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/data/DownloadLinkTemplateMCP/fullReconstructionWBPCTFDW.mrc &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Getting the data ===&lt;br /&gt;
Currently the data necessary to tun this walkthrough can be downloaded using the link:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;!--https://drive.google.com/file/d/1ME2r6cDw6_sJVtFPTFTgOVBWIuQn44Wl/view?usp=drive_link--&amp;gt;&lt;br /&gt;
{{Template:DownloadLinkTemplateMCP}}&lt;br /&gt;
&lt;br /&gt;
It consists in: a tomogram fullReconstructionWBPCTFDW.mrc, a template templateMCP.mrc, a mask maskMCP.mrc and a fourier mask fmaskMCP.mrc.&lt;br /&gt;
&lt;br /&gt;
=== Tomogram description ===&lt;br /&gt;
&lt;br /&gt;
The tomogram contains Bdellovibrio bacteriovorus acquired by fast-incremental method. The tomogram has been generated using the tilt series from EMPIAR dataset entry 10226. The pixel size is 2.743 Å. The tomogram has been generated around an area of the bacteria presenting methyl-accepting chemotaxis protein (MCP) arrays. The template an average of MCP array.&lt;br /&gt;
&lt;br /&gt;
=== Acknowledgements ===&lt;br /&gt;
&lt;br /&gt;
The tomogram has been generated using the tilt series from EMPIAR dataset entry 10226 described in the paper &amp;quot;Chreifi, G., Chen, S., Metskas, L. A., Kaplan, M., &amp;amp; Jensen, G. J. (2019b). Rapid tilt-series acquisition for electron cryotomography. Journal of Structural Biology, 205(2), 163–169. https://doi.org/10.1016/j.jsb.2018.12.008&amp;quot;. The alignment and reconstruction was done using the [[Walkthrough on GUI based tilt series alignment | Dynamo AWF procedure]] as detailed in &amp;quot;Coray, R., Navarro, P., Scaramuzza, S., Stahlberg, H., &amp;amp; Castaño-Díez, D. (2024). Automated fiducial-based alignment of cryo-electron tomography tilt series in Dynamo. Structure, 32(10), 1808-1819.e4. https://doi.org/10.1016/j.str.2024.07.003&amp;quot;. The template has been generated by STA as described in the same paper.&lt;br /&gt;
&lt;br /&gt;
=== Visualizing the tomogram ===&lt;br /&gt;
&lt;br /&gt;
The tomogram can be found in the path with:&amp;lt;br&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tomofile = &#039;fullReconstructionWBPCTFDW.mrc&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We can get a first glance on how the tomogram looks like:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dshow(tomofile);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The tomogram should appear like the following figure. Note the MCP arrays on the inner membrane of the bacteria.&lt;br /&gt;
[[ File:tomogram_dshow_TM_MCP.png |thumb|center|500px| &amp;lt;tt&amp;gt;dshow&amp;lt;/tt&amp;gt; on the tomogram, View along &#039;&#039;z&#039;&#039; ]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
==== Estimation of the missing wedge ====&lt;br /&gt;
&lt;br /&gt;
We can quickly check the extent of the missing wedge in the tomogram. We extract a sample of the tomogram:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;fragment = dynamo_read_subtomogram(tomofile, &#039;r&#039;,128,&#039;c&#039;,[450,450,450]); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and plot a map of the distribution of the Fourier coefficients:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dynamo_wedge_estimate(fragment,&#039;show&#039;,1); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&amp;lt;br&amp;gt;&lt;br /&gt;
The wedge estimation will show a bi-directional tilt-series acquisition by fast-incremental from around -60 to 60 degrees. &lt;br /&gt;
[[ File:missing_wedge_MCP.png |thumb|center|500px| Estimation of the missing wedge]]&lt;br /&gt;
&lt;br /&gt;
=== Inspecting the template and mask ===&lt;br /&gt;
&lt;br /&gt;
In this walkthrough, a template and its mask are already provided. The template was generated by averaging ~50000 particles aligned with Dynamo. &lt;br /&gt;
&lt;br /&gt;
The template can be loaded by:&lt;br /&gt;
 &amp;lt;tt&amp;gt;av = dread(&#039;templateMCP.mrc&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
And the mask can be loaded by:&lt;br /&gt;
 &amp;lt;tt&amp;gt;mask = dread(&#039;maskMCP.mrc&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The template and mask positioning can be inspected with:&lt;br /&gt;
 &amp;lt;tt&amp;gt;dshow(av+mask); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:template_mask_MCP.png |thumb|center|500px| Template with its mask, View along &#039;&#039;Z&#039;&#039; ]]&lt;br /&gt;
&lt;br /&gt;
[[ File:template_mask_MCP_Y.png |thumb|center|500px| Template with its mask, View along &#039;&#039;Y&#039;&#039; ]]&lt;br /&gt;
&lt;br /&gt;
Note the membrane bilayer on which the MCP array is present is at the bottom of the template. The bacterial cytoplasm would be at the top of the template.&lt;br /&gt;
&lt;br /&gt;
== Description of basic chunk manipulations ==&lt;br /&gt;
&lt;br /&gt;
The GUI for chunk manipulation is &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; with a tomogram as input. It has a tab called Template Matching in the top bar of the GUI.&lt;br /&gt;
It is through this tab that general attributes of chunks distributions and TM processes can be manipulated.&lt;br /&gt;
Additionally, each chunk has its own attributes (such as position and size) that can be manipulated after they are created.&lt;br /&gt;
&lt;br /&gt;
[[ File:general_GUI_MCP.png |thumb|center|500px| &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; and template match tab.]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
=== Chunk creation ===&lt;br /&gt;
&lt;br /&gt;
Create a chunk by pointing the cursor on the tomogram and pressing the &amp;quot;B&amp;quot; key.&lt;br /&gt;
[[ File:newchunk_GUI_MCP.png |thumb|center|500px| Newly created chunk.]]&lt;br /&gt;
&lt;br /&gt;
Multiple chunks can be created by pressing the &amp;quot;B&amp;quot; key again. A chunk can be deleted by right-clicking it and selecting &amp;quot;Delete box&amp;quot;. This will also update the number of existing chunks noted in the Template Matching tab.&lt;br /&gt;
&lt;br /&gt;
[[ File:delete_chunk_MCP.png |thumb|center|500px| Delete options for chunks.]]&lt;br /&gt;
&lt;br /&gt;
Each created chunk is represented with a colored box indicating its position, size and orientation in the tomogram. The coordinate system defined by each chunk is noted by the colored axis. The X axis is magenta, the Y axis is green and the Z axis is black.&lt;br /&gt;
[[ File:chunk_axis_MCP.png |thumb|center|500px| Close-up of a new chunk.]]&lt;br /&gt;
&lt;br /&gt;
=== Basic chunk manipulations ===&lt;br /&gt;
&lt;br /&gt;
Resize a chunk by clicking an edge and dragging it with the cursor. The figure shows the chunk being increased in size along all directions.&lt;br /&gt;
[[ File:chunk_resizing_MCP.png |thumb|center|500px| Chunk during resizing operation.]]&lt;br /&gt;
&lt;br /&gt;
Move a chunk by shift-clicking an edge and dragging it with the cursor.  The figure shows the chunk being moved along its Z direction.&lt;br /&gt;
[[ File:chunk_moving_MCP.png |thumb|center|500px| Chunk during moving operation.]]&lt;br /&gt;
&lt;br /&gt;
Rotate a chunk by alt-clicking an edge and dragging it with the cursor.&lt;br /&gt;
[[ File:chunk_rotating_method1_MCP.png |thumb|center|500px| Chunk during change of chunk orientation by alt-click.]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
This can also be done by right-clicking the chunk and then selection the option &amp;quot;Change chunk orientation (into an oblique view)&amp;quot;. This will spawn a interactable lever that can rotate the chunk in any direction.&lt;br /&gt;
[[ File:chunk_rotating_method2_before_MCP.png |thumb|center|500px| Selection of chunk orientation by lever.]]&lt;br /&gt;
[[ File:chunk_rotating_method2_after_MCP.png |thumb|center|500px| Chunk during change of chunk orientation by lever.]]&lt;br /&gt;
&lt;br /&gt;
=== Chunk inspection ===&lt;br /&gt;
&lt;br /&gt;
The tomogram data included in a chunk can be inspected by right-clicking the chunk and selecting &amp;quot;show chunk (in tomoshow)&amp;quot;.&lt;br /&gt;
&lt;br /&gt;
The data can also be inspected through a chunk-specific template match process that will be described in the following sections&lt;br /&gt;
&lt;br /&gt;
=== Chunk cone setting ===&lt;br /&gt;
The chunk cone orientation is the direction around which a template would be oriented during template match. It can be seen as the most probable direction that copies of the template present in the volume defined by the chunk. The graphical object allowing changes in the cone orientation is accessible by right-clicking a chunk as in the next figure.&lt;br /&gt;
&lt;br /&gt;
[[ File:cone_rotating_before_MCP.png |thumb|center|500px| Selection of cone orientation.]]&lt;br /&gt;
&lt;br /&gt;
The graphical object has some functionalities that can be accessed by right-clicking it as in the next figure.&lt;br /&gt;
&lt;br /&gt;
[[ File:cone_rotating_options_MCP.png |thumb|center|500px| Option for cone orientation.]]&lt;br /&gt;
&lt;br /&gt;
The cone orientation is changed by dragging the lever as in the following figure. Once the cone orientation is satisfactory, the lever graphical object should be removed by pressing the &amp;quot;Delete rotation frame&amp;quot; option shown in the previous figure.&lt;br /&gt;
&lt;br /&gt;
[[ File:cone_rotating_after_MCP.png |thumb|center|500px| Change of cone orientation.]]&lt;br /&gt;
&lt;br /&gt;
=== Per-chunk TM ===&lt;br /&gt;
&lt;br /&gt;
As mentioned before, it is possible to run a TM project on a chunk directly from the GUI. This can be done by right-click the chunk and select &amp;quot;Launch TM process for this chunk&amp;quot;. However, more parameters are necessary than only the chunk positions, size, orientation and cone orientation. These parameter can be accessed by selecting the &amp;quot;Template Matching&amp;quot; option on the top bar of the GUI and clicking &amp;quot;Settings for template match process&amp;quot; as in the next figure.&lt;br /&gt;
&lt;br /&gt;
[[ File:access_TM_setting_GUI.png |thumb|center|500px| How to access the TM parameters GUI.]]&lt;br /&gt;
&lt;br /&gt;
The TM parameter GUI is initially blank and need to be filled to be able to run a per-chunk TM. The main advantage of per-chunk TM is that it can be done directly from the GUI and on any type of chunk, including oblique chunks.&lt;br /&gt;
[[ File:blank_TM_setting_GUI.png |thumb|center|500px| Blank TM parameter GUI.]]&lt;br /&gt;
&lt;br /&gt;
It should be noted that the area of the chunk that will generate valid cross-correlation scores is reduced by half of the size of the template in all directions.&lt;br /&gt;
&lt;br /&gt;
== Relationship between GUI models and tessellations ==&lt;br /&gt;
&lt;br /&gt;
The GUI allows the creation and manipulation of tessellation with the tool mentioned in the previous section. However, these tessellations will be saved or loaded from .omd files. This can be done from the &amp;quot;Template Matching&amp;quot; tab in the GUI with the options &amp;quot;Save chunk distribution&amp;quot; and &amp;quot;Load chunk distribution from .omd file&amp;quot;.&amp;lt;br&amp;gt;&lt;br /&gt;
However, TM processes require a tessellation in either table or dStar format as described in the tutorial [[Walkthrough for model-aware template matching | on model-aware template matching]]. This difference in format exists because .omd file tessellations are simplified so that their representations in the GUI would not be cumbersome. As such two converting functions are available in the Dynamo TM package:&lt;br /&gt;
&lt;br /&gt;
The function &amp;lt;tt&amp;gt;dpktomo.match.modelling.createTesselationFromGUIomd&amp;lt;/tt&amp;gt; converts an .omd tessellation into a dStar tessellation ready for &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt;.&amp;lt;br&amp;gt;&lt;br /&gt;
The function &amp;lt;tt&amp;gt;dpktomo.match.modelling.saveTesselationAsGUIomd&amp;lt;/tt&amp;gt; converts a dStar tessellation into an object that can be saved as a .omd file with &amp;lt;tt&amp;gt;dwrite&amp;lt;/tt&amp;gt;.&amp;lt;br&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Walkthrough on chunk manipulation ==&lt;br /&gt;
&lt;br /&gt;
In this walkthrough the basic function described before will be used to create a tesselation and run a model-aware TM project. Additionally, on per-chunk TM will be tested with different cones.&lt;br /&gt;
&lt;br /&gt;
=== Chunk setup ===&lt;br /&gt;
&lt;br /&gt;
First, if not done already, open the &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; GUI with the tomogram.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmslice(&#039;fullReconstructionWBPCTFDW.mrc&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Then, create a single chunk in the top area of the bacteria presenting an MCP array. For now, do not use oblique chunks.&amp;lt;br&amp;gt;&lt;br /&gt;
Ensure the chunk is thick enough to include the MCP array area even considering the template size.&amp;lt;br&amp;gt;&lt;br /&gt;
Rescale and shift the chunk until a configuration similar to the following figure is reached. The cone orientation will be left as the default one for now (that is, collinear to the Z axis of the tomogram).&lt;br /&gt;
[[ File:first_chunk_position_MCP.png |thumb|center|500px| Position of first chunk.]]&lt;br /&gt;
&lt;br /&gt;
=== Global TM ===&lt;br /&gt;
&lt;br /&gt;
In this first experiment, an per-chunk TM with isotropic angular scanning will be used.&amp;lt;br&amp;gt;&lt;br /&gt;
Howver, first it is necessary to set up the global TM parameters from the GUI. Update the GUI as in the following figure.&lt;br /&gt;
[[ File:settings_TM_GUI_360_MCP.png |thumb|center|500px| TM parameters for isotropic angular scans.]]&lt;br /&gt;
&lt;br /&gt;
This setup will allow the GUI to access template, mask and missing wedge mask. The scanning ranges are 360 degrees to ensure isotropic angular scans. The angular scanning steps are set to 10 to allow fine enough sampling to achieve good cross-correlation maps. The binning is set to 2 to speed up calculations.&amp;lt;br&amp;gt;&lt;br /&gt;
It is preferable to compute using GPUs for computing speed. Only one GPU is required. If more than one GPU are accessible by MATLAB, their corresponding id numbers can be checked with the MATLAB command:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;gpuDeviceTable&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The per-chunk TM can then by launched. Right-click the chunk and select &amp;quot;Launch TM process for this chunk&amp;quot;. This will automatically create a folder called &amp;quot;chunkTM.CTM&amp;quot; containing the oblique chunk and its resulting TM process.&amp;lt;br&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Finally, inspect the resulting cross-correlation map. In the created folder this can be done by:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dshow(&#039;process.TM/cc.mrc&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:CC_first_chunk_360_MCP.png |thumb|center|500px| Resulting CC map.]]&lt;br /&gt;
&lt;br /&gt;
=== Cone-restricted TM ===&lt;br /&gt;
&lt;br /&gt;
One of the main advantages of tesselation is that each chunk can limit the number of scanning angles by exploiting the know general orientation of the particle of interest present in the chunk area. This information is encoded in the cone orientation of each chunk. In this case, we know that the chunk is positioned on the top of the bacteria presenting the MCP arrays. This means that the MCP template is expected to identify the MCP array when it is oriented towards the bottom of the chunk. As such, updated the chunk orientation appropriately like in the following figure.&lt;br /&gt;
[[ File:first_chunk_correct_cone_MCP.png |thumb|center|500px| Position of first chunk with proper cone orientation.]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
The general TM parameters must be updated as well. In particular the cone range should be reduced from 360 degrees to 60 degrees.&lt;br /&gt;
&lt;br /&gt;
[[ File:settings_TM_GUI_60_MCP.png |thumb|center|500px| TM parameters for cone-limited angular scans.]]&lt;br /&gt;
&lt;br /&gt;
The per-chunk TM can then by launched and inspect the resulting cross-correlation map. In the created folder this can be done as before:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dshow(&#039;process.TM/cc.mrc&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The map will look similar to the previous per-chunk TM, but the computing time will be reduced by a factor of 10.&lt;br /&gt;
&lt;br /&gt;
[[ File:CC_first_chunk_correct_cone_MCP.png |thumb|center|500px| Resulting CC map with limited angular cone.]]&lt;br /&gt;
&lt;br /&gt;
It must be noted that cone orientation can be used to test if sets of template orientations are not present. For example, we it is not expected that the MCP array on top of the bacteria will be horizontal. Update the chunk orientation like in the following figure. &lt;br /&gt;
[[ File:first_chunk_wrong_cone_MCP.png |thumb|center|500px| Position of first chunk with incorrect cone orientation.]]&lt;br /&gt;
&lt;br /&gt;
The per-chunk TM can then by launched and inspect the resulting cross-correlation map. The cross-correlation map shows a lack of matches for the scanned orientations, as expected.&lt;br /&gt;
[[ File:CC_first_chunk_wrong_cone_MCP.png |thumb|center|500px| Resulting CC map with limited angular cone oriented incorrectly.]]&lt;br /&gt;
&lt;br /&gt;
== Walkthrough on tessellation generation ==&lt;br /&gt;
&lt;br /&gt;
Tessellation are sets of chunks an cone orientations designed to be used by &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt; for advantageous TM. Here, the process to create and uses tesselations by GUI is shown.&lt;br /&gt;
&lt;br /&gt;
=== Add more chunks ===&lt;br /&gt;
&lt;br /&gt;
Firstly, add two new chunks with their cone orientations with the GUI as in the following figure. In total three non-oblique chunks are created.&lt;br /&gt;
&lt;br /&gt;
[[ File:full_tesselation_MCP.png |thumb|center|500px| Positions of multiple chunks with their cones.]]&lt;br /&gt;
&lt;br /&gt;
Now, save the tesselation to disk by pressing the &amp;quot;Save chunk distribution&amp;quot; in the &amp;quot;Template Match&amp;quot; tab. This will create a file &amp;lt;tt&amp;gt;tesselation.omd&amp;lt;/tt&amp;gt; to disk.&lt;br /&gt;
&lt;br /&gt;
=== Generate a tesselation ===&lt;br /&gt;
&lt;br /&gt;
As mentioned before, a .omd file need ot be converted to a star object to be an accepted input of &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt;.&amp;lt;br&amp;gt;&lt;br /&gt;
The conversion can be done by:&lt;br /&gt;
 &amp;lt;tt&amp;gt;star = dpktomo.match.modelling.createTesselationFromGUIomd(&#039;tesselation.omd&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The values encoded in the star object cen be inspected with:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;star.tbl&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The properties will look similar to the following:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
    index     tdrot      tilt       narot      posX      posY      posZ     sizeX     sizeY     sizeZ     coneRange    inplaneRange&lt;br /&gt;
    _____    _______    _______    _______    ______    ______    ______    ______    ______    ______    _________    ____________&lt;br /&gt;
&lt;br /&gt;
      1      -156.91    -160.25     156.91    702.55    743.66    564.27    515.44     397.2     270.9       60            360     &lt;br /&gt;
      2       147.92    -97.808    -147.92    912.01    455.29    326.33    414.75    387.03    242.75       60            360     &lt;br /&gt;
      3      -51.289    -78.113     51.289     486.3       883    322.65    455.65    549.42    282.14       60            360&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Run model-aware TM with manual tessellation ===&lt;br /&gt;
&lt;br /&gt;
Finally, a full model-aware TM process can be run.&lt;br /&gt;
 &amp;lt;tt&amp;gt;pts_GPU = dynamo_match(&#039;fullReconstructionWBPCTFDW.mrc&#039;,&#039;templateMCP.mrc&#039;,&#039;mask&#039;,&#039;maskMCP.mrc&#039;,...&lt;br /&gt;
 &#039;outputFolder&#039;,&#039;MCP_tesselation&#039;,...&lt;br /&gt;
 &#039;ytilt&#039;,[-60,60],&#039;is&#039;,10,&#039;cs&#039;,10,&#039;bin&#039;,2,&#039;mw&#039;,10,&#039;gpus&#039;,1,&#039;tilingTable&#039;,star);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The resulting TM object pts_GPU can be then used as in the tutorials [[Walkthrough for template matching | on basic TM]] and [[Walkthrough for model-aware template matching | model-aware TM]].&lt;br /&gt;
&lt;br /&gt;
== Additional functionalities ==&lt;br /&gt;
&lt;br /&gt;
Two other functionalities will be introduced in this section. First, an per-chunk TM with an oblique chunk and then a conversion of &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt; tesselation into an .omd file ready to be loaded in the GUI.&lt;br /&gt;
&lt;br /&gt;
=== Oblique chunks ===&lt;br /&gt;
&lt;br /&gt;
Oblique chunks are currently not supported by &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt;. However, per-chunk TM can be done on oblique chunks.&lt;br /&gt;
First, create an oblique chunk with appropriate cone orientation like in the following figure.&lt;br /&gt;
&lt;br /&gt;
[[ File:oblique_chunk_position_MCP.png |thumb|center|500px| Oblique chunk with correct cone.]]&lt;br /&gt;
&lt;br /&gt;
Per-chunk TM can then by run as in the previous sections.&lt;br /&gt;
&lt;br /&gt;
[[ File:CC_oblique_chunk_correct_cone_MCP.png |thumb|center|500px| Resulting CC map with limited angular cone on oblique chunk.]]&lt;br /&gt;
&lt;br /&gt;
=== Manipulation a tessellation with the GUI ===&lt;br /&gt;
&lt;br /&gt;
The GUI can save and load .omd files, allowing of their manipulation and as such, the manipulations of tesselations.&amp;lt;br&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
If a tesselation is available as a star object, it can be converted in a .omd object with:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;newomd = dpktomo.match.modelling.saveTesselationAsGUIomd(star);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Which can be save to disk as usual:&lt;br /&gt;
 &amp;lt;tt&amp;gt;dwrite(newomd,&#039;tesselation_back.omd&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The new .omd file can then be loaded by the GUI.&amp;lt;br&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Note that tesselations can be generated automatically with the functions: &amp;lt;br&amp;gt;&lt;br /&gt;
&amp;lt;tt&amp;gt;dpktomo.match.modelling.estimateTesselationForFilament&amp;lt;/tt&amp;gt;&amp;lt;br&amp;gt; &lt;br /&gt;
&amp;lt;tt&amp;gt;dpktomo.match.modelling.estimateTesselationForMembrane&amp;lt;/tt&amp;gt;&amp;lt;br&amp;gt; &lt;br /&gt;
&amp;lt;tt&amp;gt;dpktomo.match.modelling.estimateTesselationForDipole&amp;lt;/tt&amp;gt;&amp;lt;br&amp;gt; &lt;br /&gt;
and the creator of tesselation star objects:&lt;br /&gt;
&amp;lt;tt&amp;gt;dpktomo.match.modelling.setUpTilingTable&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
More information on this can be found in the tutorial [[Walkthrough for model-aware template matching | on model-aware template matching]].&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
=== Programmatic GUI customization for template matching ===&lt;br /&gt;
&lt;br /&gt;
It is possible to add custom functionalities to the GUI as described in the [[Programmatic GUI customization for template matching | corresponding tutorial]].&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Walkthrough_for_template_matching_(Tsinghua_Spring_School_2025)&amp;diff=5594</id>
		<title>Walkthrough for template matching (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Walkthrough_for_template_matching_(Tsinghua_Spring_School_2025)&amp;diff=5594"/>
		<updated>2025-03-01T08:26:57Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Data set */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:WalkthroughsSpecific]]&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;Dynamo&#039;&#039; includes a set of tools for location of particles inside tomograms. The most simple one is &#039;&#039;template matching&#039;&#039;.&lt;br /&gt;
&lt;br /&gt;
== Template matching ==&lt;br /&gt;
In this technique, a template representing a molecule of interest is systematically cross-correlated against a tomogram, producing a &#039;&#039;cross-correlation map&#039;&#039; of the tomogram. Each pixel in this map represents a score assigned the corresponding pixel in the tomogram map. This score measures the similarity of the neighbourhood of the tomogram pixel to the used template.&lt;br /&gt;
This similarity is measured exclusively inside a mask.&lt;br /&gt;
&lt;br /&gt;
==Data set ==&lt;br /&gt;
&lt;br /&gt;
In this course, the data for this walkthrough is in:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/data/DownloadLinkTemplateMatchingBasic/&amp;lt;/tt&amp;gt;&lt;br /&gt;
and the tomogram with the data is in the link:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/data/DownloadLinkTemplateMatchingBasic/t20s.mrc &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Tomogram description ===&lt;br /&gt;
&lt;br /&gt;
The tomogram contains a buffer with T20S proteasome on a holey carbon grid collected on a Krios + K2. Original pixelsize was 1.76 angstroms. The tomogram provided here has bin binned twice (yielding thus 7.04 ang), defocus is 4.4 microns, no CTF correction, no energy filter.&lt;br /&gt;
&lt;br /&gt;
=== Acknowledgements ===&lt;br /&gt;
The tomogram has been kindly provided by Alex Noble, from the New York Structural Biology Center. Data collection was performed using Leginon and Appion-Protomo at the Simons Electron Microscopy Center and National Resource for Automated Molecular Microscopy located at the New York Structural Biology Center, supported by grants from the Simons Foundation (349247), NYSTAR, and the NIH National Institute of General Medical Sciences (GM103310) with additional support from Agouron Institute [Grant Number: F00316].&lt;br /&gt;
&lt;br /&gt;
=== Getting the tomogram ===&lt;br /&gt;
You should have already a local version of the data. Therefore, navigate to the directory where you just created the tutorial dataset and project.&lt;br /&gt;
&lt;br /&gt;
=== Visualizing the tomogram ===&lt;br /&gt;
&lt;br /&gt;
We can get a first glance on how the tomogram looks like:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmshow -otf t20s.mrc &amp;lt;/tt&amp;gt; &lt;br /&gt;
&lt;br /&gt;
to use the &#039;&#039;on-the-fly&#039;&#039; access to the slice shown at each given moment, or &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;v = dread(&#039;t20s.mrc&#039;);dtmshow(v);&amp;lt;/tt&amp;gt; &lt;br /&gt;
&lt;br /&gt;
to preload the full tomogram into a memory variable (arbitrarily called &amp;lt;tt&amp;gt;v&amp;lt;/tt&amp;gt;). In either option, you will see, the proteasomes are densely packed in an layer. The layer is slightly oblique, what can be seen browsing through &#039;&#039;z&#039;&#039; or &#039;&#039;y&#039;&#039;. &lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingTomoshowZ.png |thumb|center|500px| &amp;lt;tt&amp;gt;dtmshow&amp;lt;/tt&amp;gt; on the pt20s tomogram, View along &#039;&#039;z&#039;&#039; ]]&lt;br /&gt;
&lt;br /&gt;
Navigating on-the-fly you&#039;ll see that transitions in &#039;&#039;y&#039;&#039; are slower than transitions in &#039;&#039;z&#039;&#039;, because all the pixels of the same slice are stored sequentially in the disk. &lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingTomoshowY.png |thumb|center|500px| &amp;lt;tt&amp;gt;dtmshow&amp;lt;/tt&amp;gt; on the pt20s tomogram, View along &#039;&#039;y&#039;&#039; ]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
==== Estimation of the missing wedge ====&lt;br /&gt;
&lt;br /&gt;
We can quickly check the extent of the missing wedge in the tomogram. We extract a sample of the tomogram:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;fragment = dynamo_read_subtomogram(&#039;t20s.mrc&#039;, &#039;r&#039;,64,&#039;c&#039;,[450,450,100]); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and plot a map of the distribution of the Fourier coefficients:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dynamo_wedge_estimate(fragment,&#039;show&#039;,1); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingWedgeEstimation.png |thumb|center|500px| Estimation of the missing wedge&#039; ]]&lt;br /&gt;
&lt;br /&gt;
== Creating a template ==&lt;br /&gt;
&lt;br /&gt;
There are different strategies to create the first template. In the case where the general shape of each protein is roughly recognisable by eye, it is not difficult to just crop and align manually some of the particles. When this is not possible, you have the option of using a density map that mimics the general topology of your protein.&lt;br /&gt;
&lt;br /&gt;
=== Through manual alignment ===&lt;br /&gt;
&lt;br /&gt;
We will use a model inside [[Dtmslice | &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt;]] to pick a set of ~10 particles. We will then crop them, and align them manually using &amp;lt;tt&amp;gt;dgallery&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
====Manual selection of some particles ====&lt;br /&gt;
&lt;br /&gt;
We use for this our tool &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt;. As the tomogram is provided is fairly small you can probably just open it without any further binning.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmslice t20s.mrc -c ct20s&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingTomosliceGeneral.png |thumb|center|500px| &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; on tomogram ]]&lt;br /&gt;
&lt;br /&gt;
Use the &amp;lt;tt&amp;gt;model pool&amp;lt;/tt&amp;gt; menu to add a new model of type &amp;lt;tt&amp;gt;General&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingTomosliceModel.png |thumb|center|500px| Opening a model ]]&lt;br /&gt;
&lt;br /&gt;
Try to pick particles on different orientations, both in top and side views.  Particles are picked with the key &amp;lt;tt&amp;gt;C&amp;lt;/tt&amp;gt;, use &amp;lt;tt&amp;gt;backspace&amp;lt;/tt&amp;gt; to clear the latest selection.&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingTomoslicePick.png |thumb|center|500px| Pick particles with the &amp;lt;tt&amp;gt;C&amp;lt;/tt&amp;gt; key ]]&lt;br /&gt;
&lt;br /&gt;
You can move the slice with the &#039;&#039;z&#039;&#039; slidebar in the control panel, or dragging it while the mouse button is pressed. Top views are more abundant below the crowded accumulation of side views in the central slice.&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingTomoslicePickTop.png |thumb|center|500px| Use the wheel to go up and down in the tomogram to locate top views ]]&lt;br /&gt;
&lt;br /&gt;
When you have clicked around ten, we will prepare to crop them out of the tomogram. For this, we first need to get an approximative idea of how big should be  the box. With the keys [1] and [2] you can place anchor points in the scene. Auxiliary click in the bar between them shows the distance (in pixels of the unbinned tomogram). In view of the measured distance of around 32, we will use a cropping box  size of 48 pixels, in order to ensure that the particles will comfortably fit inside the boxes, as our clicks will not be very precise. &lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingMeasure.png |thumb|center|500px| Measure distances with the [1] and [2] anchors  ]]&lt;br /&gt;
&lt;br /&gt;
Now we can open the &amp;lt;tt&amp;gt;dtcrop&amp;lt;/tt&amp;gt; utility for this model, by visiting the &#039;&#039;Active model&#039;&#039; menu.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingMenuForDtcrop.png |thumb|center|500px | invoking the &amp;lt;tt&amp;gt;dtcrop&amp;lt;/tt&amp;gt; GUI for the active model. ]]&lt;br /&gt;
&lt;br /&gt;
In the GUI that pops up we can fix the sidelength to the value 48. &lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingDtcrop.png |thumb|center|500px  | &amp;lt;tt&amp;gt;dtcrop&amp;lt;/tt&amp;gt; GUI ]]&lt;br /&gt;
&lt;br /&gt;
After completion of the cropping process, you will get a [[data folder]] called  &amp;lt;tt&amp;gt;t20s_Particles.Data&amp;lt;/tt&amp;gt;, which will also contain a [[table]] file called &amp;lt;tt&amp;gt;t20s_Particles.Data/crop.tbl&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
====Manual alignment of some particles ====&lt;br /&gt;
&lt;br /&gt;
Now we want to align the particles. We open them inside the &amp;lt;tt&amp;gt;dgallery&amp;lt;/tt&amp;gt; browser:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dgallery -d t20s_Particles.Data -t t20s_Particles.Data/crop.tbl &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This GUI has several functionalities. We will focus in using it to quickly get an alignment of the particles.  For this, we first load the particles expressed in the table into the internal memory of the &amp;lt;tt&amp;gt;gallery&amp;lt;/tt&amp;gt; by clicking into &#039;&#039;Load&#039;&#039;.&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingGalleryLoad.png |thumb|center|500px | Preload all the particles into memory ]]&lt;br /&gt;
&lt;br /&gt;
This seems not to have any effect in the depiction: you need to fix the range of the depicted particles moving the slider bar. When you do so, each particle will appear in the scene as  a single red box.&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingGalleryShowAll.png |thumb|center|500px  | Adjust the scene to show all the particles ]]&lt;br /&gt;
&lt;br /&gt;
You can play with different settings for viewing, like the direction (&#039;&#039;x&#039;&#039;, &#039;&#039;y&#039;&#039; or &#039;&#039;z&#039;&#039;)&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingControlViewing.png |thumb|center|500px| viewing direction controls  ]]&lt;br /&gt;
&lt;br /&gt;
or the number of slices that are projected into the depicted image for each particle.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingControlThickness.png |thumb|center|500px | Thickness controls  ]]&lt;br /&gt;
&lt;br /&gt;
Then, you go through each particle and indicate a point that you considere that could lay in the central axis of the particle by clicking on &amp;lt;tt&amp;gt;[N]&amp;lt;/tt&amp;gt;. The particle will rotate on screen to match this direction.  The center of the particle can also be set by clicking on &amp;lt;tt&amp;gt;[C]&amp;lt;/tt&amp;gt;. In this case, the particle will not rotate, but will shift to put its center on the spot where the click was operated.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingClickNorth.png |thumb|center|500px| Select the north direction with &amp;lt;tt&amp;gt;N&amp;lt;/tt&amp;gt;  ]]&lt;br /&gt;
&lt;br /&gt;
Top views viewed along &#039;&#039;z&#039;&#039; should not be changed with the &amp;lt;tt&amp;gt;N&amp;lt;/tt&amp;gt; click, only with the &amp;lt;tt&amp;gt;C&amp;lt;/tt&amp;gt; to recenter them if necessary.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingClickNorthTopViewX.png |thumb|center|500px |  Select the north direction with &amp;lt;tt&amp;gt;N&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
You may need to complete two rounds of operating on the particles, changing the viewing direction (first in &#039;&#039;x&#039;&#039;, then in &#039;&#039;y&#039;&#039;).&lt;br /&gt;
&lt;br /&gt;
==== Averaging manually aligned particles ====&lt;br /&gt;
&lt;br /&gt;
We export the table we have computed &lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingQuickSave.png  |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
Now we can use the table (saved as file &amp;lt;tt&amp;gt;quickbuffer.tbl&amp;lt;/tt&amp;gt; by default) to create an average of the manually aligned particles:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;oa = daverage(&#039;t20s_Particles.Data&#039;,&#039;t&#039;,&#039;quickbuffer.tbl&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
which can be visualized in &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(oa.average);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingAverageManual.png |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
==== Creating a tight mask  ====&lt;br /&gt;
===== Measure distances =====&lt;br /&gt;
&lt;br /&gt;
Open the computed average in &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt;,&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dpkdev.legacy.dynamo_mapview(oa.average); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
set the view to the XZ or YZ planes, &lt;br /&gt;
&lt;br /&gt;
Hit the buttons next to the anchors [C] and [N] then place them with left and right click respectively. This is to measure the semiaxis of the average. Here, we want to click well outside of the signal, as we are measuring the distances that define a mask that needs to contain the average.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingMarkZaxis.png |thumb|center|500px| Measuring the semiaxis in the longitudinal direction in &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt; ]]&lt;br /&gt;
&lt;br /&gt;
Use the &#039;&#039;solid&#039;&#039; button to make the points more visible (as solid circles instead of rings). Now, move the [N] anchor to move the radius of the average in the xy plane,&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingMarkXYPlane.png |thumb|center|500px| Measuring the semiaxis in the transversal direction in &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt;  ]]&lt;br /&gt;
&lt;br /&gt;
===== Create mask =====&lt;br /&gt;
&lt;br /&gt;
We now symmetrize the density map. Use an arbitrary high value, we have use 17 in our example. The goal is simply to have a strong representation of the signal and to check how the template fits inside the mask that we will create later. &lt;br /&gt;
&lt;br /&gt;
Now, we create a cylindrical mask using the lengths of the semiaxes that we have measured using the anchor points.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingMaskOptions.png |thumb|center|500px  | Creating a cylindrical mask inside  &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
We save the created mask into a file&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingMaskSave.png |thumb|center|500px | exporting the created mask into file inside &amp;lt;tt&amp;gt;mapview&amp;lt;/tt&amp;gt; ]]&lt;br /&gt;
&lt;br /&gt;
====Cropping the borders of a template====&lt;br /&gt;
&lt;br /&gt;
We check how the mask looks like on the template&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;shifted =circshift(dsym(oa.average,&#039;c17&#039;),[0,0,-1]);dslices(shifted,&#039;y&#039;,&#039;overlay&#039;,&#039;maskTight.em&#039;,&#039;overlay_as&#039;,&#039;mask&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The &amp;lt;tt&amp;gt;circshift&amp;lt;/tt&amp;gt; operation is just shifting the template, as it seems that it is not well centered. It&#039;s normal: it&#039;s difficult to catch a perfect centering in a manual alignment. Probably in your own data set things will look slightly different. If necessary, you should try with different parameters, and stick with the one that looks like the best alignment. Then save it into a variable in the memory space:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;shifted = circshift(dsym(oa.average,&#039;c17&#039;),[0,0,-1]); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingCircshiftTemplate.png |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
Now  we can extract the part of the created template where we actually have signal:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;cropped = dynamo_crop(shifted ,32);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
which can be visualized with: &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dslices(cropped,&#039;y&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingTemplateInterior.png |thumb|center|500px| Template cropped to 32 pixels ]]&lt;br /&gt;
&lt;br /&gt;
We create a file to contain this cropped template:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; dwrite(cropped,&#039;average32.em&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and proceed similarly with the mask:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; dwrite(dcrop(dread(&#039;maskTight.em&#039;),32),&#039;maskTight32.em&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Through geometrical shapes ===&lt;br /&gt;
Alternatively, you can use &amp;lt;tt&amp;gt;dynamo_mask&amp;lt;/tt&amp;gt; or &amp;lt;tt&amp;gt;dynamo_tube&amp;lt;/tt&amp;gt; to create a synthetic model.&lt;br /&gt;
&lt;br /&gt;
== Creating a template matching process==&lt;br /&gt;
&lt;br /&gt;
The main function is &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;pts = dynamo_match(&#039;t20s.mrc&#039;,&#039;average32.em&#039;,&#039;mask&#039;,&#039;maskTight32.em&#039;,...&lt;br /&gt;
    &#039;outputFolder&#039;,&#039;cs30&#039;,...&lt;br /&gt;
    &#039;ytilt&#039;,[-39,36],&#039;sc&#039;,[256,256,256],&#039;cr&#039;,360,&#039;cs&#039;,30,&#039;bin&#039;,1);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note: when working in the [[standalone]], you cannot write the &amp;lt;tt&amp;gt;...&amp;lt;/tt&amp;gt; to break the lines, so you&#039;ll need to write in one single line.&lt;br /&gt;
&lt;br /&gt;
* &#039;bin&#039; &amp;lt;br/&amp;gt;  allows binning on the fly. Template, mask and tomograms are input in original size.&lt;br /&gt;
* &#039;sc&#039; : size of chunk &amp;lt;br/&amp;gt; This is the maximum extent of a block in the unbinned tomogram that will be kept in memory by each one of the processors working in parallel (only one in this experiment). We need to be careful not to crowd the available memory.&lt;br /&gt;
* &#039;cr&#039; : cone range &amp;lt;br/&amp;gt; orientations will be looked for inside a cone. In this context, the most usual values are 360 (sample the full sphere) or 0 (do not scan orientations)&lt;br /&gt;
* &#039;cs&#039; : cone sampling &amp;lt;br/&amp;gt; Determines the scanning density inside the sphere.&lt;br /&gt;
* &#039;ir&#039; : in plane range &amp;lt;br/&amp;gt; in plane rotation range&lt;br /&gt;
* &#039;is&#039; : in plane sampling &amp;lt;br/&amp;gt; determines the scanning density for in plane rotations&lt;br /&gt;
* &#039;mw&#039; : number of matlab workers for parallel computation&lt;br /&gt;
&lt;br /&gt;
&#039;ir&#039; and &#039;is&#039; are not used here to speed up computation and because the proteasome has a high rotational symmetry.&lt;br /&gt;
&lt;br /&gt;
&#039;mw&#039; is not used here for compatibility with all systems.&lt;br /&gt;
&lt;br /&gt;
You should get the following response on the screen (will take around 5 minutes to complete)&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;------------------------------------------------------------&lt;br /&gt;
 &lt;br /&gt;
 Template matching process.&lt;br /&gt;
 computing in CPU&lt;br /&gt;
 Output folder: cs30.TM&lt;br /&gt;
A total of 1 tiles have been created&lt;br /&gt;
  - Mb per tile (reading)   : 724.19&lt;br /&gt;
  - Mb per tile (operation) : 663.84&lt;br /&gt;
 ... initializing output elements&lt;br /&gt;
Preparing to run on 25 blocks&lt;br /&gt;
Running on single processor&lt;br /&gt;
 Computing tile 1&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;Information for each block&amp;gt;&lt;br /&gt;
&lt;br /&gt;
  ... tile 1 finished in 387 seconds (8 for setup;  7.73 per triplet)&lt;br /&gt;
  [ok] ... template matching process completed upto creation of cross correlation&lt;br /&gt;
       you can proceed to peak location and particle extraction.&lt;br /&gt;
------------------------------------------------------------&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The main result of &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt; is  a volume (&#039;&#039;cross correlation&#039;&#039; volume) that assigns a score to each pixel. This tomogram is written in the file &amp;lt;tt&amp;gt;cs30/CC.mrc&amp;lt;/tt&amp;gt;. Some auxiliary outputs are other volumes that store the angles [tdrot,tilt,narot] that maximize the cross-correlation for each pixel in the volume. It also creates a binned version of the tomogram, which will be useful to quickly crop particles for the purpose of evaluating the quality of the template matching. &amp;lt;br&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;b&amp;gt;Performance note &amp;lt;/b&amp;gt;: it is possible to run &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt; with several CPU cores in parallel, or with several GPUs. Both options increase the performance of the computation.&lt;br /&gt;
* The use of several CPUs can be called by the flag &amp;lt;tt&amp;gt;&#039;matlabWorkers&#039;&amp;lt;/tt&amp;gt; or &amp;lt;tt&amp;gt;&#039;mw&#039;&amp;lt;/tt&amp;gt; . The value &amp;lt;tt&amp;gt;&#039;*&#039;&amp;lt;/tt&amp;gt;  will instruct Matlab to use all available cores.&lt;br /&gt;
* You can activate the GPUs by the flag &amp;lt;tt&amp;gt;&#039;gpus&#039;&amp;lt;/tt&amp;gt;. For this, take into account that in this command, the numbers that identify each GPU device are the ones assigned by Matlab; they typically start with 1. This is in opposition to the device counting that you would get from the system, for instance through &amp;lt;tt&amp;gt;nvidia-smi&amp;lt;/tt&amp;gt;, where the counting starts typically with 0. &lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
=== The &amp;lt;tt&amp;gt;Process&amp;lt;/tt&amp;gt; object ===&lt;br /&gt;
The return &amp;lt;tt&amp;gt;pts&amp;lt;/tt&amp;gt; of the function &amp;lt;tt&amp;gt;dynamo_match&amp;lt;/tt&amp;gt; is an object that keeps track of the location of all the created output, and is used in the subsequent steps that extract the actual location of the peaks&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
if you need to reload this object after closing a matlab shell, simply use dynamo_read() on the process.mat file in the template matching directory&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;pts = dread(&#039;cs30.TM/process.mat&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Locating cross correlation peaks  ==&lt;br /&gt;
&lt;br /&gt;
Now we need to identify which peaks of the cross correlation correspond to actual particles.&lt;br /&gt;
&lt;br /&gt;
=== Looking at the cross correlation map ===&lt;br /&gt;
&lt;br /&gt;
We first examine the cross correlation map.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;pts.showCC&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingCCRaw.png |thumb|center|500px| &amp;lt;tt&amp;gt;tmshow&amp;lt;/tt&amp;gt; on the CC volume  ]]&lt;br /&gt;
&lt;br /&gt;
It is possible to operate on the map (through bandpassing or gaussian filtering) to smoothen the volume and get rid of many spurious peaks, but  we won&#039;t do it like thtr in this exercise.&lt;br /&gt;
&lt;br /&gt;
=== Looking at the cross correlation profile ===&lt;br /&gt;
&lt;br /&gt;
We can get a plot of the cross-correlation value found on the local maxima of the cc volume wiith the order&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;pts.peaks.plotCCPeaks(&#039;sidelength&#039;,32);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The cross-correlation values of the peaks appear in ascending order. We can check the quality of the peaks by auxiliary clicking on the curve to select one particle and then selecting some visualization option. &lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingPeakGood.png |thumb|center|500px|  auxiliary click on the area of good peaks ]]&lt;br /&gt;
&lt;br /&gt;
The &amp;lt;tt&amp;gt;sidelength&amp;lt;/tt&amp;gt; that we pass will be used for this visualization options to crop the particle around the peak.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingPeakGoodVolume.png |thumb|center|500px  |  particle cropped around the selected correlation peak]]&lt;br /&gt;
&lt;br /&gt;
We click on a couple of particles in the area of kink in the cross-correlation to roughly estimate the cross-correlation threshold. In our case, it seems to be around 0.37 (being rather conservative)&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingPeakKink.png |thumb|center|500px |  Looking for an area of transition between good and bad peaks]]&lt;br /&gt;
&lt;br /&gt;
In the gaussian distribution below this ara , the peaks do not correspond to particles&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingPeakBad.png |thumb|center|500px | false positives ]]&lt;br /&gt;
&lt;br /&gt;
=== Extracting a table ===&lt;br /&gt;
A table can be extracted through:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;myTable = pts.peaks.computeTable(&#039;mcc&#039;,0.38);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In this procedure, the template is first placed back in the position of highest correlation, using the alignment parameters. Then the next correlation maximum is considered, and the template is placed in its location. If the second placement overlaps with the previous one, the second one is considered an spurious maximum and skipped. This procedure is repeated till a threshold of cross correlation is attained (0.38 in this case).&lt;br /&gt;
&lt;br /&gt;
This order creates the variable &amp;lt;tt&amp;gt;myTable&amp;lt;/tt&amp;gt; in the workspace, and stores a copy of it inside the &amp;lt;tt&amp;gt;pts&amp;lt;/tt&amp;gt; objects, so that we can use it to invoke some axiliary functions to evaluate the result of our experiment.&lt;br /&gt;
&lt;br /&gt;
== Visual evaluation of results ==&lt;br /&gt;
&lt;br /&gt;
=== Looking at  table positions===&lt;br /&gt;
&lt;br /&gt;
A sketch of the 3d positions of the particles can be created through&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtplot(myTable,&#039;pf&#039;,&#039;oriented_positions&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
where &amp;lt;tt&amp;gt;&#039;pf&#039;&amp;lt;/tt&amp;gt; stands for &#039;&#039;profile&#039;&#039;. There are different predefined visualization profiles that can be passed to &amp;lt;tt&amp;gt;dtplot&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[   File:TemplateMatchingTable3d.png |thumb|center|500px | Particle positions ]]&lt;br /&gt;
&lt;br /&gt;
When rotated to show the YZ plane we see the shape of the layer were proteosomes are packing. This indicates that we don&#039;t have too many false positives.&lt;br /&gt;
&lt;br /&gt;
[[   File:TemplateMatchingTable3dSide.png |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
=== Looking at cropped particles ===&lt;br /&gt;
We can check how the individual particles look like on a gallery modus:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;pts.peaks.browse();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This order just opens &amp;lt;tt&amp;gt;ddbrowse&amp;lt;/tt&amp;gt;. We are using here the support object &amp;lt;tt&amp;gt;peaks&amp;lt;/tt&amp;gt;, but this command is equivalent to just invoking &amp;lt;tt&amp;gt;ddbrowse&amp;lt;/tt&amp;gt; as &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;ddbrowse(&#039;d&#039;,&#039;cs30.TM/binnedTomogram.mrc&#039;,&#039;t&#039;,myTable); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingDDBrowseNoTable.png |thumb|center|500px| &amp;lt;tt&amp;gt;ddbrowse&amp;lt;/tt&amp;gt; with a tomogram as a data source, needing the input of a sidelength in pixels]]&lt;br /&gt;
&lt;br /&gt;
We check the first 100 particles, as they appear inside the tomogram (i.e., without aligning them). We use the &#039;&#039;z&#039;&#039; direction (corresponding to the direction of the electron beam)&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingDDBrowseZ.png |thumb|center|500px| Result launched by &amp;lt;tt&amp;gt;ddbrowse&amp;lt;/tt&amp;gt;  without a connected table  ]]&lt;br /&gt;
&lt;br /&gt;
Now we look at them along the &#039;&#039;z&#039;&#039; direction of the aligned particles.&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingDDBrowseWithTable.png |thumb|center|500px| The table must be connected to align the particles   ]]&lt;br /&gt;
&lt;br /&gt;
Along the z direction we can only recognize particles that were already in a top view/&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingDDBrowseZAligned.png|thumb|center|500px|  &#039;&#039;z&#039;&#039;-view of aligned particles ]]&lt;br /&gt;
&lt;br /&gt;
Note the different appearance of the particles along the &#039;&#039;x&#039;&#039; and &#039;&#039;y&#039;&#039; direction.&lt;br /&gt;
&lt;br /&gt;
{|style=&amp;quot;margin: 0 auto;&amp;quot;&lt;br /&gt;
| [[ File:TemplateMatchingDDBrowseXAligned.png |thumb|center|350px| &#039;&#039;x&#039;&#039;-view of aligned particles   ]]&lt;br /&gt;
| [[ File:TemplateMatchingDDBrowseYAligned.png |thumb|center|350px|  &#039;&#039;y&#039;&#039;-view of aligned particles  ]]&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
This different behaviour occurs because we haven&#039;t used any rotational search during the template matching procedure. Thus, the azimuthal angle is initialized to zero, creating this bias.&lt;br /&gt;
&lt;br /&gt;
=== Looking at averages ===&lt;br /&gt;
&lt;br /&gt;
The bias visualized in the aligned particles is not important for the purpose of locating the particles, but we need to take it into account if we want to produce a new template on the results we just computed. A simple averaging&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;oap = pts.peaks.average(48);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
will produce a density map showing this different behaviour along &#039;&#039;x&#039;&#039; and &#039;&#039;y&#039;&#039;. Note that we need to introduce a sidelength (48), as the particles have never been cropped to this point, we are extracting them continuously from the binned tomogram.&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;dview(oap);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingAverageRaw.png |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
We should randomize the azimuthal angle &lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;oapRandomized = pts.peaks.average(48,&#039;ra&#039;,1);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
in order to get a well balanced template&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingAverageRandomized.png |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
== Getting the tables back into the catalogue ==&lt;br /&gt;
&lt;br /&gt;
You don&#039;t need to operate with the catalogue: you could just use &amp;lt;tt&amp;gt;dtcrop&amp;lt;/tt&amp;gt; on the just computed table  to extract particles from the original tomogram into a [[data folder]]. However, cataloguing has to advantages:&lt;br /&gt;
* Eases keeping track of all the steps you&#039;ve performed, specially if you are going to use several tomograms, and..&lt;br /&gt;
*allows you to visualize the peaks on the tomogram interactively, so that you can delete false positives or add peaks that were not located by the template matching.&lt;br /&gt;
&lt;br /&gt;
===Rescaling the table ===&lt;br /&gt;
&lt;br /&gt;
Remember that the table that we are working with has the scale of the auxiliary binned volume that has been created along with the CC matrix. In the catalogue, we want to work with the particles in their original scale.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tableOriginalScale = dynamo_table_rescale(myTable,&#039;factor&#039;,2);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the syntax of &amp;lt;tt&amp;gt; dynamo_table_rescale&amp;lt;/tt&amp;gt;, the &amp;lt;tt&amp;gt;factor&amp;lt;/tt&amp;gt; is expressed in terms of how many times is the apix in the original table bigger than in the target table to be computed. In our case, the target table was computed with an apix of 14 Angstrom (one time binned in relation to the tomogram &amp;lt;tt&amp;gt;t20s.rec&amp;lt;/tt&amp;gt;, with an apix of 7.04A). The factor is thus 2. In case of doubt, it is convenient to just run &lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;dtinfo(tableOriginalScale);&amp;lt;/tt&amp;gt; &lt;br /&gt;
&lt;br /&gt;
to check the extent of the entries in the columns 24, 25 and 26, which are positions (in pixels) of the particles indexed by the table.  &lt;br /&gt;
Now, if we write the upscaled table into a file&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;dwrite(tableOriginalScale,&#039;peaks.tbl&#039;);&amp;lt;/tt&amp;gt; &lt;br /&gt;
&lt;br /&gt;
===Entering result in catalogue ===&lt;br /&gt;
we can just put this table back into the catalogue through:&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;dmimport -t peaks.tbl -c ct20s -i 1 -mn ccpeaks&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
which will create a model called &amp;lt;tt&amp;gt;ccpeaks&amp;lt;/tt&amp;gt; and assign it to the first volume (&amp;lt;tt&amp;gt;-i 1&amp;lt;/tt&amp;gt;) in the catalogue &amp;lt;tt&amp;gt;ct20s&amp;lt;/tt&amp;gt;. You can check it by writing:&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;dcm -c ct20s -i 1 -l m&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
which asks for a listing of models (&amp;lt;tt&amp;gt;-l m&amp;lt;/tt&amp;gt;) in the first volume of the catalogue.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingIntoCatalogue.png |thumb|center|500px  ]]&lt;br /&gt;
[[  File:TemplateMatchingIntoCatalogueZoom.png |thumb|center|500px | Zooming inside &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; with &amp;lt;tt&amp;gt;Ctrl+ mouse wheell&amp;lt;/tt&amp;gt; ]]&lt;br /&gt;
&lt;br /&gt;
The model is editable and you can add or remove individual points.&lt;br /&gt;
&lt;br /&gt;
== Discarding regions ==&lt;br /&gt;
&lt;br /&gt;
Below the planar area that contains the most proteosomes, we see several false positives. Some false positives insist in having high correlation peaks and cannot be discarded  by thresholding. In order to remove them, we can inspect and remove them individually. If they are too many, we will probably prefer to mark regions in the tomogram where we want to keep of discard peaks. In this case we will mark a polygon in the XZ plane, and keep those peaks that fall inside (indepently of the y coordinate). &lt;br /&gt;
&lt;br /&gt;
To to this, press [Y] to get a slice orthogonal to this direction, and adjust the transparence in order to see the points behind the slice.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingDiscardTransparence.png |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
Now, we create a surface model, and change its name to &amp;lt;tt&amp;gt;boundary&amp;lt;/tt&amp;gt; for future reference.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingSurfaceMenu.png |thumb|center|500px  ]]&lt;br /&gt;
&lt;br /&gt;
Use  the mouse while keeping CTRL pressed to adjust the view and see along the &#039;&#039;direction&#039;&#039;. Then, use C to draw a line that enclose the area where we see valid peaks.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingSurface.png |thumb|center|600px  ]]&lt;br /&gt;
&lt;br /&gt;
Don&#039;t forget to save the model when you are done.&lt;br /&gt;
&lt;br /&gt;
[[  File:TemplateMatchingSurfaceSave.png |thumb|center|200px  ]]&lt;br /&gt;
&lt;br /&gt;
=== Keeping peaks inside the selected polygon ===&lt;br /&gt;
&lt;br /&gt;
Now, we can read both models into memory&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dcmodels ct20s -nc peaks -ws output&lt;br /&gt;
p = dread(output.files{1});&lt;br /&gt;
dcmodels ct20s -nc bound -ws output&lt;br /&gt;
b = dread(output.files{1});&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Consider only the XZ coordinates in both&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;pXZ = p.points(:,[1,3]);&lt;br /&gt;
bXZ = b.points(:,[1,3]);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and compute the indices of the points in the &amp;lt;tt&amp;gt;peaks&amp;lt;/tt&amp;gt; model that are enclosed inside the &amp;lt;tt&amp;gt;boundary&amp;lt;/tt&amp;gt; model (in the xz plane).&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;indicesOfPInsideB = inpolygon(pXZ(:,1),pXZ(:,2),bXZ(:,1),bXZ(:,2));&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Plotting the kept peaks ===&lt;br /&gt;
  &amp;lt;nowiki&amp;gt;f = figure();&lt;br /&gt;
hs1 = subplot(2,1,1);&lt;br /&gt;
h = dpkgeom.plotCloud(p.points); axis equal&lt;br /&gt;
h.Marker = &#039;.&#039;;&lt;br /&gt;
view([0,1,0]);&lt;br /&gt;
hs1.ZLim = [0,200];&lt;br /&gt;
hs1.XLim = [0,1000];&lt;br /&gt;
title(&#039;Original peaks&#039;);&lt;br /&gt;
&lt;br /&gt;
hs2 = subplot(2,1,2);&lt;br /&gt;
h = dpkgeom.plotCloud(p.points(indicesOfPInsideB,:)); axis equal; &lt;br /&gt;
h.Marker = &#039;.&#039;;&lt;br /&gt;
hold on;&lt;br /&gt;
hB = dpkgeom.plotCloud(b.points); axis equal&lt;br /&gt;
hB.Marker = &#039;o&#039;;&lt;br /&gt;
hB.LineStyle = &#039;--&#039;;&lt;br /&gt;
hB.MarkerFaceColor = &#039;b&#039;;&lt;br /&gt;
hB.Color = &#039;k&#039;;&lt;br /&gt;
title(&#039;Peaks inside boundary&#039;);&lt;br /&gt;
view([0,1,0]);&lt;br /&gt;
axis(hs2,axis(hs1)); &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:TemplateMatchingDiscardTPlot.png  |thumb|center|500px  ]]&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_command_line_based_tilt_series_alignment_(Tsinghua_Spring_School_2025)&amp;diff=5593</id>
		<title>Walkthrough on command line based tilt series alignment (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_command_line_based_tilt_series_alignment_(Tsinghua_Spring_School_2025)&amp;diff=5593"/>
		<updated>2025-03-01T08:24:58Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Data */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:WalkthroughsSpecific]]&lt;br /&gt;
&lt;br /&gt;
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 [[Walkthrough on GUI based tilt series alignment | 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).&lt;br /&gt;
&lt;br /&gt;
= Data =&lt;br /&gt;
&lt;br /&gt;
We use a binned version of the first tilt series from the EMPIAR entry 10164, depicting a set of virus like particles (VLP). You can download it directly from EMPIAR, then bin it,   &amp;lt;!--[https://drive.google.com/file/d/1EsnKBvbFuWD1njk8dRVLc3SlhdsTHIpY/view?usp=drive_link or simply follow this link]--&amp;gt;[{{Template:DownloadLinkAWFHIV1TS}} or simply follow this link] to download a 600Mb file. You can also follow this tutorial using your own data.&lt;br /&gt;
&lt;br /&gt;
In this course, the data for this walkthrough is in:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/data/DownloadLinkAWFHIV1TS/&amp;lt;/tt&amp;gt;&lt;br /&gt;
and the tomogram with the data is in the link:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/data/DownloadLinkAWFHIV1TS/b001ts001.mrc &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
= Create the workflow =&lt;br /&gt;
The following commands create a new alignment workflow in a separate folder. Make sure &#039;&#039;Dynamo&#039;&#039; is running and type the following commands into the Matlab command line (or the &#039;&#039;Dynamo&#039;&#039; console, if you work on the standalone version):&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;nowiki&amp;gt;name = &#039;hivCommandLine&#039;;&lt;br /&gt;
folder = &#039;workflows&#039;;&lt;br /&gt;
u = dtsa(name,&#039;--nogui&#039;,&#039;-path&#039;,folder,&#039;fp&#039;,1); &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
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 &amp;lt;tt&amp;gt;whos&amp;lt;/tt&amp;gt; to see a list of all variables in the workspace.&lt;br /&gt;
&lt;br /&gt;
= Entering the data =&lt;br /&gt;
&lt;br /&gt;
The variable &amp;lt;tt&amp;gt;u&amp;lt;/tt&amp;gt; is an object that contains several &#039;&#039;fields&#039;&#039; to interact with the workflow. They can be found through autocompletion by using the &amp;lt;tt&amp;gt;tab&amp;lt;/tt&amp;gt; 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.&lt;br /&gt;
&lt;br /&gt;
[[ File:alignCommandLine_autocompletionOfUserObject.png |thumb|center| 700px|autocompletion of user object to access different fields in matlab and standalone version]]&lt;br /&gt;
&lt;br /&gt;
== Basic data==&lt;br /&gt;
Basic data can be entered using the &#039;&#039;enter&#039;&#039; 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 and the angles are passed to the workflow:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;u.enter.tiltSeries(&#039;b001ts001.mrc&#039;);&lt;br /&gt;
u.enter.tiltAngles(-57:3:60); &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If necessary (not in this tutorial), you can use the &#039;&#039;discardedTiltIndices&#039;&#039; field to reject tilts that are of too bad quality using the following command (e.g., tilt 1 and 40):&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.enter.discardedTiltIndices([1,40]); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Acquisition settings==&lt;br /&gt;
Here you can enter parameters such as &amp;lt;tt&amp;gt;Cs&amp;lt;/tt&amp;gt;, nominal defocus, etc. For this tutorial we just provide the pixel size in Angstroms:&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.enter.settingAcquisition.apix(2.7);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Computation settings==&lt;br /&gt;
We enable the use of parallel cores&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.enter.settingComputing.parallelCPUUse(1); &amp;lt;/tt&amp;gt;&lt;br /&gt;
This will be using mainly for gold bead detection (cc computation) and reconstruction.&lt;br /&gt;
&lt;br /&gt;
To use all available physical cores use:&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.enter.settingComputing.cpus(&#039;*&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Detection settings==&lt;br /&gt;
These here are the actual design decisions when running an alignment workflow. The gold bead radius has to be known beforehand ( see [[Walkthrough on GUI based tilt series alignment | GUI based alignment walkthrough]] on how to measure it). Binning is used internally only for quick and robust bead detection.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;u.enter.settingDetection.detectionBinningFactor(1);&lt;br /&gt;
u.enter.settingDetection.beadRadius(16);&lt;br /&gt;
u.enter.settingDetection.maskRadius(28);&lt;br /&gt;
u.enter.templateSidelength(64);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Changing generic parameters ==&lt;br /&gt;
You can find all parameters of the individuals steps using autocompletion on the &amp;lt;tt&amp;gt;area&amp;lt;/tt&amp;gt; field and then by adding &amp;lt;tt&amp;gt;step&amp;lt;/tt&amp;gt; in the end. For example, the residual threshold of the tilt gap filler can be changed as follows:&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.area.indexing.step.tiltGapFiller.parameterSet.residualsThreshold(8);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
= Running the workflow =&lt;br /&gt;
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.&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.run.all(&#039;noctf&#039;,1);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Checking the results ==&lt;br /&gt;
After completion, the &amp;lt;tt&amp;gt;view&amp;lt;/tt&amp;gt; field allows you to check different output items for diagnose, such as the tilt lines:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.view.tiltLines.unaligned();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:alignCommandLine_viewOfTiltLines.png |thumb|center| 600px|view of tilt lines]]&lt;br /&gt;
&lt;br /&gt;
or the different reconstructions &lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;u.view.reconstruction.binnedWBP();&lt;br /&gt;
u.view.reconstruction.binnedSIRT();&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
or the aligned stacks themselves.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;u.view.stack.alignedFull();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can also use the autocompletion of the &amp;lt;tt&amp;gt;info&amp;lt;/tt&amp;gt; field (as shown in the beginning) to find and display different logs:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;&amp;gt;&amp;gt; u.info.fit;&lt;br /&gt;
------------------------------------------------------------&lt;br /&gt;
File with info:&lt;br /&gt;
  workflows/hivCommandLine.AWF/info/fitting.doc&lt;br /&gt;
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - &lt;br /&gt;
rms:  1.41&lt;br /&gt;
psi: 85.20&lt;br /&gt;
fit modus: normal&lt;br /&gt;
total markers: 79&lt;br /&gt;
total observations: 2702&lt;br /&gt;
fit created at: 11-Aug-2021 10:56:24&lt;br /&gt;
------------------------------------------------------------&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;&amp;gt;&amp;gt; u.info.markers;&lt;br /&gt;
------------------------------------------------------------&lt;br /&gt;
Info on working markers [used during detection, indexing refinement]&lt;br /&gt;
  ... item saved and in memory&lt;br /&gt;
Item in memory:&lt;br /&gt;
Number of shapes          :  79&lt;br /&gt;
Number of frames          :  40&lt;br /&gt;
Number of observations    :  2702 (out of 3160)&lt;br /&gt;
Number of empty frames    :  1&lt;br /&gt;
Number of complete frames :  0&lt;br /&gt;
Number of complete shapes :  0&lt;br /&gt;
 &lt;br /&gt;
Item in disk:&lt;br /&gt;
Markers in disk and currently in memory contain equal coordinates&lt;br /&gt;
 &lt;br /&gt;
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - &lt;br /&gt;
 &lt;br /&gt;
Info on final markers [used from alignment step]&lt;br /&gt;
  ... item saved and in memory&lt;br /&gt;
Item in memory:&lt;br /&gt;
Number of shapes          :  79&lt;br /&gt;
Number of frames          :  40&lt;br /&gt;
Number of observations    :  2702 (out of 3160)&lt;br /&gt;
Number of empty frames    :  1&lt;br /&gt;
Number of complete frames :  0&lt;br /&gt;
Number of complete shapes :  0&lt;br /&gt;
 &lt;br /&gt;
Item in disk:&lt;br /&gt;
Markers in disk and currently in memory contain equal coordinates&lt;br /&gt;
------------------------------------------------------------&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If you are following this tutorial during a &#039;&#039;Dynamo&#039;&#039; workshop, the exercise ends here.&lt;br /&gt;
&lt;br /&gt;
= On the fly reconstruction of particles=&lt;br /&gt;
&lt;br /&gt;
In this section we show how to avoid having to reconstruct a &#039;&#039;&#039;full&#039;&#039;&#039; tomogram at &#039;&#039;&#039;full&#039;&#039;&#039; resolution for the case where only a set of subtomograms are need. For this exercise we will use the gold beads as proxies that represent any particles of interest. We will first locate a few of them in the &#039;&#039;&#039;binned&#039;&#039;&#039; tomogram, and then use those coordinates to directly reconstruct the subtomograms in full resolution and skipping the need to reconstruct the whole full sized tomogram..&lt;br /&gt;
&lt;br /&gt;
== Define coordinates in the binned tomogram==&lt;br /&gt;
&lt;br /&gt;
First, we open the binned reconstruction tht we created before using the visualization tool &amp;lt;tt&amp;gt;dtmslice&amp;lt;/tt&amp;gt; and adjust the contrast if necessary (arrow):&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmslice &#039;workflows/hivCommandLine.AWF/reconstruction/binnedReconstructionWBP.mrc&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:alignCommandLine_dtmsliceOfBinnedReconstruction.png |thumb|center| 600px|dtmslice of binned reconstruction]]&lt;br /&gt;
[[ File:alignCommandLine_dtmsliceAfterContrastCorrection.png |thumb|center| 600px|dtmslice after contrast correction]]&lt;br /&gt;
To manually define the particle coordinates, we first open a new model of type &amp;lt;tt&amp;gt;general&amp;lt;/tt&amp;gt;:&lt;br /&gt;
[[ File:alignCommandLine_createANewModel.png |thumb|center| 600px|create a new model]]&lt;br /&gt;
To quickly find the 3d positions of a set of particles, we use a projection of the tomogram:&lt;br /&gt;
[[ File:alignCommandLine_showAFullProjection.png |thumb|center| 600px|show a full projection]]&lt;br /&gt;
[[ File:alignCommandLine_fullProjectionOfBinnedReconstruction.png |thumb|center| 600px|full projection of binned reconstruction]]&lt;br /&gt;
Right click on the (x,y) position of a particle opens two small windows showing the x-z and y-z planes:&lt;br /&gt;
[[ File:alignCommandLine_rightClickOnAPoint.png |thumb|center| 600px|right click on a point]]&lt;br /&gt;
Use the y-z depiction to left clicking on the marker. After clicking, the marker coordinates are saved in the model:&lt;br /&gt;
[[ File:alignCommandLine_xViewOfClickedPoint.png |thumb|center| 600px|x view of clicked point]]&lt;br /&gt;
[[ File:alignCommandLine_mainClickToFixThe3dCoordinates.png |thumb|center| 600px|main click to fix the 3d coordinates]]&lt;br /&gt;
Go back to the projection view and repeat the procedure until you have a few more markers (but no more than ten in this exercise). The x-z and y-z planes will be updated automatically when clicking on new markers on the projection and do not need to be closed every time. When you are done, you can close all the plane views and also the projection view.&lt;br /&gt;
[[ File:alignCommandLine_clickAroundTenMarkers.png |thumb|center| 600px|click around ten markers]]&lt;br /&gt;
To save the coordinates we first export them into the Matlab workspace in table format:&lt;br /&gt;
[[ File:alignCommandLine_exportATableIntoTheMatlabWorkspace.png |thumb|center| 600px|export a table into the matlab workspace]]&lt;br /&gt;
The Matlab shell should report the variable name used to store the table:&lt;br /&gt;
[[ File:alignCommandLine_theCommandLineShowsTheVariableNameAssignedToTheCreatedTable.png |thumb|center| 400px|the command line shows the variable name assigned to the created table]]&lt;br /&gt;
&lt;br /&gt;
Now we can save the table with the coordinates as a file in the current directory (this table will be used to crop the subtomograms in the next steps):&lt;br /&gt;
 &amp;lt;tt&amp;gt;dwrite(temp_table,&#039;binnedGoldbeads.tbl&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Cropping the gold bead particles ===&lt;br /&gt;
&lt;br /&gt;
We can now crop the particles using the table file that we generated before:&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;tomo = &#039;workflows/hivCommandLine.AWF/reconstruction/binnedReconstructionWBP.mrc&#039;;&lt;br /&gt;
tbl  = &#039;binnedGoldbeads.tbl&#039;;&lt;br /&gt;
targetBinnedParticles = &#039;binnedGoldBeads.Data&#039;;&lt;br /&gt;
sidelengthBinned = 32;&lt;br /&gt;
o = dtcrop(tomo,tbl, targetBinnedParticles, sidelengthBinned);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
To monitor if everything worked correctly, we visualize a projection along &amp;lt;tt&amp;gt;z&amp;lt;/tt&amp;gt; of each cropped particle using the command:&lt;br /&gt;
 &amp;lt;tt&amp;gt;dslices(targetBinnedParticles,&#039;proj&#039;,&#039;c&#039;);shg;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[ File:alignCommandLine_dslicesOnBinnedGoldBeads.png |thumb|center| 600px|dslices on binned gold beads]]&lt;br /&gt;
== Reconstruct particles on the fly ==&lt;br /&gt;
&lt;br /&gt;
The command that reconstructs full sized particles from an aligned stack is &amp;lt;tt&amp;gt;dynamo_table_trec&amp;lt;/tt&amp;gt;. This is an independent function, not part of the workflow, implying that we will need to perform some format conversion.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tbl     = dread(&#039;binnedGoldbeads.tbl&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We scale the table. &amp;quot;Bin level 2&amp;quot; means that each pixel in the binned tomogram is 2 times twice its size in the full resolution tomogram. This is the factor that we input into &amp;lt;tt&amp;gt;dynamo_table_rescale&amp;lt;/tt&amp;gt;:&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;alignmentBinLevel = 2;&lt;br /&gt;
tblFull = dynamo_table_rescale(tbl,&#039;factor&#039;,2^alignmentBinLevel); &amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Now we fetch the full sized aligned stack stored inside the alignment folder:&lt;br /&gt;
 &amp;lt;tt&amp;gt;source  = &#039;workflows/hivCommandLine.AWF/align/alignedFullStack.mrc&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We create a data folder to contain the particles to be reconstructed on the fly:&lt;br /&gt;
 &amp;lt;tt&amp;gt;targetDirectory = &#039;tempCrop.Data&#039;&amp;lt;/tt&amp;gt;;&lt;br /&gt;
&lt;br /&gt;
Angles &#039;&#039;actually&#039;&#039; used during the reconstruction are contained in the &#039;&#039;reconstructionTiltAngles&#039; item of the output folder. Note that they might differ from the nominal angles, as some views might have been eliminated, both explicitely by the user, of by the program not being able to align all tilts.&lt;br /&gt;
 &amp;lt;tt&amp;gt;angles =  &#039;workflows/hivCommandLine.AWF/align/reconstructionTiltAngles.tlt&#039;;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The (binned) coordinates were measured in a binned tomogram, whose dimensionality is requested by &amp;lt;tt&amp;gt;dynamo_table_rec&amp;lt;/tt&amp;gt;. We need to provide &amp;lt;tt&amp;gt;dynamo_table_rec&amp;lt;/tt&amp;gt; with &lt;br /&gt;
 &amp;lt;nowiki&amp;gt;visualizationTomogram =  &#039;workflows/hivCommandLine.AWF/reconstruction/binnedReconstructionWBP.mrc&#039;;&lt;br /&gt;
sizeTomogram = dynamo_read_size(visualizationTomogram);&lt;br /&gt;
sizeTomogramFull = sizeTomogram*2^alignmentBinLevel;&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The tomogram center can be shifted in order to account for a possible shift in the centre in the binned reconstruction that was used to crop the particles.&lt;br /&gt;
 &amp;lt;tt&amp;gt;shiftTomogramCenter = [0,0,0];&amp;lt;/tt&amp;gt;&lt;br /&gt;
We proceed now to the reconstruction. Our sid length should be 4 times the size we used before:&lt;br /&gt;
 &amp;lt;tt&amp;gt;sidelengthFullSize = 128;&amp;lt;/tt&amp;gt;&lt;br /&gt;
We use the &amp;lt;tt&amp;gt;applyRampFilter&amp;lt;/tt&amp;gt; option in order to explicitely estate the kind of filter that we want during the back projection.&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;dynamo_table_rec(tblFull,source,angles,targetDirectory, sidelengthFullSize, &#039;applyRampFilter&#039;,1, &#039;sizeTomogram&#039;,sizeTomogramFull, &#039;shiftTomogramCenter&#039;,shiftTomogramCenter);&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
We can now check that the particles have been reconstructed in full size:&lt;br /&gt;
 &amp;lt;tt&amp;gt;figure;dslices(targetDirectory,&#039;proj&#039;,&#039;c&#039;);shg;&amp;lt;/tt&amp;gt;&lt;br /&gt;
[[ File:alignCommandLine_dslicesOnFullSizedGoldBeads.png |thumb|center| 600px|dslices on full sized gold beads]]&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_GUI_based_tilt_series_alignment_(Tsinghua_Spring_School_2025)&amp;diff=5592</id>
		<title>Walkthrough on GUI based tilt series alignment (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_GUI_based_tilt_series_alignment_(Tsinghua_Spring_School_2025)&amp;diff=5592"/>
		<updated>2025-03-01T08:23:53Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Data */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:WalkthroughsSpecific]]&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;Dynamo&#039;&#039; 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 GUI-based mode. The [[Walkthrough on command line based tilt series alignment | walkthrough on command line based tilt series alignment]] shows how to operate this procedure through the command line.&lt;br /&gt;
&lt;br /&gt;
= Data =&lt;br /&gt;
&lt;br /&gt;
We use a binned version of the first tilt series from the EMPIAR entry 10164, depicting a set of virus like particles (VLP). You can download it directly from EMPIAR, then bin it,   &amp;lt;!--[https://drive.google.com/file/d/1EsnKBvbFuWD1njk8dRVLc3SlhdsTHIpY/view?usp=drive_link or simply follow this link]--&amp;gt;[{{Template:DownloadLinkAWFHIV1TS}} or simply follow this link] to download a 600Mb file. You can also follow this tutorial using your own data.&lt;br /&gt;
&lt;br /&gt;
In this course, the data for this walkthrough is in:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/data/DownloadLinkAWFHIV1TS/&amp;lt;/tt&amp;gt;&lt;br /&gt;
and the tomogram with the data is in the link:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/data/DownloadLinkAWFHIV1TS/b001ts001.mrc &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
= Creating an alignment workflow= &lt;br /&gt;
&lt;br /&gt;
Start the alignment GUI by typing the command &amp;lt;tt&amp;gt;dtsa&amp;lt;/tt&amp;gt; (short form of &amp;lt;tt&amp;gt;dynamo_tilt_series_alignment&amp;lt;/tt&amp;gt;) into the &#039;&#039;Dynamo&#039;&#039; command line: &lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt&amp;gt;dtsa&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A pop-up window appears. Click on &amp;quot;create a new workflow&amp;quot;:&lt;br /&gt;
&lt;br /&gt;
[[ File:alignGUI_creatingAWorkflow.png |thumb|center| 600px|creating a workflow]]&lt;br /&gt;
&lt;br /&gt;
Here, the input data for the workflow (tilt series, angles, ...) is introduced:&lt;br /&gt;
&lt;br /&gt;
[[ File:alignGUI_inputWorkflowParameters.png |thumb|center| 600px|input workflow parameters]]&lt;br /&gt;
&lt;br /&gt;
The option &amp;lt;tt&amp;gt;configuration file&amp;lt;/tt&amp;gt; is used to pass information on possible tilts that should be discarded. Here, we leave this option untouched. Press on &#039;&#039;create workflow&#039;&#039;, to open the alignment GUI.&lt;br /&gt;
&lt;br /&gt;
= GUI description =&lt;br /&gt;
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:&lt;br /&gt;
# &#039;&#039;&#039;Menu:&#039;&#039;&#039; Different tools for visualization and customization of general settings. The option &#039;&#039;Settings&#039;&#039; &amp;gt; &#039;&#039;edit[general]&#039;&#039; for example lets you adjust the pixel size and different acquisition parameters such as Cs etc. Here we keep the default settings.&lt;br /&gt;
# &#039;&#039;&#039;Icons:&#039;&#039;&#039; Quick access to tools such as &#039;&#039;dmarkers&#039;&#039;, &#039;&#039;occupancy plot&#039;&#039;, &#039;&#039;gold bead gallery&#039;&#039;, &#039;&#039;gold bead targeting&#039;&#039;, &#039;&#039;fitting&#039;&#039; and &#039;&#039;marker selection&#039;&#039;. Their functionalities will be explained later.&lt;br /&gt;
# &#039;&#039;&#039;Tabs:&#039;&#039;&#039; The tabs describe the 6 &#039;&#039;execution areas&#039;&#039; that are executed from left to right: &#039;&#039;detection&#039;&#039;, &#039;&#039;indexing&#039;&#039;, &#039;&#039;refinement&#039;&#039;, &#039;&#039;alignment&#039;&#039;, &#039;&#039;ctf&#039;&#039;, &#039;&#039;reconstruction&#039;&#039;. Each execution areas contains a set of processing steps.&lt;br /&gt;
# &#039;&#039;&#039;Steps:&#039;&#039;&#039; 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 &#039;&#039;View&#039;&#039; button which provides specific tools to visualize and inspect the results of each step.&lt;br /&gt;
# &#039;&#039;&#039;Run options:&#039;&#039;&#039; Options to run multiple steps.&lt;br /&gt;
&lt;br /&gt;
[[ File:alignGUI_alignmentGUIBeforeCompletionOfAnyStep.png |thumb|center| 600px|alignment GUI before completion of any step]]&lt;br /&gt;
&lt;br /&gt;
= Processing =&lt;br /&gt;
We are now ready to run all the processing steps. In the following, each step is described in detail.&lt;br /&gt;
== Detection ==&lt;br /&gt;
The goal of this step is to find the positions of the gold bead projections in the tilt series.  To do that, &#039;&#039;Dynamo&#039;&#039; 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 (&#039;&#039;peak feature&#039;&#039; and &#039;&#039;peak selection&#039;&#039;).&lt;br /&gt;
&lt;br /&gt;
=== Visualization matrix ===&lt;br /&gt;
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 &#039;&#039;creates a binned tilt series&#039;&#039; button with a &#039;&#039;+&#039;&#039; symbol, an option box appears, indicating the default binning factor which is 2. This parameter can be changed by users. Binning factor 2 in &#039;&#039;Dynamo&#039;&#039; is equivalent to a binning factor of 4 in &#039;&#039;IMOD&#039;&#039;.&lt;br /&gt;
Click on &#039;&#039;creates a binned tilt series&#039;&#039; button to create a binned tilt series stack.&lt;br /&gt;
Rightclick on &#039;&#039;View&#039;&#039; button to visualize the newly binned tilt series stack in &amp;lt;tt&amp;gt;tmshow&amp;lt;/tt&amp;gt;. In the &amp;lt;tt&amp;gt;tmshow&amp;lt;/tt&amp;gt; window, visualization parameters as binning, band and thickness can be adjusted if needed.&lt;br /&gt;
&lt;br /&gt;
Now, we are going to measure the diameter of the gold beads precisely in &amp;lt;tt&amp;gt;tmshow&amp;lt;/tt&amp;gt; in the original (unbinned) tilt series data. To do that, press the &#039;&#039;IO&#039;&#039; in the upper toolbox of the &#039;&#039;alignment workflow GUI&#039;&#039;, then go to &#039;&#039;tilt series matrix &amp;gt; inspect &amp;gt; On-the-fly view [dtmshow]&#039;&#039;. The &amp;lt;tt&amp;gt;tmshow&amp;lt;/tt&amp;gt; window opens, adjust contrast if necessary for better visualization.&lt;br /&gt;
[[ File:openOriginalTiltSeriesDataGUI.png |thumb|center| 600px| open unbinned tilt series data to measure gold bead diameter]]&lt;br /&gt;
&lt;br /&gt;
Zoom in a gold bead by holding the &amp;lt;tt&amp;gt;shift&amp;lt;/tt&amp;gt; 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 &amp;lt;tt&amp;gt;shift&amp;lt;/tt&amp;gt; key again and dragging with right mouse click on &amp;lt;tt&amp;gt;tmshow&amp;lt;/tt&amp;gt; window.&lt;br /&gt;
&lt;br /&gt;
[[ File:alignGUI_openTomoshowOnTheFullSizedMatrixToCheckTheSizeOfAGoldBead.png |thumb|center| 600px|open tomoshow on the full sized matrix to check the size of a gold bead]]&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
[[ File:OriginalGoldBeadDiameter.png |thumb|center| 600px|the ruler tool allows to measure in pixels the diameter of a gold bead]]&lt;br /&gt;
&lt;br /&gt;
=== Detection of gold beads ===&lt;br /&gt;
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).&lt;br /&gt;
&lt;br /&gt;
[[ File:alignGUI_DetectionParameters.png |thumb|center| 600px|the plus icon at corner reveals the values of the parameters of a given step.]]&lt;br /&gt;
&lt;br /&gt;
After pressing the button &#039;&#039;detect peaks&#039;&#039;, &#039;&#039;Dynamo&#039;&#039; 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 &#039;&#039;detect peaks&#039;&#039; button turns black bold, the computation is finished. Right click on the &amp;lt;tt&amp;gt;view&amp;lt;/tt&amp;gt; area of the step to access the different visualisation options.&lt;br /&gt;
&lt;br /&gt;
[[ File:alignGUI_markerSetsCanBeViewedAsCloudOfPoints.png |thumb|center| 600px| Secondary click the view panel to open a menu to access different results of a step. Marker sets can be viewed as cloud of points.]]&lt;br /&gt;
&lt;br /&gt;
This view shows the overlaid sum of the x,y coordinates of &#039;&#039;all&#039;&#039; cc peaks from &#039;&#039;all&#039;&#039; micrographs in the tilt series.&lt;br /&gt;
[[ File:alignGUI_cloudOfUnindexedCcPeaks.png |thumb|center| 600px|cloud of unindexed cc peaks]]&lt;br /&gt;
We can also check the positions of all the detected spots on each micrograph:&lt;br /&gt;
[[ File:alignGUI_showsTheDetectedSpotsOnTheVideoGUI.png |thumb|center| 600px|shows the detected spots on the video GUI]]&lt;br /&gt;
This GUI does not allow for edition of the markers. &#039;&#039;&#039;Tip:&#039;&#039;&#039; enable &#039;&#039;auto&#039;&#039; option at the bottom center of the visualization GUI to facilitate tilt series visualization.&lt;br /&gt;
[[ File:alignGUI_staticVideoAnnotationsCannotBeEdited.png |thumb|center| 600px|static video annotations cannot be edited]]&lt;br /&gt;
The neighbourhood of cross correlation peaks can be visualised individually as 2D patches from the tilt series image data:&lt;br /&gt;
[[ File:alignGUI_EachPatchWillBeAPutativeGoldBead.png |thumb|center| 600px|Each patch will be a putative gold bead]]&lt;br /&gt;
[[ File:alignGUI_theSetOfCcPeaksIsShownAsAMontage.png |thumb|center| 600px|the set of cc peaks is shown as a montage]]&lt;br /&gt;
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&lt;br /&gt;
[[ File:alignGUI_exampleOfFailedSearch.png |thumb|center| 600px|example of failed gold bead detection]]&lt;br /&gt;
Note that you have the option of testing your parameters against a single image before launching a full detection procedure. Right-click on the tool icon on the right side of &#039;&#039;detect peaks&#039;&#039; pushbutton.&lt;br /&gt;
[[ File:alignGUI_toolboxOptionForTestingTheParametersOnACentralImage.png |thumb|center| 600px|toolbox option for testing the parameters on a central image]]&lt;br /&gt;
[[ File:alignGUI_resultsOfTestingOnACentralImage.png |thumb|center| 600px|results of testing on a central image]]&lt;br /&gt;
&lt;br /&gt;
=== Computation of observation features ===&lt;br /&gt;
At this stage, the observed cross correlation peaks are analysed. A merit figure is assigned to each peak based on a &#039;&#039;rotational merit&#039;&#039; that measures its rotational symmetry. Press the button &#039;&#039;Peak features&#039;&#039; 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:&lt;br /&gt;
[[ File:alignGUI_patchGalleryForFeatures.png |thumb|center| 600px|patch gallery for features]]&lt;br /&gt;
[[ File:alignGUI_theGalleryAllowsRelatingAppearanceOfGoldBeadAnValueOfTheFeatures.png |thumb|center| 600px|the gallery shows the detected gold beads, the CC score (yellow) and the rotational merit (red). Tilt number is purple.]]&lt;br /&gt;
or extracting properties of the whole data set.&lt;br /&gt;
[[ File:alignGUI_featurePlotterAllowsCheckingOfTheFeatureValuesOnTheWholeSet.png |thumb|center| 600px|feature plotter allows checking of the feature values on the whole set]]&lt;br /&gt;
[[ File:alignGUI_scatter2dOption.png |thumb|center| 600px| We select &#039;&#039;scatter&#039;&#039;, set the y axis to &#039;&#039;rotationaMerit&#039;&#039; and then press &#039;&#039;Scatter 2d.]]&lt;br /&gt;
[[ File:alignGUI_eachPointRepresentsACcPeak.png |thumb|center| 600px| We get a scatter plot of each peak and its relation to the CC and rotational merit score. Seeing two distinct populations means that the majority of the gold beads are distinguishable from other signal such as background.]]&lt;br /&gt;
&lt;br /&gt;
=== Selection of best gold beads===&lt;br /&gt;
The population with the best markers is automatically selected by clicking on &#039;&#039;Peak selection&#039;&#039;. The results can be inspected again in a plot&lt;br /&gt;
[[ File:alignGUI_checkObservationCloudAfterSelectionOrClustering.png |thumb|center| 600px|check observation cloud after selection or clustering ]]&lt;br /&gt;
[[ File:alignGUI_observationCloudHasBeenThinned.png |thumb|center| 600px|observation cloud has been thinned]]&lt;br /&gt;
or in the micrographs themselves:&lt;br /&gt;
[[ File:alignGUI_checkMarkerPositionsAfterClustering.png |thumb|center| 600px|check marker positions after clustering]]&lt;br /&gt;
[[ File:alignGUI_markerPositionsAfterClustering.png |thumb|center| 600px|marker positions after clustering]]&lt;br /&gt;
&lt;br /&gt;
== Indexing == &lt;br /&gt;
The goal of this execution area is to find &#039;&#039;trails&#039;&#039; 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 &#039;&#039;working markers&#039;&#039;.&lt;br /&gt;
&lt;br /&gt;
=== Rough Alignment ===&lt;br /&gt;
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 &#039;&#039;occupancy graph&#039;&#039;&lt;br /&gt;
[[ File:alignGUI_occupancySchemeOfTheResultsOfAStep.png |thumb|center| 600px|occupancy scheme of the results of a step]]&lt;br /&gt;
[[ File:alignGUI_roughAlignmentSelectsManyPotentialTrails.png |thumb|center| 600px| The rough alignment selects many potential trails. On the x-axis is the tilt number, on the y-axis the trail number and each red dot marks the presence of a marker.]]&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
=== Keep long chains ===&lt;br /&gt;
Click on &#039;&#039;keep long chains&#039;&#039; to select the longest trails, which will then be used to generate a 3d model of the markers:&lt;br /&gt;
[[ File:alignGUI_trailsWithFewMarkersAreThenRejected.png |thumb|center| 600px|short trails have been rejected]]&lt;br /&gt;
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.&lt;br /&gt;
[[ File:alignGUI_noteWorkingMarkersCanBeRestoredToTheResultOfAPreviousStep.png |thumb|center| 600px|working markers can be restored to the result of a previous step]]&lt;br /&gt;
&lt;br /&gt;
=== Iterative reindexing ===&lt;br /&gt;
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 &#039;&#039;iterative reindexing&#039;&#039;.&lt;br /&gt;
[[ File:alignGUI_parametersForIterativeReindexing.png |thumb|center| 600px|parameters for iterative reindexing]]&lt;br /&gt;
[[ File:alignGUI_resultOfIterativeReindexing.png |thumb|center| 600px|Result of iterative reindexing. Missing markers have been added to the trails]]&lt;br /&gt;
&lt;br /&gt;
===Tilt gap filling ===&lt;br /&gt;
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 &#039;&#039;fill tilts without markers&#039;&#039;.&lt;br /&gt;
[[ File:alignGUI_parametersForTiltGapFiller.png |thumb|center| 600px|parameters for tilt gap filler]]&lt;br /&gt;
[[ File:alignGUI_occupancyAfterTiltGapFiller.png |thumb|center| 600px|Results of tilt gap filler. Note how (in this example) a lot of markers have been rescued on the first tilt.]]&lt;br /&gt;
[[ File:alignGUI_weHave66TracesAfterGapFiller.png |thumb|center| 600px|Click on &#039;&#039;working markers&#039;&#039; to see that (in this example) we have 66 traces after tilt gap filling.]]&lt;br /&gt;
[[ File:alignGUI_resultsOfTiltGapFiller.png |thumb|center| 600px|results of tilt gap filler (&#039;&#039;show markers created by this step on tilt series&#039;&#039;)]]&lt;br /&gt;
&lt;br /&gt;
===Trail extension===&lt;br /&gt;
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.&lt;br /&gt;
&amp;lt;!--[[ File:alignGUI_parametersOfTiltExtensor.png |thumb|center| 600px|parameters of tilt extensor]]--&amp;gt;&lt;br /&gt;
[[ File:align_gui_parameters_tilt_extensor.png |thumb|center| 600px|parameters of tilt extensor]]&lt;br /&gt;
[[ File:alignGUI_trailExtensorAddsAFewNewTrails.png |thumb|center| 600px|trail extensor adds a few new trails]]&lt;br /&gt;
&lt;br /&gt;
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. &lt;br /&gt;
[[ File:alignGUI_someOfTheNewTrailsHaveEmptySpaces.png |thumb|center| 600px|some of the new trails may have empty spaces]]&lt;br /&gt;
[[ File:alignGUI_resultOfTrailExtensor.png |thumb|center| 600px|result of trail extensor]]&lt;br /&gt;
&lt;br /&gt;
==Refinement ==&lt;br /&gt;
This area refines the positions of the gold beads. We will run all steps of this area by pressing on a single button (the &#039;&#039;run this tab&#039;&#039; option at the bottom of the GUI). The button will remain green while the different steps are computed.&lt;br /&gt;
[[ File:alignGUI_tabForRefinement.png |thumb|center| 600px|tab for refinement]]&lt;br /&gt;
Check the current refinement error:&lt;br /&gt;
[[ File:alignGUI_betterFiitingIsAttained.png |thumb|center| 600px|better fitting is attained]]&lt;br /&gt;
Optionally, we can use the scissors icon to &amp;quot;trim&amp;quot; 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 &#039;&#039;Tools&#039;&#039; and then &#039;&#039;Show residuals per observation&#039;&#039;:&lt;br /&gt;
[[ File:alignGUI_trimmingOfMarkersCanBeAccessedThroughTheScissorIcon.png |thumb|center| 600px|trimming of markers can be accessed through the scissor icon]]&lt;br /&gt;
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.&lt;br /&gt;
[[ File:alignGUI_residualsAtEachObservation.png |thumb|center| 600px|residuals at each observation]]&lt;br /&gt;
&lt;br /&gt;
== Alignment ==&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
=== Fix the markers ===&lt;br /&gt;
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 &#039;&#039;fix alignment markers&#039;&#039;.&lt;br /&gt;
&lt;br /&gt;
[[ File:alignGUI_areaForCreationOfAnAlignedTiltSeries.png |thumb|center| 600px|area for creation of an aligned tilt series]]&lt;br /&gt;
&lt;br /&gt;
=== Align the tilt series ===&lt;br /&gt;
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 &#039;&#039;Create full-size aligned stack&#039;&#039; and &#039;&#039;Create binned aligned stack&#039;&#039;. For a quick assessment, open the binned stack in tomoshow:&lt;br /&gt;
[[ File:alignGUI_visualizationOfAlignedTiltStack.png |thumb|center| 600px|visualization of aligned tilt stack]]&lt;br /&gt;
[[ File:alignGUI_binnedAlignedTiltStack.png |thumb|center| 600px|binned aligned tilt stack]]&lt;br /&gt;
A quick way to gauge the quality of the alignment is by checking that the beads move nicely horizontally over all tilts.&lt;br /&gt;
&lt;br /&gt;
== CTF  ==&lt;br /&gt;
In this GUI, CTF estimation and correction are done using CTFFIND4 and IMOD&#039;s ctfphaseflip. This part will not be used in the workshop.&lt;br /&gt;
&lt;br /&gt;
== Reconstruction ==&lt;br /&gt;
&lt;br /&gt;
=== Binned reconstruction ===&lt;br /&gt;
Click on &#039;&#039;binned reconstruction&#039;&#039; 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 &#039;&#039;binned SIRT-like reconstruction&#039;&#039; to generate a high contrast tomogram. Run the step &#039;&#039;binned reconstruction&#039;&#039; and visualize the resulting binned SIRT-like tomogram: &lt;br /&gt;
[[ File:alignGUI_chooseAVisualization.png |thumb|center| 700px|choose a visualization]]&lt;br /&gt;
[[ File:alignGUI_binnedWeightedBackProjectionReconstruction.png |thumb|center| 600px|binned SIRT-like reconstruction]]&lt;br /&gt;
&lt;br /&gt;
=== Full sized reconstruction ===&lt;br /&gt;
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:&lt;br /&gt;
[[ File:alignGUI_thePinToolIsUsefulForLocatingIsolatedPoints.png |thumb|center| 600px|Click in the center of an object of interest using the pin tool.]]&lt;br /&gt;
&lt;br /&gt;
We check the size of the structure by using the measuring tool:&lt;br /&gt;
[[ File:alignGUI_weCheckTheDistanceOfTheObjectOfInterest.png |thumb|center| 600px|we check the distance of the object of interest]]&lt;br /&gt;
&lt;br /&gt;
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 &#039;&#039;use center of binned coordniates&#039;&#039; and enter the values we measured before with the pin tool. Select &#039;&#039;WBP reconstruction&#039;&#039; and run the step &#039;&#039;full reconstruction&#039;&#039;. Use the inspection tools to fetch the result:&lt;br /&gt;
[[ File:alignGUI_asAnSpecificViewerIsNotAvailableForThisStepWeCanUseTheToolboxOfTheStepsItems.png |thumb|center| 700px|as an specific viewer is not available for this step we can use the toolbox of the steps items]]&lt;br /&gt;
&lt;br /&gt;
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:&lt;br /&gt;
[[ File:alignGUI_theFullSizeReconstructionIncludesOnlyTheObjectOfInterest.png |thumb|center| 600px|the full size WBP reconstruction includes only the object of interest]]&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
	<entry>
		<id>https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_manual_marker_clicking_(Tsinghua_Spring_School_2025)&amp;diff=5591</id>
		<title>Walkthrough on manual marker clicking (Tsinghua Spring School 2025)</title>
		<link rel="alternate" type="text/html" href="https://www.dynamo-em.org//w/index.php?title=Walkthrough_on_manual_marker_clicking_(Tsinghua_Spring_School_2025)&amp;diff=5591"/>
		<updated>2025-03-01T08:22:28Z</updated>

		<summary type="html">&lt;p&gt;Andrés Molina: /* Loading the data */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Category:WalkthroughsSpecific]]&lt;br /&gt;
&lt;br /&gt;
This walkthrough describes the tools to &#039;&#039;manually&#039;&#039; locate fiducial markers for tilt series alignment using different graphical tools. &#039;&#039;Automatic&#039;&#039; alignment is described in [[Walkthrough on GUI based tilt series alignment]] and [[Walkthrough on command line based tilt series alignment ]].&lt;br /&gt;
&lt;br /&gt;
= Data set =&lt;br /&gt;
We use a binned version of the first tilt series from the EMPIAR entry 10164, depicting a set of virus like particles (VLP). You can download it directly from EMPIAR, then bin it,   &amp;lt;!--[https://drive.google.com/file/d/1EsnKBvbFuWD1njk8dRVLc3SlhdsTHIpY/view?usp=drive_link or simply follow this link]--&amp;gt;[{{Template:DownloadLinkAWFHIV1TS}} or simply follow this link] to download a 600Mb file. You can also follow this tutorial using your own data.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;!--This tutorial uses the tilt series VPP_tomo4.mrc from the EMPIAR database entry 10064. You can download it directly from the website: https://www.ebi.ac.uk/pdbe/emdb/empiar/entry/10064/{{Template:DownloadLinkAWFmanualEMPIAR}}&lt;br /&gt;
&lt;br /&gt;
The tilt series has already been prepared and can be found by following the next steps.--&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note that this tilt series has the following tilt angles: &amp;lt;code&amp;gt;-57:3:60&amp;lt;/code&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
= The &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt; GUI =&lt;br /&gt;
&lt;br /&gt;
This GUI is the basic tool for exploring tilt series and annotating on it  using  &#039;&#039;Dynamo&#039;&#039;. It allows to edit manually positions of markers, to fit them to a projection model, and to create an aligned data stack and a reconstruction based on this fitting.&lt;br /&gt;
&lt;br /&gt;
== Loading the data ==&lt;br /&gt;
&lt;br /&gt;
In this course, the data for this walkthrough is in:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/data/DownloadLinkAWFHIV1TS/&amp;lt;/tt&amp;gt;&lt;br /&gt;
and the tomogram with the data is in the link:&lt;br /&gt;
 &amp;lt;tt &amp;gt; /mnt/fs/2025workshop/data/DownloadLinkAWFHIV1TS/b001ts001.mrc &amp;lt;/tt&amp;gt;&lt;br /&gt;
Opening the &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt; GUI on a tilt series:&lt;br /&gt;
&lt;br /&gt;
It is convenient to first read the tilt series: &amp;lt;br/&amp;gt;&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;ts = dread(&#039;b001ts001.mrc&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and then pass the variable to the gui &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt;:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; gui = dmarkers(ts,&#039;tiltAngles&#039;,-57:3:60);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
here, &amp;lt;tt&amp;gt;gui&amp;lt;/tt&amp;gt; is just a handle to the GUI. This handle can be used on a later point to operate on it. Note that we also need to pass the tilt angles, as they will be needed for fitting a projection model. &lt;br /&gt;
&lt;br /&gt;
[[File:manual_marker_HIV_TS.png|thumb|center|600px| &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt; GUI ]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&amp;lt;!--Opening the &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt; GUI on a tilt series:&lt;br /&gt;
&lt;br /&gt;
It is convenient to first read the tilt series: &amp;lt;br/&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the &#039;&#039;&#039;local version&#039;&#039;&#039; that was distributed yesterday: &amp;lt;br/&amp;gt;&lt;br /&gt;
 &amp;lt;tt&amp;gt;ts = dread(&#039;b001ts001.mrc&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the remote version: &amp;lt;br/&amp;gt;&lt;br /&gt;
 &amp;lt;tt&amp;gt;ts = dread(&#039;b001ts001_15_08_2023.mrc&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and then pass the variable to the gui &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt;:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt; gui = dmarkers(ts,&#039;tiltAngles&#039;,-57:3:60);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
here, &amp;lt;tt&amp;gt;gui&amp;lt;/tt&amp;gt; is just a handle to the GUI. This handle can be used on a later point to operate on it. Note that we also need to pass the tilt angles, as they will be needed for fitting a projection model. &lt;br /&gt;
&lt;br /&gt;
[[File:ManualAlignmentDmarkers.png|thumb|center|600px| &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt; GUI ]]--&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Basic visualization controls ==&lt;br /&gt;
&lt;br /&gt;
=== Slide on micrographs ===&lt;br /&gt;
* Use the slide bar to view a transition of the micrographs (lower resolution images will be shown during the transition, full resolution images will be shown )&lt;br /&gt;
* left and right arrows move the  previous or next micrograph in the tilt series.&lt;br /&gt;
&lt;br /&gt;
===Zoom=== &lt;br /&gt;
* You can zoom into a point by using the wheel. &lt;br /&gt;
* The small red  window in the tool bar can be used as magnifying-glass to zoom in into a  hand-draw a region.&lt;br /&gt;
* The tool with the four arrows pointing into the corners zooms out of the scene totally.&lt;br /&gt;
&lt;br /&gt;
[[File:ManualAlignmentControls.png|thumb|center|400px|  Basic controls inn &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt; GUI ]]&lt;br /&gt;
&lt;br /&gt;
=== Dragging ===&lt;br /&gt;
The scene gets dragged by moving the mouse while keeping pressed the right mouse button.&lt;br /&gt;
&lt;br /&gt;
=== Elimination of defective tilts ===&lt;br /&gt;
&lt;br /&gt;
Some micrographs may be defective because of errors during acquisition. They can be markers as invalid by the key  &amp;lt;tt&amp;gt;x&amp;lt;/tt&amp;gt;. If you want to undo the marking of a micrograph as invalid, use &amp;lt;tt&amp;gt;shift+x&amp;lt;/tt&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
== Initiating a trace ==&lt;br /&gt;
A  three-dimensional gold bead is represented by a &#039;&#039;trace&#039;&#039;. A trace is a set of &#039;&#039;observations&#039;&#039;, where we call observation to the location of the projection of a gold bead in a given micrograph.&lt;br /&gt;
&lt;br /&gt;
The tool with a black point and a red edge starts the trace initiator. The cursor in the GUI becomes a cross; while this cursor is active, clicking on the screen will create a new gold bead.&lt;br /&gt;
&lt;br /&gt;
== Following a trace ==&lt;br /&gt;
To select a gold bead, click on it with the mouse, a green box will appear on the observation corresponding to the selected markers  in the current micrograph. &#039;&#039;&#039;Important&#039;&#039;&#039;:  to add observations into a trace that you have just created, you need to select it, otherwise your next clicks on the screen will be assigned to the trace that is currently under selection.&lt;br /&gt;
&lt;br /&gt;
Once you have selected a gold bead, you should switch off the tool for adding gold beads, and switch on the tool for adding observations to the gold bead currently under selection. The icon represents a point being tracked  across  several micrographs.&lt;br /&gt;
&lt;br /&gt;
You can use the arrows to move to the next or previous micrograph after clicking the gold bead.&lt;br /&gt;
&lt;br /&gt;
Additionally, you can connect the &#039;&#039;click and right&#039;&#039; or &#039;&#039;click and left&#039;&#039; tools. When they are switched on, after a click on the screen, the GUI will automatically move to the next micrograph.&lt;br /&gt;
&lt;br /&gt;
[[File:ManualAlignmentSetGoldBead.png |thumb|center|400px|  The gold bead click tools sets new traces, the track tool allows adding new observations to the currently selected trace ]]&lt;br /&gt;
&lt;br /&gt;
=== Key controls during clicking ===&lt;br /&gt;
&lt;br /&gt;
* &amp;lt;tt&amp;gt;d&amp;lt;/tt&amp;gt; will delete the closest observation (point in currently shown  micrograph).&lt;br /&gt;
* &amp;lt;tt&amp;gt;shift&amp;lt;/tt&amp;gt; + &amp;lt;tt&amp;gt;d&amp;lt;/tt&amp;gt; will delete a full trace.&lt;br /&gt;
*  &amp;lt;tt&amp;gt;m&amp;lt;/tt&amp;gt; will move the observation of the currently selected shape to the location of the cursor.&lt;br /&gt;
&lt;br /&gt;
=== Auxiliar views during clicking ===&lt;br /&gt;
There are two auxiliary GUIs that can be used to control the growth of the traces based as you click the points. The &#039;&#039;occupancy&#039;&#039; window updates as a new observation is added into a gold bead, showing the current content of each trace. And additional control shows the content of each trace as new points are clicked inside.&lt;br /&gt;
&lt;br /&gt;
[[File:ManualAlignmentControlViewers.png |thumb|center|400px|  Tools to follow the traces across the micrographs ]]&lt;br /&gt;
&lt;br /&gt;
== Saving the marker set ==&lt;br /&gt;
We want to save current set of markers into disk, by using the &amp;lt;tt&amp;gt;save to disk&amp;lt;/tt&amp;gt; option in the &amp;lt;tt&amp;gt;Tracks&amp;lt;/tt&amp;gt; menu. This will create the file &amp;lt;tt&amp;gt;Tracks.dms&amp;lt;/tt&amp;gt; in disk.&lt;br /&gt;
&lt;br /&gt;
= Fitting to an alignment model =&lt;br /&gt;
&lt;br /&gt;
When you have enough observations, you can proceed to fitting the location of your gold beads to a projection model. The tool with the icon &amp;lt;tt&amp;gt;Fit&amp;lt;/tt&amp;gt; will compute a set of shifts and a single angle &amp;lt;tt&amp;gt;psi&amp;lt;/tt&amp;gt; of rotation for the tilt axis. &lt;br /&gt;
&lt;br /&gt;
In the &#039;&#039;Fit&#039;&#039; menu on the GUI, you can find the current error, i.e., the mean residual between each observation and the projection estimated by the fitting model.&lt;br /&gt;
&lt;br /&gt;
[[File:ManualAlignmentFitting.png |thumb|center|400px| Fitting menu in &amp;lt;tt&amp;gt;dmarkers&amp;lt;/tt&amp;gt;]]&lt;br /&gt;
&lt;br /&gt;
== Extended fitting models ==&lt;br /&gt;
In a coarse fitting, &#039;&#039;Dynamo&#039;&#039; only tries to solve for shifts and a single rotation angle for all micrographs. It is possible to refine this fitting allowing a different rotation of the tilt axis for each micrograph. You can select for a richer model that computes for one different rotation angle on each micrograph by checking the option &amp;lt;tt&amp;gt;eachTilt&amp;lt;/tt&amp;gt;  on the parameter &amp;lt;tt&amp;gt;psi&amp;lt;/tt&amp;gt; (default is &amp;lt;tt&amp;gt;single&amp;lt;/tt&amp;gt;). &lt;br /&gt;
&lt;br /&gt;
Although you will get a lower error value, this might be due to overfitting. Thus, richer parametric models should not be used if you don&#039;t have enough markers on each micrograph (in the order of the tens.)&lt;br /&gt;
&lt;br /&gt;
= Reconstruction through the command line =&lt;br /&gt;
&lt;br /&gt;
Creating reconstructions through the command line is convenient when organizing the processing of  batches of tilt series. Automatic selection of markers is explored in a different walkthrough, here we describe the command line tools for creating reconstructions once a marker set is available. The steps are:&lt;br /&gt;
* Fitting of the available markers (using a &#039;&#039;fitter&#039;&#039; object).&lt;br /&gt;
* Extraction of alignment  parameters (using an &#039;&#039;aligner&#039;&#039; object).&lt;br /&gt;
* Creation of an aligned tilt series.&lt;br /&gt;
* Weighting the tilt series appropriately for a weighted-back-projection or Sirt-like reconstruction.&lt;br /&gt;
* Creation of the tomogram through back projecting the filtered aligned stack.&lt;br /&gt;
&lt;br /&gt;
If you have a set of markers saved  in a file in disk, you can load it to memory through:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;markers = dread(&#039;Tracks.dms&#039;);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Then, you can create a fitter object:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;fitter = dfitter(markers);&amp;lt;/tt&amp;gt;&lt;br /&gt;
 &lt;br /&gt;
This object needs to know where to put the rotation center of the aligned tilt series. &lt;br /&gt;
 &amp;lt;tt&amp;gt;fitter.setCenter(ts);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and prepare it to run with standard parameters:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;fitter.physical.defaultInitialization();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The command&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;fitter.linearScan();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
will then compute the best &amp;lt;tt&amp;gt;psi&amp;lt;/tt&amp;gt; angle for the rotation of the tilt axis together with the shifts.  They can be gathered into an stack alignment object&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;stackAligner = fitter.getStackAligner();&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
that gets then applied onto the original tilt series in the variable &amp;lt;tt&amp;gt;ts&amp;lt;/tt&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tsAligned  = stackAligner.applyOnStack(ts);&amp;lt;/tt&amp;gt; &lt;br /&gt;
&lt;br /&gt;
This aligned stack can be visualized through:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmshow(tsAligned);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Binned reconstruction  ==&lt;br /&gt;
&lt;br /&gt;
A reconstruction with a bigger pixel size can be computed by resizing both tilt series and markers. A marker object can be resized through:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;markersBinned = markers.math.bin(2);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Here, the factor 2 indicates that the coordinates of the markers get halved twice. This factor needs to be applied also to the tilt series:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;tt&amp;gt;tsBinned = dpktilt.bin(ts,2);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Now, we can refit the binned markers, proceeding as above:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;pre&amp;gt;binnedFitter = dfitter(markersBinned);&lt;br /&gt;
binnedFitter.setCenter(tsBinned);&lt;br /&gt;
binnedFitter.physical.defaultInitialization();&lt;br /&gt;
binnedFitter.linearScan();&lt;br /&gt;
binnedAligner = binnedFitter.getStackAligner();&lt;br /&gt;
tsBinnedAligned = binnedAligner.applyOnStack(tsBinned);&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
To create a weighted back projection reconstruction, this stack needs to be weighted with a ramp function in the Fourier space.&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;tt&amp;gt; tsBinnedRamp = dpktomo.rec.applyRampFilter(tsBinnedAligned);&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Then, we can use the command &amp;lt;tt&amp;gt;dpktilt.math.backproject&amp;lt;/tt&amp;gt; to create a reconstruction.&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;fbp = dpktilt.math.backproject([400,400,400],tsBinnedRamp,-57:3:60,&#039;mw&#039;,&#039;*&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Here, the flag &amp;lt;tt&amp;gt;&#039;mw&#039;&amp;lt;/tt&amp;gt; is merely instructing &#039;&#039;Dynamo&#039;&#039; to use all available cores.&lt;br /&gt;
&lt;br /&gt;
In case you did not mark a bead on every tilt you might get an error message at this point. Ideally you would go back and either mark at least one bead on the corresponding tilt or, if there are no good beads, you would exclude the tilt. Alternatively (but not recommended) you can use the following command to exclude the tilts without marked beads from the reconstruction:&lt;br /&gt;
&lt;br /&gt;
  &amp;lt;tt&amp;gt;fbp = dpktilt.math.backproject([400,400,400],tsBinnedRamp,fitter.physical.thetas(fitter.physical.indicesActiveTilts),&#039;mw&#039;,&#039;*&#039;); &amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
The reconstruction object &amp;lt;tt&amp;gt;fbp&amp;lt;/tt&amp;gt; contains the reconstructed tomogram in its property &amp;lt;tt&amp;gt;.rec&amp;lt;/tt&amp;gt;, which can be visualized through:&lt;br /&gt;
 &lt;br /&gt;
 &amp;lt;tt&amp;gt;dtmshow(fbp.rec);&amp;lt;/tt&amp;gt;&lt;/div&gt;</summary>
		<author><name>Andrés Molina</name></author>
	</entry>
</feed>