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

biotite/structure/io/gro/file.py

@@ -48,7 +48,6 @@ class GROFile(TextFile):
     >>> file = GROFile()
     >>> file.set_structure(array_stack_mod)
     >>> file.write(os.path.join(path_to_directory, "1l2y_mod.gro"))
-
     """
 
     def get_model_count(self):
@@ -89,13 +88,13 @@ class GROFile(TextFile):
             The return type depends on the `model` parameter.
         """
 
-        def get_atom_line_i(model_start_i, model_atom_counts):
+        def _get_atom_line_i(model_start_i, model_atom_counts):
             """
             Helper function to get the indices of all atoms for a model
             """
             return np.arange(model_start_i + 1, model_start_i + 1 + model_atom_counts)
 
-        def set_box_dimen(box_param):
+        def _set_box_dimen(box_param):
             """
             Helper function to create the box vectors from the values
             in the GRO file
@@ -145,7 +144,7 @@ class GROFile(TextFile):
 
             # Line indices for annotation determination is determined
             # from model 1
-            annot_i = get_atom_line_i(model_start_i[0], length)
+            annot_i = _get_atom_line_i(model_start_i[0], length)
         else:
             if model == 0:
                 raise ValueError("The model index must not be 0")
@@ -160,7 +159,7 @@ class GROFile(TextFile):
             length = model_atom_counts[model - 1]
             array = AtomArray(length)
 
-            annot_i = get_atom_line_i(model_start_i[model - 1], length)
+            annot_i = _get_atom_line_i(model_start_i[model - 1], length)
 
         # Replace empty strings for elements with guessed types
         # i is index in array, line_i is line index
@@ -183,11 +182,11 @@ class GROFile(TextFile):
             # Box is stored in last line (after coordinates)
             box_i = atom_i[-1] + 1
             box_param = [float(e) * 10 for e in self.lines[box_i].split()]
-            array.box = set_box_dimen(box_param)
+            array.box = _set_box_dimen(box_param)
 
         elif isinstance(array, AtomArrayStack):
             for m in range(len(model_start_i)):
-                atom_i = get_atom_line_i(model_start_i[m], model_atom_counts[m])
+                atom_i = _get_atom_line_i(model_start_i[m], model_atom_counts[m])
                 for i, line_i in enumerate(atom_i):
                     line = self.lines[line_i]
                     array.coord[m, i, 0] = float(line[20:28]) * 10
@@ -196,7 +195,7 @@ class GROFile(TextFile):
                 # Box is stored in last line (after coordinates)
                 box_i = atom_i[-1] + 1
                 box_param = [float(e) * 10 for e in self.lines[box_i].split()]
-                box = set_box_dimen(box_param)
+                box = _set_box_dimen(box_param)
                 # Create a box in the stack if not already existing
                 # and the box is not a dummy
                 if box is not None:
@@ -311,7 +310,7 @@ class GROFile(TextFile):
 
             for i in range(array.stack_depth()):
                 self.lines.append(
-                    f"Generated by Biotite at {datetime.now()}, model={i+1}"
+                    f"Generated by Biotite at {datetime.now()}, model={i + 1}"
                 )
                 self.lines.append(str(array.array_length()))
 

biotite/structure/io/mol/convert.py

@@ -52,7 +52,7 @@ def set_structure(
     ----------
     mol_file : MOLFile
         The MOL file.
-    array : AtomArray
+    atoms : AtomArray
         The array to be saved into this file.
         Must have an associated :class:`BondList`.
         Bond type fallback for the *Bond block*, if a

biotite/structure/io/mol/ctab.py

@@ -19,24 +19,19 @@ from biotite.file import InvalidFileError
 from biotite.structure.atoms import AtomArray, AtomArrayStack
 from biotite.structure.bonds import BondList, BondType
 from biotite.structure.error import BadStructureError
+from biotite.structure.io.util import number_of_integer_digits
 
 BOND_TYPE_MAPPING = {
     1: BondType.SINGLE,
     2: BondType.DOUBLE,
     3: BondType.TRIPLE,
+    4: BondType.AROMATIC,
     5: BondType.ANY,
-    6: BondType.SINGLE,
-    7: BondType.DOUBLE,
+    6: BondType.AROMATIC_SINGLE,
+    7: BondType.AROMATIC_DOUBLE,
     8: BondType.ANY,
 }
-BOND_TYPE_MAPPING_REV = {
-    BondType.SINGLE: 1,
-    BondType.DOUBLE: 2,
-    BondType.TRIPLE: 3,
-    BondType.AROMATIC_SINGLE: 1,
-    BondType.AROMATIC_DOUBLE: 2,
-    BondType.ANY: 8,
-}
+BOND_TYPE_MAPPING_REV = {v: k for k, v in BOND_TYPE_MAPPING.items()}
 
 CHARGE_MAPPING = {0: 0, 1: 3, 2: 2, 3: 1, 5: -1, 6: -2, 7: -3}
 CHARGE_MAPPING_REV = {val: key for key, val in CHARGE_MAPPING.items()}
@@ -56,7 +51,7 @@ def read_structure_from_ctab(ctab_lines):
     ----------
     ctab_lines : lines of str
         The lines containing the *ctab*.
-        Must begin with the *counts* line and end with the `M END` line
+        Must begin with the *counts* line and end with the `M END` line.
 
     Returns
     -------
@@ -71,7 +66,6 @@ def read_structure_from_ctab(ctab_lines):
     `<https://discover.3ds.com/sites/default/files/2020-08/biovia_ctfileformats_2020.pdf>`_.
 
     .. footbibliography::
-
     """
     match _get_version(ctab_lines[0]):
         case "V2000":
@@ -119,11 +113,10 @@ def write_structure_to_ctab(atoms, default_bond_type=BondType.ANY, version=None)
     `<https://discover.3ds.com/sites/default/files/2020-08/biovia_ctfileformats_2020.pdf>`_.
 
     .. footbibliography::
-
     """
     if isinstance(atoms, AtomArrayStack):
         raise TypeError(
-            "An 'AtomArrayStack' was given, " "but only a single model can be written"
+            "An 'AtomArrayStack' was given, but only a single model can be written"
         )
     if atoms.bonds is None:
         raise BadStructureError("Input AtomArray has no associated BondList")
@@ -141,8 +134,7 @@ def write_structure_to_ctab(atoms, default_bond_type=BondType.ANY, version=None)
                 atoms.array_length(), atoms.bonds.get_bond_count()
             ):
                 raise ValueError(
-                    "The given number of atoms or bonds is too large "
-                    "for V2000 format"
+                    "The given number of atoms or bonds is too large for V2000 format"
                 )
             return _write_structure_to_ctab_v2000(atoms, default_bond_type)
         case "V3000":
@@ -174,7 +166,7 @@ def _read_structure_from_ctab_v2000(ctab_lines):
             charge = CHARGE_MAPPING.get(int(line[36:39]))
             if charge is None:
                 warnings.warn(
-                    f"Cannot handle MDL charge type {int(line[36 : 39])}, "
+                    f"Cannot handle MDL charge type {int(line[36:39])}, "
                     f"0 is used instead"
                 )
                 charge = 0
@@ -194,7 +186,7 @@ def _read_structure_from_ctab_v2000(ctab_lines):
         bond_type = BOND_TYPE_MAPPING.get(int(line[6:9]))
         if bond_type is None:
             warnings.warn(
-                f"Cannot handle MDL bond type {int(line[6 : 9])}, "
+                f"Cannot handle MDL bond type {int(line[6:9])}, "
                 f"BondType.ANY is used instead"
             )
             bond_type = BondType.ANY
@@ -247,8 +239,7 @@ def _read_structure_from_ctab_v3000(ctab_lines):
         bond_type = BOND_TYPE_MAPPING.get(v30_type)
         if bond_type is None:
             warnings.warn(
-                f"Cannot handle MDL bond type {v30_type}, "
-                f"BondType.ANY is used instead"
+                f"Cannot handle MDL bond type {v30_type}, BondType.ANY is used instead"
             )
             bond_type = BondType.ANY
         bond_array[i, 0] = v30_atom_indices[v30_atom_index_1]
@@ -307,10 +298,17 @@ def _write_structure_to_ctab_v2000(atoms, default_bond_type):
         "  0     0  0  0  0  0  0  1 V2000"
     )
 
+    for i, coord_name in enumerate(["x", "y", "z"]):
+        n_coord_digits = number_of_integer_digits(atoms.coord[:, i])
+        if n_coord_digits > 5:
+            raise BadStructureError(
+                f"5 pre-decimal columns for {coord_name}-coordinates are "
+                f"available, but array would require {n_coord_digits}"
+            )
     atom_lines = [
-        f"{atoms.coord[i,0]:>10.4f}"
-        f"{atoms.coord[i,1]:>10.4f}"
-        f"{atoms.coord[i,2]:>10.4f}"
+        f"{atoms.coord[i, 0]:>10.4f}"
+        f"{atoms.coord[i, 1]:>10.4f}"
+        f"{atoms.coord[i, 2]:>10.4f}"
         f" {atoms.element[i].capitalize():3}"
         f"{0:>2}"  # Mass difference -> unused
         f"{CHARGE_MAPPING_REV.get(charge[i], 0):>3d}"
@@ -321,7 +319,7 @@ def _write_structure_to_ctab_v2000(atoms, default_bond_type):
 
     default_bond_value = BOND_TYPE_MAPPING_REV[default_bond_type]
     bond_lines = [
-        f"{i+1:>3d}{j+1:>3d}"
+        f"{i + 1:>3d}{j + 1:>3d}"
         f"{BOND_TYPE_MAPPING_REV.get(bond_type, default_bond_value):>3d}"
         + f"{0:>3d}"
         * 4
@@ -337,7 +335,7 @@ def _write_structure_to_ctab_v2000(atoms, default_bond_type):
     ):
         charge_lines.append(
             f"M  CHG{len(batch):>3d}"
-            + "".join(f" {atom_i+1:>3d} {c:>3d}" for atom_i, c in batch)
+            + "".join(f" {atom_i + 1:>3d} {c:>3d}" for atom_i, c in batch)
         )
 
     return [counts_line] + atom_lines + bond_lines + charge_lines + ["M  END"]
@@ -351,12 +349,19 @@ def _write_structure_to_ctab_v3000(atoms, default_bond_type):
 
     counts_line = f"COUNTS {atoms.array_length()} {atoms.bonds.get_bond_count()} 0 0 0"
 
+    for i, coord_name in enumerate(["x", "y", "z"]):
+        n_coord_digits = number_of_integer_digits(atoms.coord[:, i])
+        if n_coord_digits > 5:
+            raise BadStructureError(
+                f"5 pre-decimal columns for {coord_name}-coordinates are "
+                f"available, but array would require {n_coord_digits}"
+            )
     atom_lines = [
         f"{i + 1}"
         f" {_quote(atoms.element[i].capitalize())}"
-        f" {atoms.coord[i,0]:.4f}"
-        f" {atoms.coord[i,1]:.4f}"
-        f" {atoms.coord[i,2]:.4f}"
+        f" {atoms.coord[i, 0]:.4f}"
+        f" {atoms.coord[i, 1]:.4f}"
+        f" {atoms.coord[i, 2]:.4f}"
         # 'aamap' is unused
         f" 0"
         f" {_to_property(charges[i])}"

biotite/structure/io/mol/mol.py

@@ -122,7 +122,7 @@ class MOLFile(TextFile):
 
         Parameters
         ----------
-        array : AtomArray
+        atoms : AtomArray
             The array to be saved into this file.
             Must have an associated :class:`BondList`.
         default_bond_type : BondType, optional

biotite/structure/io/mol/sdf.py

@@ -78,7 +78,6 @@ class Metadata(MutableMapping):
     >>> print(metadata[Metadata.Key(number=42, name="bar")])
     dolor sit amet,
     consectetur
-
     """
 
     @dataclass(frozen=True, kw_only=True)
@@ -144,12 +143,18 @@ class Metadata(MutableMapping):
         @staticmethod
         def deserialize(text):
             """
-            Create an object by deserializing the given text content.
+            Create a :class:`Metadata.Key` object by deserializing the given text
+            content.
 
             Parameters
             ----------
-            content : str
+            text : str
                 The content to be deserialized.
+
+            Returns
+            -------
+            key : Metadata.Key
+                The parsed key.
             """
             # Omit the leading '>'
             key_components = text[1:].split()
@@ -207,12 +212,17 @@ class Metadata(MutableMapping):
     @staticmethod
     def deserialize(text):
         """
-        Create an object by deserializing the given text content.
+        Create a :class:`Metadata` objtect by deserializing the given text content.
 
         Parameters
         ----------
-        content : str
+        text : str
             The content to be deserialized.
+
+        Returns
+        -------
+        metadata : Metadata
+            The parsed metadata.
         """
         metadata = {}
         current_key = None
@@ -423,19 +433,23 @@ class SDRecord:
             self._metadata = Metadata(metadata)
         else:
             raise TypeError(
-                "Expected 'Metadata' or Mapping, "
-                f"but got '{type(metadata).__name__}'"
+                f"Expected 'Metadata' or Mapping, but got '{type(metadata).__name__}'"
             )
 
     @staticmethod
     def deserialize(text):
         """
-        Create an object by deserializing the given text content.
+        Create an :class:`SDRecord` by deserializing the given text content.
 
         Parameters
         ----------
-        content : str
+        text : str
             The content to be deserialized.
+
+        Returns
+        -------
+        record : SDRecord
+            The parsed record.
         """
         lines = text.splitlines()
         ctab_end = _get_ctab_stop(lines)
@@ -494,7 +508,7 @@ class SDRecord:
 
         Parameters
         ----------
-        array : AtomArray
+        atoms : AtomArray
             The array to be saved into this file.
             Must have an associated :class:`BondList`.
         default_bond_type : BondType, optional
@@ -539,6 +553,13 @@ class SDFile(File, MutableMapping):
     :class:`SDRecord` object via :func:`get_structure()` or
     :func:`set_structure()`, respectively.
 
+    Parameters
+    ----------
+    records : dict (str -> SDRecord), optional
+        The initial records of the file.
+        Maps the record names to the corresponding :class:`SDRecord` objects.
+        By default no initial records are added.
+
     Attributes
     ----------
     record : CIFBlock
@@ -732,12 +753,17 @@ class SDFile(File, MutableMapping):
     @staticmethod
     def deserialize(text):
         """
-        Create an object by deserializing the given text content.
+        Create an :class:`SDFile` by deserializing the given text content.
 
         Parameters
         ----------
-        content : str
+        text : str
             The content to be deserialized.
+
+        Returns
+        -------
+        file_object : SDFile
+            The parsed file.
         """
         lines = text.splitlines()
         record_ends = np.array(
@@ -896,7 +922,7 @@ def _to_metadata_key(key):
         return Metadata.Key(name=key)
     else:
         raise TypeError(
-            "Expected 'Metadata.Key' or str, " f"but got '{type(key).__name__}'"
+            f"Expected 'Metadata.Key' or str, but got '{type(key).__name__}'"
         )
 
 

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):
     """
@@ -89,14 +91,13 @@ def get_structure(
     -------
     array : AtomArray or AtomArrayStack
         The return type depends on the `model` parameter.
-
     """
     return pdb_file.get_structure(model, altloc, extra_fields, include_bonds)
 
 
 def set_structure(pdb_file, array, hybrid36=False):
     """
-    write an :class:`AtomArray` or :class:`AtomArrayStack` into a
+    Write an :class:`AtomArray` or :class:`AtomArrayStack` into a
     :class:`PDBFile`.
 
     This function is a thin wrapper around the :class:`PDBFile` method
@@ -114,7 +115,7 @@ def set_structure(pdb_file, array, hybrid36=False):
     array : AtomArray or AtomArrayStack
         The structure to be written. If a stack is given, each array in
         the stack will be in a separate model.
-    hybrid36: boolean, optional
+    hybrid36 : boolean, optional
         Defines wether the file should be written in hybrid-36 format.
 
     Notes
@@ -233,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
 ):
@@ -246,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
@@ -304,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)