biotite 1.3.0__cp312-cp312-macosx_10_13_x86_64.whl

biotite/structure/io/netcdf/__init__.py

@@ -0,0 +1,13 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+"""
+This subpackage is used for reading and writing trajectories in the
+*AMBER* NetCDF format.
+"""
+
+__name__ = "biotite.structure.io.netcdf"
+__author__ = "Patrick Kunzmann"
+
+from .file import *

biotite/structure/io/netcdf/file.py

@@ -0,0 +1,64 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+__name__ = "biotite.structure.io.netcdf"
+__author__ = "Patrick Kunzmann"
+__all__ = ["NetCDFFile"]
+
+import biotraj
+import numpy as np
+from biotite.structure.box import unitcell_from_vectors, vectors_from_unitcell
+from biotite.structure.io.trajfile import TrajectoryFile
+
+
+class NetCDFFile(TrajectoryFile):
+    """
+    This file class represents a NetCDF trajectory file.
+    """
+
+    @classmethod
+    def traj_type(cls):
+        return biotraj.NetCDFTrajectoryFile
+
+    @classmethod
+    def process_read_values(cls, read_values):
+        # .dcd files use Angstrom
+        coord = read_values[0]
+        time = read_values[1]
+        cell_lengths = read_values[2]
+        cell_angles = read_values[3]
+        if cell_lengths is None or cell_angles is None:
+            box = None
+        else:
+            box = np.stack(
+                [
+                    vectors_from_unitcell(a, b, c, alpha, beta, gamma)
+                    for (a, b, c), (alpha, beta, gamma) in zip(
+                        cell_lengths, np.deg2rad(cell_angles)
+                    )
+                ],
+                axis=0,
+            )
+        return coord, box, time
+
+    @classmethod
+    def prepare_write_values(cls, coord, box, time):
+        coord = coord.astype(np.float32, copy=False) if coord is not None else None
+        time = time.astype(np.float32, copy=False) if time is not None else None
+        if box is None:
+            cell_lengths = None
+            cell_angles = None
+        else:
+            cell_lengths = np.zeros((len(box), 3), dtype=np.float32)
+            cell_angles = np.zeros((len(box), 3), dtype=np.float32)
+            for i, model_box in enumerate(box):
+                a, b, c, alpha, beta, gamma = unitcell_from_vectors(model_box)
+                cell_lengths[i] = np.array((a, b, c))
+                cell_angles[i] = np.rad2deg((alpha, beta, gamma))
+        return {
+            "coordinates": coord,
+            "time": time,
+            "cell_lengths": cell_lengths,
+            "cell_angles": cell_angles,
+        }

biotite/structure/io/pdb/__init__.py

@@ -0,0 +1,20 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+"""
+This subpackage is used for reading and writing an :class:`AtomArray` or
+:class:`AtomArrayStack` using the popular PDB format.
+Since this format has some limitations, it will be completely replaced
+someday by the modern PDBx format.
+Therefore this subpackage should only be used, if usage of the
+PDBx (CIF or BinaryCIF) format is not suitable (e.g. when interfacing
+other software).
+In all other cases, usage of the :mod:`pdbx` subpackage is encouraged.
+"""
+
+__name__ = "biotite.structure.io.pdb"
+__author__ = "Patrick Kunzmann"
+
+from .convert import *
+from .file import *

biotite/structure/io/pdb/convert.py

@@ -0,0 +1,388 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+"""
+Some convenience functions for consistency with other ``structure.io``
+subpackages.
+"""
+
+__name__ = "biotite.structure.io.pdb"
+__author__ = "Patrick Kunzmann"
+__all__ = [
+    "get_model_count",
+    "get_structure",
+    "set_structure",
+    "list_assemblies",
+    "get_assembly",
+    "get_unit_cell",
+]
+
+import warnings
+
+
+def get_model_count(pdb_file):
+    """
+    Get the number of models contained in a :class:`PDBFile`.
+
+    Parameters
+    ----------
+    pdb_file : PDBFile
+        The file object.
+
+    Returns
+    -------
+    model_count : int
+        The number of models.
+    """
+    return pdb_file.get_model_count()
+
+
+def get_structure(
+    pdb_file, model=None, altloc="first", extra_fields=[], include_bonds=False
+):
+    """
+    Create an :class:`AtomArray` or :class:`AtomArrayStack` from a
+    :class:`PDBFile`.
+
+    This function is a thin wrapper around the :class:`PDBFile` method
+    :func:`get_structure()` for the sake of consistency with other
+    ``structure.io`` subpackages.
+
+    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
+    -------
+    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
+    :class:`PDBFile`.
+
+    This function is a thin wrapper around the :class:`PDBFile` method
+    :func:`set_structure()` for the sake of consistency with other
+    ``structure.io`` subpackages.
+
+    This will save the coordinates, the mandatory annotation categories
+    and the optional annotation categories
+    'atom_id', 'b_factor', 'occupancy' and 'charge'.
+
+    Parameters
+    ----------
+    pdb_file : PDBFile
+        The file object.
+    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
+        Defines wether the file should be written in hybrid-36 format.
+
+    Notes
+    -----
+    If `array` has an associated :class:`BondList`, ``CONECT``
+    records are also written for all non-water hetero residues
+    and all inter-residue connections.
+    """
+    pdb_file.set_structure(array, hybrid36)
+
+
+def list_assemblies(pdb_file):
+    """
+    List the biological assemblies that are available for the
+    structure in the given file.
+
+    This function receives the data from the ``REMARK 300`` records
+    in the file.
+    Consequently, this remark must be present in the file.
+
+    Parameters
+    ----------
+    pdb_file : PDBFile
+        The file object.
+
+    Returns
+    -------
+    assemblies : list of str
+        A list that contains the available assembly IDs.
+
+    Examples
+    --------
+    >>> import os.path
+    >>> file = PDBFile.read(os.path.join(path_to_structures, "1f2n.pdb"))
+    >>> print(list_assemblies(file))
+    ['1']
+    """
+    return pdb_file.list_assemblies()
+
+
+def get_assembly(
+    pdb_file,
+    assembly_id=None,
+    model=None,
+    altloc="first",
+    extra_fields=[],
+    include_bonds=False,
+):
+    """
+    Build the given biological assembly.
+
+    This function receives the data from ``REMARK 350`` records in
+    the file.
+    Consequently, this remark must be present in the file.
+
+    Parameters
+    ----------
+    pdb_file : PDBFile
+        The file object.
+    assembly_id : str
+        The assembly to build.
+        Available assembly IDs can be obtained via
+        :func:`list_assemblies()`.
+    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
+    -------
+    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
+    --------
+
+    >>> import os.path
+    >>> file = PDBFile.read(os.path.join(path_to_structures, "1f2n.pdb"))
+    >>> assembly = get_assembly(file, model=1)
+    """
+    return pdb_file.get_assembly(
+        assembly_id, model, altloc, extra_fields, include_bonds
+    )
+
+
+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
+):
+    """
+    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 :func:`get_unit_cell()` instead.
+
+    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_symmetry_mates(file, model=1)
+    """
+    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)