biotite 1.1.0__cp312-cp312-macosx_11_0_arm64.whl → 1.2.0__cp312-cp312-macosx_11_0_arm64.whl

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

@@ -89,14 +89,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 +113,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

biotite/structure/io/pdb/file.py

@@ -24,6 +24,7 @@ from biotite.structure.io.pdb.hybrid36 import (
     encode_hybrid36,
     max_hybrid36_number,
 )
+from biotite.structure.io.util import number_of_integer_digits
 from biotite.structure.repair import infer_elements
 from biotite.structure.util import matrix_rotate
 
@@ -70,10 +71,10 @@ class PDBFile(TextFile):
     records cannot be written.
     Additionally, *REMARK* records can be read
 
-    See also
+    See Also
     --------
-    CIFFile
-    BinaryCIFFile
+    CIFFile : Interface to CIF files, a modern replacement for PDB files.
+    BinaryCIFFile : Interface to BinaryCIF files, a binary variant of CIF files.
 
     Examples
     --------
@@ -597,7 +598,7 @@ class PDBFile(TextFile):
             The array or stack to be saved into this file. If a stack
             is given, each array in the stack is saved as separate
             model.
-        hybrid36: bool, optional
+        hybrid36 : bool, optional
             Defines wether the file should be written in hybrid-36
             format.
 
@@ -894,7 +895,7 @@ class PDBFile(TextFile):
         if assembly_start_i is None:
             if assembly_id is None:
                 raise InvalidFileError(
-                    "File does not contain transformation " "expressions for assemblies"
+                    "File does not contain transformation expressions for assemblies"
                 )
             else:
                 raise KeyError(f"The assembly ID '{assembly_id}' is not found")
@@ -1106,7 +1107,7 @@ class PDBFile(TextFile):
                 length = model_length
             if model_length != length:
                 raise InvalidFileError(
-                    f"Model {model_i+1} has {model_length} atoms, "
+                    f"Model {model_i + 1} has {model_length} atoms, "
                     f"but model 1 has {length} atoms, must be equal"
                 )
         return length
@@ -1248,21 +1249,21 @@ def _check_pdb_compatibility(array, hybrid36):
     if any([len(name) > 4 for name in array.atom_name]):
         raise BadStructureError("Some atom names exceed 4 characters")
     for i, coord_name in enumerate(["x", "y", "z"]):
-        n_coord_digits = _number_of_integer_digits(array.coord[..., i])
+        n_coord_digits = number_of_integer_digits(array.coord[..., i])
         if n_coord_digits > 4:
             raise BadStructureError(
                 f"4 pre-decimal columns for {coord_name}-coordinates are "
                 f"available, but array would require {n_coord_digits}"
             )
     if "b_factor" in annot_categories:
-        n_b_factor_digits = _number_of_integer_digits(array.b_factor)
+        n_b_factor_digits = number_of_integer_digits(array.b_factor)
         if n_b_factor_digits > 3:
             raise BadStructureError(
                 "3 pre-decimal columns for B-factor are available, "
                 f"but array would require {n_b_factor_digits}"
             )
     if "occupancy" in annot_categories:
-        n_occupancy_digits = _number_of_integer_digits(array.occupancy)
+        n_occupancy_digits = number_of_integer_digits(array.occupancy)
         if n_occupancy_digits > 3:
             raise BadStructureError(
                 "3 pre-decimal columns for occupancy are available, "
@@ -1270,21 +1271,9 @@ def _check_pdb_compatibility(array, hybrid36):
             )
     if "charge" in annot_categories:
         # The sign can be omitted is it is put into the adjacent column
-        n_charge_digits = _number_of_integer_digits(np.abs(array.charge))
+        n_charge_digits = number_of_integer_digits(np.abs(array.charge))
         if n_charge_digits > 1:
             raise BadStructureError(
                 "1 column for charge is available, "
                 f"but array would require {n_charge_digits}"
             )
-
-
-def _number_of_integer_digits(values):
-    """
-    Get the maximum number of characters needed to represent the
-    pre-decimal positions of the given numeric values.
-    """
-    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/io/pdbqt/file.py

@@ -525,9 +525,9 @@ class PDBQTFile(TextFile):
                 f"{atoms.chain_id[i]:1}"
                 f"{atoms.res_id[i]:>4d}"
                 f"{atoms.ins_code[i]:1}   "
-                f"{atoms.coord[i,0]:>8.3f}"
-                f"{atoms.coord[i,1]:>8.3f}"
-                f"{atoms.coord[i,2]:>8.3f}"
+                f"{atoms.coord[i, 0]:>8.3f}"
+                f"{atoms.coord[i, 1]:>8.3f}"
+                f"{atoms.coord[i, 2]:>8.3f}"
                 f"{occupancy[i]:>6.2f}"
                 f"{b_factor[i]:>6.2f}    "
                 f"{charges[i]:>6.3f} "
@@ -604,7 +604,7 @@ class PDBQTFile(TextFile):
                 length = model_length
             if model_length != length:
                 raise InvalidFileError(
-                    f"Model {model_i+1} has {model_length} atoms, "
+                    f"Model {model_i + 1} has {model_length} atoms, "
                     f"but model 1 has {length} atoms, must be equal"
                 )
         return length

biotite/structure/io/pdbx/bcif.py

@@ -195,7 +195,7 @@ class BinaryCIFColumn(_Component):
                 mask = BinaryCIFData(mask)
             if len(data) != len(mask):
                 raise IndexError(
-                    f"Data has length {len(data)}, " f"but mask has length {len(mask)}"
+                    f"Data has length {len(data)}, but mask has length {len(mask)}"
                 )
         self._data = data
         self._mask = mask
@@ -256,6 +256,11 @@ class BinaryCIFColumn(_Component):
             ``MaskValue.INAPPLICABLE`` or ``MaskValue.MISSING``.
             By default, masked elements are converted to ``'.'`` or
             ``'?'`` depending on the :class:`MaskValue`.
+
+        Returns
+        -------
+        array : ndarray
+            The column data as array.
         """
         if dtype is None:
             dtype = self._data.array.dtype
@@ -341,12 +346,15 @@ class BinaryCIFCategory(_HierarchicalContainer):
         into a :class:`BinaryCIFColumn`).
         By default, an empty category is created.
         Each column must have the same length.
+    row_count : int, optional
+        The number of rows in the category.
 
     Attributes
     ----------
     row_count : int
         The number of rows in the category, i.e. the length of each
         column.
+        By default, the row count is determined when the first column is added.
 
     Examples
     --------
@@ -526,6 +534,19 @@ class BinaryCIFFile(File, _HierarchicalContainer):
     object, use the high-level :func:`get_structure()` or
     :func:`set_structure()` function respectively.
 
+    Parameters
+    ----------
+    blocks : dict (str -> BinaryCIFBlock), optional
+        The initial blocks of the file.
+        Maps the block names to the corresponding :class:`BinaryCIFBlock` objects.
+        By default no initial blocks are added.
+
+    Attributes
+    ----------
+    block : BinaryCIFBlock
+        The sole block of the file.
+        If the file contains multiple blocks, an exception is raised.
+
     Notes
     -----
     The content of *BinaryCIF* files are lazily deserialized:
@@ -534,12 +555,6 @@ class BinaryCIFFile(File, _HierarchicalContainer):
     The decoded :class:`BinaryCIFBlock`/:class:`BinaryCIFCategory`
     objects are cached for subsequent accesses.
 
-    Attributes
-    ----------
-    block : BinaryCIFBlock
-        The sole block of the file.
-        If the file contains multiple blocks, an exception is raised.
-
     Examples
     --------
     Read a *BinaryCIF* file and access its content:

biotite/structure/io/pdbx/cif.py

@@ -149,7 +149,7 @@ class CIFColumn:
                 mask = CIFData(mask, np.uint8)
             if len(mask) != len(data):
                 raise IndexError(
-                    f"Data has length {len(data)}, " f"but mask has length {len(mask)}"
+                    f"Data has length {len(data)}, but mask has length {len(mask)}"
                 )
         self._data = data
         self._mask = mask
@@ -215,6 +215,11 @@ class CIFColumn:
             ``MaskValue.INAPPLICABLE`` or ``MaskValue.MISSING``.
             By default, masked elements are converted to ``'.'`` or
             ``'?'`` depending on the :class:`MaskValue`.
+
+        Returns
+        -------
+        array : ndarray
+            The column data as array.
         """
         if self._mask is None:
             return self._data.array.astype(dtype, copy=False)
@@ -721,6 +726,19 @@ class CIFFile(_Component, File, MutableMapping):
     use the high-level :func:`get_structure()` or
     :func:`set_structure()` function respectively.
 
+    Parameters
+    ----------
+    blocks : dict (str -> CIFBlock), optional
+        The initial blocks of the file.
+        Maps the block names to the corresponding :class:`CIFBlock` objects.
+        By default no initial blocks are added.
+
+    Attributes
+    ----------
+    block : CIFBlock
+        The sole block of the file.
+        If the file contains multiple blocks, an exception is raised.
+
     Notes
     -----
     The content of CIF files are lazily deserialized:
@@ -731,12 +749,6 @@ class CIFFile(_Component, File, MutableMapping):
     The deserialized :class:`CIFBlock`/:class:`CIFCategory` objects
     are cached for subsequent accesses.
 
-    Attributes
-    ----------
-    block : CIFBlock
-        The sole block of the file.
-        If the file contains multiple blocks, an exception is raised.
-
     Examples
     --------
     Read a CIF file and access its content:
@@ -884,6 +896,7 @@ class CIFFile(_Component, File, MutableMapping):
                 block = CIFBlock.deserialize(block)
             except Exception:
                 raise DeserializationError(f"Failed to deserialize block '{key}'")
+            block.name = key
             # Update with deserialized object
             self._blocks[key] = block
         return block

biotite/structure/io/pdbx/component.py

@@ -120,6 +120,12 @@ class _HierarchicalContainer(_Component, MutableMapping, metaclass=ABCMeta):
     A component is only deserialized from the serialized data, if it
     is accessed.
     The deserialized component is then cached in the container.
+
+    Parameters
+    ----------
+    elements : dict, optional
+        The initial elements of the container.
+        By default no initial elements are added.
     """
 
     def __init__(self, elements=None):

biotite/structure/io/pdbx/compress.py

@@ -27,6 +27,8 @@ def compress(data, float_tolerance=1e-6):
     ----------
     data : BinaryCIFFile or BinaryCIFBlock or BinaryCIFCategory or BinaryCIFColumn or BinaryCIFData
         The data to compress.
+    float_tolerance : float, optional
+        The relative error that is accepted when compressing floating point numbers.
 
     Returns
     -------
@@ -35,8 +37,6 @@ def compress(data, float_tolerance=1e-6):
         If no improved compression is found for a :class:`BinaryCIFData` array,
         the input data is kept.
         Hence, the return value is no deep copy of the input data.
-    float_tolerance : float, optional
-        The relative error that is accepted when compressing floating point numbers.
 
     Examples
     --------