biotite 1.0.1__cp312-cp312-win_amd64.whl → 1.2.0__cp312-cp312-win_amd64.whl

biotite/structure/io/pdb/file.py

@@ -7,6 +7,7 @@ __author__ = "Patrick Kunzmann, Daniel Bauer, Claude J. Rogers"
 __all__ = ["PDBFile"]
 
 import warnings
+from collections import namedtuple
 import numpy as np
 from biotite.file import InvalidFileError, TextFile
 from biotite.structure.atoms import AtomArray, AtomArrayStack, repeat
@@ -23,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
 
@@ -53,6 +55,8 @@ _c = slice(24, 33)
 _alpha = slice(33, 40)
 _beta = slice(40, 47)
 _gamma = slice(47, 54)
+_space = slice(55, 66)
+_z = slice(66, 70)
 
 
 class PDBFile(TextFile):
@@ -67,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
     --------
@@ -545,6 +549,38 @@ class PDBFile(TextFile):
 
         return array
 
+    def get_space_group(self):
+        """
+        Extract the space group and Z value from the CRYST1 record.
+
+        Returns
+        -------
+        space_group : str
+            The extracted space group.
+        z_val : int
+            The extracted Z value.
+        """
+        # Initialize the namedtuple
+        SpaceGroupInfo = namedtuple("SpaceGroupInfo", ["space_group", "z_val"])
+
+        # CRYST1 is a one-time record so we can extract it directly
+        for line in self.lines:
+            if line.startswith("CRYST1"):
+                try:
+                    # Extract space group and Z value
+                    space_group = str(line[_space])
+                    z_val = int(line[_z])
+                except ValueError:
+                    # File contains invalid 'CRYST1' record
+                    raise InvalidFileError(
+                        "File does not contain valid space group and/or Z values"
+                    )
+                    # Set default values
+                    space_group = "P 1"
+                    z_val = 1
+                break
+        return SpaceGroupInfo(space_group=space_group, z_val=z_val)
+
     def set_structure(self, array, hybrid36=False):
         """
         Set the :class:`AtomArray` or :class:`AtomArrayStack` for the
@@ -562,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.
 
@@ -700,6 +736,32 @@ class PDBFile(TextFile):
 
         self._index_models_and_atoms()
 
+    def set_space_group(self, info):
+        """
+        Update the CRYST1 record with the provided space group and Z value.
+
+        Parameters
+        ----------
+        info : tuple(str, int) or SpaceGroupInfo
+            Contains the space group and Z-value.
+        """
+        for i, line in enumerate(self.lines):
+            if line.startswith("CRYST1"):
+                try:
+                    # Format the replacement string
+                    space_group_str = info.space_group.ljust(11)
+                    z_val_str = str(info.z_val).rjust(4)
+
+                    # Replace the existing CRYST1 record
+                    self.lines[i] = line[:55] + space_group_str + z_val_str + line[70:]
+                except (ValueError, AttributeError) as e:
+                    # Raise an exception with context
+                    raise AttributeError(
+                        f"Failed to update CRYST1 record. "
+                        f"Line: {line.strip()} | Error: {e}"
+                    )
+                break
+
     def list_assemblies(self):
         """
         List the biological assemblies that are available for the
@@ -790,6 +852,8 @@ class PDBFile(TextFile):
         assembly : AtomArray or AtomArrayStack
             The assembly.
             The return type depends on the `model` parameter.
+            Contains the `sym_id` annotation, which enumerates the copies of the
+            asymmetric unit in the assembly.
 
         Examples
         --------
@@ -831,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")
@@ -853,8 +917,12 @@ class PDBFile(TextFile):
             affected_chain_ids = []
             transform_start = None
             for j, line in enumerate(assembly_lines[start:stop]):
-                if line.startswith("APPLY THE FOLLOWING TO CHAINS:") or line.startswith(
-                    "                   AND CHAINS:"
+                if any(
+                    line.startswith(chain_signal_string)
+                    for chain_signal_string in [
+                        "APPLY THE FOLLOWING TO CHAINS:",
+                        "                   AND CHAINS:",
+                    ]
                 ):
                     affected_chain_ids += [
                         chain_id.strip() for chain_id in line[30:].split(",")
@@ -1039,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
@@ -1148,7 +1216,11 @@ def _apply_transformations(structure, rotations, translations):
         coord += translation
         assembly_coord[i] = coord
 
-    return repeat(structure, assembly_coord)
+    assembly = repeat(structure, assembly_coord)
+    assembly.set_annotation(
+        "sym_id", np.repeat(np.arange(len(rotations)), structure.array_length())
+    )
+    return assembly
 
 
 def _check_pdb_compatibility(array, hybrid36):
@@ -1177,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, "
@@ -1199,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

@@ -58,48 +58,48 @@ class PDBQTFile(TextFile):
     >>> mask = file.set_structure(ligand, rotatable_bonds="all")
     >>> # Print removed nonpolar hydrogen atoms
     >>> print(ligand[~mask])
-    HET         0  BTN H101   H         3.740    1.170    0.970
-    HET         0  BTN H102   H         4.070    1.340   -0.770
-    HET         0  BTN H91    H         2.800   -0.740   -1.210
-    HET         0  BTN H92    H         2.480   -0.910    0.530
-    HET         0  BTN H81    H         1.290    1.260    0.520
-    HET         0  BTN H82    H         1.620    1.440   -1.220
-    HET         0  BTN H71    H         0.350   -0.650   -1.660
-    HET         0  BTN H72    H         0.020   -0.820    0.080
-    HET         0  BTN H2     H        -0.840    1.580   -1.630
-    HET         0  BTN H61    H        -3.800    1.840    1.290
-    HET         0  BTN H62    H        -3.370    2.740   -0.200
-    HET         0  BTN H5     H        -4.310    0.810   -1.210
-    HET         0  BTN H4     H        -2.450   -0.040   -2.250
+    HET         0  BTN H101   H         3.745    1.171    0.974
+    HET         0  BTN H102   H         4.071    1.343   -0.767
+    HET         0  BTN H91    H         2.802   -0.740   -1.211
+    HET         0  BTN H92    H         2.476   -0.912    0.530
+    HET         0  BTN H81    H         1.289    1.265    0.523
+    HET         0  BTN H82    H         1.616    1.437   -1.218
+    HET         0  BTN H71    H         0.346   -0.646   -1.662
+    HET         0  BTN H72    H         0.020   -0.818    0.079
+    HET         0  BTN H2     H        -0.838    1.576   -1.627
+    HET         0  BTN H61    H        -3.797    1.837    1.286
+    HET         0  BTN H62    H        -3.367    2.738   -0.205
+    HET         0  BTN H5     H        -4.307    0.812   -1.205
+    HET         0  BTN H4     H        -2.451   -0.038   -2.252
     >>> print(file)
     ROOT
-    HETATM    1 C11  BTN     0       5.090  -0.280   0.170  1.00  0.00     0.258 C
-    HETATM    2 O11  BTN     0       4.960  -1.470   0.030  1.00  0.00    -0.264 OA
+    HETATM    1 C11  BTN     0       5.089  -0.280   0.173  1.00  0.00     0.258 C
+    HETATM    2 O11  BTN     0       4.956  -1.473   0.030  1.00  0.00    -0.264 OA
     ENDROOT
     BRANCH   1   3
-    HETATM    3 O12  BTN     0       6.300   0.230   0.440  1.00  0.00    -0.331 OA
-    HETATM   17 HO2  BTN     0       7.030  -0.390   0.520  1.00  0.00     0.221 HD
+    HETATM    3 O12  BTN     0       6.299   0.233   0.444  1.00  0.00    -0.331 OA
+    HETATM   17 HO2  BTN     0       7.034  -0.391   0.517  1.00  0.00     0.221 HD
     ENDBRANCH   1   3
     BRANCH   1   4
-    HETATM    4 C10  BTN     0       3.900   0.630   0.040  1.00  0.00     0.105 C
+    HETATM    4 C10  BTN     0       3.896   0.631   0.039  1.00  0.00     0.105 C
     BRANCH   4   5
-    HETATM    5 C9   BTN     0       2.650  -0.200  -0.280  1.00  0.00     0.010 C
+    HETATM    5 C9   BTN     0       2.651  -0.200  -0.276  1.00  0.00     0.010 C
     BRANCH   5   6
-    HETATM    6 C8   BTN     0       1.440   0.720  -0.410  1.00  0.00     0.002 C
+    HETATM    6 C8   BTN     0       1.440   0.725  -0.412  1.00  0.00     0.002 C
     BRANCH   6   7
-    HETATM    7 C7   BTN     0       0.200  -0.110  -0.730  1.00  0.00     0.016 C
+    HETATM    7 C7   BTN     0       0.196  -0.106  -0.727  1.00  0.00     0.016 C
     BRANCH   7   8
-    HETATM    8 C2   BTN     0      -1.020   0.820  -0.860  1.00  0.00     0.065 C
-    HETATM    9 S1   BTN     0      -1.420   1.600   0.750  1.00  0.00    -0.154 SA
-    HETATM   10 C6   BTN     0      -3.200   1.830   0.370  1.00  0.00     0.090 C
-    HETATM   11 C5   BTN     0      -3.530   0.580  -0.480  1.00  0.00     0.091 C
-    HETATM   12 N1   BTN     0      -3.970  -0.510   0.410  1.00  0.00    -0.239 NA
-    HETATM   13 C3   BTN     0      -3.140  -1.550   0.270  1.00  0.00     0.272 C
-    HETATM   14 O3   BTN     0      -3.270  -2.590   0.890  1.00  0.00    -0.259 OA
-    HETATM   15 N2   BTN     0      -2.150  -1.340  -0.610  1.00  0.00    -0.239 NA
-    HETATM   16 C4   BTN     0      -2.290   0.010  -1.170  1.00  0.00     0.093 C
-    HETATM   18 HN1  BTN     0      -4.740  -0.470   1.000  1.00  0.00     0.132 HD
-    HETATM   19 HN2  BTN     0      -1.460  -1.980  -0.840  1.00  0.00     0.132 HD
+    HETATM    8 C2   BTN     0      -1.015   0.819  -0.863  1.00  0.00     0.065 C
+    HETATM    9 S1   BTN     0      -1.419   1.604   0.751  1.00  0.00    -0.154 SA
+    HETATM   10 C6   BTN     0      -3.205   1.827   0.371  1.00  0.00     0.090 C
+    HETATM   11 C5   BTN     0      -3.530   0.581  -0.476  1.00  0.00     0.091 C
+    HETATM   12 N1   BTN     0      -3.970  -0.507   0.412  1.00  0.00    -0.239 NA
+    HETATM   13 C3   BTN     0      -3.141  -1.549   0.271  1.00  0.00     0.272 C
+    HETATM   14 O3   BTN     0      -3.271  -2.589   0.888  1.00  0.00    -0.259 OA
+    HETATM   15 N2   BTN     0      -2.154  -1.343  -0.612  1.00  0.00    -0.239 NA
+    HETATM   16 C4   BTN     0      -2.289   0.010  -1.175  1.00  0.00     0.093 C
+    HETATM   18 HN1  BTN     0      -4.738  -0.474   1.004  1.00  0.00     0.132 HD
+    HETATM   19 HN2  BTN     0      -1.462  -1.982  -0.843  1.00  0.00     0.132 HD
     ENDBRANCH   7   8
     ENDBRANCH   6   7
     ENDBRANCH   5   6
@@ -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/__init__.py

@@ -18,5 +18,6 @@ __author__ = "Patrick Kunzmann"
 from .bcif import *
 from .cif import *
 from .component import *
+from .compress import *
 from .convert import *
 from .encoding import *

biotite/structure/io/pdbx/bcif.py

@@ -38,8 +38,9 @@ class BinaryCIFData(_Component):
     array : array_like or int or float or str
         The data array to be stored.
         If a single item is given, it is converted into an array.
-    encoding : list of Encoding
+    encoding : list of Encoding , optional
         The encoding steps that are successively applied to the data.
+        By default, the data is stored uncompressed directly as bytes.
 
     Attributes
     ----------
@@ -61,7 +62,7 @@ class BinaryCIFData(_Component):
     >>> print(data.array)
     ['apple']
 
-    Well-chosen encoding can significantly reduce the serialized data
+    A well-chosen encoding can significantly reduce the serialized data
     size:
 
     >>> # Default uncompressed encoding
@@ -194,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
@@ -255,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
@@ -340,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
     --------
@@ -457,7 +466,12 @@ class BinaryCIFBlock(_HierarchicalContainer):
     """
 
     def __init__(self, categories=None):
-        super().__init__(categories)
+        if categories is None:
+            categories = {}
+        super().__init__(
+            # Actual bcif files use leading '_' as category names
+            {"_" + name: category for name, category in categories.items()}
+        )
 
     @staticmethod
     def subcomponent_class():
@@ -470,25 +484,43 @@ class BinaryCIFBlock(_HierarchicalContainer):
     @staticmethod
     def deserialize(content):
         return BinaryCIFBlock(
-            BinaryCIFBlock._deserialize_elements(content["categories"], "name")
+            {
+                # The superclass uses leading '_' in category names,
+                # but on the level of this class, the leading '_' is omitted
+                name.lstrip("_"): category
+                for name, category in BinaryCIFBlock._deserialize_elements(
+                    content["categories"], "name"
+                ).items()
+            }
         )
 
     def serialize(self):
         return {"categories": self._serialize_elements("name")}
 
     def __getitem__(self, key):
-        # Actual bcif files use leading '_' as categories
-        return super().__getitem__("_" + key)
+        try:
+            return super().__getitem__("_" + key)
+        except KeyError:
+            raise KeyError(key)
 
     def __setitem__(self, key, element):
-        return super().__setitem__("_" + key, element)
+        try:
+            return super().__setitem__("_" + key, element)
+        except KeyError:
+            raise KeyError(key)
 
     def __delitem__(self, key):
-        return super().__setitem__("_" + key)
+        try:
+            return super().__setitem__("_" + key)
+        except KeyError:
+            raise KeyError(key)
 
     def __iter__(self):
         return (key.lstrip("_") for key in super().__iter__())
 
+    def __contains__(self, key):
+        return super().__contains__("_" + key)
+
 
 class BinaryCIFFile(File, _HierarchicalContainer):
     """
@@ -502,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:
@@ -510,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: