biotite 1.1.0__cp311-cp311-macosx_11_0_arm64.whl → 1.3.0__cp311-cp311-macosx_11_0_arm64.whl

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")
@@ -953,7 +954,7 @@ class PDBFile(TextFile):
 
         return assembly
 
-    def get_symmetry_mates(
+    def get_unit_cell(
         self, model=None, altloc="first", extra_fields=[], include_bonds=False
     ):
         """
@@ -1020,7 +1021,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(
@@ -1040,6 +1041,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(
@@ -1106,7 +1184,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 +1326,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 +1348,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

@@ -3,6 +3,7 @@ __name__ = "biotite.structure.io.pdbx"
 __author__ = "Patrick Kunzmann"
 
 import itertools
+import warnings
 import msgpack
 import numpy as np
 import biotite.structure.io.pdbx.bcif as bcif
@@ -17,7 +18,7 @@ from biotite.structure.io.pdbx.encoding import (
 )
 
 
-def compress(data, float_tolerance=1e-6):
+def compress(data, float_tolerance=None, rtol=1e-6, atol=1e-4):
     """
     Try to reduce the size of a *BinaryCIF* file (or block, category, etc.) by testing
     different data encodings for each data array and selecting the one, which results in
@@ -27,6 +28,14 @@ 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.
+        DEPRECATED: Use `rtol` instead.
+    rtol, atol : float, optional
+        The compression factor of floating point numbers is chosen such that
+        either the relative (`rtol`) or absolute (`atol`) tolerance is fulfilled
+        for each value, i.e. the difference between the compressed and uncompressed
+        value is smaller than the tolerance.
 
     Returns
     -------
@@ -35,8 +44,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
     --------
@@ -58,55 +65,70 @@ def compress(data, float_tolerance=1e-6):
     >>> print(f"{len(compressed_file.read()) // 1000} KB")
     111 KB
     """
+    if float_tolerance is not None:
+        warnings.warn(
+            "The 'float_tolerance' parameter is deprecated, use 'rtol' instead",
+            DeprecationWarning,
+        )
+
     match type(data):
         case bcif.BinaryCIFFile:
-            return _compress_file(data, float_tolerance)
+            return _compress_file(data, rtol, atol)
         case bcif.BinaryCIFBlock:
-            return _compress_block(data, float_tolerance)
+            return _compress_block(data, rtol, atol)
         case bcif.BinaryCIFCategory:
-            return _compress_category(data, float_tolerance)
+            return _compress_category(data, rtol, atol)
         case bcif.BinaryCIFColumn:
-            return _compress_column(data, float_tolerance)
+            return _compress_column(data, rtol, atol)
         case bcif.BinaryCIFData:
-            return _compress_data(data, float_tolerance)
+            return _compress_data(data, rtol, atol)
         case _:
             raise TypeError(f"Unsupported type {type(data).__name__}")
 
 
-def _compress_file(bcif_file, float_tolerance):
+def _compress_file(bcif_file, rtol, atol):
     compressed_file = bcif.BinaryCIFFile()
     for block_name, bcif_block in bcif_file.items():
-        compressed_block = _compress_block(bcif_block, float_tolerance)
+        try:
+            compressed_block = _compress_block(bcif_block, rtol, atol)
+        except Exception:
+            raise ValueError(f"Failed to compress block '{block_name}'")
         compressed_file[block_name] = compressed_block
     return compressed_file
 
 
-def _compress_block(bcif_block, float_tolerance):
+def _compress_block(bcif_block, rtol, atol):
     compressed_block = bcif.BinaryCIFBlock()
     for category_name, bcif_category in bcif_block.items():
-        compressed_category = _compress_category(bcif_category, float_tolerance)
+        try:
+            compressed_category = _compress_category(bcif_category, rtol, atol)
+        except Exception:
+            raise ValueError(f"Failed to compress category '{category_name}'")
         compressed_block[category_name] = compressed_category
     return compressed_block
 
 
-def _compress_category(bcif_category, float_tolerance):
+def _compress_category(bcif_category, rtol, atol):
     compressed_category = bcif.BinaryCIFCategory()
     for column_name, bcif_column in bcif_category.items():
-        compressed_column = _compress_column(bcif_column, float_tolerance)
+        try:
+            compressed_column = _compress_column(bcif_column, rtol, atol)
+        except Exception:
+            raise ValueError(f"Failed to compress column '{column_name}'")
         compressed_category[column_name] = compressed_column
     return compressed_category
 
 
-def _compress_column(bcif_column, float_tolerance):
-    data = _compress_data(bcif_column.data, float_tolerance)
+def _compress_column(bcif_column, rtol, atol):
+    data = _compress_data(bcif_column.data, rtol, atol)
     if bcif_column.mask is not None:
-        mask = _compress_data(bcif_column.mask, float_tolerance)
+        mask = _compress_data(bcif_column.mask, rtol, atol)
     else:
         mask = None
     return bcif.BinaryCIFColumn(data, mask)
 
 
-def _compress_data(bcif_data, float_tolerance):
+def _compress_data(bcif_data, rtol, atol):
     array = bcif_data.array
     if len(array) == 1:
         # No need to compress a single value -> Use default uncompressed encoding
@@ -123,16 +145,28 @@ def _compress_data(bcif_data, float_tolerance):
         return bcif.BinaryCIFData(array, [encoding])
 
     elif np.issubdtype(array.dtype, np.floating):
+        if not np.isfinite(array).all():
+            # NaN/inf values cannot be represented by integers
+            # -> do not use integer encoding
+            return bcif.BinaryCIFData(array, [ByteArrayEncoding()])
         to_integer_encoding = FixedPointEncoding(
-            10 ** _get_decimal_places(array, float_tolerance)
+            10 ** _get_decimal_places(array, rtol, atol)
         )
-        integer_array = to_integer_encoding.encode(array)
-        best_encoding, size_compressed = _find_best_integer_compression(integer_array)
-        if size_compressed < _data_size_in_file(bcif.BinaryCIFData(array)):
-            return bcif.BinaryCIFData(array, [to_integer_encoding] + best_encoding)
-        else:
-            # The float array is smaller -> encode it directly as bytes
+        try:
+            integer_array = to_integer_encoding.encode(array)
+        except ValueError:
+            # With the given tolerances integer underflow/overflow would occur
+            # -> do not use integer encoding
             return bcif.BinaryCIFData(array, [ByteArrayEncoding()])
+        else:
+            best_encoding, size_compressed = _find_best_integer_compression(
+                integer_array
+            )
+            if size_compressed < _data_size_in_file(bcif.BinaryCIFData(array)):
+                return bcif.BinaryCIFData(array, [to_integer_encoding] + best_encoding)
+            else:
+                # The float array is smaller -> encode it directly as bytes
+                return bcif.BinaryCIFData(array, [ByteArrayEncoding()])
 
     elif np.issubdtype(array.dtype, np.integer):
         array = _to_smallest_integer_type(array)
@@ -273,7 +307,7 @@ def _data_size_in_file(data):
     return len(bytes_in_file)
 
 
-def _get_decimal_places(array, tol):
+def _get_decimal_places(array, rtol, atol):
     """
     Get the number of decimal places in a floating point array.
 
@@ -281,21 +315,24 @@ def _get_decimal_places(array, tol):
     ----------
     array : numpy.ndarray
         The array to analyze.
-    tol : float, optional
-        The relative tolerance allowed when the values are cut off after the returned
-        number of decimal places.
+    rtol, atol : float, optional
+        The relative and absolute tolerance allowed when the values are cut off after
+        the returned number of decimal places.
 
     Returns
     -------
     decimals : int
         The number of decimal places.
     """
-    # Decimals of NaN or infinite values do not make sense
-    # and 0 would give NaN when rounding on decimals
-    array = array[np.isfinite(array) & (array != 0)]
-    for decimals in itertools.count(start=-_order_magnitude(array)):
+    if rtol <= 0 and atol <= 0:
+        raise ValueError("At least one of 'rtol' and 'atol' must be greater than 0")
+    # 0 would give NaN when rounding on decimals
+    array = array[array != 0]
+    for decimals in itertools.count(start=min(0, -_order_magnitude(array))):
         error = np.abs(np.round(array, decimals) - array)
-        if np.all(error < tol * np.abs(array)):
+        if decimals == 100:
+            raise
+        if np.all((error < rtol * np.abs(array)) | (error < atol)):
             return decimals