susan.data.TiltRangeSelector¶

class susan.data.TiltRangeSelector(tomograms, tilt_deg_min, tilt_deg_max, angle_source='eZYZ_Y')[source]¶

Bases: object

Build per-tomogram projection masks for a signed tilt range and emit reduced Tomograms / Particles on the surviving projections.

The selector is built once from a source Tomograms and a signed tilt range [tilt_deg_min, tilt_deg_max). For each tomogram it computes the indices of projections whose canonicalised signed tilt falls within that range and that are currently active (proj_wgt > 0). The same selector can then be applied to multiple inputs that share the projection layout — typically a b1 and a b2 Tomograms produced via bin() — so the index arithmetic only happens once.

The reduced output uses a single rectangular per-projection axis of length new_n_projs = max_t(kept_count[t]); tomograms keeping fewer projections pad the trailing slots with zeros (proj_wgt = 0). Each rewritten stack MRC contains only that tomogram’s kept slices, so stack_size[t, 2] = kept_count[t].

Tilt convention

Rmat_eZYZ (the canonical decomposition used throughout SUSAN) places β in [0, π], so a stage tilt of, e.g., −60° is stored as roughly (±π, 60°, ±π). The selector reads proj_eZYZ, decomposes the rotation matrix, and switches to the equivalent representation (α∓π, −β, γ∓π) whenever |α| > π/2. This yields a signed tilt β ∈ [−90°, 90°] with the in-plane component near zero, which is what one usually thinks of as “the tilt angle”. The canonicalised angles are used only for the filter test; the emitted new.proj_eZYZ keeps SUSAN’s original convention.

Note

For lightweight filtering that does not need on-disk reduction, susan.data.Particles.Geom.enable_by_tilt_range() zeros the relevant prj_w slots without touching the projection axis or the MRC stacks.

Attributes

tilt_deg_min: float¶: Signed lower bound of the kept range (inclusive), in degrees.

tilt_deg_max: float¶: Signed upper bound of the kept range (exclusive), in degrees.

new_n_projs: int¶: Per-projection axis length of the reduced Tomograms / Particles.

tag: str¶: Filename tag derived from the bounds, e.g. 'tlt_m60p60' for [-60, 60) and 'tlt_m45d5p45d5' for [-45.5, 45.5). m / p mark sign; d replaces the decimal point.

Properties

property kept_indices: list[ndarray]¶: List of length n_tomos; each entry holds the original projection indices kept for that tomogram, as int32 arrays.

property kept_count: ndarray¶: uint32 array of length n_tomos with the per-tomogram kept-projection count.

Methods

to_tomograms(tomograms, write_stacks=True, in_subfolder=True, filename=None) → Tomograms[source]¶

Emit a reduced Tomograms on the kept projections.

The selector’s kept-index list is applied to tomograms — which may differ from the source used to build the selector, as long as the projection layout matches (same n_tomos, same tomo_id ordering, and num_proj[t] at least as large as the source’s). This lets the same selector reduce a b1 and a b2 Tomograms consistently.

Parameters:

tomograms (Tomograms or str) – Tomograms to reduce, or a path to a .tomostxt file.
write_stacks (bool, optional) – If True (default), each input stack MRC is read and a new MRC containing only the kept projections is written. If False, the new stack_file entries keep the input paths and stack_size[:, 2] is left equal to the kept count (the caller is responsible for slicing at read time).
in_subfolder (bool, optional) – If True (default), each rewritten stack is placed in a <tag>/ sibling directory next to the input stack; if False, written alongside with the tag inserted into the stem. Matches the behaviour of Tomograms.bin().
filename (str, optional) – If given, also save the reduced Tomograms to this .tomostxt file.

Returns:

New Tomograms with per-projection arrays of length new_n_projs.

Return type:

Tomograms

to_particles(particles, filename=None) → Particles[source]¶

Emit a reduced Particles on the kept projections.

Slices prj_eu, prj_t, prj_cc, prj_w and the per- particle defocus arrays along the per-projection axis, using each particle’s tomo_id to look up the matching kept-index list. Non-projection fields (positions, alignments, identifiers, half-sets) are copied verbatim.

Defocus values are not recomputed. If you want them rederived from the reduced tomograms, call Particles.update_defocus(new_tomos) on the returned object.

Parameters:

particles (Particles or str) – Particles to reduce, or a path to a .ptclsraw file.
filename (str, optional) – If given, also save the reduced Particles to this .ptclsraw file.

Returns:

New Particles with per-projection arrays of length new_n_projs.

Return type:

Particles