biotite 1.5.0__cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

biotite/application/viennarna/rnafold.py

@@ -0,0 +1,254 @@
+# 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.application.viennarna"
+__author__ = "Tom David Müller, Patrick Kunzmann"
+__all__ = ["RNAfoldApp"]
+
+from tempfile import NamedTemporaryFile
+import numpy as np
+from biotite.application.application import AppState, requires_state
+from biotite.application.localapp import LocalApp, cleanup_tempfile
+from biotite.application.viennarna.util import build_constraint_string
+from biotite.sequence.io.fasta import FastaFile, set_sequence
+from biotite.structure.dotbracket import base_pairs_from_dot_bracket
+
+
+class RNAfoldApp(LocalApp):
+    """
+    Compute the minimum free energy secondary structure of a ribonucleic
+    acid sequence using *ViennaRNA's* *RNAfold* software.
+
+    Internally this creates a :class:`Popen` instance, which handles
+    the execution.
+
+    Parameters
+    ----------
+    sequence : NucleotideSequence
+        The RNA sequence.
+    temperature : int, optional
+        The temperature (°C) to be assumed for the energy parameters.
+    bin_path : str, optional
+        Path of the *RNAfold* binary.
+
+    Examples
+    --------
+
+    >>> sequence = NucleotideSequence("CGACGTAGATGCTAGCTGACTCGATGC")
+    >>> app = RNAfoldApp(sequence)
+    >>> app.start()
+    >>> app.join()
+    >>> print(app.get_free_energy())
+    -1.3
+    >>> print(app.get_dot_bracket())
+    (((.((((.......)).)))))....
+    """
+
+    def __init__(self, sequence, temperature=37, bin_path="RNAfold"):
+        self._sequence = sequence.copy()
+        self._temperature = str(temperature)
+        self._constraints = None
+        self._enforce = None
+        self._in_file = NamedTemporaryFile("w", suffix=".fa", delete=False)
+        super().__init__(bin_path)
+
+    def run(self):
+        # Insert no line breaks
+        # -> Extremely high value for characters per line
+        fasta_file = FastaFile(chars_per_line=np.iinfo(np.int32).max)
+        set_sequence(fasta_file, self._sequence)
+        if self._constraints is not None:
+            fasta_file.lines.append(self._constraints)
+        fasta_file.write(self._in_file)
+        self._in_file.flush()
+
+        options = [
+            "--noPS",
+            "-T",
+            self._temperature,
+        ]
+        if self._enforce is True:
+            options.append("--enforceConstraint")
+        if self._constraints is not None:
+            options.append("-C")
+
+        self.set_arguments(options + [self._in_file.name])
+        super().run()
+
+    def evaluate(self):
+        super().evaluate()
+        lines = self.get_stdout().splitlines()
+        content = lines[2]
+        dotbracket, free_energy = content.split(" ", maxsplit=1)
+        free_energy = float(free_energy[1:-1])
+
+        self._free_energy = free_energy
+        self._dotbracket = dotbracket
+
+    def clean_up(self):
+        super().clean_up()
+        cleanup_tempfile(self._in_file)
+
+    @requires_state(AppState.CREATED)
+    def set_temperature(self, temperature):
+        """
+        Adjust the energy parameters according to a temperature in
+        degrees Celsius.
+
+        Parameters
+        ----------
+        temperature : int
+            The temperature.
+        """
+        self._temperature = str(temperature)
+
+    @requires_state(AppState.CREATED)
+    def set_constraints(
+        self,
+        pairs=None,
+        paired=None,
+        unpaired=None,
+        downstream=None,
+        upstream=None,
+        enforce=False,
+    ):
+        """
+        Add constraints of known paired or unpaired bases to the folding
+        algorithm.
+
+        Constraints forbid pairs conflicting with the respective
+        constraint.
+
+        Parameters
+        ----------
+        pairs : ndarray, shape=(n,2), dtype=int, optional
+            Positions of constrained base pairs.
+        paired : ndarray, shape=(n,), dtype=int or dtype=bool, optional
+            Positions of bases that are paired with any other base.
+        unpaired : ndarray, shape=(n,), dtype=int or dtype=bool, optional
+            Positions of bases that are unpaired.
+        downstream : ndarray, shape=(n,), dtype=int or dtype=bool, optional
+            Positions of bases that are paired with any downstream base.
+        upstream : ndarray, shape=(n,), dtype=int or dtype=bool, optional
+            Positions of bases that are paired with any upstream base.
+        enforce : bool, optional
+            If set to true, the given constraints are enforced, i.e. a
+            the respective base pairs must form.
+            By default (false), a constraint does only forbid formation
+            of a pair that would conflict with this constraint.
+        """
+        self._constraints = build_constraint_string(
+            len(self._sequence), pairs, paired, unpaired, downstream, upstream
+        )
+        self._enforce = enforce
+
+    @requires_state(AppState.JOINED)
+    def get_free_energy(self):
+        """
+        Get the free energy (kcal/mol) of the suggested
+        secondary structure.
+
+        Returns
+        -------
+        free_energy : float
+            The free energy.
+
+        Examples
+        --------
+
+        >>> sequence = NucleotideSequence("CGACGTAGATGCTAGCTGACTCGATGC")
+        >>> app = RNAfoldApp(sequence)
+        >>> app.start()
+        >>> app.join()
+        >>> print(app.get_free_energy())
+        -1.3
+        """
+        return self._free_energy
+
+    @requires_state(AppState.JOINED)
+    def get_dot_bracket(self):
+        """
+        Get the minimum free energy secondary structure of the input
+        sequence in dot bracket notation.
+
+        Returns
+        -------
+        dotbracket : str
+            The secondary structure in dot bracket notation.
+
+        Examples
+        --------
+
+        >>> sequence = NucleotideSequence("CGACGTAGATGCTAGCTGACTCGATGC")
+        >>> app = RNAfoldApp(sequence)
+        >>> app.start()
+        >>> app.join()
+        >>> print(app.get_dot_bracket())
+        (((.((((.......)).)))))....
+        """
+        return self._dotbracket
+
+    @requires_state(AppState.JOINED)
+    def get_base_pairs(self):
+        """
+        Get the base pairs from the minimum free energy secondary
+        structure of the input sequence.
+
+        Returns
+        -------
+        base_pairs : ndarray, shape=(n,2)
+            Each row corresponds to the positions of the bases in the
+            sequence.
+
+        Examples
+        --------
+
+        >>> sequence = NucleotideSequence("CGACGTAGATGCTAGCTGACTCGATGC")
+        >>> app = RNAfoldApp(sequence)
+        >>> app.start()
+        >>> app.join()
+        >>> print(app.get_base_pairs())
+            [[ 0 22]
+             [ 1 21]
+             [ 2 20]
+             [ 4 19]
+             [ 5 18]
+             [ 6 16]
+             [ 7 15]]
+
+        For reference, the corresponding dot bracket notation can be
+        displayed as below.
+
+        >>> print(app.get_dot_bracket())
+        (((.((((.......)).)))))....
+        """
+        return base_pairs_from_dot_bracket(self._dotbracket)
+
+    @staticmethod
+    def compute_secondary_structure(sequence, bin_path="RNAfold"):
+        """
+        Compute the minimum free energy secondary structure of a
+        ribonucleic acid sequence using *ViennaRNA's* *RNAfold* software.
+
+        This is a convenience function, that wraps the
+        :class:`RNAfoldApp` execution.
+
+        Parameters
+        ----------
+        sequence : NucleotideSequence
+            The RNA sequence.
+        bin_path : str, optional
+            Path of the *RNAfold* binary.
+
+        Returns
+        -------
+        dotbracket : str
+            The secondary structure in dot bracket notation.
+        free_energy : float
+            The free energy.
+        """
+        app = RNAfoldApp(sequence, bin_path=bin_path)
+        app.start()
+        app.join()
+        return app.get_dot_bracket(), app.get_free_energy()

biotite/application/viennarna/rnaplot.py

@@ -0,0 +1,208 @@
+# 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.application.viennarna"
+__author__ = "Tom David Müller"
+__all__ = ["RNAplotApp"]
+
+from enum import IntEnum
+from os import remove
+from tempfile import NamedTemporaryFile
+import numpy as np
+from biotite.application.application import AppState, requires_state
+from biotite.application.localapp import LocalApp, cleanup_tempfile
+from biotite.structure.dotbracket import dot_bracket as dot_bracket_
+
+
+class RNAplotApp(LocalApp):
+    """
+    Get coordinates for a 2D representation of any unknotted RNA
+    structure using *ViennaRNA's* *RNAplot*.
+
+    The structure has to be provided either in dot bracket notation or
+    as a ``ndarray`` of base pairs and the total sequence length.
+
+    Internally this creates a :class:`Popen` instance, which handles
+    the execution.
+
+    Parameters
+    ----------
+    dot_bracket : str, optional
+        The structure in dot bracket notation.
+    base_pairs : ndarray, shape=(n,2), optional
+        Each row corresponds to the positions of the bases in the
+        strand. This parameter is mutually exclusive to ``dot_bracket``.
+    length : int, optional
+        The number of bases in the strand. This parameter is required if
+        ``base_pairs`` is given.
+    layout_type : RNAplotApp.Layout, optional
+        The layout type according to the *RNAplot* documentation.
+    bin_path : str, optional
+        Path of the *RNAplot* binary.
+
+    Examples
+    --------
+
+    >>> app = RNAplotApp('((..))')
+    >>> app.start()
+    >>> app.join()
+    >>> print(app.get_coordinates())
+    [[ -92.50   92.50]
+     [ -92.50   77.50]
+     [ -90.31   58.24]
+     [-109.69   58.24]
+     [-107.50   77.50]
+     [-107.50   92.50]]
+    """
+
+    class Layout(IntEnum):
+        """
+        This enum type represents the layout type of the plot according
+        to the official *RNAplot* orientation.
+        """
+
+        RADIAL = (0,)
+        NAVIEW = (1,)
+        CIRCULAR = (2,)
+        RNATURTLE = (3,)
+        RNAPUZZLER = 4
+
+    def __init__(
+        self,
+        dot_bracket=None,
+        base_pairs=None,
+        length=None,
+        layout_type=Layout.NAVIEW,
+        bin_path="RNAplot",
+    ):
+        super().__init__(bin_path)
+
+        if dot_bracket is not None:
+            self._dot_bracket = dot_bracket
+        elif (base_pairs is not None) and (length is not None):
+            self._dot_bracket = dot_bracket_(
+                base_pairs, length, max_pseudoknot_order=0
+            )[0]
+        else:
+            raise ValueError(
+                "Structure has to be provided in either dot bracket notation "
+                "or as base pairs and total sequence length"
+            )
+
+        # Get the value of the enum type
+        self._layout_type = str(int(layout_type))
+        self._in_file = NamedTemporaryFile("w", suffix=".fold", delete=False)
+
+    def run(self):
+        self._in_file.write("N" * len(self._dot_bracket) + "\n")
+        self._in_file.write(self._dot_bracket)
+        self._in_file.flush()
+        self.set_arguments(
+            [
+                "-i", self._in_file.name,
+                "--output-format", "xrna",
+                "-t", self._layout_type,
+            ]
+        )  # fmt: skip
+        super().run()
+
+    def evaluate(self):
+        super().evaluate()
+        self._coordinates = np.loadtxt("rna.ss", usecols=(2, 3))
+
+    def clean_up(self):
+        super().clean_up()
+        cleanup_tempfile(self._in_file)
+        remove("rna.ss")
+
+    @requires_state(AppState.CREATED)
+    def set_layout_type(self, layout_type):
+        """
+        Adjust the layout type for the plot according to the *RNAplot*
+        documentation.
+
+        Parameters
+        ----------
+        layout_type : RNAplotApp.Layout
+            The layout type.
+        """
+        self._layout_type = str(layout_type)
+
+    @requires_state(AppState.JOINED)
+    def get_coordinates(self):
+        """
+        Get coordinates for a 2D representation of the input structure.
+
+        Returns
+        -------
+        coordinates : ndarray, shape=(n,2)
+            The 2D coordinates. Each row represents the *x* and *y*
+            coordinates for a total sequence length of *n*.
+
+        Examples
+        --------
+
+        >>> app = RNAplotApp('((..))')
+        >>> app.start()
+        >>> app.join()
+        >>> print(app.get_coordinates())
+        [[ -92.50   92.50]
+         [ -92.50   77.50]
+         [ -90.31   58.24]
+         [-109.69   58.24]
+         [-107.50   77.50]
+         [-107.50   92.50]]
+        """
+        return self._coordinates
+
+    @staticmethod
+    def compute_coordinates(
+        dot_bracket=None,
+        base_pairs=None,
+        length=None,
+        layout_type=Layout.NAVIEW,
+        bin_path="RNAplot",
+    ):
+        """
+        Get coordinates for a 2D representation of any unknotted RNA
+        structure using *ViennaRNA's* *RNAplot*.
+
+        The structure has to be provided either in dot bracket notation
+        or as a ``ndarray`` of base pairs and the total sequence length.
+
+        This is a convenience function, that wraps the
+        :class:`RNAplotApp` execution.
+
+        Parameters
+        ----------
+        dot_bracket : str, optional
+            The structure in dot bracket notation.
+        base_pairs : ndarray, shape=(n,2), optional
+            Each row corresponds to the positions of the bases in the
+            strand. This parameter is mutually exclusive to
+            ``dot_bracket``.
+        length : int, optional
+            The number of bases in the strand. This parameter is
+            required if ``base_pairs`` is given.
+        layout_type : Layout
+            The desired layout of the plot.
+        bin_path : str, optional
+            Path of the *RNAplot* binary.
+
+        Returns
+        -------
+        coordinates : ndarray, shape=(n,2)
+            The 2D coordinates. Each row represents the *x* and *y*
+            coordinates for a total sequence length of *n*.
+        """
+        app = RNAplotApp(
+            dot_bracket=dot_bracket,
+            base_pairs=base_pairs,
+            length=length,
+            layout_type=layout_type,
+            bin_path=bin_path,
+        )
+        app.start()
+        app.join()
+        return app.get_coordinates()

biotite/application/viennarna/util.py

@@ -0,0 +1,77 @@
+# 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.application.viennarna"
+__author__ = "Patrick Kunzmann"
+__all__ = ["build_constraint_string"]
+
+import numpy as np
+from biotite.structure.pseudoknots import pseudoknots
+
+
+def build_constraint_string(
+    sequence_length,
+    pairs=None,
+    paired=None,
+    unpaired=None,
+    downstream=None,
+    upstream=None,
+):
+    """
+    Build a ViennaRNA constraint string.
+
+    Parameters
+    ----------
+    sequence_length : int
+        The length of the string to be built.
+    pairs : ndarray, shape=(n,2), dtype=int, optional
+        Positions of constrained base pairs.
+    paired : ndarray, shape=(n,), dtype=int or dtype=bool, optional
+        Positions of bases that are paired with any other base.
+    unpaired : ndarray, shape=(n,), dtype=int or dtype=bool, optional
+        Positions of bases that are unpaired.
+    downstream : ndarray, shape=(n,), dtype=int or dtype=bool, optional
+        Positions of bases that are paired with any downstream base.
+    upstream : ndarray, shape=(n,), dtype=int or dtype=bool, optional
+        Positions of bases that are paired with any upstream base.
+
+    Returns
+    -------
+    constraints : str
+        The constraint string.
+    """
+    constraints = np.full(sequence_length, ".", dtype="U1")
+
+    if pairs is not None:
+        pairs = np.asarray(pairs)
+        # Ensure that pairs do not contain pseudoknots
+        if (pseudoknots(pairs, max_pseudoknot_order=1) == -1).any():
+            raise ValueError("Given pairs include pseudoknots")
+        # Ensure the lower base comes first for each pair
+        pairs = np.sort(pairs, axis=-1)
+        _set_constraints(constraints, pairs[:, 0], "(")
+        _set_constraints(constraints, pairs[:, 1], ")")
+
+    _set_constraints(constraints, paired, "|")
+    _set_constraints(constraints, unpaired, "x")
+    _set_constraints(constraints, downstream, "<")
+    _set_constraints(constraints, upstream, ">")
+
+    return "".join(constraints)
+
+
+def _set_constraints(constraints, index, character):
+    if index is None:
+        return
+
+    # Search for conflicts with other constraints
+    potential_conflict_indices = np.where(constraints[index] != ".")[0]
+    if len(potential_conflict_indices) > 0:
+        conflict_i = index[potential_conflict_indices[0]]
+        raise ValueError(
+            f"Constraint '{character}' at position {conflict_i} "
+            f"conflicts with existing constraint '{constraints[conflict_i]}'"
+        )
+
+    constraints[index] = character

biotite/application/webapp.py

@@ -0,0 +1,76 @@
+# 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.application"
+__author__ = "Patrick Kunzmann"
+__all__ = ["WebApp", "RuleViolationError"]
+
+import abc
+from biotite.application.application import Application
+
+
+class WebApp(Application, metaclass=abc.ABCMeta):
+    """
+    The base class for all web based applications.
+
+    It allows for getting and setting the URL of the app and raises
+    an :class:`RuleViolationError` when a subclass calls
+    :func:`violate_rule()`
+    (e.g. when the server was contacted too often.)
+
+    Be careful, when calling func:`get_app_state()`. This may involve a
+    server contact and therefore frequent calls may raise a
+    :class:`RuleViolationError`.
+
+    Parameters
+    ----------
+    app_url : str
+        URL of the web app.
+    obey_rules : bool, optional
+        If true, the application raises an :class:`RuleViolationError`, if
+        the server rules are violated.
+    """
+
+    def __init__(self, app_url, obey_rules=True):
+        super().__init__()
+        self._obey_rules = obey_rules
+        self._app_url = app_url
+
+    def violate_rule(self, msg=None):
+        """
+        Indicate that a server rule was violated, i.e. this raises a
+        :class:`RuleViolationError` unless `obey_rules` is false.
+
+        PROTECTED: Do not call from outside.
+
+        Parameters
+        ----------
+        msg : str, optional
+            A custom message for the :class:`RuleViolationError`.
+        """
+        if self._obey_rules:
+            if msg is None:
+                raise RuleViolationError("The user guidelines would be violated")
+            else:
+                raise RuleViolationError(msg)
+
+    def app_url(self):
+        """
+        Get the URL of the web app.
+
+        Returns
+        -------
+        url : str
+            URL of the web app.
+        """
+        return self._app_url
+
+
+class RuleViolationError(Exception):
+    """
+    Indicates that the user guidelines of the web application would be
+    violated, if the program continued.
+    """
+
+    pass

biotite/copyable.py

@@ -0,0 +1,71 @@
+# 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"
+__author__ = "Patrick Kunzmann"
+__all__ = ["Copyable"]
+
+import abc
+
+
+class Copyable(metaclass=abc.ABCMeta):
+    """
+    Base class for all objects, that should be copyable.
+
+    The public method `copy()` first creates a fresh instance of the
+    class of the instance, that is copied via the `__copy_create__()`
+    method. All variables, that could not be set via the constructor,
+    are then copied via `__copy_fill__()`, starting with the method in
+    the uppermost base class and ending with the class of the instance
+    to be copied.
+
+    This approach solves the problem of encapsulated variables in
+    superclasses.
+    """
+
+    def copy(self):
+        """
+        Create a deep copy of this object.
+
+        Returns
+        -------
+        copy
+            A copy of this object.
+        """
+        clone = self.__copy_create__()
+        self.__copy_fill__(clone)
+        return clone
+
+    def __copy_create__(self):
+        """
+        Instantiate a new object of this class.
+
+        Only the constructor should be called in this method.
+        All further attributes, that need to be copied are handled
+        in `__copy_fill__()`
+
+        Do not call the `super()` method here.
+
+        This method must be overridden, if the constructor takes
+        parameters.
+
+        Returns
+        -------
+        copy
+            A freshly instantiated copy of *self*.
+        """
+        return type(self)()
+
+    def __copy_fill__(self, clone):
+        """
+        Copy all necessary attributes to the new object.
+
+        Always call the `super()` method as first statement.
+
+        Parameters
+        ----------
+        clone
+            The freshly instantiated copy of *self*.
+        """
+        pass

biotite/database/__init__.py

@@ -0,0 +1,23 @@
+# 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.
+
+"""
+A subpackage for fetching data from online databases.
+
+Each subpackage of the database package contains an interface for a
+specific database.
+
+All subpackages provide at least two functions:
+:func:`search()` is used to search for IDs (e.g. PDB ID) that match the
+given search parameters.
+The search parameters are usually abstracted by the respective
+:class:`Query` objects.
+Then the obtained IDs can be given to the :func:`fetch()` function to
+download the associated files.
+"""
+
+__name__ = "biotite.database"
+__author__ = "Patrick Kunzmann"
+
+from .error import *