susan.project.SubtomoAvg

class susan.project.SubtomoAvg.SubtomoAvg(prj_name, box_size=None)

Bases: SubtomoAvgCore

Subtomogram averaging project manager.

Manages an STA project stored on disk. Provide box_size to create (or reuse) a project directory; omit it to open an existing project.

The main entry point for automated workflows is run_iteration(). Individual pipeline steps (run_estimation(), select_particles(), run_reconstruction(), run_postprocessing()) can also be called directly.

Project files

prj_name: str

box_size: int

tomogram_file: str

initial_reference: str

initial_particles: str

GPU & processing

list_gpus_ids: list of int

Default: [0].

Iteration control

iteration_type: int or str

Value	Step
3 / '3D'	3-D angular + offset search
2 / '2D'	2-D in-plane alignment
'ctf'	CTF refinement

Default: 3.

cc_threshold: float

Fraction of top-scoring particles kept per half-set. Default: 0.8.

fsc_threshold: float

FSC threshold for resolution reporting. Default: 0.143.

Modules

aligner: :class:`~susan.modules.Aligner`

averager: :class:`~susan.modules.Averager`

ctf_refiner: :class:`~susan.modules.CtfRefiner`

Advanced

mpi: :class:`~susan.utils.datatypes.mpi_params`

verbosity: int

Default: 1.

max_2d_delta_angstroms: float

Maximum per-iteration 2-D shift magnitude (Å). 0 disables. Default: 0.

max_tilt_reconstruction: None, float, or array-like of length 2

• None or negative scalar — disabled (default: -1).

• Scalar — tilt_deg_max passed to enable_by_tilt.

• Two-element sequence [min, max] — passed to enable_by_tilt_range.

use_nominal: bool

If True, the tilt comparison in max_tilt_reconstruction uses Tomograms.nominal_tilt_angles instead of deriving the tilt from proj_eZYZ. Default: False.

discard_oversampled_views: None, int, or dict

Flatten preferential orientation before reconstruction by keeping only the best particles per equal-area view bin (via Particles.Geom.discard_oversampled_views()).

• None or non-positive scalar — disabled (default: None).

• Positive integer — used as k_per_bin with default bin_size_deg=5.0.

• Dict — passed verbatim as keyword arguments (e.g. {'bin_size_deg': 4.0, 'k_per_bin': 2}).

type_2d_shift_fitting: str

Warning

Experimental.

Post-alignment 2-D shift regularisation: 'none', 'affine', 'gaussian', 'tps', or 'global'. Default: 'none'.

'tps' fits a regularised thin-plate spline to the per-tilt 2-D shift field. It is the middle ground between 'affine' (globally rigid) and 'gaussian' (purely local): a globally smooth warp whose stiffness is set by tps_lambda.

'global' is different in kind from the other three. Those fit each projection independently in the projected 2-D plane; 'global' fits a single 3-D displacement field per tomogram, jointly across the whole tilt series, and projects it back into each image. Because every tilt constrains one field, it can represent deformations that are invisible to a per-tilt 2-D fit, notably doming: a displacement along the specimen normal projects as sinθ·dz, so it vanishes at 0° and is carried almost entirely by the high-tilt images. Always fits from origin, so fitting_from_origin does not apply.

global_grid: tuple of 3 int

Warning

Experimental.

Control points per axis for the 'global' B-spline field. Deliberately anisotropic by default: the lateral extent of a tomogram exceeds its thickness by one to two orders of magnitude, so Z needs far fewer knots. Degree adapts per axis (cubic where the axis allows, linear at 2 control points). A tomogram needs at least 3 * nx * ny * nz particles or it is skipped. Default: (4, 4, 2).

global_lambda: float or None

Warning

Experimental.

Roughness penalty for the 'global' field, normalised so the value is comparable across datasets. None (default) selects it per tomogram by two-fold cross-validation over particles, which lets a tomogram with no real deformation collapse to a stiff, near-null field on its own rather than by user choice.

tps_lambda: float

Warning

Experimental.

Stiffness of the 'tps' shift warp (dimensionless; coordinates are normalised per tomogram so the value is comparable across datasets). 0 interpolates every shift (overfits noise), large values converge to the pure affine fit. Default: 1.0.

image_grid: tuple of 2 int

Warning

Experimental.

Control points per axis for the per-projection 2-D warp used by type_2d_shift_fitting = 'global+image', fitted on the residual left by the global field. Models per-image effects no specimen-frame field can express: residual stage drift, magnification and rotation errors, beam-induced image warp within an exposure. Default: (4, 4).

image_lambda: float or None

Warning

Experimental.

Stiffness of the image warp; None (default) selects it by two-fold cross-validation over particles, pooled across projections.

image_orthogonalize: bool

Warning

Experimental. Default False; leave it there.

Project the image-warp basis out of the global field’s span at each projection. This does not separate the two terms. At a single projection the global field already spans span(B) independently per output component, which contains ~99.96% of a 2-D spline in projected coordinates, so enabling this annihilates the warp instead: in simulation a genuine 28.6 Å per-image warp is recovered as 27.7 Å with the flag off and 1.1 Å with it on.

With the flag off, the global field is fitted first and the warp takes the residual, so content representable by both is attributed to the global field. The total written to prj_t is correct either way; only the split between the two terms is ambiguous, which matters if the global field’s amplitude is being read as a physical doming measurement. Resolving it properly requires a joint solve over both coefficient blocks, which is not implemented.

fitting_from_origin: bool

Warning

Experimental.

Controls what the 'affine'/'gaussian'/'tps' shift regularisers fit. If True (default) they fit the absolute current prj_t (measured from origin). If False they fit only the incremental prj_t (the delta versus the previous iteration) and add the smoothed delta back onto the previous shifts. Incremental deltas are smaller and noisier, so tps_lambda typically needs to be larger in this mode. Default: True.

smooth_ctf: bool

Warning

Experimental.

Enable spatial smoothing of per-particle CTF defocus deltas (the change versus the previous iteration), per tilt. The smoother is selected by type_ctf_smoothing. Default: False.

type_ctf_smoothing: str

Warning

Experimental.

Smoother used when smooth_ctf is enabled: 'gaussian' (local kNN average) or 'tps' (regularised thin-plate spline warp). Default: 'gaussian'.

ctf_tps_lambda: float

Warning

Experimental.

Stiffness of the 'tps' defocus warp, analogous to tps_lambda but applied independently to the CTF deltas. Default: 1.0.

reweight_classification: bool or float

Warning

Experimental.

Multi-reference CC reweighting. False keeps the raw CC; True normalises each particle’s per-class CC to sum to one; a positive number is an inverse-temperature beta selecting soft ML weights (softmax responsibilities scaled by a per-particle evidence gate, so noise fades toward a small floor). Pairs with aligner.ignore_classes = True, averager.ignore_classes = True and averager.weighting_type = '3DCC'. Default: False.

cross_halfmaps: bool

If True, the half-map paths in the reference are swapped when writing cur.reference after each reconstruction: half1 particles will be aligned against the half2 map and vice versa in the next iteration. Requires aligner.halfsets_independ to be True to take effect. Default: False.

save_raw_map: bool

If True, the unfiltered map produced by the averager is saved alongside the final map as map_classNNN.raw.mrc before any filter is applied. Default: False.

map_filter: callable or None

Optional post-reconstruction filter that does not use the FSC. Signature: filter(vol) -> vol. Setting this clears map_filter_fsc. Default: None.

map_filter_fsc: callable or None

Optional post-reconstruction filter that uses the FSC (e.g. FOM, spectral Wiener). Signature: filter(vol, fsc) -> vol, where fsc is the 1-D FSC array for that reference. Setting this clears map_filter. Default: None.

rho_v: float

MACE consensus weight for the volume. Must be in (0, 1].

• 1.0 (default) — classical mode: if a filter is set it is applied directly to V_data with no consensus.

• < 1.0 — MACE mode: V_cons = ρ·V_data + (1−ρ)·V_prior, where V_prior is the filter output. The residual U_V = U_V + V_data − V_cons is saved as map_classNNN.residual.mrc in the iteration directory and loaded from the previous iteration to form the denoiser input V_data + U_V. Setting rho_v < 1 also forces save_raw_map behaviour (V_data is always saved as map_classNNN.raw.mrc).

Iteration Execution

run_iteration(ite) → float | ndarray

Run a complete STA iteration, or skip the seed iteration.

For ite >= 1 this defers to SubtomoAvgCore.run_iteration(). Iteration 0 is the project seed and cannot be processed: a warning is issued, the iteration is skipped, and the configured starting lowpass is returned instead — the lowpass of aligner for a 3-D/2-D iteration or ctf_refiner for a CTF iteration. For a multi-reference project (initial reference holding more than one map) a numpy.ndarray of length n_refs filled with that value is returned, matching the per-reference shape of a real iteration’s result; otherwise a scalar float.

Parameters:

ite (int)

Return type:

float or numpy.ndarray

execute_iteration(ite) → float | ndarray

Alias of run_iteration(), for backward compatibility with STA.

Note

execute_iteration() is an alias of run_iteration(), kept for backward compatibility with STA.

setup_iteration(ite) → tuple[_IterationFiles, _IterationFiles]

Create the iteration directory and validate previous outputs.

Parameters:

ite (int) – Iteration number (≥ 1).

Returns:

(cur, prv) — _IterationFiles for this and the previous iteration.

Return type:

tuple

Raises:

NameError – If the previous iteration’s files are missing.

run_estimation(cur, prv)

Run alignment or CTF refinement (dispatches on iteration_type).

Parameters:

• cur (_IterationFiles)

• prv (_IterationFiles)

select_particles(cur, prv)

Classify, regularise, threshold, and write cur.ptcl_temp.

Parameters:

• cur (_IterationFiles)

• prv (_IterationFiles)

run_reconstruction(cur, prv)

Reconstruct reference maps and update cur.reference.

Parameters:

• cur (_IterationFiles)

• prv (_IterationFiles)

run_postprocessing(cur, prv) → float | ndarray

Compute FSC-based resolution estimates and apply post-reconstruction filtering (classical or MACE consensus).

Parameters:

• cur (_IterationFiles)

• prv (_IterationFiles)

Returns:

Estimated resolution in Fourier pixels.

Return type:

float or numpy.ndarray

Path Helpers

iteration_dir(ite) → str

Return the directory path for iteration ite.

Parameters:

ite (int)

Returns:

<prj_name>/ite_NNNN/

Return type:

str

iteration_files(ite) → _IterationFiles

Return the standard file-path bundle for iteration ite.

Parameters:

ite (int) – Use 0 for the initial state.

Return type:

_IterationFiles

path_map(ite, ref=1) → str

Path to the full reference map for iteration ite.

Parameters:

• ite (int)

• ref (int, optional) – 1-based class index (default 1).

Return type:

str

path_halfmap(ite, ref=1) → tuple[str, str]

Paths to the two half-maps for iteration ite.

Returns:

(half1_path, half2_path)

Return type:

tuple of str

path_mask(ite, ref=1) → str

Path to the soft mask for iteration ite.

Return type:

str

path_refstxt(ite) → str

Path to the .refstxt file for iteration ite.

Return type:

str

path_ptcls(ite) → str

Path to the .ptclsraw file for iteration ite.

Return type:

str

path_map_rec(ite) → str

Base path prefix used by the averager when reconstructing iteration ite.

The averager appends _classNNN.mrc, _classNNN_half1.mrc, etc. to this prefix.

Returns:

<prj_name>/ite_NNNN/map

Return type:

str

Data Access

get_map(ite, ref=1) → ndarray

Load and return the reference map for iteration ite.

Return type:

numpy.ndarray

get_ptcls(ite) → Particles

Load and return the particles for iteration ite.

Return type:

Particles

get_cc(ite, ref=1) → ndarray

Per-particle CC scores for iteration ite, reference ref.

Return type:

numpy.ndarray, shape (N,)

get_fsc(ite, ref=1) → ndarray

Compute the FSC curve for iteration ite, reference ref.

Return type:

numpy.ndarray

map_change(ite, ref=1) → float

L2 norm of the voxel-wise difference between iterations ite and ite-1.

Useful as a convergence monitor: a decreasing value indicates the reference is stabilising.

Parameters:

• ite (int) – Iteration number (≥ 1).

• ref (int, optional) – 1-based reference index. Default: 1.

Return type:

float