biotite 1.5.0__cp314-cp314-macosx_10_13_x86_64.whl

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,213 @@
+# 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
+    ----------
+    nucleic_acid_strand : AtomArray
+        The nucleic acid strand to be represented in DBL-notation.
+    scores : ndarray, dtype=int, shape=(n,)
+        The score for each base pair, which is passed on to
+        :func:`pseudoknots()`.
+    max_pseudoknot_order : int
+        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 : Compute the base pairs from a structure as passed to this function.
+    dot_bracket : Compute the dot bracket notation directly from base pairs.
+    pseudoknots : Get the pseudoknot order for each base pair.
+
+    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,)
+        The score for each base pair, which is passed on to :func:`pseudoknots()`.
+    max_pseudoknot_order : int
+        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()`.
+
+    See Also
+    --------
+    base_pairs_from_dot_bracket : The reverse operation.
+    dot_bracket_from_structure : Compute the dot bracket notation from a structure.
+    base_pairs : Compute the base pairs from a structure as passed to this function.
+    pseudoknots : Get the pseudoknot order for each base pair.
+
+    References
+    ----------
+
+    .. footbibliography::
+
+    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]
+    '(..).'
+    """
+    # 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.
+
+    See Also
+    --------
+    dot_bracket : The reverse operation.
+
+    References
+    ----------
+
+    .. footbibliography::
+
+    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]])
+    """
+    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