susan.modules.CtfRefiner

class susan.modules.CtfRefiner[source]

Bases: object

Per-particle CTF refinement engine.

Wraps the susan_ctf_refiner binary. Jointly refines defocus, tilt angles, and in-plane shifts for each particle. Configure the attributes, then call refine() (single-node) or refine_mpi() (multi-node MPI).

Attributes

list_gpus_ids

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

Type:

list of int

bandpass

Frequency bandpass applied during refinement. Default: bandpass(0, -1, 2) (full range, 2-pixel rolloff).

Type:

bandpass

extra_padding

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

Type:

int

padding_type

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

Type:

str

normalize_type

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

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: 'cfsc_substack'.

Type:

str

halfsets_independ

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

Type:

bool

refine_astigmatism

Refine per-particle astigmatism (def_U, def_V, def_ang). Default: False.

Type:

bool

phase_flip

Apply CTF phase-flipping to the projections instead of full CTF multiplication during refinement. Useful when the data is noisy or to prevent overfitting. Default: False.

Type:

bool

defocus_angstroms

Defocus search range and step in Ångströms. Default: search_params(1000, 100).

Type:

search_params

angles

Tilt-angle search range and step in degrees. Default: search_params(2, 1).

Type:

search_params

phase_shift_deg

Phase-shift search range and step in sexagesimal degrees (converted to radians before being passed to the binary). span = 0 disables the search (single iteration at the stored per-projection value). Useful for Volta phase-plate data where the plate setting drifts. Default: search_params(0, 1).

Type:

search_params

offset

In-plane translational search range and step. Default: offset_params([4, 4, 4], 1, 'circle').

Type:

offset_params

ssnr

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

Type:

ssnr

offset_sigma

Width (pixels) of a Gaussian prior on the translation magnitude. Down-weights large in-plane shifts during the joint (defocus, phase-shift, translation) argmax — the per-point score becomes CC(t) · exp(−|t|² / (2·offset_sigma²)). Raw CC values are preserved in stats and downstream outputs.

0 (default) disables the prior. Typical useful values lie between offset.span / 4 (aggressive) and offset.span / 2 (mild). Default: 0 (disabled).

Type:

float

defocus_sigma

Width (Ångströms) of a Gaussian prior on the isotropic defocus deviation |(dU, dV)|. Pulls the per-tilt argmax toward the starting defocus, the main lever to stop noise-driven defocus drift in low-signal tilts. Form: exp(−(dU² + dV²) / (2·defocus_sigma²)). In non-astigmatism mode dV = dU so the formula reduces to exp(−dU² / defocus_sigma²) — the same σ value is then the “1/e along dU” radius.

0 (default) disables. Typical starting values: defocus_angstroms.span / 4 (aggressive) to defocus_angstroms.span / 2 (mild). Default: 0 (disabled).

Type:

float

phase_sigma_deg

Width (sexagesimal degrees) of a Gaussian prior on the phase-shift deviation. Converted to radians before being passed to the binary. Form: exp(−dP² / (2·phase_sigma_rad²)).

0 (default) disables. Default: 0 (disabled).

Type:

float

mpi

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

Type:

mpi_params

verbosity

Verbosity level passed to the binary. Default: 0.

Type:

int

Methods

Set the in-plane offset search range.

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].

  • 3-element sequence — [X, Y, Z].

Raises:

ValueError – If off_range has more than 3 elements.

get_args(ptcls_out, refs_file, tomos_file, ptcls_in, box_size)[source]

Build the command-line argument string for susan_ctf_refiner.

Parameters:

  • ptcls_out (str) – Path for the output .ptclsraw file with refined CTF parameters.

  • 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.

Returns:

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

Return type:

str

refine(ptcls_out, refs_file, tomos_file, ptcls_in, box_size)[source]

Execute the CTF refinement 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_ctf_refiner binary returns a non-zero exit code.

refine_mpi(ptcls_out, refs_file, tomos_file, ptcls_in, box_size)[source]

Execute the CTF refinement 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.