View source for Walkthrough for GUI-based template matching (I2PC – Instruct Course on Electron Tomography and Subtomogram Averaging 2025)

[[Category:WalkthroughsSpecific]]

== Template matching ==

In this technique, a template representing a molecule of interest is systematically cross-correlated against a tomogram, producing a ''cross-correlation map'' 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.
This similarity is measured exclusively inside a mask.

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. 

In this walkthrough, the methods to manually manipulate these chunk is introduced.

Walkthroughs on [[Walkthrough for template matching | basic TM]] in Dynamo and [[Walkthrough for model-aware template matching | model-aware TM]] are also available.

== Data set ==

In this course, the data for this walkthrough is in:
 <tt > /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkTemplateMCP/</tt>
and the tomogram with the data is in the link:
 <tt > /mnt/fs/2025workshop/Users/user**/Data/DownloadLinkTemplateMCP/fullReconstructionWBPCTFDW.mrc </tt>

=== Getting the data ===
Currently the data necessary to tun this walkthrough can be downloaded using the link:

<!--https://drive.google.com/file/d/1ME2r6cDw6_sJVtFPTFTgOVBWIuQn44Wl/view?usp=drive_link-->
{{Template:DownloadLinkTemplateMCP}}

It consists in: a tomogram fullReconstructionWBPCTFDW.mrc, a template templateMCP.mrc, a mask maskMCP.mrc and a fourier mask fmaskMCP.mrc.

=== Tomogram description ===

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.

=== Acknowledgements ===

The tomogram has been generated using the tilt series from EMPIAR dataset entry 10226 described in the paper "Chreifi, G., Chen, S., Metskas, L. A., Kaplan, M., & 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". The alignment and reconstruction was done using the [[Walkthrough on GUI based tilt series alignment | Dynamo AWF procedure]] as detailed in "Coray, R., Navarro, P., Scaramuzza, S., Stahlberg, H., & 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". The template has been generated by STA as described in the same paper.

=== Visualizing the tomogram ===

The tomogram can be found in the path with:<br>

 <tt>tomofile = 'fullReconstructionWBPCTFDW.mrc';</tt>

We can get a first glance on how the tomogram looks like:

 <tt>dshow(tomofile);</tt>

The tomogram should appear like the following figure. Note the MCP arrays on the inner membrane of the bacteria.
[[ File:tomogram_dshow_TM_MCP.png |thumb|center|500px| <tt>dshow</tt> on the tomogram, View along ''z'' ]]


==== Estimation of the missing wedge ====

We can quickly check the extent of the missing wedge in the tomogram. We extract a sample of the tomogram:

 <tt>fragment = dynamo_read_subtomogram(tomofile, 'r',128,'c',[450,450,450]); </tt>

and plot a map of the distribution of the Fourier coefficients:

 <tt>dynamo_wedge_estimate(fragment,'show',1); </tt>
<br>
The wedge estimation will show a bi-directional tilt-series acquisition by fast-incremental from around -60 to 60 degrees. 
[[ File:missing_wedge_MCP.png |thumb|center|500px| Estimation of the missing wedge]]

=== Inspecting the template and mask ===

In this walkthrough, a template and its mask are already provided. The template was generated by averaging ~50000 particles aligned with Dynamo. 

The template can be loaded by:
 <tt>av = dread('templateMCP.mrc'); </tt>
And the mask can be loaded by:
 <tt>mask = dread('maskMCP.mrc'); </tt>

The template and mask positioning can be inspected with:
 <tt>dshow(av+mask); </tt>

[[ File:template_mask_MCP.png |thumb|center|500px| Template with its mask, View along ''Z'' ]]

[[ File:template_mask_MCP_Y.png |thumb|center|500px| Template with its mask, View along ''Y'' ]]

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.

== Description of basic chunk manipulations ==

The GUI for chunk manipulation is <tt>dtmslice</tt> with a tomogram as input. It has a tab called Template Matching in the top bar of the GUI.
It is through this tab that general attributes of chunks distributions and TM processes can be manipulated.
Additionally, each chunk has its own attributes (such as position and size) that can be manipulated after they are created.

[[ File:general_GUI_MCP.png |thumb|center|500px| <tt>dtmslice</tt> and template match tab.]]


=== Chunk creation ===

Create a chunk by pointing the cursor on the tomogram and pressing the "B" key.
[[ File:newchunk_GUI_MCP.png |thumb|center|500px| Newly created chunk.]]

Multiple chunks can be created by pressing the "B" key again. A chunk can be deleted by right-clicking it and selecting "Delete box". This will also update the number of existing chunks noted in the Template Matching tab.

[[ File:delete_chunk_MCP.png |thumb|center|500px| Delete options for chunks.]]

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.
[[ File:chunk_axis_MCP.png |thumb|center|500px| Close-up of a new chunk.]]

=== Basic chunk manipulations ===

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.
[[ File:chunk_resizing_MCP.png |thumb|center|500px| Chunk during resizing operation.]]

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.
[[ File:chunk_moving_MCP.png |thumb|center|500px| Chunk during moving operation.]]

Rotate a chunk by alt-clicking an edge and dragging it with the cursor.
[[ File:chunk_rotating_method1_MCP.png |thumb|center|500px| Chunk during change of chunk orientation by alt-click.]]


This can also be done by right-clicking the chunk and then selection the option "Change chunk orientation (into an oblique view)". This will spawn a interactable lever that can rotate the chunk in any direction.
[[ File:chunk_rotating_method2_before_MCP.png |thumb|center|500px| Selection of chunk orientation by lever.]]
[[ File:chunk_rotating_method2_after_MCP.png |thumb|center|500px| Chunk during change of chunk orientation by lever.]]

=== Chunk inspection ===

The tomogram data included in a chunk can be inspected by right-clicking the chunk and selecting "show chunk (in tomoshow)".

The data can also be inspected through a chunk-specific template match process that will be described in the following sections

=== Chunk cone setting ===
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.

[[ File:cone_rotating_before_MCP.png |thumb|center|500px| Selection of cone orientation.]]

The graphical object has some functionalities that can be accessed by right-clicking it as in the next figure.

[[ File:cone_rotating_options_MCP.png |thumb|center|500px| Option for cone orientation.]]

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 "Delete rotation frame" option shown in the previous figure.

[[ File:cone_rotating_after_MCP.png |thumb|center|500px| Change of cone orientation.]]

=== Per-chunk TM ===

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 "Launch TM process for this chunk". However, more parameters are necessary than only the chunk positions, size, orientation and cone orientation. These parameter can be accessed by selecting the "Template Matching" option on the top bar of the GUI and clicking "Settings for template match process" as in the next figure.

[[ File:access_TM_setting_GUI.png |thumb|center|500px| How to access the TM parameters GUI.]]

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.
[[ File:blank_TM_setting_GUI.png |thumb|center|500px| Blank TM parameter GUI.]]

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.

== Relationship between GUI models and tessellations ==

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 "Template Matching" tab in the GUI with the options "Save chunk distribution" and "Load chunk distribution from .omd file".<br>
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:

The function <tt>dpktomo.match.modelling.createTesselationFromGUIomd</tt> converts an .omd tessellation into a dStar tessellation ready for <tt>dynamo_match</tt>.<br>
The function <tt>dpktomo.match.modelling.saveTesselationAsGUIomd</tt> converts a dStar tessellation into an object that can be saved as a .omd file with <tt>dwrite</tt>.<br>

== Walkthrough on chunk manipulation ==

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.

=== Chunk setup ===

First, if not done already, open the <tt>dtmslice</tt> GUI with the tomogram.

 <tt>dtmslice('fullReconstructionWBPCTFDW.mrc');</tt>

Then, create a single chunk in the top area of the bacteria presenting an MCP array. For now, do not use oblique chunks.<br>
Ensure the chunk is thick enough to include the MCP array area even considering the template size.<br>
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).
[[ File:first_chunk_position_MCP.png |thumb|center|500px| Position of first chunk.]]

=== Global TM ===

In this first experiment, an per-chunk TM with isotropic angular scanning will be used.<br>
Howver, first it is necessary to set up the global TM parameters from the GUI. Update the GUI as in the following figure.
[[ File:settings_TM_GUI_360_MCP.png |thumb|center|500px| TM parameters for isotropic angular scans.]]

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.<br>
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:

 <tt>gpuDeviceTable</tt>

The per-chunk TM can then by launched. Right-click the chunk and select "Launch TM process for this chunk". This will automatically create a folder called "chunkTM.CTM" containing the oblique chunk and its resulting TM process.<br>

Finally, inspect the resulting cross-correlation map. In the created folder this can be done by:

 <tt>dshow('process.TM/cc.mrc')</tt>

[[ File:CC_first_chunk_360_MCP.png |thumb|center|500px| Resulting CC map.]]

=== Cone-restricted TM ===

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.
[[ File:first_chunk_correct_cone_MCP.png |thumb|center|500px| Position of first chunk with proper cone orientation.]]


The general TM parameters must be updated as well. In particular the cone range should be reduced from 360 degrees to 60 degrees.

[[ File:settings_TM_GUI_60_MCP.png |thumb|center|500px| TM parameters for cone-limited angular scans.]]

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:

 <tt>dshow('process.TM/cc.mrc')</tt>

The map will look similar to the previous per-chunk TM, but the computing time will be reduced by a factor of 10.

[[ File:CC_first_chunk_correct_cone_MCP.png |thumb|center|500px| Resulting CC map with limited angular cone.]]

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. 
[[ File:first_chunk_wrong_cone_MCP.png |thumb|center|500px| Position of first chunk with incorrect cone orientation.]]

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.
[[ File:CC_first_chunk_wrong_cone_MCP.png |thumb|center|500px| Resulting CC map with limited angular cone oriented incorrectly.]]

== Walkthrough on tessellation generation ==

Tessellation are sets of chunks an cone orientations designed to be used by <tt>dynamo_match</tt> for advantageous TM. Here, the process to create and uses tesselations by GUI is shown.

=== Add more chunks ===

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.

[[ File:full_tesselation_MCP.png |thumb|center|500px| Positions of multiple chunks with their cones.]]

Now, save the tesselation to disk by pressing the "Save chunk distribution" in the "Template Match" tab. This will create a file <tt>tesselation.omd</tt> to disk.

=== Generate a tesselation ===

As mentioned before, a .omd file need ot be converted to a star object to be an accepted input of <tt>dynamo_match</tt>.<br>
The conversion can be done by:
 <tt>star = dpktomo.match.modelling.createTesselationFromGUIomd('tesselation.omd');</tt>

The values encoded in the star object cen be inspected with:

 <tt>star.tbl</tt>

The properties will look similar to the following:
<pre>
    index     tdrot      tilt       narot      posX      posY      posZ     sizeX     sizeY     sizeZ     coneRange    inplaneRange
    _____    _______    _______    _______    ______    ______    ______    ______    ______    ______    _________    ____________

      1      -156.91    -160.25     156.91    702.55    743.66    564.27    515.44     397.2     270.9       60            360     
      2       147.92    -97.808    -147.92    912.01    455.29    326.33    414.75    387.03    242.75       60            360     
      3      -51.289    -78.113     51.289     486.3       883    322.65    455.65    549.42    282.14       60            360
</pre>

=== Run model-aware TM with manual tessellation ===

Finally, a full model-aware TM process can be run.
 <tt>pts_GPU = dynamo_match('fullReconstructionWBPCTFDW.mrc','templateMCP.mrc','mask','maskMCP.mrc',...
 'outputFolder','MCP_tesselation',...
 'ytilt',[-60,60],'is',10,'cs',10,'bin',2,'mw',10,'gpus',1,'tilingTable',star);</tt>

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

== Additional functionalities ==

Two other functionalities will be introduced in this section. First, an per-chunk TM with an oblique chunk and then a conversion of <tt>dynamo_match</tt> tesselation into an .omd file ready to be loaded in the GUI.

=== Oblique chunks ===

Oblique chunks are currently not supported by <tt>dynamo_match</tt>. However, per-chunk TM can be done on oblique chunks.
First, create an oblique chunk with appropriate cone orientation like in the following figure.

[[ File:oblique_chunk_position_MCP.png |thumb|center|500px| Oblique chunk with correct cone.]]

Per-chunk TM can then by run as in the previous sections.

[[ File:CC_oblique_chunk_correct_cone_MCP.png |thumb|center|500px| Resulting CC map with limited angular cone on oblique chunk.]]

=== Manipulation a tessellation with the GUI ===

The GUI can save and load .omd files, allowing of their manipulation and as such, the manipulations of tesselations.<br>


If a tesselation is available as a star object, it can be converted in a .omd object with:

 <tt>newomd = dpktomo.match.modelling.saveTesselationAsGUIomd(star);</tt>

Which can be save to disk as usual:
 <tt>dwrite(newomd,'tesselation_back.omd');</tt>

The new .omd file can then be loaded by the GUI.<br>


Note that tesselations can be generated automatically with the functions: <br>
<tt>dpktomo.match.modelling.estimateTesselationForFilament</tt><br> 
<tt>dpktomo.match.modelling.estimateTesselationForMembrane</tt><br> 
<tt>dpktomo.match.modelling.estimateTesselationForDipole</tt><br> 
and the creator of tesselation star objects:
<tt>dpktomo.match.modelling.setUpTilingTable</tt>

More information on this can be found in the tutorial [[Walkthrough for model-aware template matching | on model-aware template matching]].


=== Programmatic GUI customization for template matching ===

It is possible to add custom functionalities to the GUI as described in the [[Programmatic GUI customization for template matching | corresponding tutorial]].