susan.data.Tomograms

class susan.data.Tomograms(filename=None, n_tomo=0, n_proj=0)[source]

Bases: object

Per-tomogram metadata container for SUSAN workflows.

Holds geometry, CTF, and acquisition parameters for a set of tomograms. Each tomogram entry stores per-projection tilt angles, alignment shifts, defocus values, and microscope optics.

File format: plain-text .tomostxt (key-value header per tomogram followed by one data row per projection).

Geometry & acquisition

tomo_id: ndarray, uint32, shape(N)

User-assigned integer ID for each tomogram.

tomo_size: ndarray, uint32, shape(N, 3)

Tomogram dimensions (X, Y, Z) in pixels.

tomo_position: ndarray, float32, shape(N, 3)

Origin offset (X, Y, Z) of the tomogram in Ångströms, subtracted from the particle position before projecting. Same units as Particles.position. Defaults to (0, 0, 0), which is a no-op.

stack_file: list of str, length N

Path to the tilt-series image stack for each tomogram.

stack_size: ndarray, uint32, shape(N, 3)

Stack dimensions (X, Y, n_proj) in pixels.

num_proj: ndarray, uint32, shape(N)

Number of valid projections for each tomogram.

pix_size: ndarray, float32, shape(N)

Pixel size in Ångströms.

proj_eZYZ: ndarray, float32, shape(N, P, 3)

Per-projection tilt orientation as ZYZ Euler angles in degrees.

proj_shift: ndarray, float32, shape(N, P, 2)

Per-projection in-plane shifts (X, Y) in Ångströms.

proj_wgt: ndarray, float32, shape(N, P)

Per-projection weight (0 = excluded, 1 = active).

doses: ndarray, float32, shape(N, P)

Cumulative electron dose per projection in e⁻/Ų.

nominal_tilt_angles: ndarray, float32, shape(N, P)

Stage tilt angles in degrees (from the .tlt file).

Optics

voltage: ndarray, float32, shape(N)

Accelerating voltage in kV. Default 300.

sph_aber: ndarray, float32, shape(N)

Spherical aberration Cs in mm. Default 2.7.

amp_cont: ndarray, float32, shape(N)

Amplitude contrast fraction. Default 0.07.

handedness: ndarray, float32, shape(N)

Z-axis handedness (+1 or −1). Default −1.

CTF

def_U, def_V

Per-projection defocus major/minor axis in Ångströms.

def_ang: ndarray, float32, shape(N, P)

Defocus astigmatism angle in degrees.

def_phas: ndarray, float32, shape(N, P)

Phase shift in degrees.

def_Bfct: ndarray, float32, shape(N, P)

Per-projection B-factor in Ų, applied as \(e^{-s^2 B/4}\). Part of the CTF model, and therefore compensated: the Wiener inversion deconvolves it. Seeds susan.data.Particles.def_Bfct.

def_ExFl: ndarray, float32, shape(N, P)

Per-projection exposure filter (dose) in Ų, applied as \(e^{-s^2 D/4}\). Despite sharing its form with def_Bfct, it is uncompensated: it enters the Wiener numerator only, so it persists in the reconstructed map. Seeds susan.data.Particles.def_ExFl, which the aligner then overwrites on every run. See CryoET Background.

def_mres: ndarray, float32, shape(N, P)

Maximum resolution used for CTF fitting in Ångströms.

def_scor: ndarray, float32, shape(N, P)

CTF fit score.

ctf_scale_factor: ndarray, float32, shape(N, P)

Per-projection CTF scale factor (RELION convention).

Properties

property n_tomos: int

Return the number of tomograms stored.

property n_projs: int

Return the maximum number of projections per tomogram.

Methods

set_stack(idx, stk_name)[source]

Populate tomogram entry from a tilt-series stack file.

Reads the MRC header to fill stack_file, stack_size, pix_size, and num_proj. Projection weights are set to 1 for all valid projections and 0 for the rest.

Parameters:

  • idx (int) – Tomogram index to update.

  • stk_name (str) – Path to the MRC tilt-series stack.

set_angles(idx, tlt_filename, xf_filename=None, xf_apix=None)[source]

Set per-projection tilt angles and optional IMOD alignment transforms.

If only tlt_filename is provided, tilt angles are set directly as the Y Euler angle (ZYZ convention) with no in-plane shifts. If xf_filename is also provided, the IMOD .xf affine transforms are combined with the tilt angles to produce full ZYZ orientations and X/Y shifts in Ångströms.

Parameters:

  • idx (int) – Tomogram index to update.

  • tlt_filename (str) – Path to a IMOD .tlt file with one tilt angle per line (degrees).

  • xf_filename (str, optional) – Path to a IMOD .xf alignment transform file.

  • xf_apix (float, optional) – Pixel size to use when converting .xf shifts to Ångströms. Defaults to pix_size[idx] if not given.

set_defocus(idx, def_file, skip_max_res=True)[source]

Load CTF defocus parameters from file into a tomogram entry.

Supports two file formats:

  • .defocus — IMOD CTFPlotter output (versions 2 and 3). Version 2 stores one isotropic defocus per projection; version 3 stores astigmatic defocus (def_U, def_V, def_ang).

  • .txt — SUSAN per-projection text format with eight columns: def_U, def_V, def_ang, def_phas, def_Bfct, def_ExFl, def_mres, def_scor.

Projections the CTF estimator flagged as empty (blank frames, written out with def_U == def_V == 0) have their projection weight zeroed so they are excluded from downstream alignment and reconstruction.

Parameters:

  • idx (int) – Tomogram index to update.

  • def_file (str) – Path to the defocus file (.defocus or .txt).

  • skip_max_res (bool, optional) – If True (default), zero out def_mres after loading so the stored maximum-resolution limit is ignored during processing.

save(filename)[source]

Save to a .tomostxt file.

Parameters:

filename (str) – Output path; must have a .tomostxt extension.

Notes

Unset entries (see get_is_set()) are skipped, so a preallocated object can be over-dimensioned and only partially filled.

Raises:

ValueError – If tomo_id is not unique: the IDs are the key particles are matched against, so duplicates cannot be resolved.