susan.data.Particles¶

class susan.data.Particles(filename=None, n_ptcl=0, n_proj=0, n_refs=0)[source]¶

Bases: object

Per-particle metadata container for SUSAN subtomogram averaging.

Stores coordinates, 3-D alignment, per-projection 2-D alignment, CTF defocus, and half-set assignments for a set of particles.

Two auxiliary modules are accessible as class attributes:

Particles.Geom (PtclsGeom) — geometry operations: in-place rotation/translation, symmetry expansion, tilt-angle filtering, and distance-based deduplication.
Particles.MRA (PtclsMRA) — multi-reference alignment helpers: duplicating and selecting reference slots.

File format: binary .ptclsraw (magic SsaPtcl1 + uint32 header + one packed float32 record per particle).

Identification & bookkeeping

ptcl_id: ndarray, uint32, shape(M)¶: User-assigned particle identifier.

tomo_id: ndarray, uint32, shape(M)¶: Tomogram ID the particle belongs to (matches Tomograms.tomo_id).

tomo_cix: ndarray, uint32, shape(M)¶: Contiguous index into the Tomograms array.

Deprecated since version Not: read by SUSAN anymore. The index is derived from tomo_id through Tomograms.get_cix(), so it cannot go stale when a particle set is paired with a different Tomograms. The field is still stored in the .ptclsraw file for older SUSAN versions; refresh it with update_tomo_cix() before saving.

ref_cix: ndarray, uint32, shape(M)¶: Current reference-class assignment (0-based index).

half_id: ndarray, uint32, shape(M)¶: Half-set label: 1 or 2. 0 means unassigned.

extra_1, extra_2: User-defined auxiliary fields.

Position & 3-D alignment

position: ndarray, float32, shape(M, 3)¶: Particle centre in Ångströms (X, Y, Z).

ali_eu: ndarray, float32, shape(R, M, 3)¶: 3-D alignment: ZYZ Euler angles in radians, one set per reference. Maps the reference onto the tomogram, and reads (cone azimuth, cone polar, in-plane): a pure in-plane search moves the last angle. Note the mirrored reading of prj_eu; see angular conventions.

ali_t: ndarray, float32, shape(R, M, 3)¶: 3-D alignment: translations (X, Y, Z) in Ångströms.

ali_cc: ndarray, float32, shape(R, M)¶: 3-D cross-correlation score per reference.

ali_w: ndarray, float32, shape(R, M)¶: 3-D alignment weight per reference.

Per-projection 2-D alignment

prj_eu: ndarray, float32, shape(M, P, 3)¶: Per-projection 2-D alignment: ZYZ Euler angles in radians. Applied in the projection frame, so the triplet reads mirrored with respect to ali_eu — (in-plane, cone polar, cone azimuth) — and a pure in-plane search moves the first angle. The cone and in-plane sampling parameters themselves mean the same thing in both searches; see angular conventions.

prj_t: ndarray, float32, shape(M, P, 2)¶: Per-projection 2-D alignment: shifts (X, Y) in Ångströms.

prj_cc: ndarray, float32, shape(M, P)¶: Per-projection cross-correlation score.

prj_w: ndarray, float32, shape(M, P)¶: Per-projection weight (0 = excluded).

CTF

def_U, def_V: Per-projection defocus major/minor axis in Ångströms.

def_ang: ndarray, float32, shape(M, P)¶: Defocus astigmatism angle in degrees.

def_phas: ndarray, float32, shape(M, P)¶: Phase shift in degrees.

def_Bfct: ndarray, float32, shape(M, P)¶

Per-projection B-factor in Å², applied as \(e^{-s^2 B/4}\).

It is part of the CTF model: the reconstruction multiplies it into the CTF, so it enters the Wiener numerator once and the denominator squared, and the division deconvolves it. Use this field for an envelope that the reconstruction should undo. It is never estimated automatically (estimate_ctf only resets it to 0), so it is free for the user to set.

See CryoET Background for how it enters the reconstruction, and contrast with def_ExFl, which has the same form but the opposite effect.

def_ExFl: ndarray, float32, shape(M, P)¶

Per-projection exposure filter (dose) in Å², applied as \(e^{-s^2 D/4}\).

Unlike def_Bfct, it enters the Wiener numerator only, so it is not compensated: it survives into the reconstructed map and permanently attenuates that projection. Use this field for an envelope that the reconstruction should keep, such as dose weighting.

Warning

This field is an output of the aligner, not a user input. Every alignment overwrites it with expfilt_gain * dose, where the dose is estimated from the width of the cross-correlation peak. Setting expfilt_gain = 0 writes zeros rather than preserving the field, so a hand-set value cannot survive an alignment; it is only meaningful between an alignment and a reconstruction. For a user-owned envelope, use def_Bfct instead.

A value of 9999 is the sentinel written when the CC peak width cannot be measured. It zeroes the projection’s contribution to the numerator while that projection still carries its full weight in the denominator.

Only the 'wiener', 'pre_wiener' and 'wiener_ssnr' reconstruction policies apply it; 'none' and 'phase_flip' ignore it.

def_mres: ndarray, float32, shape(M, P)¶: Maximum resolution for CTF fitting in Ångströms.

def_scor: ndarray, float32, shape(M, P)¶: CTF fit score.

Properties

property n_ptcl: int¶

property n_refs: int¶

property n_proj: int¶

Static Methods

static grid_2d(tomograms, step_angstroms=None, step_pixels=None, skip_border_pixels=0, angle_deg_Y=0) → Particles[source]¶

Create a 2-D regular grid of particles at Z=0 across all tomograms.

Positions are placed on an XY grid centred at the tomogram origin. Defocus values are initialised from the Tomograms metadata.

Parameters:

tomograms (Tomograms) – All tomograms must share the same pixel size.
step_angstroms (float, optional) – Grid spacing in Ångströms. Mutually exclusive with step_pixels.
step_pixels (float, optional) – Grid spacing in pixels. Mutually exclusive with step_angstroms.
skip_border_pixels (int or array-like of int (3,), optional) – Pixels to exclude near each tomogram edge. Default 0.
angle_deg_Y (float, optional) – Rotate the grid plane by this angle around Y (degrees). Default 0.

Return type:

Particles

static grid_3d(tomograms, step_angstroms=None, step_pixels=None, skip_border_pixels=0) → Particles[source]¶

Create a 3-D regular grid of particles across all tomograms.

Positions fill the full XYZ volume of each tomogram. Half-sets are assigned by even/odd index; defocus values are initialised from the Tomograms metadata.

Parameters:

tomograms (Tomograms) – All tomograms must share the same pixel size.
step_angstroms (float, optional) – Grid spacing in Ångströms. Mutually exclusive with step_pixels.
step_pixels (float, optional) – Grid spacing in pixels. Mutually exclusive with step_angstroms.
skip_border_pixels (int or array-like of int (3,), optional) – Pixels to exclude near each tomogram edge. Default 0.

Return type:

Particles

static import_data(tomograms, position, tomos_id, ptcls_id=None, randomize_angles=False) → Particles[source]¶

Create a Particles object from external coordinate data.

Converts pixel-space coordinates (relative to tomogram corner) to Ångström-space coordinates centred at the tomogram origin, and initialises defocus from the Tomograms metadata.

Parameters:

tomograms (Tomograms) – All tomograms must share the same pixel size.
position (ndarray, shape (N, 3)) – Particle positions in pixels, relative to the tomogram corner.
tomos_id (array-like, shape (N,)) – Tomogram ID for each particle (must match Tomograms.tomo_id).
ptcls_id (array-like of int, shape (N,), optional) – Particle identifiers. Defaults to 0, 1, …, N−1.
randomize_angles (bool, optional) – If True, initialise ali_eu with random ZYZ Euler angles. Default False.

Return type:

Particles

Methods

sort() → None[source]¶: Sort particles in-place by (tomo_id, ptcl_id).

select(idx) → Particles[source]¶

Return a new Particles containing only the selected entries.

Parameters:: idx (array-like of int or bool) – Integer indices or boolean mask selecting which particles to keep.
Return type:: Particles

append_ptcls(ptcls) → None[source]¶

Append another Particles object to this one in-place.

Both objects must have the same n_proj and n_refs. The combined list is sorted by (tomo_id, ptcl_id) after appending.

Parameters:: ptcls (Particles)

set_weights(in_wgt) → None[source]¶

Set per-projection weights, preserving already-excluded projections.

Multiplies in_wgt by the existing prj_w > 0 mask so that projections already set to zero remain excluded.

Parameters:: in_wgt (array-like, shape (P,) or (M, P)) – New weight values.

halfsets_by_Y() → None[source]¶

Assign half-sets by splitting each tomogram at its Y-median.

Particles above the median Y coordinate get half_id=2; those at or below get half_id=1. Applied per tomogram independently.

halfsets_even_odd()[source]¶: Assign half-sets by even/odd index (half_id alternates 1, 2, 1, 2…).

halfsets_randomize()[source]¶: Assign half-sets randomly (each particle independently drawn from {1, 2}).

update_position(ref_id=0)[source]¶

Absorb the 3-D alignment translation into the particle position.

Adds ali_t[ref_id] to position and resets ali_t[ref_id] to zero. Useful after alignment to make coordinates absolute again.

Parameters:: ref_id (int, optional) – Reference index whose translation to absorb. Default 0.

update_defocus(tomos_info, ref_id=0, z_sign=None)[source]¶

Recompute per-projection defocus values from the current 3-D positions.

For each particle, projects the 3-D position (position + ali_t[ref_id]) onto each tilt projection’s Z-axis and corrects the tomogram-level defocus by the resulting depth offset. Also copies projection weights, astigmatism, B-factor, and CTF scores from the Tomograms metadata.

The depth-to-defocus-offset mapping depends on the defocus sign convention: with the underfocus (positive) convention, δ_z and dZ have opposite signs; with the overfocus (negative) convention, they have the same sign. The effective Z coefficient is therefore multiplied by sign(base_defocus) so the addition stays consistent with whatever convention the tomogram’s defocus values were stored in.

Parameters:

tomos_info (Tomograms) – Tomogram metadata providing tilt geometries and base defocus values.
ref_id (int, optional) – Reference index whose translation is included in the position. Default 0.
z_sign (float, optional) – Override the Z-axis handedness (+1 or −1). If None (default), tomos_info.handedness is used per tomogram. This value is still combined with the base-defocus sign internally.

export_positions(tomograms, ref_cix=0, tomo_id=None) → ndarray[source]¶

Convert particle positions back to pixel coordinates relative to the tomogram corner.

Inverse of the conversion done by import_data. Useful for exporting coordinates to IMOD or other tools that expect pixel-space positions.

Parameters:

tomograms (Tomograms) – Provides pixel size and tomogram dimensions.
ref_cix (int, optional) – Reference index whose translation is included. Default 0.
tomo_id (int, optional) – Restrict the output to the particles of this tomogram, in their stored order. All the tomograms must share the same pixel size when converting the whole set; selecting one tomogram uses its own pixel size, so a mixed-binning set can still be exported one tomogram at a time.

Returns:

Positions in pixels, relative to the tomogram corner. M is the number of particles of tomo_id when it is given.

Return type:

ndarray, float32, shape (M, 3)

save(filename) → None[source]¶

Save to a .ptclsraw binary file.

Parameters:: filename (str) – Output path; must have a .ptclsraw extension.

x(ref_idx=0) → ndarray[source]¶: Absolute X coordinate: position[:,0] + ali_t[ref_idx,:,0] (Ångströms).

y(ref_idx=0) → ndarray[source]¶: Absolute Y coordinate: position[:,1] + ali_t[ref_idx,:,1] (Ångströms).

z(ref_idx=0) → ndarray[source]¶: Absolute Z coordinate: position[:,2] + ali_t[ref_idx,:,2] (Ångströms).

pos(ref_idx=0) → ndarray[source]¶: Absolute (X, Y, Z) positions: position + ali_t[ref_idx], shape (M, 3), Ångströms.