Tutorial.md

Tutorial for the CATM and TM

Introduction

To simplify the batch processing of the program, each demo tomogram is placed in a separate folder. Here, we will test two chromatin datasets with tomogram IDs "s210" and "s68". We will walk through the test for "s210". Pre-computed results are also available in the results folder, which may be overwritten during the process.

Tune the parameters

All parameters are configured in the config.py file, where you can specify the input/output directories and detailed parameters for template matching and the clash resolver. You can tailor these settings to meet specific requirements.

Inputs

In the input folder, you will find the following files:

1. s210.test1.wi8Apx.mrc: Denoised tomogram for visual inspection.
2. s210.test1.lps25.mrc: Low-pass filtered tomogram for template matching.
3. s210.pick1.csv: Picked particles, which can be manually selected or generated using AI-based pickers (such as DeepFinder).
4. s210_0000000_ctf_8.00A.mrc: CTF file for the tomogram, which can be obtained from Warp or Relion (optional).
5. mono-8Apx-lps30-box30-rot12-core.mrc: Mononucleosome template file.
6. mask-mono-8Apx-lps30-box30-rot12-ex2-s2.mrc: Soft mask for the template (optional).

Run the CATM pipline

cd test/s210/catm

simply run "catm"

catm

This will take 1-5 minutes, depending on the number of available CPUs. If the program runs successfully, it will output several different formats, and we will examine the results.

Run the TM pipeline

cd ../tm

simply run "tm" command, and this should only take a few seconds given the tiny size of the tomogram

tm

After template matching, you can run a postprocessing script to filter particles by distance and remove clashing particles. The results will be mapped back to the tomogram. You can also specify the cutoff for cross-correlation coefficients, which by default are set to 0.2 and 0.3.

To clean the particles based solely on distance (traditional method), run:

python plot_and_clean_results.py

Alternatively, to clean particles by distance and also remove steric clashes, use the following command. The cleaned file will be saved with the *rc.mrc suffix:

python plot_and_clean_results_remove_clash.py

Examine the results

The easiest way to look at the results is using 3dmod or ChimeraX

cd ..
3dmod catm/inputs/s210.test1.wi8Apx.mrc catm/results/s210.test1.catm.models.mrc  tm/results/s210.test1.tm_*.mrc

As you may have observed, there are nucleosomes stacked within the crowded tomogram that are accurately assigned by CATM, but not by TM. In the vicinity of the coordinates [25, 10, 17], two nucleosomes are stacked in a face-on view. This is illustrated in the [CATM vs TM movie], where TM results in incorrect orientation or an incorrect particle count, whereas CATM successfully assigns both nucleosomes. This is also true for the tacked nucleosomes with side-on view around [10,24,18] and [7,19,12]. It is important to note that the recall of CATM is dependent on the pre-assigned coordinates, and we exclude the particle too close to the edges of the tomogram. The angles for template matching are generated via randomly samping on 3D sphere, so you might expect small difference in results for each run.