susan.data.Particles.Geom

class susan.data._PtclsGeom.PtclsGeom

Bases: object

Geometry operations on Particles alignment data.

All methods are static and operate on a Particles instance in-place or return a new one. Accessible as Particles.Geom.

Static Methods

static rot_shift(ptcls, eZYZdeg=None, R=None, t=None, ref_idx=0) → None

Apply a single rotation and/or translation to all particles in-place.

Modifies ali_eu[ref_idx] and ali_t[ref_idx] directly. Supply either eZYZdeg or R, not both.

Parameters:

• ptcls (Particles)

• eZYZdeg (array-like of float (3,), optional) – ZYZ Euler angles in degrees.

• R (ndarray, float32 (3, 3), optional) – Rotation matrix.

• t (array-like of float (3,), optional) – Translation in Ångströms. Default zeros.

• ref_idx (int, optional) – Reference alignment slot to modify. Default 0.

static expand_by_rot_shift(ptcls, eZYZdeg=None, R=None, t=None, ref_idx=0) → Particles

Expand a particle list by applying multiple rotations/translations.

For each particle, produces one output copy per supplied rotation/translation, resulting in n_ptcl × n_transforms particles. Useful for symmetry expansion. Returns a new Particles object; the original is unchanged.

Parameters:

• ptcls (Particles)

• eZYZdeg (array-like, shape (K, 3) or (3,), optional) – ZYZ Euler angles in degrees for each transform.

• R (ndarray, float32, shape (K, 3, 3) or (3, 3), optional) – Rotation matrices. Mutually exclusive with eZYZdeg.

• t (array-like, shape (K, 3) or (3,), optional) – Translations in Ångströms for each transform. Default zeros.

• ref_idx (int, optional) – Reference alignment slot to use as input and output. Default 0.

Return type:

Particles

static enable_by_tilt(ptcls, tomos, tilt_deg_max, tilt_deg_min=0, use_nominal=False) → None

Set per-projection weights based on tilt angle range.

Projections whose absolute tilt angle falls within [tilt_deg_min, tilt_deg_max) are set to weight 1; all others are set to 0. Projections already excluded in the Tomograms metadata (proj_wgt == 0) remain excluded.

Parameters:

• ptcls (Particles) – Modified in-place (prj_w updated).

• tomos (Tomograms)

• tilt_deg_max (float) – Maximum absolute tilt angle to include (degrees).

• tilt_deg_min (float, optional) – Minimum absolute tilt angle to include (degrees). Default 0.

• use_nominal (bool, optional) – If True, use tomos.nominal_tilt_angles instead of the Y component of proj_eZYZ. Default False.

static enable_by_tilt_range(ptcls, tomos, tilt_deg_min, tilt_deg_max, use_nominal=False) → None

Set per-projection weights based on a signed tilt-angle range.

The tilt angle is derived from the full ZYZ rotation matrix of each projection (not from proj_eZYZ[:,1] directly), making it robust to non-canonical Euler-angle storage. The signed angle is defined as the angle between the beam direction and the tomogram Z axis, positive in the direction of increasing stage tilt.

Projections whose signed tilt falls within [tilt_deg_min, tilt_deg_max) are set to weight 1; all others are set to 0. Projections already excluded in the Tomograms metadata (proj_wgt == 0) remain excluded.

Unlike enable_by_tilt(), both bounds are signed, so asymmetric ranges such as (-20, 40) are supported.

Parameters:

• ptcls (Particles) – Modified in-place (prj_w updated).

• tomos (Tomograms)

• tilt_deg_min (float) – Lower bound of the signed tilt range in degrees (inclusive).

• tilt_deg_max (float) – Upper bound of the signed tilt range in degrees (exclusive).

• use_nominal (bool, optional) – If True, use tomos.nominal_tilt_angles directly as the signed stage tilt instead of deriving it from proj_eZYZ. Default False.

static discard_closer(ptcls, min_dist_angs, ref_idx=0, verbose=False) → Particles

Remove duplicate/overlapping particles closer than a minimum distance.

Within each tomogram, particles are sorted by descending ali_cc and greedily kept; any particle within min_dist_angs of an already kept particle is discarded. Returns a new Particles object.

Parameters:

• ptcls (Particles)

• min_dist_angs (float) – Minimum allowed inter-particle distance in Ångströms.

• ref_idx (int, optional) – Reference index used to compute effective positions (position + ali_t[ref_idx]). Default 0.

• verbose (bool, optional) – Print per-tomogram particle counts. Default False.

Return type:

Particles

static get_min_distance(ptcls, ref_idx=0) → ndarray

Return the distance to the nearest neighbour for every particle.

Computed per tomogram using effective positions (position + ali_t[ref_idx]).

Parameters:

• ptcls (Particles)

• ref_idx (int, optional) – Reference index for the translation offset. Default 0.

Returns:

Nearest-neighbour distance in Ångströms for each particle.

Return type:

ndarray, float32, shape (M,)