biotite 1.2.0__cp313-cp313-macosx_11_0_arm64.whl → 1.4.0__cp313-cp313-macosx_11_0_arm64.whl

biotite/structure/chains.py

@@ -22,23 +22,23 @@ __all__ = [
     "chain_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_chain_starts(array, add_exclusive_stop=False):
+def get_chain_starts(array, add_exclusive_stop=False, extra_categories=()):
     """
     Get the indices in an atom array, which indicates the beginning of
     a new chain.
 
-    A new chain starts, when the chain ID changes or when the residue ID
+    A new chain starts, when the chain or sym ID changes or when the residue ID
     decreases.
 
     Parameters
@@ -49,6 +49,9 @@ def get_chain_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 chain,
+        when their value change from one atom to the next.
 
     Returns
     -------
@@ -60,24 +63,15 @@ def get_chain_starts(array, add_exclusive_stop=False):
     This method is internally used by all other chain-related
     functions.
     """
-    if array.array_length() == 0:
-        return np.array([], dtype=int)
-
-    diff = np.diff(array.res_id)
-    res_id_decrement = diff < 0
-    # This mask is 'true' at indices where the value changes
-    chain_id_changes = array.chain_id[1:] != array.chain_id[:-1]
-
-    # Convert mask to indices
-    # Add 1, to shift the indices from the end of a chain
-    # to the start of a new chain
-    chain_starts = np.where(res_id_decrement | chain_id_changes)[0] + 1
-
-    # The first chain is not included yet -> Insert '[0]'
-    if add_exclusive_stop:
-        return np.concatenate(([0], chain_starts, [array.array_length()]))
-    else:
-        return np.concatenate(([0], chain_starts))
+    categories = ["chain_id"] + list(extra_categories)
+    if "sym_id" in array.get_annotation_categories():
+        categories.append("sym_id")
+    return get_segment_starts(
+        array,
+        add_exclusive_stop,
+        continuous_categories=("res_id",),
+        equal_categories=categories,
+    )
 
 
 def apply_chain_wise(array, data, function, axis=None):

biotite/structure/compare.py

@@ -449,6 +449,8 @@ def lddt(
     # Aggregate the fractions over the desired level
     if isinstance(aggregation, str) and aggregation == "all":
         # Average over all contacts
+        if len(fraction_preserved_bins) == 0:
+            return np.float32(np.nan)
         return np.mean(fraction_preserved_bins, axis=-1)
     else:
         # A string is also a 'Sequence'

biotite/structure/dotbracket.py

@@ -33,10 +33,10 @@ def dot_bracket_from_structure(
     ----------
     nucleic_acid_strand : AtomArray
         The nucleic acid strand to be represented in DBL-notation.
-    scores : ndarray, dtype=int, shape=(n,) (default: None)
+    scores : ndarray, dtype=int, shape=(n,)
         The score for each base pair, which is passed on to
         :func:`pseudoknots()`.
-    max_pseudoknot_order : int (default: None)
+    max_pseudoknot_order : int
         The maximum pseudoknot order to be found. If a base pair would
         be of a higher order, it is represented as unpaired. If ``None``
         is given, all base pairs are evaluated.
@@ -82,9 +82,9 @@ def dot_bracket(basepairs, length, scores=None, max_pseudoknot_order=None):
         strand.
     length : int
         The number of bases in the strand.
-    scores : ndarray, dtype=int, shape=(n,) (default: None)
+    scores : ndarray, dtype=int, shape=(n,)
         The score for each base pair, which is passed on to :func:`pseudoknots()`.
-    max_pseudoknot_order : int (default: None)
+    max_pseudoknot_order : int
         The maximum pseudoknot order to be found. If a base pair would
         be of a higher order, it is represented as unpaired. If ``None``
         is given, all pseudoknot orders are evaluated.

biotite/structure/graphics/rna.py

@@ -57,59 +57,62 @@ def plot_nucleotide_secondary_structure(
         sequence. The positions are counted from zero.
     length : int
         The number of bases in the sequence.
-    layout_type : RNAplotApp.Layout, optional (default: RNAplotApp.Layout.NAVIEW)
+    layout_type : RNAplotApp.Layout, optional
         The layout type according to the *RNAplot* documentation.
-    draw_pseudoknots : bool, optional (default: True)
+    draw_pseudoknots : bool, optional
         Whether pseudoknotted bonds should be drawn.
-    pseudoknot_order : iterable, optional (default: None)
+    pseudoknot_order : iterable, optional
         The pseudoknot order of each pair in the input `base_pairs`.
         If no pseudoknot order is given, a solution determined by
         :func:`biotite.structure.pseudoknots` is picked at random.
-    angle : int or float, optional (default: 0)
+    angle : int or float, optional
         The angle the plot should be rotated.
-    bond_linewidth : float or int or iterable, optional (default: 1)
+    bond_linewidth : float or int or iterable, optional
         The linewidth of each bond. Provide a single value to set the
         linewidth for all bonds or an iterable to set the linewidth for
         each individual bond.
-    bond_linestyle : str or iterable, optional (default: None)
+    bond_linestyle : str or iterable, optional
         The *Matplotlib* compatible linestyle of each bond. Provide a
         single value to set the linewidth for all bonds or an iterable
         to set the linewidth for each individual bond. By default, solid
         lines are used for non-pseudoknotted bonds and dashed lines are
         used for pseudoknotted bonds.
-    bond_color : str or ndarray, shape(n,) or shape(n,3) or shape(n,4), optional (default: 'black')
+    bond_color : str or ndarray, shape(n,) or shape(n,3) or shape(n,4), optional
         The *Matplotlib* compatible color of each bond. Provide a single
         string to set the color for all bonds or an array to set the
         color for each individual bond.
-    backbone_linewidth : float, optional (default: 1)
+    backbone_linewidth : float, optional
         The linewidth of the backbone.
-    backbone_linestyle : str, optional (default: 'solid')
+    backbone_linestyle : str, optional
         The *Matplotlib* compatible linestyle of the backbone.
-    backbone_color : str or ndarray, shape=(3,) or shape=(4,), dtype=float, optional (default: 'grey')
+    backbone_color : str or ndarray, shape=(3,) or shape=(4,), dtype=float, optional
         The *Matplotlib* compatible color of the backbone.
-    base_text : dict or iterable, optional (default: {'size': 'small'})
+    base_text : dict or iterable, optional
         The keyword parameters for the *Matplotlib* ``Text`` objects
         denoting the type of each base. Provide a single value to set
         the parameters for all labels or an iterable to set the
         parameters for each individual label.
-    base_box : dict or iterable, optional (default: {'pad'=0, 'color'='white'})
+        The default is ``{'size': 'small'}``.
+    base_box : dict or iterable, optional)
         The *Matplotlib* compatible properties of the ``FancyBboxPatch``
         surrounding the base labels. Provide a single dictionary to
         set the properties of all base lables or an iterable to set the
         properties for each individual label.
-    annotation_positions : iterable, optional (default: None)
+        The default is ``{'pad'=0, 'color'='white'}``.
+    annotation_positions : iterable, optional
         The positions of the bases to be numbered. By default every
         second base is annotated. Please note that while the positions
         in the sequence are counted from zero, they are displayed on the
         graph counted from one.
-    annotation_offset : int or float, optional (default: 8.5)
+    annotation_offset : int or float, optional
         The offset of the annotations from the base labels.
-    annotation_text : dict or iterable, optional (default: {'size': 'small'})
+    annotation_text : dict or iterable, optional
         The keyword parameters for the *Matplotlib* ``Text`` objects
         annotating the sequence. Provide a single value to set the
         parameters for all annotations or an iterable to set the
         parameters for each individual annotation.
-    border : float, optional (default: 0.03)
+        The default is ``{'size': 'small'}``.
+    border : float, optional
         The percentage of the coordinate range to be left as whitespace
         to create a border around the plot.
     bin_path : str, optional

biotite/structure/hbond.py

@@ -59,8 +59,7 @@ def hbond(
         The angle cutoff in degree between Donor-H..Acceptor to be
         considered a hydrogen bond.
     donor_elements, acceptor_elements : tuple of str
-        Elements to be considered as possible donors or acceptors
-        (Default: O, N, S).
+        Elements to be considered as possible donors or acceptors.
     periodic : bool, optional
         If true, hydrogen bonds can also be detected in periodic
         boundary conditions.

biotite/structure/io/pdb/convert.py

@@ -15,9 +15,11 @@ __all__ = [
     "set_structure",
     "list_assemblies",
     "get_assembly",
-    "get_symmetry_mates",
+    "get_unit_cell",
 ]
 
+import warnings
+
 
 def get_model_count(pdb_file):
     """
@@ -232,6 +234,80 @@ def get_assembly(
     )
 
 
+def get_unit_cell(
+    pdb_file, model=None, altloc="first", extra_fields=[], include_bonds=False
+):
+    """
+    Build a structure model containing all symmetric copies
+    of the structure within a single unit cell, given by the space
+    group.
+
+    This function receives the data from ``REMARK 290`` records in
+    the file.
+    Consequently, this remark must be present in the file, which is
+    usually only true for crystal structures.
+
+    Parameters
+    ----------
+    pdb_file : PDBFile
+        The file object.
+    model : int, optional
+        If this parameter is given, the function will return an
+        :class:`AtomArray` from the atoms corresponding to the given
+        model number (starting at 1).
+        Negative values are used to index models starting from the
+        last model instead of the first model.
+        If this parameter is omitted, an :class:`AtomArrayStack`
+        containing all models will be returned, even if the
+        structure contains only one model.
+    altloc : {'first', 'occupancy', 'all'}
+        This parameter defines how *altloc* IDs are handled:
+            - ``'first'`` - Use atoms that have the first
+                *altloc* ID appearing in a residue.
+            - ``'occupancy'`` - Use atoms that have the *altloc* ID
+                with the highest occupancy for a residue.
+            - ``'all'`` - Use all atoms.
+                Note that this leads to duplicate atoms.
+                When this option is chosen, the ``altloc_id``
+                annotation array is added to the returned structure.
+    extra_fields : list of str, optional
+        The strings in the list are optional annotation categories
+        that should be stored in the output array or stack.
+        These are valid values:
+        ``'atom_id'``, ``'b_factor'``, ``'occupancy'`` and
+        ``'charge'``.
+    include_bonds : bool, optional
+        If set to true, a :class:`BondList` will be created for the
+        resulting :class:`AtomArray` containing the bond information
+        from the file.
+        Bonds, whose order could not be determined from the
+        *Chemical Component Dictionary*
+        (e.g. especially inter-residue bonds),
+        have :attr:`BondType.ANY`, since the PDB format itself does
+        not support bond orders.
+
+    Returns
+    -------
+    symmetry_mates : AtomArray or AtomArrayStack
+        All atoms within a single unit cell.
+        The return type depends on the `model` parameter.
+
+    Notes
+    -----
+    To expand the structure beyond a single unit cell, use
+    :func:`repeat_box()` with the return value as its
+    input.
+
+    Examples
+    --------
+
+    >>> import os.path
+    >>> file = PDBFile.read(os.path.join(path_to_structures, "1aki.pdb"))
+    >>> atoms_in_unit_cell = get_unit_cell(file, model=1)
+    """
+    return pdb_file.get_unit_cell(model, altloc, extra_fields, include_bonds)
+
+
 def get_symmetry_mates(
     pdb_file, model=None, altloc="first", extra_fields=[], include_bonds=False
 ):
@@ -245,6 +321,8 @@ def get_symmetry_mates(
     Consequently, this remark must be present in the file, which is
     usually only true for crystal structures.
 
+    DEPRECATED: Use :func:`get_unit_cell()` instead.
+
     Parameters
     ----------
     pdb_file : PDBFile
@@ -303,4 +381,8 @@ def get_symmetry_mates(
     >>> file = PDBFile.read(os.path.join(path_to_structures, "1aki.pdb"))
     >>> atoms_in_unit_cell = get_symmetry_mates(file, model=1)
     """
-    return pdb_file.get_symmetry_mates(model, altloc, extra_fields, include_bonds)
+    warnings.warn(
+        "'get_symmetry_mates()' is deprecated, use 'get_unit_cell()' instead",
+        DeprecationWarning,
+    )
+    return pdb_file.get_unit_cell(model, altloc, extra_fields, include_bonds)

biotite/structure/io/pdb/file.py

@@ -936,7 +936,11 @@ class PDBFile(TextFile):
             if transform_start is None:
                 raise InvalidFileError("No 'BIOMT' records found for chosen assembly")
             rotations, translations = _parse_transformations(
-                assembly_lines[transform_start:stop]
+                [
+                    line
+                    for line in assembly_lines[transform_start:stop]
+                    if len(line.strip()) > 0
+                ]
             )
             # Filter affected chains
             sub_structure = structure[
@@ -954,7 +958,7 @@ class PDBFile(TextFile):
 
         return assembly
 
-    def get_symmetry_mates(
+    def get_unit_cell(
         self, model=None, altloc="first", extra_fields=[], include_bonds=False
     ):
         """
@@ -1021,7 +1025,7 @@ class PDBFile(TextFile):
 
         >>> import os.path
         >>> file = PDBFile.read(os.path.join(path_to_structures, "1aki.pdb"))
-        >>> atoms_in_unit_cell = file.get_symmetry_mates(model=1)
+        >>> atoms_in_unit_cell = file.get_unit_cell(model=1)
         """
         # Get base structure
         structure = self.get_structure(
@@ -1041,6 +1045,83 @@ class PDBFile(TextFile):
         rotations, translations = _parse_transformations(transform_lines)
         return _apply_transformations(structure, rotations, translations)
 
+    def get_symmetry_mates(
+        self, model=None, altloc="first", extra_fields=[], include_bonds=False
+    ):
+        """
+        Build a structure model containing all symmetric copies
+        of the structure within a single unit cell, given by the space
+        group.
+
+        This function receives the data from ``REMARK 290`` records in
+        the file.
+        Consequently, this remark must be present in the file, which is
+        usually only true for crystal structures.
+
+        DEPRECATED: Use :meth:`get_unit_cell()` instead.
+
+        Parameters
+        ----------
+        model : int, optional
+            If this parameter is given, the function will return an
+            :class:`AtomArray` from the atoms corresponding to the given
+            model number (starting at 1).
+            Negative values are used to index models starting from the
+            last model instead of the first model.
+            If this parameter is omitted, an :class:`AtomArrayStack`
+            containing all models will be returned, even if the
+            structure contains only one model.
+        altloc : {'first', 'occupancy', 'all'}
+            This parameter defines how *altloc* IDs are handled:
+                - ``'first'`` - Use atoms that have the first
+                  *altloc* ID appearing in a residue.
+                - ``'occupancy'`` - Use atoms that have the *altloc* ID
+                  with the highest occupancy for a residue.
+                - ``'all'`` - Use all atoms.
+                  Note that this leads to duplicate atoms.
+                  When this option is chosen, the ``altloc_id``
+                  annotation array is added to the returned structure.
+        extra_fields : list of str, optional
+            The strings in the list are optional annotation categories
+            that should be stored in the output array or stack.
+            These are valid values:
+            ``'atom_id'``, ``'b_factor'``, ``'occupancy'`` and
+            ``'charge'``.
+        include_bonds : bool, optional
+            If set to true, a :class:`BondList` will be created for the
+            resulting :class:`AtomArray` containing the bond information
+            from the file.
+            Bonds, whose order could not be determined from the
+            *Chemical Component Dictionary*
+            (e.g. especially inter-residue bonds),
+            have :attr:`BondType.ANY`, since the PDB format itself does
+            not support bond orders.
+
+        Returns
+        -------
+        symmetry_mates : AtomArray or AtomArrayStack
+            All atoms within a single unit cell.
+            The return type depends on the `model` parameter.
+
+        Notes
+        -----
+        To expand the structure beyond a single unit cell, use
+        :func:`repeat_box()` with the return value as its
+        input.
+
+        Examples
+        --------
+
+        >>> import os.path
+        >>> file = PDBFile.read(os.path.join(path_to_structures, "1aki.pdb"))
+        >>> atoms_in_unit_cell = file.get_symmetry_mates(model=1)
+        """
+        warnings.warn(
+            "'get_symmetry_mates()' is deprecated, use 'get_unit_cell()' instead",
+            DeprecationWarning,
+        )
+        return self.get_unit_cell(model, altloc, extra_fields, include_bonds)
+
     def _index_models_and_atoms(self):
         # Line indices where a new model starts
         self._model_start_i = np.array(
@@ -1116,7 +1197,7 @@ class PDBFile(TextFile):
         conect_lines = [line for line in self.lines if line.startswith("CONECT")]
 
         # Mapping from atom ids to indices in an AtomArray
-        atom_id_to_index = np.zeros(atom_ids[-1] + 1, dtype=int)
+        atom_id_to_index = np.full(atom_ids[-1] + 1, -1, dtype=int)
         try:
             for i, id in enumerate(atom_ids):
                 atom_id_to_index[id] = i
@@ -1125,15 +1206,21 @@ class PDBFile(TextFile):
 
         bonds = []
         for line in conect_lines:
-            center_id = atom_id_to_index[decode_hybrid36(line[6:11])]
+            center_index = atom_id_to_index[decode_hybrid36(line[6:11])]
+            if center_index == -1:
+                # Atom ID is not in the AtomArray (probably removed altloc)
+                continue
             for i in range(11, 31, 5):
                 id_string = line[i : i + 5]
                 try:
-                    id = atom_id_to_index[decode_hybrid36(id_string)]
+                    contact_index = atom_id_to_index[decode_hybrid36(id_string)]
+                    if contact_index == -1:
+                        # Atom ID is not in the AtomArray (probably removed altloc)
+                        continue
                 except ValueError:
                     # String is empty -> no further IDs
                     break
-                bonds.append((center_id, id))
+                bonds.append((center_index, contact_index))
 
         # The length of the 'atom_ids' array
         # is equal to the length of the AtomArray

biotite/structure/io/pdbx/bcif.py

@@ -511,7 +511,7 @@ class BinaryCIFBlock(_HierarchicalContainer):
 
     def __delitem__(self, key):
         try:
-            return super().__setitem__("_" + key)
+            return super().__delitem__("_" + key)
         except KeyError:
             raise KeyError(key)
 
@@ -581,9 +581,12 @@ class BinaryCIFFile(File, _HierarchicalContainer):
 
     @property
     def block(self):
-        if len(self) != 1:
+        if len(self) == 0:
+            raise ValueError("There are no blocks in the file")
+        elif len(self) > 1:
             raise ValueError("There are multiple blocks in the file")
-        return self[next(iter(self))]
+        else:
+            return self[next(iter(self))]
 
     @staticmethod
     def subcomponent_class():

biotite/structure/io/pdbx/cif.py

@@ -799,9 +799,12 @@ class CIFFile(_Component, File, MutableMapping):
 
     @property
     def block(self):
-        if len(self) != 1:
+        if len(self) == 0:
+            raise ValueError("There are no blocks in the file")
+        elif len(self) > 1:
             raise ValueError("There are multiple blocks in the file")
-        return self[next(iter(self))]
+        else:
+            return self[next(iter(self))]
 
     @staticmethod
     def subcomponent_class():