susan.project.STA

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

Bases: object

Subtomogram averaging project manager.

Manages an STA project stored on disk. If box_size is provided the project directory prj_name is created (or reused) and a metadata file is written. If box_size is omitted the constructor reads the existing project.

The main entry point for automated workflows is execute_iteration(). Lower-level helpers (exec_estimation(), exec_particle_selection(), exec_averaging(), exec_postprocessing()) can also be called individually for custom pipelines.

Project files

prj_name: str

Project directory path. Set by the constructor.

box_size: int

Subvolume box size in pixels. Set by the constructor.

tomogram_file: str

Path to the .tomostxt file used throughout the project.

initial_reference: str

Path to the initial .refstxt file (iteration 0 reference).

initial_particles: str

Path to the initial .ptclsraw file (iteration 0 particles).

GPU & processing

list_gpus_ids: list of int

GPU device IDs forwarded to aligner, averager, and ctf_refiner at execution time. Default: [0].

Iteration control

iteration_type: int or str

Type of processing step executed by execute_iteration():

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 for reconstruction (by cross-correlation score within each half-set). Must be in (0, 1]. Default: 0.8.

fsc_threshold: float

FSC threshold used for resolution estimation in exec_postprocessing(). Default: 0.143.

Modules

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

Aligner instance used for 3-D/2-D alignment steps.

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

Averager instance used for map reconstruction.

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

CtfRefiner instance used for CTF refinement steps.

Advanced

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

MPI launcher forwarded to child modules when mpi.arg > 1. Default: mpi_params('srun -n %d ', 1).

verbosity: int

Verbosity level forwarded to child modules. Default: 1.

max_2d_delta_angstroms: float

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

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

Tilt-angle limit applied during reconstruction. Three forms:

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

• Scalar (int or float) — passes tilt_deg_max to enable_by_tilt(); projections whose absolute tilt exceeds this value are zeroed.

• Two-element sequence [min, max] — passes both signed bounds to enable_by_tilt_range(), allowing asymmetric tilt ranges.

type_2d_shift_fitting: str

Warning

Experimental. This feature may change or be removed in a future release.

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

'tps' fits a regularised thin-plate spline to the per-tilt 2-D shift field: a globally smooth warp sitting between 'affine' (globally rigid) and 'gaussian' (purely local), with stiffness controlled by tps_lambda.

tps_lambda: float

Warning

Experimental. This feature may change or be removed in a future release.

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.

fitting_from_origin: bool

Warning

Experimental. This feature may change or be removed in a future release.

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. This feature may change or be removed in a future release.

If True, apply spatial smoothing to the per-particle CTF defocus deltas (difference from previous iteration) after CTF refinement. The smoother is selected by type_ctf_smoothing. Default: False.

type_ctf_smoothing: str

Warning

Experimental. This feature may change or be removed in a future release.

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

ctf_tps_lambda: float

Warning

Experimental. This feature may change or be removed in a future release.

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. This feature may change or be removed in a future release.

Multi-reference classification weight strategy. False keeps raw CC scores; True normalises them to sum to 1; a float p raises them to the power p before normalising. Default: False.

Note

Retained for backward compatibility. New projects should use SubtomoAvg (or SubtomoAvgSched / SubtomoAvgN2N), which supersede this interface.

Main Method

execute_iteration(ite) → float | ndarray

Run a complete STA iteration.

Executes setup_iteration(), exec_estimation(), exec_particle_selection(), exec_averaging(), and exec_postprocessing() in sequence.

Parameters:

ite (int) – Iteration number (must be ≥ 1). If the iteration directory already exists its results are overwritten.

Returns:

Estimated resolution in Fourier pixels (see exec_postprocessing()).

Return type:

float or numpy.ndarray

Notes

Iteration 0 is the project seed and cannot be processed. In that case 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 a numpy.ndarray of length n_refs filled with that value is returned; otherwise a scalar.

Step-by-step Execution

setup_iteration(ite) → tuple[_iteration_files, _iteration_files]

Prepare the directory and file-path objects for iteration ite.

Creates the iteration directory if needed and validates that the previous iteration’s output files exist.

Parameters:

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

Returns:

(cur, prv) — file-path objects for the current and previous iterations respectively.

Return type:

tuple

Raises:

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

exec_estimation(cur, prv)

Run the alignment or CTF refinement step.

Dispatches to align() (or align_mpi()) for 3-D/2-D iteration types, or to refine() for CTF iterations. The type is determined by iteration_type.

Parameters:

• cur (_iteration_files) – File paths for the current iteration (output).

• prv (_iteration_files) – File paths for the previous iteration (input).

exec_particle_selection(cur, prv)

Select particles and prepare the input for reconstruction.

Performs multi-reference classification (if n_refs > 1), applies optional 2-D shift corrections (max_2d_delta_angstroms, type_2d_shift_fitting) for 2-D alignment and CTF iterations, filters particles by CC score (cc_threshold), and optionally limits the tilt range (max_tilt_reconstruction). The selected particles are saved to cur.ptcl_temp.

Parameters:

• cur (_iteration_files) – File paths for the current iteration.

• prv (_iteration_files) – File paths for the previous iteration.

exec_averaging(cur, prv)

Reconstruct the reference maps and update the .refstxt file.

Calls reconstruct() (or MPI variant), then updates cur.reference with the new map paths.

Parameters:

• cur (_iteration_files) – File paths for the current iteration.

• prv (_iteration_files) – File paths for the previous iteration (provides the mask paths).

exec_postprocessing(cur) → float | ndarray

Compute FSC-based resolution estimates for all references.

Parameters:

cur (_iteration_files) – File paths for the current iteration.

Returns:

Estimated resolution in Fourier pixels at the fsc_threshold level. A scalar for single-reference projects; a 1-D array for multi-reference projects.

Return type:

float or numpy.ndarray

Data Access

get_map(ite, ref=1) → ndarray

Load and return the reference map for iteration ite.

Parameters:

• ite (int) – Iteration number.

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

Returns:

3-D map array.

Return type:

numpy.ndarray

get_ptcls(ite) → Particles

Load and return the particles for iteration ite.

Parameters:

ite (int) – Iteration number.

Returns:

Particle container with aligned positions and scores.

Return type:

Particles

get_cc(ite, ref=1) → ndarray

Return the per-particle cross-correlation scores for iteration ite.

Parameters:

• ite (int) – Iteration number.

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

Returns:

CC scores for all particles assigned to reference ref.

Return type:

numpy.ndarray, shape (N,)

get_fsc(ite, ref=1) → ndarray

Compute and return the FSC curve for iteration ite.

Parameters:

• ite (int) – Iteration number.

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

Returns:

1-D FSC array indexed by Fourier shell.

Return type:

numpy.ndarray

get_name_ptcls(ite) → str

Return the path to the .ptclsraw file for iteration ite.

Parameters:

ite (int) – Iteration number. 0 returns initial_particles.

Returns:

Path to the .ptclsraw file.

Return type:

str

get_name_refstxt(ite) → str

Return the path to the .refstxt file for iteration ite.

Parameters:

ite (int) – Iteration number. 0 returns initial_reference.

Returns:

Path to the .refstxt file.

Return type:

str

get_names_map(ite, ref=1) → str

Return the path to the full reference map for iteration ite.

Parameters:

• ite (int) – Iteration number. 0 returns the path from the initial .refstxt.

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

Returns:

Path to the MRC map file.

Return type:

str

get_names_mask(ite, ref=1) → str

Return the path to the soft mask for iteration ite.

Parameters:

• ite (int) – Iteration number. 0 reads from the initial .refstxt.

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

Returns:

Path to the mask MRC file.

Return type:

str

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

Return the paths to the two half-maps for iteration ite.

Parameters:

• ite (int) – Iteration number. 0 reads from the initial .refstxt.

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

Returns:

(half1_path, half2_path).

Return type:

tuple of str

get_iteration_dir(ite) → str

Return the directory path for iteration ite.

Parameters:

ite (int) – Iteration number (1-based).

Returns:

Path of the form <prj_name>/ite_NNNN/.

Return type:

str

get_iteration_files(ite) → _iteration_files

Return the standard file paths for iteration ite.

For ite < 1 the initial files (initial_particles and initial_reference) are returned.

Parameters:

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

Returns:

Object with attributes ptcl_rslt, ptcl_temp, reference, and ite_dir.

Return type:

_iteration_files