susan.modules.Aligner

class susan.modules.Aligner

Bases: object

Particle alignment engine for 3-D and 2-D subtomogram averaging.

Wraps the susan_aligner binary. Configure the attributes, then call align() (single-node) or align_mpi() (multi-node MPI).

Attributes

list_gpus_ids

GPU device IDs to use. Default: [0].

Type:

list of int

bandpass

Frequency bandpass applied to both particle and reference. Default: bandpass(0, -1, 2) (full range, 2-pixel rolloff).

Type:

bandpass

dimensionality

Alignment search space: 3 for full 3-D, 2 for in-plane only. Default: 3.

Type:

int

extra_padding

Extra zero-padding (pixels) added on each side before FFT. Default: 0.

Type:

int

allow_drift

If True, 2-D shifts accumulate across iterations (drift mode). Default: True.

Type:

bool

halfsets_independ

Process the two half-sets with independent references. Default: False.

Type:

bool

ignore_classes

Ignore reference-class assignments; align against all references. Default: False.

Type:

bool

cone

Out-of-plane (cone) angular search range and step in degrees. Default: search_params(0, 1) (no search). The range is honoured exactly and the step is rounded to the nearest value that divides it, so the requested aperture is always reached.

Type:

search_params

inplane

In-plane angular search range and step in degrees. Default: search_params(0, 1) (no search). The step is adjusted to divide the range, as for cone.

Type:

search_params

refine

Multi-level angular refinement policy. Default: refine_params(0, 2) (no refinement). When levels are enabled, keep factor at 2 or more: the worst-case gap of the level-0 cone grid is about 0.7 times the cone step, so factor=1 leaves roughly 20% of directions outside the reach of the next level.

Type:

refine_params

angle_sigma

Width (degrees) of a Gaussian prior on the candidate orientation’s deviation from the previous pose. Acts as a soft regulariser that down-weights candidates with large angular offsets. The out-of-plane (cone) and in-plane (twist) deviations are penalised independently with the same width and multiplied, so the per-orientation score becomes CC · exp(−θ_cone² / (2·angle_sigma²)) · exp(−θ_inplane² / (2·angle_sigma²)) for the argmax tiebreak only. Raw CC values are preserved in stats and downstream outputs.

0 (default) disables the prior and reproduces the unregularised behaviour. θ is the deviation from the current pose, so for a search of full width span the most-deviated candidate sits at span / 2. Useful settings (per axis): angle_sigma = span barely touches the search (edge candidate ≈ 0.88); span / 2 is mild (edge ≈ 0.61); span / 4 is aggressive (edge ≈ 0.14). Because the two axes multiply, a candidate at the edge of both cone and in-plane gets the square of the per-axis weight (e.g. 0.88² ≈ 0.77).

Recommended in 2-D mode (dimensionality=2) with a cone search, where each tilt picks its own orientation and the per-particle degrees of freedom can otherwise drive overfitting. Set to 0 for coarse / template-matching searches that depend on broad angular exploration. Default: 0 (disabled).

Type:

float

offset_sigma

Width (pixels/voxels) of a Gaussian prior on the candidate translation’s magnitude. Acts as a soft regulariser that down-weights large shifts — the per-point score becomes CC(t) · exp(−|t|² / (2·offset_sigma²)) for the translation argmax, and the combined joint score CC · w_shift · w_angle drives the cross-orientation tiebreak. Raw CC values are preserved in stats and downstream outputs; the Sigma cc-stats tracker’s PSR / z-score uses raw CC so its discriminability metric is not polluted by the prior.

Units are pixels in 2-D mode and voxels in 3-D mode, matching offset (offset.span / offset.step). 0 (default) disables the prior and reproduces the unregularised behaviour. Typical useful values lie between offset.span / 4 (aggressive: edge of the offset grid gets weight ≈ 0.14) and offset.span / 2 (mild: edge gets weight ≈ 0.61).

Useful when the translational search has converged near the previous estimate and you want to prevent late iterations from wandering due to noise. Set to 0 for initial / coarse alignment when the true shift may be far from the current estimate. Default: 0 (disabled).

Type:

float

offset

Translational search range, step, and shape. Default: offset_params([4, 4, 4], 1, 'ellipsoid').

Type:

offset_params

offset_space

Coordinate frame for the offset search: 'reference' or 'tomogram'. Default: 'reference'.

Type:

str

padding_type

Fill value for the padded region: 'zero' or 'noise'. Default: 'zero'.

Type:

str

normalize_type

Per-substack normalisation applied before correlation. One of 'none', 'zero_mean', 'zero_mean_one_std', 'zero_mean_unit_var', 'poisson_raw', 'poisson_normal'. Default: 'zero_mean_one_std'.

Type:

str

ctf_correction

CTF correction strategy. One of 'none', 'phase_flip', 'on_reference', 'on_substack', 'wiener_ssnr'. 'cfsc' is a deprecated alias for 'wiener_ssnr'. Default: 'on_reference'.

Type:

str

cc_type

Cross-correlation variant used for scoring: 'basic', 'cfsc' or 'cfsc_substack'. 'cfsc' whitens both the substack and the 3D reference map; 'cfsc_substack' whitens only the substack and leaves the reference untouched. Default: 'basic'.

Type:

str

cc_stats_type

Post-CC statistics normalisation: 'none', 'probability', or 'sigma'. Default: 'none'.

'sigma' scores each orientation by the prominence of its CC peak over the offset grid, then reports the z-score of the best orientation against all the others. The per-orientation prominence needs at least 3 offset points to be defined, so with offset spans that yield 1 or 2 points (notably set_offset_search(0)) it falls back to the raw peak CC; the across-orientation z-score is unaffected. Note that prominence is amplitude-invariant by construction, and that it is a weak statistic on very small grids — a 7-point grid (set_offset_search(1)) gives it only 7 samples per orientation.

Type:

str

pseudo_symmetry

Symmetry group applied to the angular search grid. Default: 'c1'.

Value	Description
'c1' / 'none'	No symmetry (identity).
'cN' / 'CN'	Cyclic N-fold (e.g. 'c4').
'dN' / 'DN'	Dihedral N-fold (e.g. 'd2').
'cbo' / 'CBO'	Cuboctahedral (order 24).
'ico' / 'ICO' / 'i2' / 'I2'	Icosahedral, I2 convention (order 60; RELION default).
'i1' / 'I1'	Icosahedral, I1 convention.
'i3' / 'I3'	Icosahedral, I3 convention.
'i4' / 'I4'	Icosahedral, I4 convention.
'cone_flip' / 'y_180'	180° rotation about the Y axis.

Type:

str

ssnr

Ad-hoc SSNR model used for CTF weighting. Default: ssnr(0, 0.001).

Type:

ssnr

mpi

MPI launcher configuration used by align_mpi(). Default: mpi_params('srun -n %d ', 1).

Type:

mpi_params

verbosity

Verbosity level passed to the binary (0 = silent). Default: 0.

Type:

int

tm_type

Template-matching output mode. When not 'none', per-voxel cross-correlation statistics are written to disk for use by downstream template-matching workflows. One of 'none' or 'csv'; 'matlab' and 'python' are deprecated aliases of 'csv'. Default: 'none'.

Requires refine levels = 0: the report holds one peak per voxel, and angular refinement only refines the single best angle.

In 3-D the CSV columns are TID,PartID,RID,X,Y,Z,CC,CC_SIGMA,EU1, EU2,EU3,BlockID. CC is the maximum over the angular search, CC_SIGMA its z-score against that voxel’s own distribution over angles, and EU1..EU3 the ZYZ Euler angles (radians, same convention as ali_eu) of the winning orientation. CC_SIGMA can only be computed during the search, as the angular spread is not recoverable from the saved maximum.

Type:

str

tm_prefix

Filename prefix for the template-matching output files (only used when tm_type ≠ 'none'). Default: 'template_matching'.

Type:

str

tm_sigma

Threshold on CC_SIGMA below which voxels are discarded when saving template-matching output. 0 keeps all values, which writes one row per searched voxel and is rarely practical for a full run. 3-D only. Default: 0.

Type:

float

dilate

Tolerance, in pixels, to residual per-projection misalignment when scoring. Each projection’s CC map is replaced by a Gaussian-weighted maximum over its neighbourhood, with weight 0.5 at dilate pixels (sigma = dilate/sqrt(2 ln 2)). 0 disables it. Default: 0.

Type:

float

expfilt_gain

Multiplicative gain applied to the dose estimated by the CC tracker (from the width of the cross-correlation peak) before it is written to the per-projection exposure filter (def_ExFl). Useful for calibrating the auto-estimated dose-weighting against an external reference; see susan.utils.dose_from_fsc(). Default: 0 (disabled).

Note that the aligner writes expfilt_gain * dose on every run, so expfilt_gain = 0 zeroes the field rather than preserving it, and a hand-set exposure filter cannot survive an alignment. The exposure filter is uncompensated in the reconstruction (it enters the Wiener numerator only), so whatever gain is used here is baked permanently into the resulting map. For an envelope the reconstruction will deconvolve, use def_Bfct instead. See CryoET Background.

Type:

float

Methods

set_angular_search(c_r=0, c_s=1, i_r=0, i_s=1)

Set the cone and in-plane angular search parameters.

Convenience wrapper that writes to cone and inplane in one call.

Parameters:

• c_r (float) – Cone (out-of-plane) search range in degrees. 0 disables the cone search. Default: 0.

• c_s (float) – Cone search angular step in degrees. Default: 1.

• i_r (float) – In-plane search range in degrees. 0 disables the in-plane search. Default: 0.

• i_s (float) – In-plane search angular step in degrees. Default: 1.

set_offset_search(off_range, off_step=1, off_type='ellipsoid')

Set the translational offset search parameters.

Parameters:

• off_range (float or sequence of float) –

  Search range in pixels.

  • scalar — same range applied to X, Y, and Z.

  • 2-element sequence — [XY, Z]: same range for X and Y, separate range for Z.

  • 3-element sequence — [X, Y, Z]: independent range per axis.

• off_step (float) – Search step size in pixels. Default: 1.

• off_type (str) – Shape of the search volume. For 3-D alignment: 'ellipsoid' (default), 'cylinder', or 'cuboid'. For 2-D alignment: 'circle' ('ellipsoid') or 'rectangle' ('cuboid').

Raises:

ValueError – If off_type is not valid for the current dimensionality, or if off_range has more than 3 elements.

get_args(ptcls_out, refs_file, tomos_file, ptcls_in, box_size)

Build the command-line argument string for susan_aligner.

Parameters:

• ptcls_out (str) – Path for the output .ptclsraw file with updated alignments.

• refs_file (str) – Path to the input .refstxt references file.

• tomos_file (str) – Path to the input .tomostxt tomograms file.

• ptcls_in (str) – Path to the input .ptclsraw particles file.

• box_size (int) – Subvolume box size in pixels.

Returns:

Space-separated argument string ready to be appended to the susan_aligner command.

Return type:

str

align(ptcls_out, refs_file, tomos_file, ptcls_in, box_size)

Execute the alignment on a single node.

Parameters:

• ptcls_out (str) – Path for the output .ptclsraw file.

• refs_file (str) – Path to the .refstxt references file.

• tomos_file (str) – Path to the .tomostxt tomograms file.

• ptcls_in (str) – Path to the input .ptclsraw particles file.

• box_size (int) – Subvolume box size in pixels.

Raises:

RuntimeError – If the susan_aligner binary returns a non-zero exit code.

align_mpi(ptcls_out, refs_file, tomos_file, ptcls_in, box_size)

Execute the alignment using MPI across multiple nodes.

The MPI command is taken from mpi.

Parameters:

• ptcls_out (str) – Path for the output .ptclsraw file.

• refs_file (str) – Path to the .refstxt references file.

• tomos_file (str) – Path to the .tomostxt tomograms file.

• ptcls_in (str) – Path to the input .ptclsraw particles file.

• box_size (int) – Subvolume box size in pixels.

Raises:

RuntimeError – If the MPI binary returns a non-zero exit code.