biotite 0.41.1__cp312-cp312-macosx_10_16_arm64.whl

biotite/application/tantan/app.py

@@ -0,0 +1,222 @@
+# 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.tantan"
+__author__ = "Patrick Kunzmann"
+__all__ = ["TantanApp"]
+
+from collections.abc import Sequence as SequenceABC
+import io
+from tempfile import NamedTemporaryFile
+import numpy as np
+from ..localapp import LocalApp, cleanup_tempfile
+from ..application import AppState, requires_state
+from ...sequence.seqtypes import NucleotideSequence, ProteinSequence
+from ...sequence.alphabet import common_alphabet
+from ...sequence.io.fasta.file import FastaFile
+from ..util import map_sequence, map_matrix
+
+
+MASKING_LETTER = "!"
+
+
+class TantanApp(LocalApp):
+    r"""
+    Mask sequence repeat regions using *tantan*. :footcite:`Frith2011`
+
+    Parameters
+    ----------
+    sequence : (list of) NucleotideSequence or ProteinSequence
+        The sequence(s) to be masked.
+        Either a single sequence or multiple sequences can be masked.
+        Masking multiple sequences in a single run decreases the
+        run time compared to multiple runs with a single sequence.
+        All sequences must be of the same type.
+    matrix : SubstitutionMatrix, optional
+        The substitution matrix to use for repeat identification.
+        A sequence segment is considered to be a repeat of another
+        segment, if the substitution score between these segments is
+        greater than a threshold value.
+    bin_path : str, optional
+        Path of the *tantan* binary.
+
+    References
+    ----------
+    
+    .. footbibliography::
+
+    Examples
+    --------
+
+    >>> sequence = NucleotideSequence("GGCATCGATATATATATATAGTCAA")
+    >>> app = TantanApp(sequence)
+    >>> app.start()
+    >>> app.join()
+    >>> repeat_mask = app.get_mask()
+    >>> print(repeat_mask)
+    [False False False False False False False False False  True  True  True
+      True  True  True  True  True  True  True  True False False False False
+     False]
+    >>> print(sequence, "\n" + "".join(["^" if e else " " for e in repeat_mask]))
+    GGCATCGATATATATATATAGTCAA 
+             ^^^^^^^^^^^         
+    """
+    
+    def __init__(self, sequence, matrix=None, bin_path="tantan"):
+        super().__init__(bin_path)
+
+        if isinstance(sequence, SequenceABC):
+            self._as_list = True
+            self._sequences = sequence
+        else:
+            # Convert to list of sequences anyway for consistent handling
+            self._as_list = False
+            self._sequences = [sequence]
+
+        self._is_protein = None
+        for seq in self._sequences:
+            if isinstance(seq, NucleotideSequence):
+                if self._is_protein is True:
+                    # Already protein sequences in the list
+                    raise ValueError(
+                        "List of sequences contains mixed "
+                        "nucleotide and protein sequences"
+                    )
+                self._is_protein = False
+            elif isinstance(seq, ProteinSequence):
+                if self._is_protein is False:
+                    # Already nucleotide sequences in the list
+                    raise ValueError(
+                        "List of sequences contains mixed "
+                        "nucleotide and protein sequences"
+                    )
+                self._is_protein = True
+            else:
+                raise TypeError(
+                    "A NucleotideSequence or ProteinSequence is required"
+                )
+        
+        if matrix is None:
+            self._matrix_file = None
+        else:
+            common_alph = common_alphabet(
+                (seq.alphabet for seq in self._sequences)
+            )
+            if common_alph is None:
+                raise ValueError(
+                    "There is no common alphabet within the sequences"
+                )
+            if not matrix.get_alphabet1().extends(common_alph):
+                raise ValueError(
+                    "The alphabet of the sequence(s) do not fit the matrix"
+                )
+            if not matrix.is_symmetric():
+                raise ValueError("A symmetric matrix is required")
+            self._matrix_file = NamedTemporaryFile(
+                "w", suffix=".mat", delete=False
+            )
+        self._matrix = matrix
+        
+        self._in_file = NamedTemporaryFile("w", suffix=".fa", delete=False)
+
+
+    def run(self):
+        FastaFile.write_iter(
+            self._in_file,
+            (
+                (f"sequence_{i:d}", str(seq))
+                for i, seq in enumerate(self._sequences)
+            )
+        )
+        self._in_file.flush()
+        if self._matrix is not None:
+            self._matrix_file.write(str(self._matrix))
+            self._matrix_file.flush()
+        
+        args = []
+        if self._matrix is not None:
+            args += ["-m", self._matrix_file.name]
+        if self._is_protein:
+             args += ["-p"]
+        args += [
+            "-x", MASKING_LETTER,
+            self._in_file.name
+        ]
+        self.set_arguments(args)
+        super().run()
+    
+
+    def evaluate(self):
+        super().evaluate()
+
+        out_file = io.StringIO(self.get_stdout())
+        self._masks = []
+        encoded_masking_letter = MASKING_LETTER.encode("ASCII")[0]
+        for _, masked_seq_string in FastaFile.read_iter(out_file):
+            array = np.frombuffer(
+                masked_seq_string.encode("ASCII"), dtype=np.ubyte
+            )
+            self._masks.append(array == encoded_masking_letter)
+    
+
+    def clean_up(self):
+        super().clean_up()
+        cleanup_tempfile(self._in_file)
+        if self._matrix_file is not None:
+            cleanup_tempfile(self._matrix_file)
+    
+
+    @requires_state(AppState.JOINED)
+    def get_mask(self):
+        """
+        Get a boolean mask covering identified repeat regions of each
+        input sequence.
+
+        Returns
+        -------
+        repeat_mask : (list of) ndarray, shape=(n,), dtype=bool
+            A boolean mask that is true for each sequence position that
+            is identified as repeat.
+            If a list of sequences were given as input, a list of masks
+            is returned instead.
+        """
+        if self._as_list:
+            return self._masks
+        else:
+            return self._masks[0]
+
+
+    @staticmethod
+    def mask_repeats(sequence, matrix=None, bin_path="tantan"):
+        """
+        Mask repeat regions of the given input sequence(s).
+
+        Parameters
+        ----------
+        sequence : (list of) NucleotideSequence or ProteinSequence
+            The sequence(s) to be masked.
+            Either a single sequence or multiple sequences can be masked.
+            Masking multiple sequences in a single run decreases the
+            run time compared to multiple runs with a single sequence.
+            All sequences must be of the same type.
+        matrix : SubstitutionMatrix, optional
+            The substitution matrix to use for repeat identification.
+            A sequence segment is considered to be a repeat of another
+            segment, if the substitution score between these segments is
+            greater than a threshold value.
+        bin_path : str, optional
+            Path of the *tantan* binary.
+
+        Returns
+        -------
+        repeat_mask : (list of) ndarray, shape=(n,), dtype=bool
+            A boolean mask that is true for each sequence position that
+            is identified as repeat.
+            If a list of sequences were given as input, a list of masks
+            is returned instead.
+        """
+        app = TantanApp(sequence, matrix, bin_path)
+        app.start()
+        app.join()
+        return app.get_mask()

biotite/application/util.py

@@ -0,0 +1,59 @@
+# 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__ = ["map_sequence", "map_matrix"]
+
+
+import numpy as np
+from ..sequence.seqtypes import ProteinSequence
+from ..sequence.align.matrix import SubstitutionMatrix
+
+
+def map_sequence(sequence):
+    """
+    Map a sequence with an arbitrary alphabet into a
+    :class:`ProteinSequence`, in order to support arbitrary sequence
+    types in software that can handle protein sequences. 
+    """
+    if len(sequence.alphabet) > len(ProteinSequence.alphabet):
+        # Cannot map into a protein sequence if the alphabet
+        # has more symbols
+        raise TypeError(
+            f"The software cannot align sequences of type "
+            f"{type(sequence).__name__}: "
+            f"Alphabet is too large to be converted into amino "
+            f"acid alphabet"
+        )
+    # Mapping is done by simply taking over the sequence
+    # code of the original sequence
+    mapped_sequence = ProteinSequence()
+    mapped_sequence.code = sequence.code
+    return mapped_sequence
+
+
+def map_matrix(matrix):
+    """
+    Map a :class:`SubstitutionMatrix` with an arbitrary alphabet into a
+    class:`SubstitutionMatrix` for protein sequences, in order to support
+    arbitrary sequence types in software that can handle protein
+    sequences. 
+    """
+    if matrix is None:
+        raise TypeError(
+            "A substitution matrix must be provided for custom "
+            "sequence types"
+        )
+    # Create a protein substitution matrix with the values taken
+    # from the original matrix
+    # All trailing symbols are filled with zeros
+    old_length = len(matrix.get_alphabet1())
+    new_length = len(ProteinSequence.alphabet)
+    new_score_matrix = np.zeros((new_length, new_length))
+    new_score_matrix[:old_length, :old_length] = matrix.score_matrix()
+    return SubstitutionMatrix(
+        ProteinSequence.alphabet, ProteinSequence.alphabet,
+        new_score_matrix
+    )

biotite/application/viennarna/__init__.py

@@ -0,0 +1,18 @@
+# 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 that provides interfaces to the *ViennaRNA* software
+package.
+
+Secondary structures can be predicted using *RNAfold* and plotted using
+*RNAplot*.
+"""
+
+__name__ = "biotite.application.viennarna"
+__author__ = "Tom David Müller"
+
+from .rnaalifold import *
+from .rnafold import *
+from .rnaplot import *

biotite/application/viennarna/rnaalifold.py

@@ -0,0 +1,304 @@
+# 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__ = ["RNAalifoldApp"]
+
+import copy
+from tempfile import NamedTemporaryFile
+import numpy as np
+from ..application import AppState, requires_state
+from ..localapp import LocalApp, cleanup_tempfile
+from ...sequence.io.fasta import FastaFile, set_alignment
+from ...structure.dotbracket import base_pairs_from_dot_bracket
+from ...structure.bonds import BondList
+from .util import build_constraint_string
+
+
+class RNAalifoldApp(LocalApp):
+    """
+    Predict the consensus secondary structure from a ribonucleic acid alignment
+    using *ViennaRNA's* *RNAalifold* software.
+
+    In contrast to :class:`RNAfoldApp`, the energy function includes
+    a term that includes coevolution information extracted from an
+    alignment in addition to the physical free energy term.
+
+    Internally this creates a :class:`Popen` instance, which handles
+    the execution.
+
+    Parameters
+    ----------
+    alignment : Alignment
+        An alignment of RNA sequences.
+    temperature : int, optional
+        The temperature (°C) to be assumed for the energy parameters.
+    bin_path : str, optional
+        Path of the *RNAalifold* binary.
+    """
+
+    def __init__(self, alignment, temperature=37, bin_path="RNAalifold"):
+        super().__init__(bin_path)
+        self._alignment = copy.deepcopy(alignment)
+        self._temperature = str(temperature)
+        self._constraints = None
+        self._enforce = None
+        self._in_file = NamedTemporaryFile(
+            "w", suffix=".fa", delete=False
+        )
+        self._constraints_file = NamedTemporaryFile(
+            "w+", suffix=".constraints", delete=False
+        )
+
+    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_alignment(
+            fasta_file, self._alignment,
+            seq_names=[str(i) for i in range(len(self._alignment.sequences))]
+        )
+        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._constraints_file.write(self._constraints)
+            self._constraints_file.flush()
+            self._constraints_file.seek(0)
+            self.set_stdin(self._constraints_file)
+
+        self.set_arguments(options + [self._in_file.name])
+        super().run()
+    
+    def clean_up(self):
+        super().clean_up()
+        cleanup_tempfile(self._in_file)
+        cleanup_tempfile(self._constraints_file)
+
+    def evaluate(self):
+        super().evaluate()
+        lines = self.get_stdout().splitlines()
+        self._consensus = lines[0].strip()
+        result = lines[1]
+        dotbracket, total_energy = result.split(" ", maxsplit=1)
+        # Energy has the form:
+        # (<total> = <free> + <covariance>)
+        total_energy = total_energy[1:-1]
+        energy_contributions = total_energy.split("=")[1].split("+")
+        self._free_energy = float(energy_contributions[0])
+        self._covariance_energy = float(energy_contributions[1])
+        self._dotbracket = dotbracket
+    
+    @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.
+        
+        Warnings
+        --------
+        If a constraint is given for a gap position in the consensus sequence,
+        the software may find no base pairs at all.
+        """
+        self._constraints = build_constraint_string(
+            len(self._alignment),
+            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 consensus
+        secondary structure.
+
+        Returns
+        -------
+        free_energy : float
+            The free energy.
+        
+        Notes
+        -----
+        The total energy of the secondary structure regarding the
+        minimization objective is the sum of the free energy and the
+        covariance term.
+        
+        See also
+        --------
+        get_covariance_energy
+        """
+        return self._free_energy
+    
+    @requires_state(AppState.JOINED)
+    def get_covariance_energy(self):
+        """
+        Get the energy of the artificial covariance term (kcal/mol) of
+        the suggested consensus secondary structure.
+
+        Returns
+        -------
+        covariance_energy : float
+            The energy of the covariance term.
+        
+        Notes
+        -----
+        The total energy of the secondary structure regarding the
+        minimization objective is the sum of the free energy and the
+        covariance term.
+        
+        See also
+        --------
+        get_free_energy
+        """
+        return self._covariance_energy
+    
+    @requires_state(AppState.JOINED)
+    def get_consensus_sequence_string(self):
+        """
+        Get the consensus sequence.
+
+        As the consensus may contain gaps, the sequence is returned as
+        string.
+
+        Returns
+        -------
+        consensus : str
+            The consensus sequence.
+        """
+        return self._consensus
+
+    @requires_state(AppState.JOINED)
+    def get_dot_bracket(self):
+        """
+        Get the consensus secondary structure in dot bracket notation.
+
+        Returns
+        -------
+        dotbracket : str
+            The secondary structure in dot bracket notation.
+        """
+        return self._dotbracket
+
+    @requires_state(AppState.JOINED)
+    def get_base_pairs(self, sequence_index=None):
+        """
+        Get the base pairs from the suggested secondary structure.
+
+        Parameters
+        ----------
+        sequence_index : int, optional
+            By default, the base pairs point to positions in the
+            alignment.
+            If `sequence_index` is set, the returned base pairs point to
+            positions in the given sequence, instead.
+            The sequence is specified as index in the alignment.
+            For example, if the alignment comprises three sequences,
+            `sequence_index` is in range 0-2.
+
+        Returns
+        -------
+        base_pairs : ndarray, shape=(n,2)
+            Each row corresponds to the positions of the bases in the
+            alignment.
+            If `sequence_index` is set, the positions correspond to the
+            given sequence.
+        """
+        base_pairs = base_pairs_from_dot_bracket(self._dotbracket)
+        if sequence_index is not None:
+            trace = self._alignment.trace[:, sequence_index]
+            # Map base pairs that point to consensus to base pairs that
+            # point to given sequence, which is only a subsequence
+            # (without gaps) of consensus sequence
+            # This is not trivial:
+            # The pairs that are not part of the subsequence must be
+            # removed and all other pairs need to be shifted
+            # To solve this problem a BondList is 'misused', since it
+            # is build to solve the same problem on the level of atoms
+            # Here the 'bonds' in the BondList are base pairs and the indices
+            # are base positions
+            pair_list = BondList(len(self._alignment), base_pairs)
+            # Remove all pairs that appear in gaps of given sequence
+            pair_list = pair_list[trace != -1]
+            # Convert back to array of base pairs,
+            # remove unused BondType column
+            base_pairs = pair_list.as_array()[:,:2]
+        return base_pairs
+
+    @staticmethod
+    def compute_secondary_structure(alignment, bin_path="RNAalifold"):
+        """
+        Predict the secondary structure of a ribonucleic acid sequence
+        using *ViennaRNA's* *RNAalifold* software.
+
+        This is a convenience function, that wraps the
+        :class:`RNAalifoldApp` execution.
+
+        Parameters
+        ----------
+        alignment : Alignment
+            An alignment of RNA sequences.
+        bin_path : str, optional
+            Path of the *RNAalifold* binary.
+
+        Returns
+        -------
+        dotbracket : str
+            The secondary structure in dot bracket notation.
+        free_energy : float
+            The free energy.
+        covariance_energy : float
+            The energy of the covariance term.
+        """
+
+        app = RNAalifoldApp(alignment, bin_path=bin_path)
+        app.start()
+        app.join()
+        return (
+            app.get_dot_bracket(),
+            app.get_free_energy(),
+            app.get_covariance_energy()
+        )