TITLE: Tomogram Reconstruction and Gold Fiducial Removal with WarpTools, Etomo, and Fidder
AUTHORS: Connor Garrels, Benjamin Barad, Steve Reichow

[DESCRIPTION]
While gold nanoparticle fiducials greatly improve tilt-series alignment in cryo-electron tomography data, they can cause artifacts during later image processing steps. We present a workflow for high-quality fiducial removal using fidder, an open-source python package. This protocol demonstrates how to flexibly incorporate fidder into tomogram reconstruction using Warp and Etomo.

[STEPS]
SECTION: Install Software
2. Make sure you have these packages installed.

- IMOD
- WarpTools 
- Fidder

SECTION: WarpTools Preprocessing
3. We will be using WarpTools for the bulk of our processing. This section follows this warptools tutorial. 

Values shown are data-specific (i.e. exposure, pixel size, paths), so please be careful when copying these commands. These are just example values!
SECTION: WarpTools Preprocessing
3.1. Create Settings Files

frameseries
 
tiltseries
 

If your data was collected at super-resolution like ours was, --bin 1 is very important!
SECTION: WarpTools Preprocessing
3.2. Motion Correction and CTF Estimation

Motion correct and CTF estimate your data and output whole frame averages as well as even and odd frame-split micrographs for later denoising.
 

SECTION: WarpTools Preprocessing
3.3. Import tiltseries metadata

 

You may need to edit your mdocs to reflect where your motion corrected micrographs are. If so, try this script.
 

SECTION: WarpTools Preprocessing
3.4. Make Stacks

 
Notice we chose to make our stacks at 6.5 Å (bin 4 from physical pixel size). Whatever size you choose, remember it, as it is the resolution you will use for alignment and reconstruction later.
SECTION: Etomo Tilt Series Alignment
4. We will use batch processing in etomo for aligning our newly created stacks. Components of this section follows this warp tutorial.
SECTION: Etomo Tilt Series Alignment
4.1. Make etomo directory
Create the directory 'etomo' in your /tiltseries directory.
SECTION: Etomo Tilt Series Alignment
4.2. etomo

Open etomo in your /tilseries/etomo directory and choose the 'Batch Processing' button.

Set up your etomo session thusly:

Batch Setup Tab
Select 'Move all stacks to dataset directory under:' and enter the path to your /tiltseries/etomo directory

Stacks Tab
Add the stacks made in the last Warp step. The stacks will be .st files.

Dataset Values (Basic Tab)
Set fiducial bead size in nm (my BSA-coated 5nm gold beads are closer to 8nm)
'Coarse aligned stack binning - single frame' should be 1 (no binning)
'Aligned stack binning' should be 1 (no binning)
Select 'R-weighted back projection' and deselect 'SIRT-like filter'

Dataset Values (Advanced Tab)
Set 'Tilt Axis Rotation' (mine was 85)
'Use existing .rawtlt file for A/only axis:' should be set to Yes. (IMPORTANT)
'Type of magnification solution' should be 0: fixed
'Type of rotation solution' should be 5: grouped
'Type of beam tilt solution' should be -1: solve one

Run Tab
Create the file /usr/local/ImodCalib/cpu.adoc per these instructions.
  
'number' is the number of logical cpu cores on your machine. 'gpu.device' is the list of GPUs on your machine (note the list starts at 1, unlike CUDA device nomenclature).

With the .adoc created, select your desired # CPUs value (I chose 56).
Select 'Parallel GPUs' and set your # GPUs value (I chose 2)
Select 'Run multiple batch jobs in parallel' if you dare. I was able to run 7 jobs with a maximum of 2 GPUs per job. 
Under 'Subset of Steps to Run', check Stop after  and select Fine alignment. (IMPORTANT)
Click Run  and rock and roll

This will output two alignments files for each tiltseries - .xf and .tlt. 

SECTION: WarpTools Importing Alignments
5. Head back to warp to import the etomo alignments and get ready for reconstruction. Still following this guide.
SECTION: WarpTools Importing Alignments
5.1. Import alignments
Copy the .xf and .tlt files from their etomo subdirectories and move to their own folder at tiltseries/imod_xf_tlt.

Then run
 
Remember we made our stacks at 6.5Å in step 2.4 and did no binning in etomo, so the alignments were all calculated at 6.5Å.

SECTION: WarpTools Importing Alignments
5.2. Check Handedness
Back to this tutorial.

 
Follow the instructions in the output of this job to change your handedness if necessary.
SECTION: Fidder Gold Removal
6. Fidder - involves two steps; creating masks of fiducials and erasing them. We have provided an example python script to complete both steps on your full and half micrographs so long as they are within the warp file structure. There is also the option to use the command-line for fidder. 
SECTION: Fidder Gold Removal
6.1. You should only have to edit the parent_dir variable.
 
Depending on your computational resources, you may want to change the Pool() variable. erase_gold runs well with Pool(48) on our 64-thread machine.

Rename your existing (gold-containing) micrograph directories so they are not recognized by warp (e.g. /averages becomes /averages_gold etc.)

Move your newly gold-erased micrographs to the directories you just renamed (e.g. /frameseries/average, /frameseries/average/even, frameseries/average/odd)

SECTION: Overview
1. Gold nanoparticle fiducials in cryoET can greatly improve tilt-series alignment and tomogram quality. They can also introduce detrimental artifacts in downstream processing steps such as denoising or membrane segmentation. While there are methods to remove gold beads from micrographs, these methods are not always high quality or easily integrated into existing workflows. 

Here, we describe a workflow using fitter as part of tomogram reconstruction with WarpTools and Etomo, incorporating a step for gold fiducial removal with Fidder. The resulting tomograms are high quality because of the ability to use gold during alignment, but with no visible gold artifacts remaining.
SECTION: WarpTools Importing Alignments
5.3. CTF Estimation

 

SECTION: WarpTools Tomogram Reconstruction
7. To reconstruct your beautiful gold-erased tomograms: