biotite 0.39.0__cp312-cp312-macosx_11_0_arm64.whl → 0.41.0__cp312-cp312-macosx_11_0_arm64.whl

biotite/structure/io/__init__.py

@@ -5,7 +5,7 @@
 """
 A subpackage for reading and writing structure related data.
 
-Macromolecular structure files (PDB, PDBx/mmCIF, MMTF, etc.) and
+Macromolecular structure files (PDB, PDBx/mmCIF, BinaryCIF, etc.) and
 small molecule files (MOL, SDF, etc.) can be used
 to load an :class:`AtomArray` or :class:`AtomArrayStack`.
 
@@ -15,10 +15,8 @@ only one *altloc* can be chosen for each atom. Hence, the amount of
 atoms may be lower in the atom array (stack) than in respective
 structure file.
 
-The recommended format for reading structure files is MMTF.
+The recommended format for reading structure files is *BinaryCIF*.
 It has by far the shortest parsing time and file size.
-Furthermore, chemical bond information can be read from MMTF files
-as :class:`BondList` instances.
 
 Besides the mentioned structure formats, Gromacs trajectory files can be
 loaded, if `mdtraj` is installed.

biotite/structure/io/ctab.py

@@ -2,46 +2,20 @@
 # under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
 # information.
 
-"""
-Functions for parsing and writing an :class:`AtomArray` from/to
-*MDL* connection tables (Ctab).
-"""
-
 __name__ = "biotite.structure.io"
 __author__ = "Patrick Kunzmann"
 __all__ = ["read_structure_from_ctab", "write_structure_to_ctab"]
 
 import warnings
-import numpy as np
-from biotite.structure.error import BadStructureError
-from ..atoms import AtomArray, AtomArrayStack
-from ..bonds import BondList, BondType
-
-BOND_TYPE_MAPPING = {
-    1: BondType.SINGLE,
-    2: BondType.DOUBLE,
-    3: BondType.TRIPLE,
-    6: BondType.SINGLE,
-    7: BondType.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,
-}
-
-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()}
+from ..bonds import BondType
 
 
 def read_structure_from_ctab(ctab_lines):
     """
     Parse a *MDL* connection table (Ctab) to obtain an
-    :class:`AtomArray`. :footcite:`Dalby1992`
+    :class:`AtomArray`. :footcite:`Dalby1992`.
+
+    DEPRECATED: Moved to :mod:`biotite.structure.io.mol.ctab`.
 
     Parameters
     ----------
@@ -60,41 +34,9 @@ def read_structure_from_ctab(ctab_lines):
 
     .. footbibliography::
     """
-    n_atoms, n_bonds = _get_counts(ctab_lines[0])
-    atom_lines = ctab_lines[1 : 1 + n_atoms]
-    bond_lines = ctab_lines[1 + n_atoms : 1 + n_atoms + n_bonds]
-
-    atoms = AtomArray(n_atoms)
-    atoms.add_annotation("charge", int)
-    for i, line in enumerate(atom_lines):
-        atoms.coord[i, 0] = float(line[0:10])
-        atoms.coord[i, 1] = float(line[10:20])
-        atoms.coord[i, 2] = float(line[20:30])
-        atoms.element[i] = line[31:34].strip().upper()
-        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"0 is used instead"
-            )
-            charge = 0
-        atoms.charge[i] = charge
-
-    bond_array = np.zeros((n_bonds, 3), dtype=np.uint32)
-    for i, line in enumerate(bond_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"BondType.ANY is used instead"
-            )
-            bond_type = BondType.ANY
-        bond_array[i, 0] = int(line[0:3]) - 1
-        bond_array[i, 1] = int(line[3:6]) - 1
-        bond_array[i, 2] = bond_type
-    atoms.bonds = BondList(n_atoms, bond_array)
-
-    return atoms
+    warnings.warn("Moved to biotite.structure.io.mol.ctab", DeprecationWarning)
+    from biotite.structure.io.mol.ctab import read_structure_from_ctab
+    return read_structure_from_ctab(ctab_lines)
 
 
 def write_structure_to_ctab(atoms, default_bond_type=BondType.ANY):
@@ -102,6 +44,8 @@ def write_structure_to_ctab(atoms, default_bond_type=BondType.ANY):
     Convert an :class:`AtomArray` into a
     *MDL* connection table (Ctab). :footcite:`Dalby1992`
 
+    DEPRECATED: Moved to :mod:`biotite.structure.io.mol.ctab`.
+
     Parameters
     ----------
     atoms : AtomArray
@@ -123,44 +67,6 @@ def write_structure_to_ctab(atoms, default_bond_type=BondType.ANY):
 
     .. footbibliography::
     """
-    if isinstance(atoms, AtomArrayStack):
-        raise TypeError(
-            "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")
-
-    try:
-        charge = atoms.charge
-    except AttributeError:
-        charge = np.zeros(atoms.array_length(), dtype=int)
-
-    atom_lines = [
-        f"{atoms.coord[i,0]:>10.5f}"
-        f"{atoms.coord[i,1]:>10.5f}"
-        f"{atoms.coord[i,2]:>10.5f}"
-        f" {atoms.element[i]:>3}"
-        f"  {CHARGE_MAPPING_REV.get(charge[i], 0):>3d}" + f"{0:>3d}" * 10
-        for i in range(atoms.array_length())
-    ]
-
-    default_bond_value = BOND_TYPE_MAPPING_REV[default_bond_type]
-
-    bond_lines = [
-        f"{i+1:>3d}{j+1:>3d}"
-        f"{BOND_TYPE_MAPPING_REV.get(bond_type, default_bond_value):>3d}"
-        + f"{0:>3d}" * 4
-        for i, j, bond_type in atoms.bonds.as_array()
-    ]
-
-    counts_line = (
-        f"{len(atom_lines):>3d}{len(bond_lines):>3d}"
-        "  0     0  0  0  0  0  0  1 V2000"
-    )
-
-    return [counts_line] + atom_lines + bond_lines + ["M  END"]
-
-
-def _get_counts(counts_line):
-    return int(counts_line[0:3]), int(counts_line[3:6])
+    warnings.warn("Moved to biotite.structure.io.mol.ctab", DeprecationWarning)
+    from biotite.structure.io.mol.ctab import write_structure_to_ctab
+    return write_structure_to_ctab(atoms, default_bond_type)

biotite/structure/io/general.py

@@ -11,9 +11,10 @@ __name__ = "biotite.structure.io"
 __author__ = "Patrick Kunzmann"
 __all__ = ["load_structure", "save_structure"]
 
+import datetime
 import os.path
 import io
-from ..atoms import AtomArray, AtomArrayStack
+from ..atoms import AtomArrayStack
 
 
 def load_structure(file_path, template=None, **kwargs):
@@ -21,12 +22,12 @@ def load_structure(file_path, template=None, **kwargs):
     Load an :class:`AtomArray` or class`AtomArrayStack` from a structure
     file without the need to manually instantiate a :class:`File`
     object.
-    
+
     Internally this function uses a :class:`File` object, based on the
     file extension.
     Trajectory files furthermore require specification of the `template`
     parameter.
-    
+
     Parameters
     ----------
     file_path : str
@@ -40,13 +41,13 @@ def load_structure(file_path, template=None, **kwargs):
         This does not affect files given via the `template` parameter.
         The only exception is the `atom_i`, which is applied to the template
         as well if number of atoms do not match.
-    
+
     Returns
     -------
     array : AtomArray or AtomArrayStack
         If the file contains multiple models, an AtomArrayStack is
         returned, otherwise an AtomArray is returned.
-    
+
     Raises
     ------
     ValueError
@@ -61,91 +62,83 @@ def load_structure(file_path, template=None, **kwargs):
 
     # We only need the suffix here
     _, suffix = os.path.splitext(file_path)
-    if suffix == ".pdb":
-        from .pdb import PDBFile
-        file = PDBFile.read(file_path)
-        array = file.get_structure(**kwargs)
-        if isinstance(array, AtomArrayStack) and array.stack_depth() == 1:
-            # Stack containing only one model -> return as atom array
-            return array[0]
-        else:
-            return array
-    elif suffix == ".pdbqt":
-        from .pdbqt import PDBQTFile
-        file = PDBQTFile.read(file_path)
-        array = file.get_structure(**kwargs)
-        if isinstance(array, AtomArrayStack) and array.stack_depth() == 1:
-            # Stack containing only one model -> return as atom array
-            return array[0]
-        else:
-            return array
-    elif suffix == ".cif" or suffix == ".pdbx":
-        from .pdbx import PDBxFile, get_structure
-        file = PDBxFile.read(file_path)
-        array = get_structure(file, **kwargs)
-        if isinstance(array, AtomArrayStack) and array.stack_depth() == 1:
-            # Stack containing only one model -> return as atom array
-            return array[0]
-        else:
-            return array
-    elif suffix == ".gro":
-        from .gro import GROFile
-        file = GROFile.read(file_path)
-        array = file.get_structure(**kwargs)
-        if isinstance(array, AtomArrayStack) and array.stack_depth() == 1:
-            # Stack containing only one model -> return as atom array
-            return array[0]
-        else:
+    match suffix:
+        case ".pdb":
+            from .pdb import PDBFile
+            file = PDBFile.read(file_path)
+            array = file.get_structure(**kwargs)
+            return _as_single_model_if_possible(array)
+        case ".pdbqt":
+            from .pdbqt import PDBQTFile
+            file = PDBQTFile.read(file_path)
+            array = file.get_structure(**kwargs)
+            return _as_single_model_if_possible(array)
+        case ".cif" | ".pdbx":
+            from .pdbx import CIFFile, get_structure
+            file = CIFFile.read(file_path)
+            array = get_structure(file, **kwargs)
+            return _as_single_model_if_possible(array)
+        case ".bcif":
+            from .pdbx import BinaryCIFFile, get_structure
+            file = BinaryCIFFile.read(file_path)
+            array = get_structure(file, **kwargs)
+            return _as_single_model_if_possible(array)
+        case ".gro":
+            from .gro import GROFile
+            file = GROFile.read(file_path)
+            array = file.get_structure(**kwargs)
+            return _as_single_model_if_possible(array)
+        case ".mmtf":
+            from .mmtf import MMTFFile, get_structure
+            file = MMTFFile.read(file_path)
+            array = get_structure(file, **kwargs)
+            return _as_single_model_if_possible(array)
+        case ".npz":
+            from .npz import NpzFile
+            file = NpzFile.read(file_path)
+            array = file.get_structure(**kwargs)
+            return _as_single_model_if_possible(array)
+        case ".mol":
+            from .mol import MOLFile
+            file = MOLFile.read(file_path)
+            array = file.get_structure(**kwargs)
+            # MOL and SDF files only contain a single model
             return array
-    elif suffix == ".mmtf":
-        from .mmtf import MMTFFile, get_structure
-        file = MMTFFile.read(file_path)
-        array = get_structure(file, **kwargs)
-        if isinstance(array, AtomArrayStack) and array.stack_depth() == 1:
-            # Stack containing only one model -> return as atom array
-            return array[0]
-        else:
+        case ".sdf" | ".sd":
+            from .mol import SDFile, get_structure
+            file = SDFile.read(file_path)
+            array = get_structure(file, **kwargs)
             return array
-    elif suffix == ".npz":
-        from .npz import NpzFile
-        file = NpzFile.read(file_path)
-        array = file.get_structure(**kwargs)
-        if isinstance(array, AtomArrayStack) and array.stack_depth() == 1:
-            # Stack containing only one model -> return as atom array
-            return array[0]
-        else:
-            return array
-    elif suffix == ".mol" or suffix == ".sdf":
-        from .mol import MOLFile
-        file = MOLFile.read(file_path)
-        array = file.get_structure(**kwargs)
-        # MOL files only contain a single model
-        return array
-    elif suffix in [".trr", ".xtc", ".tng", ".dcd", ".netcdf"]:
-        if template is None:
-            raise TypeError("Template must be specified for trajectory files")
-        # filter template for atom ids if it is an unfiltered template
-        if "atom_i" in kwargs and template.shape[-1] != len(kwargs["atom_i"]):
-            template = template[..., kwargs["atom_i"]]
-        from .trr import TRRFile
-        from .xtc import XTCFile
-        from .tng import TNGFile
-        from .dcd import DCDFile
-        from .netcdf import NetCDFFile
-        if suffix == ".trr":
-            traj_file_cls = TRRFile
-        if suffix == ".xtc":
-            traj_file_cls = XTCFile
-        if suffix == ".tng":
-            traj_file_cls = TNGFile
-        if suffix == ".dcd":
-            traj_file_cls = DCDFile
-        if suffix == ".netcdf":
-            traj_file_cls = NetCDFFile
-        file = traj_file_cls.read(file_path, **kwargs)
-        return file.get_structure(template)
-    else:
-        raise ValueError(f"Unknown file format '{suffix}'")
+        case ".trr" | ".xtc" | ".tng" | ".dcd" | ".netcdf":
+            if template is None:
+                raise TypeError(
+                    "Template must be specified for trajectory files"
+                )
+            # Filter template for atom ids, if an unfiltered template
+            if (
+                "atom_i" in kwargs
+                and template.shape[-1] != len(kwargs["atom_i"])
+            ):
+                template = template[..., kwargs["atom_i"]]
+            from .trr import TRRFile
+            from .xtc import XTCFile
+            from .tng import TNGFile
+            from .dcd import DCDFile
+            from .netcdf import NetCDFFile
+            if suffix == ".trr":
+                traj_file_cls = TRRFile
+            if suffix == ".xtc":
+                traj_file_cls = XTCFile
+            if suffix == ".tng":
+                traj_file_cls = TNGFile
+            if suffix == ".dcd":
+                traj_file_cls = DCDFile
+            if suffix == ".netcdf":
+                traj_file_cls = NetCDFFile
+            file = traj_file_cls.read(file_path, **kwargs)
+            return file.get_structure(template)
+        case unknown_suffix:
+            raise ValueError(f"Unknown file format '{unknown_suffix}'")
 
 
 def save_structure(file_path, array, **kwargs):
@@ -153,10 +146,10 @@ def save_structure(file_path, array, **kwargs):
     Save an :class:`AtomArray` or class`AtomArrayStack` to a structure
     file without the need to manually instantiate a :class:`File`
     object.
-    
+
     Internally this function uses a :class:`File` object, based on the
     file extension.
-    
+
     Parameters
     ----------
     file_path : str
@@ -174,98 +167,91 @@ def save_structure(file_path, array, **kwargs):
     """
     # We only need the suffix here
     _, suffix = os.path.splitext(file_path)
-    if suffix == ".pdb":
-        from .pdb import PDBFile
-        file = PDBFile()
-        file.set_structure(array, **kwargs)
-        file.write(file_path)
-    elif suffix == ".pdbqt":
-        from .pdbqt import PDBQTFile
-        file = PDBQTFile()
-        file.set_structure(array, **kwargs)
-        file.write(file_path)
-    elif suffix == ".cif" or suffix == ".pdbx":
-        from .pdbx import PDBxFile, set_structure
-        file = PDBxFile()
-        set_structure(file, array, data_block="STRUCTURE", **kwargs)
-        file.write(file_path)
-    elif suffix == ".gro":
-        from .gro import GROFile
-        file = GROFile()
-        file.set_structure(array, **kwargs)
-        file.write(file_path)
-    elif suffix == ".mmtf":
-        from .mmtf import MMTFFile, set_structure
-        file = MMTFFile()
-        set_structure(file, array, **kwargs)
-        file.write(file_path)
-    elif suffix == ".npz":
-        from .npz import NpzFile
-        file = NpzFile()
-        file.set_structure(array, **kwargs)
-        file.write(file_path)
-    elif suffix == ".mol" or suffix == ".sdf":
-        from .mol import MOLFile
-        file = MOLFile()
-        file.set_structure(array, **kwargs)
-        file.write(file_path)
-    elif suffix in [".trr", ".xtc", ".tng", ".dcd", ".netcdf"]:
-        from .trr import TRRFile
-        from .xtc import XTCFile
-        from .tng import TNGFile
-        from .dcd import DCDFile
-        from .netcdf import NetCDFFile
-        if suffix == ".trr":
-            traj_file_cls = TRRFile
-        if suffix == ".xtc":
-            traj_file_cls = XTCFile
-        if suffix == ".tng":
-            traj_file_cls = TNGFile
-        if suffix == ".dcd":
-            traj_file_cls = DCDFile
-        if suffix == ".netcdf":
-            traj_file_cls = NetCDFFile
-        file = traj_file_cls()
-        file.set_structure(array, **kwargs)
-        file.write(file_path)
-    else:
-        raise ValueError(f"Unknown file format '{suffix}'")
-
+    match suffix:
+        case ".pdb":
+            from .pdb import PDBFile
+            file = PDBFile()
+            file.set_structure(array, **kwargs)
+            file.write(file_path)
+        case ".pdbqt":
+            from .pdbqt import PDBQTFile
+            file = PDBQTFile()
+            file.set_structure(array, **kwargs)
+            file.write(file_path)
+        case ".cif" | ".pdbx":
+            from .pdbx import CIFFile, set_structure
+            file = CIFFile()
+            set_structure(file, array, **kwargs)
+            file.write(file_path)
+        case ".bcif":
+            from .pdbx import BinaryCIFFile, set_structure
+            file = BinaryCIFFile()
+            set_structure(file, array, **kwargs)
+            file.write(file_path)
+        case ".gro":
+            from .gro import GROFile
+            file = GROFile()
+            file.set_structure(array, **kwargs)
+            file.write(file_path)
+        case ".mmtf":
+            from .mmtf import MMTFFile, set_structure
+            file = MMTFFile()
+            set_structure(file, array, **kwargs)
+            file.write(file_path)
+        case ".npz":
+            from .npz import NpzFile
+            file = NpzFile()
+            file.set_structure(array, **kwargs)
+            file.write(file_path)
+        case ".mol":
+            from .mol import MOLFile
+            file = MOLFile()
+            file.set_structure(array, **kwargs)
+            file.header = _mol_header()
+            file.write(file_path)
+        case ".sdf" | ".sd":
+            from .mol import SDFile, SDRecord, set_structure
+            record = SDRecord()
+            record.set_structure(array, **kwargs)
+            record.header = _mol_header()
+            file = SDFile({"Molecule": record})
+            file.write(file_path)
+        case ".trr" | ".xtc" | ".tng" | ".dcd" | ".netcdf":
+            from .trr import TRRFile
+            from .xtc import XTCFile
+            from .tng import TNGFile
+            from .dcd import DCDFile
+            from .netcdf import NetCDFFile
+            if suffix == ".trr":
+                traj_file_cls = TRRFile
+            if suffix == ".xtc":
+                traj_file_cls = XTCFile
+            if suffix == ".tng":
+                traj_file_cls = TNGFile
+            if suffix == ".dcd":
+                traj_file_cls = DCDFile
+            if suffix == ".netcdf":
+                traj_file_cls = NetCDFFile
+            file = traj_file_cls()
+            file.set_structure(array, **kwargs)
+            file.write(file_path)
+        case unknown_suffix:
+            raise ValueError(f"Unknown file format '{unknown_suffix}'")
 
-# Helper function to estimate elements from atom names
-_elements = [elem.upper() for elem in 
-["H", "He", "Li", "Be", "B", "C", "N", "O", "F", "Ne", "Na", "Mg",
-"Al", "Si", "P", "S", "Cl", "Ar", "K", "Ca", "Sc", "Ti", "V", "Cr", "Mn", "Fe",
-"Co", "Ni", "Cu", "Zn", "Ga", "Ge", "As", "Se", "Br", "Kr", "Rb", "Sr", "Y",
-"Zr", "Nb", "Mo", "Tc", "Ru", "Rh", "Pd", "Ag", "Cd", "In", "Sn", "Sb", "Te",
-"I", "Xe", "Cs", "Ba", "La", "Ce", "Pr", "Nd", "Pm", "Sm", "Eu", "Gd", "Tb",
-"Dy", "Ho", "Er", "Tm", "Yb", "Lu", "Hf", "Ta", "W", "Re", "Os", "Ir", "Pt",
-"Au", "Hg", "Tl", "Pb", "Bi", "Po", "At", "Rn", "Fr", "Ra", "Ac", "Th", "Pa",
-"U", "Np", "Pu", "Am", "Cm", "Bk", "Cf", "Es", "Fm", "Md", "No", "Lr", "Rf",
-"Db", "Sg", "Bh", "Hs", "Mt", "Ds", "Rg", "Cn", "Nh", "Fl", "Mc", "Lv", "Ts",
-"Og"]
-]
-def _guess_element(atom_name):
-    # remove digits (1H -> H)
-    elem = "".join([i for i in atom_name if not i.isdigit()])
-    elem = elem.upper()
-    if len(elem) == 0:
-        return ""
 
-    # Some often used elements for biomolecules
-    if elem.startswith("C") or elem.startswith("N") or \
-        elem.startswith("O") or elem.startswith("S") or \
-        elem.startswith("H"):
-        return elem[0]
+def _as_single_model_if_possible(atoms):
+    if isinstance(atoms, AtomArrayStack) and atoms.stack_depth() == 1:
+        # Stack containing only one model -> return as atom array
+        return atoms[0]
+    else:
+        return atoms
 
-    # Exactly match element abbreviations
-    try:
-        return _elements[_elements.index(elem[:2])]
-    except ValueError:
-        try:
-            return _elements[_elements.index(elem[0])]
-        except ValueError:
-            pass
 
-    return ""
- 
+def _mol_header():
+    from .mol import Header
+    return Header(
+        mol_name="Molecule",
+        program="Biotite",
+        time=datetime.datetime.now(),
+        dimensions="3D",
+    )