biotite 1.4.0__cp311-cp311-macosx_11_0_arm64.whl → 1.5.0__cp311-cp311-macosx_11_0_arm64.whl

biotite/structure/io/pdbx/convert.py

@@ -55,6 +55,7 @@ from biotite.structure.io.pdbx.bcif import (
 from biotite.structure.io.pdbx.cif import CIFBlock, CIFFile
 from biotite.structure.io.pdbx.component import MaskValue
 from biotite.structure.io.pdbx.encoding import StringArrayEncoding
+from biotite.structure.repair import create_continuous_res_ids
 from biotite.structure.residues import (
     get_residue_count,
     get_residue_positions,
@@ -496,12 +497,6 @@ def _fill_annotations(array, atom_site, extra_fields, use_author_fields):
             atom_site, f"{prefix}_asym_id", f"{alt_prefix}_asym_id"
         ).as_array(str),
     )
-    array.set_annotation(
-        "res_id",
-        _get_or_fallback(
-            atom_site, f"{prefix}_seq_id", f"{alt_prefix}_seq_id"
-        ).as_array(int, -1),
-    )
     array.set_annotation("ins_code", atom_site["pdbx_PDB_ins_code"].as_array(str, ""))
     array.set_annotation(
         "res_name",
@@ -518,6 +513,22 @@ def _fill_annotations(array, atom_site, extra_fields, use_author_fields):
     )
     array.set_annotation("element", atom_site["type_symbol"].as_array(str))
 
+    # Special handling for `res_id`, as the `label_seq_id` is equal (`.`) for all
+    # hetero residues, which makes distinguishing subsequent residues from another
+    # difficult (https://github.com/biotite-dev/biotite/issues/553)
+    res_id = _get_or_fallback(
+        atom_site, f"{prefix}_seq_id", f"{alt_prefix}_seq_id"
+    ).as_array(int, -1)
+    if not use_author_fields and "auth_seq_id" in atom_site:
+        # Therefore, the `auth_seq_id` is still used to determine residue starts
+        # in `create_continuous_res_ids()`, even if `use_author_fields = False`.
+        res_id_for_residue_starts = atom_site["auth_seq_id"].as_array(int, -1)
+        array.set_annotation("res_id", res_id_for_residue_starts)
+        fallback_res_ids = create_continuous_res_ids(array)
+        array.set_annotation("res_id", np.where(res_id == -1, fallback_res_ids, res_id))
+    else:
+        array.set_annotation("res_id", res_id)
+
     if "atom_id" in extra_fields:
         if "id" in atom_site:
             array.set_annotation("atom_id", atom_site["id"].as_array(int))

biotite/structure/io/pdbx/encoding.pyx

@@ -225,9 +225,13 @@ class Encoding(_Component, metaclass=ABCMeta):
         -------
         decoded_data : ndarray
             The decoded data.
+
+        Warnings
+        --------
+        When overriding this method, do not omit bound checks with
+        ``@cython.boundscheck(False)`` or ``@cython.wraparound(False)``,
+        since the file content may be invalid/malicious.
         """
-        # Important: Do not omit bound checks for decoding,
-        # since the file content may be invalid/malicious.
         raise NotImplementedError()
 
     def __str__(self):
@@ -883,17 +887,39 @@ class StringArrayEncoding(Encoding):
         else:
             check_present = True
 
-        string_order = _safe_cast(np.argsort(self.strings), np.int32)
-        sorted_strings = self.strings[string_order]
-        sorted_indices = np.searchsorted(sorted_strings, data)
-        indices = string_order[sorted_indices]
-        if check_present and not np.all(self.strings[indices] == data):
+        if len(self.strings) > 0:
+            string_order = _safe_cast(np.argsort(self.strings), np.int32)
+            sorted_strings = self.strings[string_order]
+            sorted_indices = np.searchsorted(sorted_strings, data)
+            indices = string_order[sorted_indices]
+            # `"" not in self.strings` can be quite costly and is only necessary,
+            # if the the `strings` were given by the user, as otherwise we always
+            # include an empty string explicitly when we compute them in this function
+            # -> Only run if `check_present` is True
+            if check_present and "" not in self.strings:
+                # Represent empty strings as -1
+                indices[data == ""] = -1
+        else:
+            # There are no strings -> The indices can only ever be -1 to indicate
+            # missing values
+            # The check if this is correct is done below
+            indices = np.full(data.shape[0], -1, dtype=np.int32)
+
+        valid_indices_mask = indices != -1
+        if check_present and not np.all(
+            self.strings[indices[valid_indices_mask]] == data[valid_indices_mask]
+        ):
             raise ValueError("Data contains strings not present in 'strings'")
         return encode_stepwise(indices, self.data_encoding)
 
     def decode(self, data):
         indices = decode_stepwise(data, self.data_encoding)
-        return self.strings[indices]
+        # Initialize with empty strings
+        strings = np.zeros(indices.shape[0], dtype=self.strings.dtype)
+        # `-1`` indices indicate missing values
+        valid_indices_mask = indices != -1
+        strings[valid_indices_mask] = self.strings[indices[valid_indices_mask]]
+        return strings
 
     def __eq__(self, other):
         if not isinstance(other, type(self)):
@@ -1009,6 +1035,11 @@ def decode_stepwise(data, encoding):
     """
     for enc in reversed(encoding):
         data = enc.decode(data)
+    # ByteEncoding may decode in a non-writable array,
+    # as it creates the ndarray cheaply from buffer
+    if not data.flags.writeable:
+        # Make the resulting ndarray writable, by copying the underlying buffer
+        data = data.copy()
     return data
 
 

biotite/structure/residues.py

@@ -16,13 +16,17 @@ __all__ = [
     "get_residue_masks",
     "get_residue_starts_for",
     "get_residue_positions",
+    "get_all_residue_positions",
     "get_residues",
     "get_residue_count",
     "residue_iter",
+    "get_atom_name_indices",
 ]
 
+import numpy as np
 from biotite.structure.segments import (
     apply_segment_wise,
+    get_all_segment_positions,
     get_segment_masks,
     get_segment_positions,
     get_segment_starts,
@@ -72,7 +76,7 @@ def get_residue_starts(array, add_exclusive_stop=False, extra_categories=()):
     [  0  16  35  56  75  92 116 135 157 169 176 183 197 208 219 226 250 264
      278 292 304]
     """
-    categories = ["chain_id", "res_id", "ins_code", "res_name"] + list(extra_categories)
+    categories = ["chain_id", "res_id", "ins_code"] + list(extra_categories)
     if "sym_id" in array.get_annotation_categories():
         categories.append("sym_id")
     return get_segment_starts(array, add_exclusive_stop, equal_categories=categories)
@@ -361,6 +365,11 @@ def get_residue_positions(array, indices):
     residue_indices : ndarray, dtype=int, shape=(k,)
         The indices that point to the position of the residues.
 
+    See Also
+    --------
+    get_all_residue_positions :
+        Similar to this function, but for all atoms in the :class:`struc.AtomArray`.
+
     Examples
     --------
     >>> atom_index = [5, 42]
@@ -380,6 +389,50 @@ def get_residue_positions(array, indices):
     return get_segment_positions(starts, indices)
 
 
+def get_all_residue_positions(array):
+    """
+    For each atom, obtain the position of the residue
+    corresponding to this atom in the input `array`.
+
+    For example, the position of the first residue in the atom array is
+    ``0``, the the position of the second residue is ``1``, etc.
+
+    Parameters
+    ----------
+    array : AtomArray or AtomArrayStack
+        The atom array (stack) to determine the residues from.
+
+    Returns
+    -------
+    residue_indices : ndarray, dtype=int, shape=(k,)
+        The indices that point to the position of the residues.
+
+    See Also
+    --------
+    get_residue_positions :
+        Similar to this function, but for a given subset of atom indices.
+
+    Examples
+    --------
+    >>> print(get_all_residue_positions(atom_array))
+    [ 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  1  1  1  1  1  1  1  1
+      1  1  1  1  1  1  1  1  1  1  1  2  2  2  2  2  2  2  2  2  2  2  2  2
+      2  2  2  2  2  2  2  2  3  3  3  3  3  3  3  3  3  3  3  3  3  3  3  3
+      3  3  3  4  4  4  4  4  4  4  4  4  4  4  4  4  4  4  4  4  5  5  5  5
+      5  5  5  5  5  5  5  5  5  5  5  5  5  5  5  5  5  5  5  5  6  6  6  6
+      6  6  6  6  6  6  6  6  6  6  6  6  6  6  6  7  7  7  7  7  7  7  7  7
+      7  7  7  7  7  7  7  7  7  7  7  7  7  8  8  8  8  8  8  8  8  8  8  8
+      8  9  9  9  9  9  9  9 10 10 10 10 10 10 10 11 11 11 11 11 11 11 11 11
+     11 11 11 11 11 12 12 12 12 12 12 12 12 12 12 12 13 13 13 13 13 13 13 13
+     13 13 13 14 14 14 14 14 14 14 15 15 15 15 15 15 15 15 15 15 15 15 15 15
+     15 15 15 15 15 15 15 15 15 15 16 16 16 16 16 16 16 16 16 16 16 16 16 16
+     17 17 17 17 17 17 17 17 17 17 17 17 17 17 18 18 18 18 18 18 18 18 18 18
+     18 18 18 18 19 19 19 19 19 19 19 19 19 19 19 19]
+    """
+    starts = get_residue_starts(array, add_exclusive_stop=True)
+    return get_all_segment_positions(starts, array.array_length())
+
+
 def get_residues(array):
     """
     Get the residue IDs and names of an atom array (stack).
@@ -542,3 +595,122 @@ def residue_iter(array):
     starts = get_residue_starts(array, add_exclusive_stop=True)
     for residue in segment_iter(array, starts):
         yield residue
+
+
+def get_atom_name_indices(atoms, atom_names):
+    """
+    For each residue, get the index of the atom with the given atom name.
+
+    Parameters
+    ----------
+    atoms : AtomArray or AtomArrayStack
+        Search for the indices of the given atom names in this structure.
+    atom_names : list of str, length=p
+        The names of the atoms to get the indices of.
+
+    Returns
+    -------
+    indices : ndarray, dtype=int, shape=(k, p)
+        For every residue and atom name, the return value contains the atom index in
+        the :class:`AtomArray` where the sought atom name is located.
+        Where the atom name is not present in a residue, the array is filled with `-1`.
+
+    Examples
+    --------
+
+    >>> indices = get_atom_name_indices(atom_array, ["CA", "CB"])
+    >>> print(indices)
+    [[  1   4]
+     [ 17  20]
+     [ 36  39]
+     [ 57  60]
+     [ 76  79]
+     [ 93  96]
+     [117 120]
+     [136 139]
+     [158 161]
+     [170  -1]
+     [177  -1]
+     [184 187]
+     [198 201]
+     [209 212]
+     [220  -1]
+     [227 230]
+     [251 254]
+     [265 268]
+     [279 282]
+     [293 296]]
+    >>> for row in indices:
+    ...     for index in row:
+    ...         if index != -1:
+    ...             print(atom_array[index])
+    ...     print()
+        A       1  ASN CA     C        -8.608    3.135   -1.618
+        A       1  ASN CB     C        -9.437    3.396   -2.889
+    <BLANKLINE>
+        A       2  LEU CA     C        -4.923    4.002   -2.452
+        A       2  LEU CB     C        -4.411    5.450   -2.619
+    <BLANKLINE>
+        A       3  TYR CA     C        -3.690    2.738    0.981
+        A       3  TYR CB     C        -3.964    3.472    2.302
+    <BLANKLINE>
+        A       4  ILE CA     C        -5.857   -0.449    0.613
+        A       4  ILE CB     C        -7.386   -0.466    0.343
+    <BLANKLINE>
+        A       5  GLN CA     C        -4.122   -1.167   -2.743
+        A       5  GLN CB     C        -4.292   -0.313   -4.013
+    <BLANKLINE>
+        A       6  TRP CA     C        -0.716   -0.631   -0.993
+        A       6  TRP CB     C        -0.221    0.703   -0.417
+    <BLANKLINE>
+        A       7  LEU CA     C        -1.641   -2.932    1.963
+        A       7  LEU CB     C        -2.710   -2.645    3.033
+    <BLANKLINE>
+        A       8  LYS CA     C        -3.024   -5.791   -0.269
+        A       8  LYS CB     C        -4.224   -5.697   -1.232
+    <BLANKLINE>
+        A       9  ASP CA     C         0.466   -6.016   -1.905
+        A       9  ASP CB     C         1.033   -4.839   -2.724
+    <BLANKLINE>
+        A      10  GLY CA     C         2.060   -6.618    1.593
+    <BLANKLINE>
+        A      11  GLY CA     C         2.626   -2.967    2.723
+    <BLANKLINE>
+        A      12  PRO CA     C         6.333   -2.533    3.806
+        A      12  PRO CB     C         6.740   -2.387    5.279
+    <BLANKLINE>
+        A      13  SER CA     C         7.049   -6.179    2.704
+        A      13  SER CB     C         6.458   -7.371    3.472
+    <BLANKLINE>
+        A      14  SER CA     C         6.389   -5.315   -1.015
+        A      14  SER CB     C         4.914   -4.993   -1.265
+    <BLANKLINE>
+        A      15  GLY CA     C         9.451   -3.116   -1.870
+    <BLANKLINE>
+        A      16  ARG CA     C         7.289    0.084   -2.054
+        A      16  ARG CB     C         6.110   -0.243   -2.994
+    <BLANKLINE>
+        A      17  PRO CA     C         6.782    3.088    0.345
+        A      17  PRO CB     C         7.554    4.394    0.119
+    <BLANKLINE>
+        A      18  PRO CA     C         3.287    4.031    1.686
+        A      18  PRO CB     C         3.035    4.190    3.187
+    <BLANKLINE>
+        A      19  PRO CA     C         1.185    6.543   -0.353
+        A      19  PRO CB     C         0.048    6.014   -1.229
+    <BLANKLINE>
+        A      20  SER CA     C         0.852   10.027    1.285
+        A      20  SER CB     C         1.972   11.071    1.284
+    <BLANKLINE>
+    """
+    residue_indices = get_all_residue_positions(atoms)
+    indices = np.full(
+        (residue_indices[-1] + 1, len(atom_names)), fill_value=-1, dtype=int
+    )
+    for i, atom_name in enumerate(atom_names):
+        if atom_name is None:
+            atom_name_indices = np.where(atoms.hetero)[0]
+        else:
+            atom_name_indices = np.where(atoms.atom_name == atom_name)[0]
+        indices[residue_indices[atom_name_indices], i] = atom_name_indices
+    return indices

biotite/structure/segments.py

@@ -11,6 +11,7 @@ __all__ = [
     "get_segment_masks",
     "get_segment_starts_for",
     "get_segment_positions",
+    "get_all_segment_positions",
     "segment_iter",
 ]
 
@@ -62,13 +63,13 @@ def get_segment_starts(
     # Convert mask to indices
     # Add 1, to shift the indices from the end of a segment
     # to the start of a new segment
-    chain_starts = np.where(segment_start_mask)[0] + 1
+    segment_starts = np.where(segment_start_mask)[0] + 1
 
     # The first chain is not included yet -> Insert '[0]'
     if add_exclusive_stop:
-        return np.concatenate(([0], chain_starts, [array.array_length()]))
+        return np.concatenate(([0], segment_starts, [array.array_length()]))
     else:
-        return np.concatenate(([0], chain_starts))
+        return np.concatenate(([0], segment_starts))
 
 
 def apply_segment_wise(starts, data, function, axis=None):
@@ -252,6 +253,11 @@ def get_segment_positions(starts, indices):
     -------
     segment_indices : ndarray, shape=(k,)
         The indices that point to the position of the segments.
+
+    See Also
+    --------
+    get_all_segment_positions :
+        Similar to this function, but for all atoms in the :class:`struc.AtomArray`.
     """
     indices = np.asarray(indices)
     length = starts[-1]
@@ -269,6 +275,36 @@ def get_segment_positions(starts, indices):
     return np.searchsorted(starts, indices, side="right") - 1
 
 
+def get_all_segment_positions(starts, length):
+    """
+    Generalized version of :func:`get_all_residue_positions()`
+    for residues and chains.
+
+    Parameters
+    ----------
+    starts : ndarray, dtype=int
+        The sorted start indices of segments.
+        Includes exclusive stop, i.e. the length of the corresponding
+        atom array.
+    length : int
+        The length of the corresponding :class:`struc.AtomArray`.
+
+    Returns
+    -------
+    segment_indices : ndarray, shape=(k,)
+        For each atom the indices that point to the corresponding position of the
+        segments.
+
+    See Also
+    --------
+    get_segment_positions :
+        Similar to this function, but for a given subset of atom indices.
+    """
+    segment_changes = np.zeros(length, dtype=int)
+    segment_changes[starts[1:-1]] = 1
+    return np.cumsum(segment_changes)
+
+
 def segment_iter(array, starts):
     """
     Generalized version of :func:`residue_iter()`

biotite/structure/util.py

@@ -18,8 +18,9 @@ __all__ = [
 
 import numpy as np
 from biotite.structure.atoms import AtomArrayStack
-from biotite.structure.error import BadStructureError
-from biotite.structure.residues import get_residue_masks, get_residue_starts
+from biotite.structure.residues import (
+    get_atom_name_indices,
+)
 
 
 def vector_dot(v1, v2):
@@ -127,42 +128,33 @@ def coord_for_atom_name_per_residue(atoms, atom_names, mask=None):
     coord: ndarray, shape=(k, m, r, 3) or shape=(k, r, 3)
         The coordinates of the specified atom for each residue.
     """
-    is_multi_model = isinstance(atoms, AtomArrayStack)
-    residue_starts = get_residue_starts(atoms)
-    all_residue_masks = get_residue_masks(atoms, residue_starts)
+    atom_name_indices = get_atom_name_indices(atoms, atom_names)
 
+    is_multi_model = isinstance(atoms, AtomArrayStack)
     if is_multi_model:
         coord = np.full(
-            (len(atom_names), atoms.stack_depth(), len(residue_starts), 3),
+            (len(atom_names), atoms.stack_depth(), atom_name_indices.shape[0], 3),
             np.nan,
             dtype=np.float32,
         )
     else:
         coord = np.full(
-            (len(atom_names), len(residue_starts), 3),
+            (len(atom_names), atom_name_indices.shape[0], 3),
             np.nan,
             dtype=np.float32,
         )
 
-    for i, atom_name in enumerate(atom_names):
-        specified_atom_mask = atoms.atom_name == atom_name
+    for atom_name_i, atom_indices in enumerate(atom_name_indices.T):
+        valid_mask = atom_indices != -1
         if mask is not None:
-            specified_atom_mask &= mask
-        all_residue_masks_for_specified_atom = all_residue_masks & specified_atom_mask
-        number_of_specified_atoms_per_residue = np.count_nonzero(
-            all_residue_masks_for_specified_atom, axis=-1
-        )
-        if np.any(number_of_specified_atoms_per_residue > 1):
-            raise BadStructureError(f"Multiple '{atom_name}' atoms per residue")
-        residues_with_specified_atom = number_of_specified_atoms_per_residue == 1
-        coord_of_specified_atoms = atoms.coord[..., specified_atom_mask, :]
+            valid_mask &= mask[atom_indices]
+        coord_for_atom_name = atoms.coord[..., atom_indices[valid_mask], :]
         if is_multi_model:
             # Swap dimensions due to NumPy's behavior when using advanced indexing
             # (https://numpy.org/devdocs/user/basics.indexing.html#combining-advanced-and-basic-indexing)
-            coord[i, ..., residues_with_specified_atom, :] = (
-                coord_of_specified_atoms.transpose(1, 0, 2)
+            coord[atom_name_i, ..., valid_mask, :] = coord_for_atom_name.transpose(
+                1, 0, 2
             )
         else:
-            coord[i, residues_with_specified_atom, :] = coord_of_specified_atoms
-
+            coord[atom_name_i, valid_mask, :] = coord_for_atom_name
     return coord

biotite/version.py

@@ -1,7 +1,14 @@
 # file generated by setuptools-scm
 # don't change, don't track in version control
 
-__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
@@ -9,13 +16,19 @@ if TYPE_CHECKING:
     from typing import Union
 
     VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
 else:
     VERSION_TUPLE = object
+    COMMIT_ID = object
 
 version: str
 __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
 
-__version__ = version = '1.4.0'
-__version_tuple__ = version_tuple = (1, 4, 0)
+__version__ = version = '1.5.0'
+__version_tuple__ = version_tuple = (1, 5, 0)
+
+__commit_id__ = commit_id = None

{biotite-1.4.0.dist-info → biotite-1.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: biotite
-Version: 1.4.0
+Version: 1.5.0
 Summary: A comprehensive library for computational molecular biology
 Project-URL: homepage, https://www.biotite-python.org
 Project-URL: repository, https://github.com/biotite-dev/biotite