susan.project.diagnostics

Diagnostic tools for subtomogram averaging projects.

Functions here are read-only: they never modify project files.

susan.project.diagnostics.bandpass_shell_sweep(sta: SubtomoAvgBase, ite: int, shell_hw: int = 5, threshold: float = 0.01, shell_pick: str = 'first', clear_max_res: bool = True, save_cc: str = None, fpix_max: int = None)

Measure per-particle, per-projection signal as a function of resolution.

For each bandpass shell centred on successive Fourier-pixel frequencies, a 2-D alignment is run with no angular or translational search to collect the per-projection CC scores. The result is a (n_ptcl, n_proj) array of the resolution of the shell selected by shell_pick among those in which each projection shows signal above threshold.

Parameters:

• sta (SubtomoAvgBase (or subclass)) – Project object. Only box_size, list_gpus_ids, path_refstxt(), path_ptcls(), tomogram_file, fpix2A() (for the pixel size) and aligner.halfsets_independ are read. The half-set policy is inherited from the project’s own aligner so the sweep matches how the iteration was actually aligned.

• ite (int) – Iteration whose particles and reference are used.

• shell_hw (int, optional) – Half-width of each bandpass shell in Fourier pixels. Default: 5.

• threshold (float, optional) – Fraction of the global maximum positive CC used as the “above noise” cut-off. The absolute threshold is computed as threshold * max(prj_cc[prj_cc > 0]). Default: 0.01.

• shell_pick ({'first', 'last'}, optional) – Which threshold crossing defines the cut-off, with shells ordered from low to high frequency. 'first' (default) reports the last shell of the leading above-threshold run — it stops at the first shell that drops below the cut-off, so an isolated high-frequency spike cannot pull the estimate out; 'last' reports the highest-frequency shell above the cut-off anywhere in the sweep, ignoring any dips in between. The two agree when the CC decays monotonically.

• clear_max_res (bool, optional) – Run the sweep on a temporary copy of the particles with def_mres zeroed, deleted afterwards. The aligner caps the per-projection lowpass at def_mres whenever it is positive, so without this the CC is exactly zero past the cap already stored in the input and the sweep can only recover the number it was handed: on EMPIAR-10064 the shell at which the CC first vanishes has a rank correlation of -1.0000 with the input def_mres. Turn it off only to check a sweep against an existing cap on purpose. Default: True.

• save_cc (str, optional) – If given, write the full (n_shells, n_ptcl, n_proj) CC array to this MRC file path.

• fpix_max (int, optional) – Maximum Fourier-pixel shell centre. Defaults to box_size // 2 - 1.

Returns:

max_res_A – Resolution (in Å) of the selected shell in which each projection carries signal above threshold. Particles/projections with no signal in any shell are assigned the lowest-resolution shell value.

Return type:

numpy.ndarray, shape (n_ptcl, n_proj)

Inter-iteration deltas

susan.project.diagnostics.estimate_delta_3D_offset(sta, ite, ref=0, pixels=True)

Per-particle 3-D translation change ‖Δt‖ between ite-1 and ite.

Parameters:

pixels (bool, optional) – If True (default) the result is returned in pixels, using sta.pix_size; if False it is returned in Ångströms.

Returns:

Shift-change magnitude (pixels or Å), aligned to iteration ite’s particles (file order). Particles absent from ite-1 are NaN.

Return type:

numpy.ndarray, shape (n_ptcl,)

susan.project.diagnostics.estimate_delta_2D_offset(sta, ite, pixels=True)

Per-particle, per-projection 2-D shift change ‖Δt‖.

Parameters:

pixels (bool, optional) – If True (default) the result is returned in pixels, using sta.pix_size; if False it is returned in Ångströms.

Returns:

Shift-change magnitude (pixels or Å), aligned to iteration ite’s particles (file order). NaN for particles absent from ite-1 and for projections disabled (prj_w<=0) in either iteration.

Return type:

numpy.ndarray, shape (n_ptcl, n_proj)

susan.project.diagnostics.estimate_delta_3D_angle(sta, ite, ref=0, degrees=True)

Per-particle orientation change, decomposed into cone and in-plane.

Parameters:

degrees (bool, optional) – If True (default) the angles are returned in degrees; if False in radians.

Returns:

[0] cone (out-of-plane), [1] in-plane (twist), units per degrees, aligned to iteration ite’s particles (file order). Particles absent from ite-1 are NaN.

Return type:

numpy.ndarray, shape (2, n_ptcl)

susan.project.diagnostics.estimate_delta_2D_angle(sta, ite, degrees=True)

Per-particle, per-projection orientation change (cone + in-plane).

Parameters:

degrees (bool, optional) – If True (default) the angles are returned in degrees; if False in radians.

Returns:

[0] cone, [1] in-plane (units per degrees), aligned to iteration ite’s particles (file order). NaN for particles absent from ite-1 and for disabled projections. In 2-D per-projection alignment the cone component is usually weakly constrained — the in-plane slice is the meaningful one for angle_sigma.

Return type:

numpy.ndarray, shape (2, n_ptcl, n_proj)

susan.project.diagnostics.estimate_delta_3D_total_angle(sta, ite, ref=0, degrees=True)

Per-particle total (geodesic) orientation change between iterations.

Unlike estimate_delta_3D_angle(), this returns a single angle per particle — the full rotation magnitude carrying the previous pose onto the current one, combining cone and in-plane into one value.

Parameters:

degrees (bool, optional) – If True (default) the angle is returned in degrees; if False in radians.

Returns:

Total rotation magnitude (units per degrees), aligned to iteration ite’s particles (file order). Particles absent from ite-1 are NaN.

Return type:

numpy.ndarray, shape (n_ptcl,)

susan.project.diagnostics.estimate_delta_2D_total_angle(sta, ite, degrees=True)

Per-particle, per-projection total (geodesic) orientation change.

Single-angle counterpart of estimate_delta_2D_angle().

Parameters:

degrees (bool, optional) – If True (default) the angle is returned in degrees; if False in radians.

Returns:

Total rotation magnitude (units per degrees), aligned to iteration ite’s particles (file order). NaN for particles absent from ite-1 and for disabled projections.

Return type:

numpy.ndarray, shape (n_ptcl, n_proj)

susan.project.diagnostics.estimate_delta_defocus(sta, ite)

Per-particle, per-projection defocus change √(ΔU² + ΔV²).

Returns:

Defocus-change magnitude in Å, aligned to iteration ite’s particles (file order). NaN for particles absent from ite-1 and for disabled projections.

Return type:

numpy.ndarray, shape (n_ptcl, n_proj)

Prior sigma estimates

susan.project.diagnostics.estimate_sigma_3D_offset(sta, ite, ref=0, pixels=True, clip_pct=5.0, scale=1.0)

Estimate offset_sigma for 3-D alignment.

Reduces estimate_delta_3D_offset() (3 translational DOF) to a per-axis Gaussian width.

Parameters:

pixels (bool, optional) – If True (default) the result is in pixels (using sta.pix_size) — the unit the engine’s offset_sigma expects; if False it is in Ångströms.

susan.project.diagnostics.estimate_sigma_2D_offset(sta, ite, pixels=True, clip_pct=5.0, scale=1.0)

Estimate offset_sigma for 2-D per-projection alignment.

Reduces estimate_delta_2D_offset() (2 translational DOF) to a per-axis Gaussian width.

Parameters:

pixels (bool, optional) – If True (default) the result is in pixels (using sta.pix_size); if False it is in Ångströms.

susan.project.diagnostics.estimate_sigma_3D_angle(sta, ite, ref=0, degrees=True, clip_pct=5.0, scale=1.0)

Estimate the angular prior width for 3-D alignment.

Parameters:

degrees (bool, optional) – If True (default) the result is in degrees — the unit the engine’s angle_sigma expects; if False in radians.

Returns:

(sigma_cone, sigma_inplane) (units per degrees). angle_sigma is a single engine knob applied to both axes; pass whichever you prefer (or their combination — e.g. max) to the next iteration.

Return type:

(float, float)

susan.project.diagnostics.estimate_sigma_2D_angle(sta, ite, degrees=True, clip_pct=5.0, scale=1.0)

Estimate the angular prior width for 2-D alignment.

Parameters:

degrees (bool, optional) – If True (default) the result is in degrees; if False in radians.

Returns:

(sigma_cone, sigma_inplane) (units per degrees), pooled over all projections. The in-plane value is normally the relevant one for angle_sigma in 2-D mode.

Return type:

(float, float)

susan.project.diagnostics.estimate_sigma_3D_total_angle(sta, ite, ref=0, degrees=True, clip_pct=5.0, scale=1.0)

Estimate a single combined angular prior width for 3-D alignment.

Reduces estimate_delta_3D_total_angle() (the geodesic rotation, 3 rotational DOF: cone + in-plane) to one Gaussian width — a single value usable directly as angle_sigma, without choosing between the cone and in-plane components.

Parameters:

degrees (bool, optional) – If True (default) the result is in degrees — the unit the engine’s angle_sigma expects; if False in radians.

Returns:

Combined angular width (units per degrees).

Return type:

float

susan.project.diagnostics.estimate_sigma_2D_total_angle(sta, ite, degrees=True, clip_pct=5.0, scale=1.0)

Estimate a single combined angular prior width for 2-D alignment.

Single-value counterpart of estimate_sigma_2D_angle(), reducing the geodesic rotation (estimate_delta_2D_total_angle(), 3 rotational DOF) pooled over all projections.

Parameters:

degrees (bool, optional) – If True (default) the result is in degrees; if False in radians.

Returns:

Combined angular width (units per degrees).

Return type:

float

susan.project.diagnostics.estimate_sigma_defocus(sta, ite, clip_pct=5.0, scale=1.0)

Estimate defocus_sigma (Å) for CTF refinement.

Reduces estimate_delta_defocus() (2 defocus DOF, dU/dV) to a Gaussian width. For non-astigmatism refinement (dV = dU) the result is still a usable scale, though the engine’s non-astigmatic prior uses a slightly different normalisation.