Segment & Annotation Utilities#

Segment slicing (ResIdxSlice, ChainIdxSlice) and annotation helpers. For the atom-selection string languages, see Atom Selection Syntax and Query & Selection.

Segment slicing and annotation helpers for AtomArray and AtomArrayStack.

For the atom-selection string languages (the sel('...') / path-selection DSL and the pandas-like query language), see atomworks.io.utils.query.

Key public objects: - SegmentSlice - get_residue_starts()

See individual docstrings for usage and examples.

atomworks.io.utils.selection.annot_start_stop_idxs(atom_array: AtomArray | AtomArrayStack, annots: str | list[str], add_exclusive_stop: bool = False) → ndarray[source]#

Computes the start and stop indices for segments in an AtomArray where any of the specified annotation(s) change.

Parameters:

  • atom_array – The AtomArray to process.

  • annots – Annotation name or names to define segments.

  • add_exclusive_stop – Append an exclusive stop index at the end. Defaults to False.

Returns:

1D array of start/stop indices that bound segments.

Example

>>> atom_array = AtomArray(...)
>>> start_stop_idxs = annot_start_stop_idxs(atom_array, annots="chain_id", add_exclusive_stop=True)
>>> print(start_stop_idxs)
[0, 5, 10, 15]
atomworks.io.utils.selection.get_annotation(atom_array: AtomArray | AtomArrayStack, annot: str, n_body: int | None = None, default: Any = None) → ndarray[source]#

Return an annotation array if present, otherwise default.

If n_body is None, the dimensionality is auto-detected by probing 1D then 2D annotation categories.

Parameters:

  • atom_array – Structure to query.

  • annot – Annotation category name.

  • n_body – 1 for 1D annotations, 2 for 2D annotations; auto-detected if None.

  • default – Value to return if the annotation is missing. Defaults to None.

Returns:

The requested annotation array or default if missing.

atomworks.io.utils.selection.get_residue_starts(atom_array: AtomArray | AtomArrayStack, add_exclusive_stop: bool = False) → ndarray[source]#

Get the start (and optionally stop) indices of residues in an AtomArray.

This is a more robust version of biotite.structure.residues.get_residue_starts() that additionally differentiates residues across different transformation_id values when present. It is backwards compatible if the annotation is absent.

Parameters:

  • atom_array – Structure to analyze.

  • add_exclusive_stop – Append an exclusive stop index at the end. Defaults to False.

Returns:

1D array of residue boundary indices.

References