biotite 0.41.1__cp312-cp312-macosx_10_16_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,63 @@
+# 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 numpy as np
+from ..trajfile import TrajectoryFile
+from ...box import vectors_from_unitcell, unitcell_from_vectors
+
+
+class NetCDFFile(TrajectoryFile):
+    """
+    This file class represents a NetCDF trajectory file.
+    """
+    
+    @classmethod
+    def traj_type(cls):
+        import mdtraj.formats as traj
+        return traj.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/npz/__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 internal NPZ file format. This binary
+format is used to store `NumPy` arrays. Since atom arrays and stacks are
+completely built on `NumPy` arrays, this format is preferable for
+Biotite internal usage due to fast I/O operations and preservation
+of all atom annotation arrays.
+
+DEPRECATED: Pickle data directly or use
+:class:`biotite.structure.io.pdbx.BinaryCIFFile` instead.
+"""
+
+__name__ = "biotite.structure.io.npz"
+__author__ = "Patrick Kunzmann"
+
+from .file import *

biotite/structure/io/npz/file.py

@@ -0,0 +1,152 @@
+# 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.npz"
+__author__ = "Patrick Kunzmann"
+__all__ = ["NpzFile"]
+
+import numpy as np
+from ...atoms import Atom, AtomArray, AtomArrayStack
+from ...bonds import BondList
+from ....file import File, is_binary
+
+
+class NpzFile(File):
+    r"""
+    This class represents a NPZ file, the preferable format for
+    Biotite internal structure storage.
+
+    Internally the this class writes/reads all attribute arrays of an
+    :class:`AtomArray` or :class:`AtomArrayStack` using the *NumPy*
+    :func:`save()`/:func:`load()`
+    method. This format offers the fastest I/O operations and completely
+    preserves the content all atom annotation arrays.
+
+    DEPRECATED: Pickle data directly or use
+    :class:`biotite.structure.io.pdbx.BinaryCIFFile` instead.
+
+    Examples
+    --------
+    Load a \\*.npz file, modify the structure and save the new
+    structure into a new file:
+
+    >>> import os.path
+    >>> file = NpzFile.read(os.path.join(path_to_structures, "1l2y.npz"))
+    >>> array_stack = file.get_structure()
+    >>> array_stack_mod = rotate(array_stack, [1,2,3])
+    >>> file = NpzFile()
+    >>> file.set_structure(array_stack_mod)
+    >>> file.write(os.path.join(path_to_directory, "1l2y_mod.npz"))
+
+    """
+
+    def __init__(self):
+        super().__init__()
+        self._data_dict = None
+
+    def __copy_fill__(self, clone):
+        super().__copy_fill__(clone)
+        if self._data_dict is not None:
+            for key, value in self._data_dict.items():
+                clone._data_dict[key] = np.copy(value)
+
+    @classmethod
+    def read(cls, file):
+        """
+        Read a NPZ file.
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be read.
+            Alternatively a file path can be supplied.
+
+        Returns
+        -------
+        file_object : NPZFile
+            The parsed file.
+        """
+        npz_file = NpzFile()
+        # File name
+        if isinstance(file, str):
+            with open(file, "rb") as f:
+                npz_file._data_dict = dict(np.load(f, allow_pickle=False))
+        # File object
+        else:
+            if not is_binary(file):
+                raise TypeError("A file opened in 'binary' mode is required")
+            npz_file._data_dict = dict(np.load(file, allow_pickle=False))
+        return npz_file
+
+    def write(self, file):
+        """
+        Write a NPZ file.
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be read.
+            Alternatively, a file path can be supplied.
+        """
+        if isinstance(file, str):
+            with open(file, "wb") as f:
+                np.savez(f, **self._data_dict)
+        else:
+            if not is_binary(file):
+                raise TypeError("A file opened in 'binary' mode is required")
+            np.savez(file, **self._data_dict)
+
+    def get_structure(self):
+        """
+        Get an :class:`AtomArray` or :class:`AtomArrayStack` from the
+        file.
+
+        If this method returns an array or stack depends on which type
+        of object was used when the file was written.
+
+        Returns
+        -------
+        array : AtomArray or AtomArrayStack
+            The array or stack contained in this file.
+        """
+        if self._data_dict is None:
+            raise ValueError("The structure of this file "
+                             "has not been loaded or set yet")
+        coord = self._data_dict["coord"]
+        # The type of the structure is determined by the dimensionality
+        # of the 'coord' field
+        if len(coord.shape) == 3:
+            array = AtomArrayStack(coord.shape[0], coord.shape[1])
+        else:
+            array = AtomArray(coord.shape[0])
+
+        for key, value in self._data_dict.items():
+            if key == "coord":
+                array.coord = value
+            elif key == "bonds":
+                array.bonds = BondList(array.array_length(), value)
+            elif key == "box":
+                array.box = value
+            else:
+                array.set_annotation(key, value)
+        return array
+
+    def set_structure(self, array):
+        """
+        Set the :class:`AtomArray` or :class:`AtomArrayStack` for the
+        file.
+
+        Parameters
+        ----------
+        array : AtomArray or AtomArrayStack
+            The array or stack to be saved into this file.
+        """
+        self._data_dict = {}
+        self._data_dict["coord"] = np.copy(array.coord)
+        if array.bonds is not None:
+            self._data_dict["bonds"] = array.bonds.as_array()
+        if array.box is not None:
+            self._data_dict["box"] = np.copy(array.box)
+        for annot in array.get_annotation_categories():
+            self._data_dict[annot] = np.copy(array.get_annotation(annot))

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 .file import *
+from .convert import *

biotite/structure/io/pdb/convert.py

@@ -0,0 +1,293 @@
+# 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_symmetry_mates"]
+
+
+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.
+    
+    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_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.
+
+    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)
+    """
+    return pdb_file.get_symmetry_mates(
+        model, altloc, extra_fields, include_bonds
+    )