susan.modules.CtfEstimator

class susan.modules.CtfEstimator

Bases: object

CTF estimation engine.

Wraps the susan_estimate_ctf binary. Estimates per-tilt defocus and astigmatism from the tilt-series stacks. Configure the attributes, then call estimate().

Attributes

list_gpus_ids

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

Type:

list of int

resolution_max

Highest resolution, in Ångströms, included in the CTF fit. It sets the target sampling of the linearization (new_apix = resolution_max/2) and so the outer edge of every spectrum the estimator works on. Rarely needs changing. Default: 7.

Type:

float

defocus_angstroms

Defocus search range (min, max) in Ångströms. Bounds the peak search in the linearized power spectrum, where defocus maps linearly onto the bin index. It also frames the ellipse fit report. Default: range_params(10000, 65000).

Type:

range_params

resolution_thres

Correlation threshold that sets Defocus.max_res. The fitted CTF is correlated against the astigmatism-compensated radial average in sliding windows; the resolution limit is the highest frequency where that correlation stays above this value. Lower values report a more optimistic limit. Default: 0.75.

Type:

float

overfocus

If True, the signal is assumed to be overfocus and the estimated defocus is returned as a negative value; if False, it is assumed to be underfocus and the defocus is returned as a positive value. Default: False.

Type:

bool

est_phase_shift

If True, the hybrid refinement searches for an additional per-projection phase shift (Volta phase plate use case) and writes it to Defocus.ph_shft. If False, the phase-shift search is skipped and ph_shft is forced to 0 for every projection; defocus refinement still runs normally. Default: True.

Type:

bool

dechirp_cs

If True, the spherical-aberration contribution is removed from the linearized signal before the peak search. Under r = s**2 its phase is exactly quadratic in r with a coefficient that holds only microscope constants, so it is removed without knowing the defocus. This sharpens the peak and removes a bias that grows quickly as resolution_max approaches 2*pix_size. Default: True.

Type:

bool

est_initial_snr

If True, an initial per-projection weight is estimated from the depth of the Thon ring modulation and written as a ninth column of defocus.txt, which susan.data.Tomograms.set_defocus() loads into proj_wgt (and update_defocus then copies into the per-particle prj_w). The weight is proportional to the SSNR of the projection and normalised so the best tilt of each stack is 1; empty projections get 0. If False, the column is written as 1 for every projection, preserving the previous behaviour of uniform weights. Default: False.

Type:

bool

verbosity

Amount of progress information printed to the console, as in every other module: 0 silent, 1 basic, 2 full. Default: 1.

Type:

int

log_level

Amount of debug data written to out_dir. 0 writes only defocus.txt; 1 adds the per-projection SVG reports and the main diagnostic volumes; 2 adds every intermediate power spectrum. This is what verbose used to control. Default: 0.

Type:

int

Methods

get_args(out_dir, tomos_file, ptcls_in, box_size)

Build the command-line argument string for susan_estimate_ctf.

Parameters:

• out_dir (str) – Output directory where per-tilt CTF results are written.

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

• ptcls_in (str) – Path to the input .ptclsraw particles file (used to select regions of interest).

• box_size (int) – Patch size in pixels used for CTF estimation.

Returns:

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

Return type:

str

estimate(out_dir, tomos_file, ptcls_in, box_size, tomos_out=None)

Execute the CTF estimation and return a tomograms object with the newly estimated defocus values applied.

After the susan_estimate_ctf binary completes, tomos_file is re-loaded and each tomogram’s defocus parameters are refreshed from <out_dir>/Tomo<tomo_id:05d>/defocus.txt.

Parameters:

• out_dir (str) – Output directory for CTF results.

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

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

• box_size (int) – Patch size in pixels.

• tomos_out (str, optional) – If given, the updated tomograms object is saved to this path (.tomostxt).

Returns:

Tomograms loaded from tomos_file with the newly estimated defocus values applied for every tomogram.

Return type:

susan.data.Tomograms

Raises:

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