Admin: Bot edit via cryonavedit.py: add reference pages and screenshots

2026-05-20T20:57:36Z

Bot edit via cryonavedit.py: add reference pages and screenshots

New page

This page summarizes the IMOD/Etomo tomographic reconstruction pipeline as it is invoked from within CryoNAV. It covers the sequence of processing steps from raw movie frames to a trimmed 3D tomogram, with the parameters that most often need adjustment and the outputs to inspect at each stage. For background on how these steps fit into CryoNAV's broader tomography workflow, see the linked pages below.

== Motion Correction / Frame Alignment ==

Runs ''alignframes'' (or an external tool such as MotionCor2) on the raw movie frames from a direct electron detector, producing one motion-corrected, optionally dose-weighted image per tilt. This step happens '''before''' the Etomo reconstruction proper.

Key parameters:
* '''Alignment strategy''' (-pair): pairwise with 7 frames is the default for typical tilt-series SNR; use ''all pairs'' (-1) with grouping for noisy data.
* '''Filter cutoff''' (-radius2): high-frequency cutoff in cycles/pixel; default 0.06.
* '''Dose weighting''' (-dtype): enables Grant & Grigorieff frequency-dependent attenuation; typically driven from the SerialEM .mdoc.
* '''GPU''' (-gpu) and '''binning''' (-binning): primary speed knobs; binning targets ~1250 px alignment images.
* '''EER super-resolution''' (-eer): 4K/8K/16K mode and Z-sum count for ThermoFisher EER frames.

''What to look for:'' weighted residual mean (good ~ 0.05-0.3), leave-out cross-validation error, total raw-vs-smoothed shift distance, and FRC 0.5/0.25/0.125 crossings reported in alignframes.log.

== Setup ==

A configuration step (no image processing) where dataset name, pixel size, fiducial diameter, image rotation, tilt-angle source, voltage and Cs are declared. CryoNAV uses these to generate the .com scripts that drive every later step.

Key parameters:
* '''Pixel size''' and '''fiducial diameter''' (nm): used by every downstream alignment program.
* '''Image rotation''' and '''tilt-axis angle''': initial geometry seed for alignment.
* '''Tilt-angle source''': extract from header, specify a range, or supply a .rawtlt file.
* '''Exclude views''': comma-separated 1-based list applied throughout the pipeline; see also [[CryoNAV Tilt Image Exclusion|Tilt Image Exclusion]].

''What to look for:'' a populated .edf file and a complete set of .com scripts; verify the .rawtlt contents match the acquired tilt scheme.

== Pre-processing ==

''ccderaser'' removes X-ray hits, hot pixels and similar detector artifacts from the raw stack before alignment.

Key parameters:
* '''PeakCriterion''': peak strength in SDs above local mean (default 10).
* '''DiffCriterion''': adjacent-pixel difference threshold (default 8).
* '''MaximumRadius''': largest artifact radius to erase (default 2.1 px).
* '''TrialMode''': writes a detection model without erasing -- useful for tuning thresholds.

''What to look for:'' the corrected {dataset}_fixed.mrc and an eraser.log entry count consistent with expected X-ray rate; review the peak model in 3dmod if many pixels are erased.

== Coarse Alignment ==

''tiltxcorr'' cross-correlates adjacent tilts, ''xftoxg'' chains the transforms, and ''newstack'' applies them to produce a pre-aligned .preali stack.

Key parameters:
* '''FilterSigma1/Sigma2''' and '''FilterRadius2''': bandpass that suppresses low-frequency ramp and high-frequency noise during correlation.
* '''Cosine stretch''' mode: corrects foreshortening at high tilt; ''absolute'' is recommended for steep tilts.
* '''AngleOffset''' and '''SkipViews''': compensate for known geometry errors and bad tilts.
* '''SearchMagChanges''': enable when magnification drift between views is suspected.

''What to look for:'' a smooth {dataset}.preali with no obvious jumps; inspect xcorr.log for per-view shifts that grow monotonically rather than randomly.

== Fiducial Model Generation ==

The major branch point in the pipeline. ''autofidseed'' + ''beadtrack'' is used when gold fiducials are present; otherwise patch tracking via ''tiltxcorr'' in patch mode generates a fiducial-like model.

Key parameters (fiducial path):
* '''TargetNumberOfBeads''' / '''TargetDensityOfBeads''': controls how aggressively autofidseed seeds.
* '''TwoSurfaces''': set when beads lie on both surfaces of the section.
* '''BeadDiameter''' (pixels) and '''BoxSizeXandY''': beadtrack search geometry.
* '''LocalAreaTracking''' with '''LocalAreaTargetSize''': improves tracking on large fields.
* '''RoundsOfTracking''': two rounds is standard.

''What to look for:'' bead count and mean residual in track.log; trajectories with large gaps or residuals >> 1 px in 3dmod indicate the seed model or bead diameter is off.

== Fine Alignment ==

''tiltalign'' solves the projection geometry -- rotations, tilt angles, magnifications, distortions -- from the fiducial model.

Key parameters:
* '''SurfacesToAnalyze''' (1 or 2): must match the actual specimen geometry.
* '''RotOption / TiltOption / MagOption''': set which variables are solved and how they are grouped; over-fitting is the main risk.
* '''LocalAlignments''' with '''NumberOfLocalPatchesXandY''': corrects beam-induced local distortions when enough fiducials exist.
* '''RobustFitting''': down-weights outliers; recommended for noisy data.
* '''BeamTiltOption''': set to 2 to search for beam tilt when residuals show systematic curvature.

''What to look for:'' weighted mean residual in align.log (target <1 px, ideally <0.5 px at the working binning); inspect ta{dataset}.log for per-bead outliers.

== Tomogram Positioning ==

''tilt'' generates a thin sample reconstruction and ''tomopitch'' fits a plane through it to determine final thickness, Z-shift, and X-axis tilt.

Key parameters:
* '''Thickness''' (pixels): generous enough to enclose the specimen plus margin.
* '''TiltAngleOffset''', '''TiltAxisOffset''', '''ZShift''', '''XAxisTilt''': normally taken directly from tomopitch.

''What to look for:'' the model file should bracket the specimen tightly in the {dataset}_samp.rec sample volume; tomopitch.log angles should be small (degrees) -- large values suggest fine alignment problems.

== Final Aligned Stack ==

''newstack'' (newst) builds the {dataset}.ali stack used for back-projection. Optional CTF estimation with ''ctfplotter'' and 2D phase-flip correction with ''ctfphaseflip'' are applied here. Dose weighting and 2D filtering can also be turned on at this stage.

Key parameters:
* '''BinByFactor''': output binning of the aligned stack.
* '''SizeToOutputInXandY''': output X/Y from positioning.
* '''ExpectedDefocus''' and '''AutoFitRangeAndStep''' (ctfplotter): drive defocus search.
* '''DefocusTol''' (ctfphaseflip): strip width control for tiled phase flipping (default 200 nm).
* '''InvertTiltAngles''': set if tilt-axis convention differs from CTF estimation expectation.

''What to look for:'' the {dataset}.defocus file should have smoothly varying values across views; ctfplotter.log should show clear Thon-ring fits, and the CTF-corrected stack should not show ringing artifacts.

== Tomogram Generation ==

''tilt'' back-projects the aligned stack into the 3D volume; ''sirtsetup'' + ''tilt'' is used for SIRT reconstructions.

Key parameters:
* '''THICKNESS''', '''SHIFT''', '''XAXISTILT''': inherited from positioning and fine alignment.
* '''RADIAL''': bandwidth and falloff of the R-weighting filter (default 0.35, 0.035).
* '''Reconstruction method''': WBP is standard; SIRT (or '''FakeSIRTiterations''' on WBP) increases contrast for visualization.
* '''SuperSampleFactor''': higher values reduce back-projection artifacts at cost of runtime.
* '''UseGPU''': major speedup for large volumes.

''What to look for:'' tilt.log for any warnings about clipped slices or GPU fallbacks; inspect a central slice for ray artifacts (under-sampling) or fogging (residual mis-alignment).

== Post-Processing ==

''trimvol'' crops, reorients (typically '''RotateX''' so Z is up) and optionally byte-scales the reconstruction; ''squeezevol'' produces a downsampled copy for fast browsing.

Key parameters:
* '''XMin/XMax''', '''YMin/YMax''', '''ZMin/ZMax''': crop ranges in IMOD coordinates.
* '''RotateX''' / '''SwapYZ''': standard output is RotateX with Z up.
* '''ConvertToBytes''' with '''FixedScaling''': smaller files at the cost of dynamic range; section-based scaling is more robust to variable contrast.
* '''ReductionFactorX/Y/Z''' (squeezevol): typically 1.25 for a lightweight preview.

''What to look for:'' verify final volume orientation in 3dmod, confirm the cropped Z range contains only the specimen, and check that byte scaling has not clipped features of interest.

== See also ==

* [[CryoNAV Overview Tomogram Processing|Tomogram Processing Overview]]
* [[CryoNAV Integration CryoEM Tools|Integration with Cryo-EM Tools]]
* [[CryoNAV Tilt Image Exclusion|Tilt Image Exclusion]]

[[Category:Reference]]

CryoNAV IMOD Pipeline Reference - Revision history

Admin: Bot edit via cryonavedit.py: add reference pages and screenshots