biotite 1.1.0__cp313-cp313-win_amd64.whl → 1.3.0__cp313-cp313-win_amd64.whl

biotite/structure/io/pdbx/encoding.pyx

@@ -230,6 +230,12 @@ class Encoding(_Component, metaclass=ABCMeta):
         # since the file content may be invalid/malicious.
         raise NotImplementedError()
 
+    def __str__(self):
+        # Restore original behavior, as `__str__()` implementation of `_Component`
+        # may require serialization, which is not possible for some encodings prior
+        # to the first encoding pass
+        return object.__str__(self)
+
 
 @dataclass
 class ByteArrayEncoding(Encoding):
@@ -325,7 +331,8 @@ class FixedPointEncoding(Encoding):
                 )
 
         # Round to avoid wrong values due to floating point inaccuracies
-        return np.round(data * self.factor).astype(np.int32)
+        scaled_data = np.round(data * self.factor)
+        return _safe_cast(scaled_data, np.int32, allow_decimal_loss=True)
 
     def decode(self, data):
         return (data / self.factor).astype(
@@ -392,7 +399,7 @@ class IntervalQuantizationEncoding(Encoding):
             self.min, self.max, self.num_steps, dtype=data.dtype
         )
         indices = np.searchsorted(steps, data, side="left")
-        return indices.astype(np.int32, copy=False)
+        return _safe_cast(indices, np.int32)
 
     def decode(self, data):
         output = data * (self.max - self.min) / (self.num_steps - 1)
@@ -570,8 +577,14 @@ class DeltaEncoding(Encoding):
         if self.origin is None:
             self.origin = data[0]
 
+        # Differences (including `np.diff`) return an array with the same dtype as the
+        # input array
+        # As the input dtype may be unsigned, the output dtype could underflow,
+        # if the difference is negative
+        # -> cast to int64 to avoid this
+        data = data.astype(np.int64, copy=False)
         data = data - self.origin
-        return np.diff(data, prepend=0).astype(np.int32, copy=False)
+        return _safe_cast(np.diff(data, prepend=0), np.int32)
 
     def decode(self, data):
         output = np.cumsum(data, dtype=self.src_type.to_dtype())
@@ -635,7 +648,7 @@ class IntegerPackingEncoding(Encoding):
             # Only positive values -> use unsigned integers
             self.is_unsigned = data.min().item() >= 0
 
-        data = data.astype(np.int32, copy=False)
+        data = _safe_cast(data, np.int32)
         return self._encode(
             data, np.empty(0, dtype=self._determine_packed_dtype())
         )
@@ -870,7 +883,7 @@ class StringArrayEncoding(Encoding):
         else:
             check_present = True
 
-        string_order = np.argsort(self.strings).astype(np.int32)
+        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]
@@ -1010,22 +1023,25 @@ def _snake_to_camel_case(attribute_name):
     return attribute_name[0].lower() + attribute_name[1:]
 
 
-def _safe_cast(array, dtype):
-    dtype = np.dtype(dtype)
-    if dtype == array.dtype:
+def _safe_cast(array, dtype, allow_decimal_loss=False):
+    source_dtype = array.dtype
+    target_dtype = np.dtype(dtype)
+
+    if target_dtype == source_dtype:
         return array
-    if np.issubdtype(dtype, np.integer):
-        if not np.issubdtype(array.dtype, np.integer):
-            raise ValueError("Cannot cast floating point to integer")
-        dtype_info = np.iinfo(dtype)
-        if np.any(array < dtype_info.min) or np.any(array > dtype_info.max):
-            raise ValueError("Integer values do not fit into the given dtype")
-    return array.astype(dtype)
-
-
-def _get_n_decimals(value, tolerance):
-    MAX_DECIMALS = 10
-    for n in range(MAX_DECIMALS):
-        if abs(value - round(value, n)) < tolerance:
-            return n
-    return MAX_DECIMALS
+
+    if np.issubdtype(target_dtype, np.integer):
+        if np.issubdtype(source_dtype, np.floating):
+            if not allow_decimal_loss:
+                raise ValueError("Cannot cast floating point to integer")
+            if not np.isfinite(array).all():
+                raise ValueError("Data contains non-finite values")
+        elif not np.issubdtype(source_dtype, np.integer):
+            # Neither float, nor integer -> cannot cast
+            raise ValueError(f"Cannot cast '{source_dtype}' to integer")
+        dtype_info = np.iinfo(target_dtype)
+        # Check if an integer underflow/overflow would occur during conversion
+        if np.max(array) > dtype_info.max or np.min(array) < dtype_info.min:
+            raise ValueError("Values do not fit into the given dtype")
+
+    return array.astype(target_dtype)

biotite/structure/io/trajfile.py

@@ -187,9 +187,11 @@ class TrajectoryFile(File, metaclass=abc.ABCMeta):
         time : float or ndarray, dtype=float32, shape=(n,) or None
             The simulation time of the current frame or stack in *ps*.
 
-        See also
+        See Also
         --------
-        read_iter_structure
+        read_iter_structure :
+            Get an :class:`AtomArray` for each frame or an :class:`AtomArrayStack`
+            for each chunk of frames instead.
 
         Notes
         -----
@@ -315,9 +317,10 @@ class TrajectoryFile(File, metaclass=abc.ABCMeta):
             If `stack_size` is set, multiple frames are returned as
             :class:`AtomArrayStack`.
 
-        See also
+        See Also
         --------
-        read_iter
+        read_iter :
+            Get an the raw data for each frame or for each chunk of frames instead.
 
         Notes
         -----
@@ -480,7 +483,7 @@ class TrajectoryFile(File, metaclass=abc.ABCMeta):
 
         Parameters
         ----------
-        time : ndarray, dtype=float, shape=(m,3,3)
+        box : ndarray, dtype=float, shape=(m,3,3)
             The box vectors to be set.
         """
         self._check_model_count(box)
@@ -546,7 +549,7 @@ class TrajectoryFile(File, metaclass=abc.ABCMeta):
         ------
         NotImplementedError
         """
-        raise NotImplementedError("Copying is not implemented " "for trajectory files")
+        raise NotImplementedError("Copying is not implemented for trajectory files")
 
     @classmethod
     @abc.abstractmethod

biotite/structure/io/util.py

@@ -0,0 +1,38 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+"""
+Common functions used by a number of subpackages.
+"""
+
+__name__ = "biotite.structure.io"
+__author__ = "Patrick Kunzmann"
+__all__ = ["number_of_integer_digits"]
+
+import numpy as np
+
+
+def number_of_integer_digits(values):
+    """
+    Get the maximum number of characters needed to represent the
+    pre-decimal positions of the given numeric values.
+
+    Parameters
+    ----------
+    values : ndarray, dtype=float
+        The values to be checked.
+
+    Returns
+    -------
+    n_digits : int
+        The maximum number of characters needed to represent the
+        pre-decimal positions of the given numeric values.
+    """
+    if len(values) == 0:
+        return 0
+    values = values.astype(int, copy=False)
+    n_digits = 0
+    n_digits = max(n_digits, len(str(np.min(values))))
+    n_digits = max(n_digits, len(str(np.max(values))))
+    return n_digits

biotite/structure/mechanics.py

@@ -30,7 +30,6 @@ def gyration_radius(array, masses=None):
         Must have the same length as `array`. By default, the standard
         atomic mass for each element is taken.
 
-
     Returns
     -------
     masses : float or ndarray, dtype=float

biotite/structure/molecules.py

@@ -39,11 +39,6 @@ def get_molecule_indices(array):
         Consequently, the length of this list is equal to the number of
         molecules in the input `array`.
 
-    See also
-    --------
-    get_molecule_masks
-    molecule_iter
-
     Examples
     --------
     Get an :class:`AtomArray` for ATP and show that it is a single
@@ -157,11 +152,6 @@ def get_molecule_masks(array):
         Consequently, the length of this list is equal to the number of
         molecules in the input `array`.
 
-    See also
-    --------
-    get_molecule_indices
-    molecule_iter
-
     Examples
     --------
     Get an :class:`AtomArray` for ATP and show that it is a single
@@ -270,11 +260,6 @@ def molecule_iter(array):
     molecule : AtomArray or AtomArrayStack
         A single molecule of the input `array`.
 
-    See also
-    --------
-    get_molecule_indices
-    get_molecule_masks
-
     Examples
     --------
     Get an :class:`AtomArray` for ATP and break it into two molecules

biotite/structure/pseudoknots.py

@@ -69,6 +69,11 @@ def pseudoknots(base_pairs, scores=None, max_pseudoknot_order=None):
     Therefore, there are no pseudoknots between base pairs with the same
     pseudoknot order.
 
+    References
+    ----------
+
+    .. footbibliography::
+
     Examples
     --------
     Remove the pseudoknotted base pair for the sequence *ABCbac*, where
@@ -102,17 +107,6 @@ def pseudoknots(base_pairs, scores=None, max_pseudoknot_order=None):
     [[0 0 1]]
     >>> print(dot_bracket(basepairs, 6)[0])
     (([))]
-
-    See Also
-    --------
-    base_pairs
-    dot_bracket
-
-    References
-    ----------
-
-    .. footbibliography::
-
     """
     if len(base_pairs) == 0:
         # No base pairs -> empty pseudoknot order array
@@ -149,12 +143,12 @@ class _Region:
 
     Parameters
     ----------
-    base_pairs: ndarray, shape=(n,2), dtype=int
+    base_pairs : ndarray, shape=(n,2), dtype=int
         All base pairs of the structure the region is a subset for.
-    region_pairs: ndarray, dtype=int
+    region_pairs : ndarray, dtype=int
         The indices of the base pairs in ``base_pairs`` that are part of
         the region.
-    scores : ndarray, dtype=int, shape=(n,) (default: None)
+    scores : ndarray, dtype=int, shape=(n,)
         The score for each base pair.
     """
 
@@ -208,7 +202,7 @@ def _find_regions(base_pairs, scores):
     base_pairs : ndarray, dtype=int, shape=(n, 2)
         Each row is equivalent to one base pair and contains the first
         indices of the residues corresponding to each base.
-    scores : ndarray, dtype=int, shape=(n,) (default: None)
+    scores : ndarray, dtype=int, shape=(n,)
         The score for each base pair.
 
     Returns
@@ -358,7 +352,7 @@ def _get_first_occurrence_for(iterable, wanted_object):
             return i
 
 
-def _get_region_array_for(regions, content=[], dtype=[]):
+def _get_region_array_for(regions, content=(), dtype=()):
     """
     Get a :class:`ndarray` of region objects. Each object occurs twice,
     representing its start and end point. The regions positions in the
@@ -371,12 +365,12 @@ def _get_region_array_for(regions, content=[], dtype=[]):
     ----------
     regions : set {_region, ...}
         The regions to be considered
-    content : list [function, ...] (default: [])
+    content : list [function, ...]
         The functions to be considered for custom outputs. For a given
         region they must return a tuple of which the first value is
         placed at the start position and the second value at the end
         position of the region relative to the other regions.
-    dtype : list [str, ...] (default: [])
+    dtype : list [str, ...]
         The data type of the output of the custom functions.
 
     Returns
@@ -560,7 +554,7 @@ def _get_results(regions, results, max_pseudoknot_order, order=0):
         The maximum pseudoknot order to be found. If a base pair would
         be of a higher order, its order is specified as -1. If ``None``
         is given, all base pairs are evaluated.
-    order : int (default: 0)
+    order : int
         The order that is currently evaluated.
 
     Returns

biotite/structure/repair.py

@@ -48,7 +48,6 @@ def create_continuous_res_ids(atoms, restart_each_chain=True):
     >>> res_ids, _ = get_residues(atom_array)
     >>> print(res_ids)
     [ 1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19]
-
     """
     res_ids_diff = np.zeros(atoms.array_length(), dtype=int)
     res_starts = get_residue_starts(atoms)
@@ -80,7 +79,7 @@ def infer_elements(atoms):
 
     See Also
     --------
-    create_atoms_names : The opposite of this function
+    create_atoms_names : The opposite of this function.
 
     Examples
     --------
@@ -89,7 +88,6 @@ def infer_elements(atoms):
     ['N' 'C' 'C' 'O' 'C' 'C' 'O' 'N' 'H' 'H']
     >>> print(infer_elements(["CA", "C", "C1", "OD1", "HD21", "1H", "FE"]))
     ['C' 'C' 'C' 'O' 'H' 'H' 'FE']
-
     """
     if isinstance(atoms, (AtomArray, AtomArrayStack)):
         atom_names = atoms.atom_name
@@ -117,7 +115,7 @@ def create_atom_names(atoms):
 
     See Also
     --------
-    infer_elements : The opposite of this function
+    infer_elements : The opposite of this function.
 
     Notes
     -----

biotite/structure/residues.py

@@ -21,23 +21,23 @@ __all__ = [
     "residue_iter",
 ]
 
-import numpy as np
 from biotite.structure.segments import (
     apply_segment_wise,
     get_segment_masks,
     get_segment_positions,
+    get_segment_starts,
     get_segment_starts_for,
     segment_iter,
     spread_segment_wise,
 )
 
 
-def get_residue_starts(array, add_exclusive_stop=False):
+def get_residue_starts(array, add_exclusive_stop=False, extra_categories=()):
     """
     Get indices for an atom array, each indicating the beginning of
     a residue.
 
-    A new residue starts, either when the chain ID, residue ID,
+    A new residue starts, either when the chain ID, sym ID, residue ID,
     insertion code or residue name changes from one to the next atom.
 
     Parameters
@@ -48,6 +48,9 @@ def get_residue_starts(array, add_exclusive_stop=False):
         If true, the exclusive stop of the input atom array, i.e.
         ``array.array_length()``, is added to the returned array of
         start indices as last element.
+    extra_categories : tuple of str, optional
+        Additional annotation categories that induce the start of a new residue,
+        when their value change from one atom to the next.
 
     Returns
     -------
@@ -69,27 +72,10 @@ def get_residue_starts(array, add_exclusive_stop=False):
     [  0  16  35  56  75  92 116 135 157 169 176 183 197 208 219 226 250 264
      278 292 304]
     """
-    # These mask are 'true' at indices where the value changes
-    chain_id_changes = array.chain_id[1:] != array.chain_id[:-1]
-    res_id_changes = array.res_id[1:] != array.res_id[:-1]
-    ins_code_changes = array.ins_code[1:] != array.ins_code[:-1]
-    res_name_changes = array.res_name[1:] != array.res_name[:-1]
-
-    # If any of these annotation arrays change, a new residue starts
-    residue_change_mask = (
-        chain_id_changes | res_id_changes | ins_code_changes | res_name_changes
-    )
-
-    # Convert mask to indices
-    # Add 1, to shift the indices from the end of a residue
-    # to the start of a new residue
-    residue_starts = np.where(residue_change_mask)[0] + 1
-
-    # The first residue is not included yet -> Insert '[0]'
-    if add_exclusive_stop:
-        return np.concatenate(([0], residue_starts, [array.array_length()]))
-    else:
-        return np.concatenate(([0], residue_starts))
+    categories = ["chain_id", "res_id", "ins_code", "res_name"] + 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)
 
 
 def apply_residue_wise(array, data, function, axis=None):
@@ -123,9 +109,8 @@ def apply_residue_wise(array, data, function, axis=None):
     Returns
     -------
     processed_data : ndarray
-        Residue-wise evaluation of `data` by `function`. The size of the
-        first dimension of this array is equal to the amount of
-        residues.
+        Residue-wise evaluation of `data` by `function`. The size of the first dimension
+        of this array is equal to the amount of residues.
 
     Examples
     --------
@@ -193,14 +178,15 @@ def spread_residue_wise(array, input_data):
     array : AtomArray or AtomArrayStack
         The atom array (stack) to determine the residues from.
     input_data : ndarray
-        The data to be spread. The length of axis=0 must be equal to
-        the amount of different residue IDs in `array`.
+        The data to be spread.
+        The length of the 0-th axis must be equal to the amount of different residue IDs
+        in `array`.
 
     Returns
     -------
     output_data : ndarray
-        Residue-wise spread `input_data`. Length is the same as
-        `array_length()` of `array`.
+        Residue-wise spread `input_data`.
+        Length is the same as `array_length()` of `array`.
 
     Examples
     --------
@@ -260,11 +246,6 @@ def get_residue_masks(array, indices):
         Each array masks the atoms that belong to the same residue as
         the atom at the given index.
 
-    See also
-    --------
-    get_residue_starts_for
-    get_residue_positions
-
     Examples
     --------
 
@@ -338,11 +319,6 @@ def get_residue_starts_for(array, indices):
         The indices that point to the residue starts for the input
         `indices`.
 
-    See also
-    --------
-    get_residue_masks
-    get_residue_positions
-
     Examples
     --------
 
@@ -382,14 +358,9 @@ def get_residue_positions(array, indices):
 
     Returns
     -------
-    start_indices : ndarray, dtype=int, shape=(k,)
+    residue_indices : ndarray, dtype=int, shape=(k,)
         The indices that point to the position of the residues.
 
-    See also
-    --------
-    get_residue_masks
-    get_residue_starts_for
-
     Examples
     --------
     >>> atom_index = [5, 42]
@@ -569,4 +540,5 @@ def residue_iter(array):
     """
     # The exclusive stop is appended to the residue starts
     starts = get_residue_starts(array, add_exclusive_stop=True)
-    return segment_iter(array, starts)
+    for residue in segment_iter(array, starts):
+        yield residue