biotite 1.1.0__cp313-cp313-macosx_11_0_arm64.whl

biotite/structure/compare.py

@@ -0,0 +1,274 @@
+# 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 module provides functions for calculation of characteristic values when
+comparing multiple structures with each other.
+"""
+
+__name__ = "biotite.structure"
+__author__ = "Patrick Kunzmann"
+__all__ = ["rmsd", "rmspd", "rmsf", "average"]
+
+import numpy as np
+from biotite.structure.atoms import AtomArrayStack, coord
+from biotite.structure.geometry import index_distance
+from biotite.structure.util import vector_dot
+
+
+def rmsd(reference, subject):
+    r"""
+    Calculate the RMSD between two structures.
+
+    The *root-mean-square-deviation* (RMSD) indicates the overall
+    deviation of each model of a structure to a reference structure.
+    It is defined as:
+
+    .. math:: RMSD = \sqrt{ \frac{1}{n} \sum\limits_{i=1}^n (x_i - x_{ref,i})^2}
+
+    Parameters
+    ----------
+    reference : AtomArray or ndarray, dtype=float, shape=(n,3)
+        The reference structure.
+        Alternatively, coordinates can be provided directly as
+        :class:`ndarray`.
+    subject : AtomArray or AtomArrayStack or ndarray, dtype=float, shape=(n,3) or shape=(m,n,3)
+        Structure(s) to be compared with `reference`.
+        Alternatively, coordinates can be provided directly as
+        :class:`ndarray`.
+
+    Returns
+    -------
+    rmsd : float or ndarray, dtype=float, shape=(m,)
+        RMSD between subject and reference.
+        If subject is an :class:`AtomArray` a float is returned.
+        If subject is an :class:`AtomArrayStack` a :class:`ndarray`
+        containing the RMSD for each model is returned.
+
+    See Also
+    --------
+    rmsf
+
+    Notes
+    -----
+    This function does not superimpose the subject to its reference.
+    In most cases :func:`superimpose()` should be called prior to this
+    function.
+
+    Examples
+    --------
+
+    Calculate the RMSD of all models to the first model:
+
+    >>> superimposed, _ = superimpose(atom_array, atom_array_stack)
+    >>> rms = rmsd(atom_array, superimposed)
+    >>> print(np.around(rms, decimals=3))
+    [0.000 1.928 2.103 2.209 1.806 2.172 2.704 1.360 2.337 1.818 1.879 2.471
+     1.939 2.035 2.167 1.789 1.653 2.348 2.247 2.529 1.583 2.115 2.131 2.050
+     2.512 2.666 2.206 2.397 2.328 1.868 2.316 1.984 2.124 1.761 2.642 1.721
+     2.571 2.579]
+    """
+    return np.sqrt(np.mean(_sq_euclidian(reference, subject), axis=-1))
+
+
+def rmspd(reference, subject, periodic=False, box=None):
+    r"""
+    Calculate the RMSD of atom pair distances for given structures
+    relative to those found in a reference structure.
+
+    Unlike the standard RMSD, the *root-mean-square-pairwise-deviation*
+    (RMSPD) is a fit-free method to determine deviations between
+    a structure and a preset reference.
+
+    .. math:: RMSPD = \sqrt{ \frac{1}{n^2} \sum\limits_{i=1}^n \sum\limits_{j \neq i}^n (d_{ij} - d_{ref,ij})^2}
+
+    Parameters
+    ----------
+    reference : AtomArray or ndarray, dtype=float, shape=(n,3)
+        The reference structure.
+        Alternatively, coordinates can be provided directly as
+        :class:`ndarray`.
+    subject : AtomArray or AtomArrayStack or ndarray, dtype=float, shape=(n,3) or shape=(m,n,3)
+        Structure(s) to be compared with `reference`.
+        Alternatively, coordinates can be provided directly as
+        :class:`ndarray`.
+    periodic : bool, optional
+        If set to true, periodic boundary conditions are taken into
+        account (minimum-image convention).
+        The `box` attribute of the `atoms` parameter is used for
+        calculation.
+        An alternative box can be provided via the `box` parameter.
+        By default, periodicity is ignored.
+    box : ndarray, shape=(3,3) or shape=(m,3,3), optional
+        If this parameter is set, the given box is used instead of the
+        `box` attribute of `atoms`.
+
+    Returns
+    -------
+    rmspd : float or ndarray, dtype=float, shape=(m,)
+        Atom pair distance RMSD between subject and reference.
+        If subject is an :class:`AtomArray` a float is returned.
+        If subject is an :class:`AtomArrayStack` a :class:`ndarray`
+        containing the RMSD for each model is returned.
+
+    Warnings
+    --------
+    Internally, this function uses :func:`index_distance()`.
+    For non-orthorombic boxes (at least one angle deviates from
+    90 degrees), periodic boundary conditions should be corrected
+    prior to the computation of RMSPDs with `periodic` set to false
+    to ensure correct results.
+    (e.g. with :func:`remove_pbc()`).
+
+    See also
+    --------
+    index_distance
+    remove_pbc
+    rmsd
+    """
+    # Compute index pairs in reference structure -> pair_ij for j < i
+    reflen = reference.array_length()
+    index_i = np.repeat(np.arange(reflen), reflen)
+    index_j = np.tile(np.arange(reflen), reflen)
+    pairs = np.stack([index_i, index_j]).T
+    refdist = index_distance(reference, pairs, periodic=periodic, box=box)
+    subjdist = index_distance(subject, pairs, periodic=periodic, box=box)
+
+    rmspd = np.sqrt(np.sum((subjdist - refdist) ** 2, axis=-1)) / reflen
+    return rmspd
+
+
+def rmsf(reference, subject):
+    r"""
+    Calculate the RMSF between two structures.
+
+    The *root-mean-square-fluctuation* (RMSF) indicates the positional
+    deviation of a structure to a reference structure, averaged over all
+    models.
+    Usually the reference structure, is the average over all models.
+    The RMSF is defined as:
+
+    .. math:: RMSF(i) = \sqrt{ \frac{1}{T} \sum\limits_{t=1}^T (x_i(t) - x_{ref,i}(t))^2}
+
+    Parameters
+    ----------
+    reference : AtomArray or ndarray, dtype=float, shape=(n,3)
+        The reference structure.
+        Alternatively, coordinates can be provided directly as
+        :class:`ndarray`.
+    subject : AtomArrayStack or ndarray, dtype=float, shape=(m,n,3)
+        Structures to be compared with `reference`.
+        The time *t* is represented by the models in the
+        :class:`AtomArrayStack`.
+        Alternatively, coordinates can be provided directly as
+        :class:`ndarray`.
+
+    Returns
+    -------
+    rmsf : ndarray, dtype=float, shape=(n,)
+        RMSF between subject and reference structure.
+        Each element gives the RMSF for the atom at the respective
+        index.
+
+    See Also
+    --------
+    rmsd
+
+    Notes
+    -----
+    This function does not superimpose the subject to its reference.
+    In most cases :func:`superimpose()` should be called prior to this
+    function.
+
+    Examples
+    --------
+
+    Calculate the :math:`C_\alpha` RMSF of all models to the average
+    model:
+
+    >>> ca = atom_array_stack[:, atom_array_stack.atom_name == "CA"]
+    >>> ca_average = average(ca)
+    >>> ca, _ = superimpose(ca_average, ca)
+    >>> print(rmsf(ca_average, ca))
+    [1.372 0.360 0.265 0.261 0.288 0.204 0.196 0.306 0.353 0.238 0.266 0.317
+     0.358 0.448 0.586 0.369 0.332 0.396 0.410 0.968]
+    """
+    return np.sqrt(np.mean(_sq_euclidian(reference, subject), axis=-2))
+
+
+def average(atoms):
+    """
+    Calculate an average structure.
+
+    The average structure has the average coordinates
+    of the input models.
+
+    Parameters
+    ----------
+    atoms : AtomArrayStack or ndarray, dtype=float, shape=(m,n,3)
+        The structure models to be averaged.
+        Alternatively, coordinates can be provided directly as
+        :class:`ndarray`.
+
+    Returns
+    -------
+    average : AtomArray or ndarray, dtype=float, shape=(n,3)
+        Structure with averaged atom coordinates.
+        If `atoms` is a :class:`ndarray` and :class:`ndarray` is also
+        returned.
+
+    See Also
+    --------
+    rmsd, rmsf
+
+    Notes
+    -----
+    The calculated average structure is not suitable for visualization
+    or geometric calculations, since bond lengths and angles will
+    deviate from meaningful values.
+    This method is rather useful to provide a reference structure for
+    calculation of e.g. the RMSD or RMSF.
+    """
+    coords = coord(atoms)
+    if coords.ndim != 3:
+        raise TypeError("Expected an AtomArrayStack or an ndarray with shape (m,n,3)")
+    mean_coords = np.mean(coords, axis=0)
+    if isinstance(atoms, AtomArrayStack):
+        mean_array = atoms[0].copy()
+        mean_array.coord = mean_coords
+        return mean_array
+    else:
+        return mean_coords
+
+
+def _sq_euclidian(reference, subject):
+    """
+    Calculate squared euclidian distance between atoms in two
+    structures.
+
+    Parameters
+    ----------
+    reference : AtomArray or ndarray, dtype=float, shape=(n,3)
+        Reference structure.
+    subject : AtomArray or AtomArrayStack or ndarray, dtype=float, shape=(n,3) or shape=(m,n,3)
+        Structure(s) whose atoms squared euclidian distance to
+        `reference` is measured.
+
+    Returns
+    -------
+    ndarray, dtype=float, shape=(n,) or shape=(m,n)
+        Squared euclidian distance between subject and reference.
+        If subject is an :class:`AtomArray` a 1-D array is returned.
+        If subject is an :class:`AtomArrayStack` a 2-D array is
+        returned.
+        In this case the first dimension indexes the AtomArray.
+    """
+    reference_coord = coord(reference)
+    subject_coord = coord(subject)
+    if reference_coord.ndim != 2:
+        raise TypeError(
+            "Expected an AtomArray or an ndarray with shape (n,3) as reference"
+        )
+    dif = subject_coord - reference_coord
+    return vector_dot(dif, dif)

biotite/structure/density.py

@@ -0,0 +1,109 @@
+# 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 module provides functions to calculate atomistic densities.
+"""
+
+__name__ = "biotite.structure"
+__author__ = "Daniel Bauer"
+__all__ = ["density"]
+
+import numpy as np
+from biotite.structure.atoms import coord
+
+
+def density(atoms, selection=None, delta=1.0, bins=None, density=False, weights=None):
+    r"""
+    Compute the density of the selected atoms.
+
+    This creates a 3d histogram over the coordinates of selected atoms.
+    By default, the grid for the histogram is built based on the
+    coordinates of the given `atoms` with an even gridspacing of
+    `delta` in all three dimensions.
+    Alternatively, a custom grid can be used.
+
+    Parameters
+    ----------
+    atoms : AtomArray or AtomArrayStack or ndarray, shape=(n,3) or shape=(m,n,3)
+        The density is calculated based on these atoms.
+        Alternatively, the coordinates can be directly provided as
+        `ndarray`.
+    selection : ndarray, dtype=bool, shape=(n,), optional
+        Boolean mask for `atoms` to calculate the density only on a set
+        of atoms.
+    delta : float, optional
+        Distance between grid points for density calculation (in Å).
+    bins : int or sequence of scalars or str, optional
+        Bins for the RDF.
+
+        - If `bins` is an `int`, it defines the number of bins.
+        - If `bins` is a sequence, it defines the bin edges, ignoring
+          the actual coordinates of the `atoms` selection.
+        - If `bins` is a string, it defines the function used to
+          calculate the bins.
+
+        See :func:`numpy.histogramdd()` for further details.
+    density : boolean, optional
+        If False, the number of samples in each bin is returned.
+        Otherwise, returns the probability density function of each bin.
+        See :func:`numpy.histogramdd()` for further details.
+    weights: ndarray, shape=(n,) or shape=(m,n), optional
+        An array of values to weight the contribution of *n* atoms in
+        *m* models.
+        If the shape is *(n,)*, the weights will be interpreted as
+        *per atom*.
+        A shape of *(m,n)* allows to additionally weight atoms on a
+        *per model* basis.
+
+    Returns
+    -------
+    H : ndarray, dtype=float
+        The threedimensional histogram of the selected atoms.
+        The histogram takes the atoms in all models into account.
+        The length of the histogram depends on `atoms` coordinates and
+        `delta`, or the supplied `bins` input parameter.
+    edges : list of ndarray, dtype=float
+        A list containing the 3 arrays describing the bin edges.
+    """
+    coords = coord(atoms)
+
+    is_stack = coords.ndim == 3
+
+    # Define the grid for coordinate binning based on coordinates of
+    # supplied atoms
+    # This makes the binning independent of a supplied box vector and
+    # fluctuating box dimensions are not a problem
+    # However, this means that the user has to make sure the region of
+    # interest is in the center of the box, i.e. by centering the
+    # investigated protein in the box.
+    if bins is None:
+        if is_stack:
+            axis = (0, 1)
+        else:
+            axis = 0
+        grid_min, grid_max = np.min(coords, axis=axis), np.max(coords, axis=axis)
+        bins = [
+            np.arange(grid_min[0], grid_max[0] + delta, delta),
+            np.arange(grid_min[1], grid_max[1] + delta, delta),
+            np.arange(grid_min[2], grid_max[2] + delta, delta),
+        ]
+
+    if selection is None:
+        selected_coords = coords
+    else:
+        selected_coords = coords[..., selection, :]
+
+    # Reshape the coords into Nx3
+    coords = selected_coords.reshape((np.prod(selected_coords.shape[:-1]), 3))
+
+    # We need a weight value per coordinate, but input might be per atom
+    if weights is not None:
+        if is_stack and len(weights.shape) < 2:
+            weights = np.tile(weights, len(selected_coords))
+        weights = weights.reshape(coords.shape[0])
+
+    # Calculate the histogram
+    hist = np.histogramdd(coords, bins=bins, density=density, weights=weights)
+    return hist

biotite/structure/dotbracket.py

@@ -0,0 +1,214 @@
+# 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 module handles conversion of RNA structures to
+dot-bracket-notation.
+"""
+
+__name__ = "biotite.structure"
+__author__ = "Tom David Müller"
+__all__ = ["dot_bracket_from_structure", "dot_bracket", "base_pairs_from_dot_bracket"]
+
+import numpy as np
+from biotite.structure.basepairs import base_pairs
+from biotite.structure.pseudoknots import pseudoknots
+from biotite.structure.residues import get_residue_count, get_residue_positions
+
+_OPENING_BRACKETS = "([{<ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+_OPENING_BRACKETS_BYTES = _OPENING_BRACKETS.encode()
+_CLOSING_BRACKETS = ")]}>abcdefghijklmnopqrstuvwxyz"
+_CLOSING_BRACKETS_BYTES = _CLOSING_BRACKETS.encode()
+
+
+def dot_bracket_from_structure(
+    nucleic_acid_strand, scores=None, max_pseudoknot_order=None
+):
+    """
+    Represent a nucleic-acid-strand in dot-bracket-letter-notation
+    (DBL-notation). :footcite:`Antczak2018`
+
+    Parameters
+    ----------
+    atom_array : AtomArray
+        The nucleic acid strand to be represented in DBL-notation.
+    scores : ndarray, dtype=int, shape=(n,) (default: None)
+        The score for each base pair, which is passed on to
+        :func:`pseudoknots()`.
+    max_pseudoknot_order : int (default: None)
+        The maximum pseudoknot order to be found. If a base pair would
+        be of a higher order, it is represented as unpaired. If ``None``
+        is given, all base pairs are evaluated.
+
+    Returns
+    -------
+    notations : list [str, ...]
+        The DBL-notation for each solution from :func:`pseudoknots()`.
+
+    See Also
+    --------
+    base_pairs
+    pseudoknots
+
+    References
+    ----------
+
+    .. footbibliography::
+    """
+    basepairs = base_pairs(nucleic_acid_strand)
+    if len(basepairs) == 0:
+        return [""]
+    basepairs = get_residue_positions(nucleic_acid_strand, basepairs)
+    length = get_residue_count(nucleic_acid_strand)
+    return dot_bracket(
+        basepairs, length, scores=scores, max_pseudoknot_order=max_pseudoknot_order
+    )
+
+
+def dot_bracket(basepairs, length, scores=None, max_pseudoknot_order=None):
+    """
+    Represent a nucleic acid strand in dot-bracket-letter-notation
+    (DBL-notation). :footcite:`Antczak2018`
+
+    The nucleic acid strand is represented as nucleotide sequence,
+    where the nucleotides are counted continiously from zero.
+
+    Parameters
+    ----------
+    basepairs : ndarray, shape=(n,2)
+        Each row corresponds to the positions of the bases in the
+        strand.
+    length : int
+        The number of bases in the strand.
+    scores : ndarray, dtype=int, shape=(n,) (default: None)
+        The score for each base pair, which is passed on to
+        :func:`pseudoknots()`
+    max_pseudoknot_order : int (default: None)
+        The maximum pseudoknot order to be found. If a base pair would
+        be of a higher order, it is represented as unpaired. If ``None``
+        is given, all pseudoknot orders are evaluated.
+
+    Returns
+    -------
+    notations : list [str, ...]
+        The DBL-notation for each solution from :func:`pseudoknots()`.
+
+    Examples
+    --------
+    The sequence ``ACGTC`` has a length of 5. If there was to be a
+    pairing interaction between the ``A`` and ``T``, `basepairs` would
+    have the form:
+
+    >>> import numpy as np
+    >>> basepairs = np.array([[0, 3]])
+
+    The DBL Notation can then be found with ``dot_bracket()``:
+
+    >>> dot_bracket(basepairs, 5)[0]
+    '(..).'
+
+
+    See Also
+    --------
+    dot_bracket_from_structure
+    base_pairs
+    pseudoknots
+
+    References
+    ----------
+
+    .. footbibliography::
+    """
+    # Make sure the lower residue is on the left for each row
+    basepairs = np.sort(basepairs, axis=1)
+
+    # Get pseudoknot order
+    pseudoknot_order = pseudoknots(
+        basepairs, scores=scores, max_pseudoknot_order=max_pseudoknot_order
+    )
+
+    # Each optimal pseudoknot order solution is represented in
+    # dot-bracket-notation
+    notations = [bytearray((b"." * length)) for _ in range(len(pseudoknot_order))]
+    for s, solution in enumerate(pseudoknot_order):
+        for basepair, order in zip(basepairs, solution):
+            if order == -1:
+                continue
+            notations[s][basepair[0]] = _OPENING_BRACKETS_BYTES[order]
+            notations[s][basepair[1]] = _CLOSING_BRACKETS_BYTES[order]
+    return [notation.decode() for notation in notations]
+
+
+def base_pairs_from_dot_bracket(dot_bracket_notation):
+    """
+    Extract the base pairs from a nucleic-acid-strand in
+    dot-bracket-letter-notation (DBL-notation). :footcite:`Antczak2018`
+
+    The nucleic acid strand is represented as nucleotide sequence,
+    where the nucleotides are counted continiously from zero.
+
+    Parameters
+    ----------
+    dot_bracket_notation : str
+        The DBL-notation.
+
+    Returns
+    -------
+    basepairs : ndarray, shape=(n,2)
+        Each row corresponds to the positions of the bases in the
+        sequence.
+
+    Examples
+    --------
+    The notation string ``'(..).'`` contains a base pair between the
+    indices 0 and 3. This pairing interaction can be extracted
+    conveniently by the use of :func:`base_pairs_from_dot_bracket()`:
+
+    >>> base_pairs_from_dot_bracket('(..).')
+    array([[0, 3]])
+
+    See Also
+    --------
+    dot_bracket
+
+    References
+    ----------
+
+    .. footbibliography::
+    """
+    basepairs = []
+    opened_brackets = [[] for _ in range(len(_OPENING_BRACKETS))]
+
+    # Iterate through input string and extract base pairs
+    for pos, symbol in enumerate(dot_bracket_notation):
+        if symbol in _OPENING_BRACKETS:
+            # Add opening residues to list (separate list for each
+            # bracket type)
+            index = _OPENING_BRACKETS.index(symbol)
+            opened_brackets[index].append(pos)
+
+        elif symbol in _CLOSING_BRACKETS:
+            # For each closing bracket, the the base pair consists out
+            # of the current index and the last index added to the list
+            # in `opened_brackets` corresponding to the same bracket
+            # type.
+            index = _CLOSING_BRACKETS.index(symbol)
+            basepairs.append((opened_brackets[index].pop(), pos))
+
+        else:
+            if symbol != ".":
+                raise ValueError(f"'{symbol}' is an invalid character for DBL-notation")
+
+    for not_closed in opened_brackets:
+        if not_closed != []:
+            raise ValueError(
+                "Invalid DBL-notation, not all opening brackets have a "
+                "closing bracket"
+            )
+
+    # Sort the base pair indices in ascending order
+    basepairs = np.array(basepairs)
+    if len(basepairs) > 0:
+        basepairs = basepairs[np.argsort(basepairs[:, 0])]
+    return basepairs

biotite/structure/error.py

@@ -0,0 +1,39 @@
+# 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 module contains all possible errors of the `structure` subpackage.
+"""
+
+__name__ = "biotite.structure"
+__author__ = "Patrick Kunzmann"
+__all__ = [
+    "BadStructureError",
+    "IncompleteStructureWarning",
+    "UnexpectedStructureWarning",
+]
+
+
+class BadStructureError(Exception):
+    """
+    Indicates that a structure is not suitable for a certain operation.
+    """
+
+    pass
+
+
+class IncompleteStructureWarning(Warning):
+    """
+    Indicates that a structure is not complete.
+    """
+
+    pass
+
+
+class UnexpectedStructureWarning(Warning):
+    """
+    Indicates that a structure was not expected.
+    """
+
+    pass