biotite 0.41.1__cp311-cp311-macosx_10_16_x86_64.whl

biotite/application/dssp/app.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.application.dssp"
+__author__ = "Patrick Kunzmann"
+__all__ = ["DsspApp"]
+
+from tempfile import NamedTemporaryFile
+from ..localapp import LocalApp, cleanup_tempfile
+from ..application import AppState, requires_state
+from ...structure.io.pdbx.cif import CIFFile
+from ...structure.io.pdbx.convert import set_structure
+import numpy as np
+
+
+class DsspApp(LocalApp):
+    r"""
+    Annotate the secondary structure of a protein structure using the
+    *DSSP* software.
+
+    Internally this creates a :class:`Popen` instance, which handles
+    the execution.
+
+    DSSP differentiates between 8 different types of secondary
+    structure elements:
+
+       - C: loop, coil or irregular
+       - H: :math:`{\alpha}`-helix
+       - B: :math:`{\beta}`-bridge
+       - E: extended strand, participation in :math:`{\beta}`-ladder
+       - G: 3 :sub:`10`-helix
+       - I: :math:`{\pi}`-helix
+       - T: hydrogen bonded turn
+       - S: bend
+
+    Parameters
+    ----------
+    atom_array : AtomArray
+        The atom array to be annotated.
+    bin_path : str, optional
+        Path of the *DDSP* binary.
+
+    Examples
+    --------
+
+    >>> app = DsspApp(atom_array)
+    >>> app.start()
+    >>> app.join()
+    >>> print(app.get_sse())
+    ['C' 'H' 'H' 'H' 'H' 'H' 'H' 'H' 'T' 'T' 'G' 'G' 'G' 'G' 'T' 'C' 'C' 'C'
+     'C' 'C']
+    """
+
+    def __init__(self, atom_array, bin_path="mkdssp"):
+        super().__init__(bin_path)
+
+        # mkdssp requires also the
+        # 'occupancy', 'b_factor' and 'charge' fields
+        # -> Add these annotations to a copy of the input structure
+        self._array = atom_array.copy()
+        categories = self._array.get_annotation_categories()
+        if "charge" not in categories:
+            self._array.set_annotation(
+                "charge", np.zeros(self._array.array_length(), dtype=int)
+            )
+        if "b_factor" not in categories:
+            self._array.set_annotation(
+                "b_factor", np.zeros(self._array.array_length(), dtype=float)
+            )
+        if "occupancy" not in categories:
+            self._array.set_annotation(
+                "occupancy", np.ones(self._array.array_length(), dtype=float)
+            )
+
+        self._in_file  = NamedTemporaryFile("w", suffix=".cif",  delete=False)
+        self._out_file = NamedTemporaryFile("r", suffix=".dssp", delete=False)
+
+    def run(self):
+        in_file = CIFFile()
+        set_structure(in_file, self._array)
+        in_file.write(self._in_file)
+        self._in_file.flush()
+        self.set_arguments(
+            ["-i", self._in_file.name, "-o", self._out_file.name]
+        )
+        super().run()
+
+    def evaluate(self):
+        super().evaluate()
+        lines = self._out_file.read().split("\n")
+        # Index where SSE records start
+        sse_start = None
+        for i, line in enumerate(lines):
+            if line.startswith("  #  RESIDUE AA STRUCTURE"):
+                sse_start = i+1
+        if sse_start is None:
+            raise ValueError("DSSP file does not contain SSE records")
+        # Remove "!" for missing residues
+        lines = [
+            line for line in lines[sse_start:]
+            if len(line) != 0 and line[13] != "!"
+        ]
+        self._sse = np.zeros(len(lines), dtype="U1")
+        # Parse file for SSE letters
+        for i, line in enumerate(lines):
+            self._sse[i] = line[16]
+        self._sse[self._sse == " "] = "C"
+
+    def clean_up(self):
+        super().clean_up()
+        cleanup_tempfile(self._in_file)
+        cleanup_tempfile(self._out_file)
+
+    @requires_state(AppState.JOINED)
+    def get_sse(self):
+        """
+        Get the resulting secondary structure assignment.
+
+        Returns
+        -------
+        sse : ndarray, dtype="U1"
+            An array containing DSSP secondary structure symbols
+            corresponding to the residues in the input atom array.
+        """
+        return self._sse
+
+    @staticmethod
+    def annotate_sse(atom_array, bin_path="mkdssp"):
+        """
+        Perform a secondary structure assignment to an atom array.
+
+        This is a convenience function, that wraps the :class:`DsspApp`
+        execution.
+
+        Parameters
+        ----------
+        atom_array : AtomArray
+            The atom array to be annotated.
+        bin_path : str, optional
+            Path of the DDSP binary.
+
+        Returns
+        -------
+        sse : ndarray, dtype="U1"
+            An array containing DSSP secondary structure symbols
+            corresponding to the residues in the input atom array.
+        """
+        app = DsspApp(atom_array, bin_path)
+        app.start()
+        app.join()
+        return app.get_sse()

biotite/application/localapp.py

@@ -0,0 +1,306 @@
+# 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__ = ["LocalApp"]
+
+import abc
+import copy
+from os import chdir, getcwd, remove
+from .application import Application, AppState, AppStateError, requires_state
+from subprocess import Popen, PIPE, SubprocessError, TimeoutExpired
+
+class LocalApp(Application, metaclass=abc.ABCMeta):
+    """
+    The base class for all locally installed applications, that are used
+    via the command line.
+    
+    Internally this creates a :class:`Popen` instance, which handles
+    the execution.
+    
+    Parameters
+    ----------
+    bin_path : str
+        Path of the application represented by this class.
+    """
+    
+    def __init__(self, bin_path):
+        super().__init__()
+        self._bin_path = bin_path
+        self._arguments = []
+        self._options = []
+        self._exec_dir = getcwd()
+        self._process = None
+        self._command = None
+        self._stdin_file = None
+    
+    @requires_state(AppState.CREATED)
+    def set_arguments(self, arguments):
+        """
+        Set command line arguments for the application run.
+        
+        PROTECTED: Do not call from outside.
+        
+        Parameters
+        ----------
+        arguments : list of str
+            A list of strings representing the command line options.
+        """
+        self._arguments = copy.copy(arguments)
+    
+    @requires_state(AppState.CREATED)
+    def set_stdin(self, file):
+        """
+        Set a file as standard input for the application run.
+        
+        PROTECTED: Do not call from outside.
+        
+        Parameters
+        ----------
+        file : file object
+            The file for the standard input.
+            Must have a valid file descriptor, e.g. file-like objects
+            such as `StringIO` are invalid.
+        """
+        self._stdin_file = file
+    
+    @requires_state(AppState.CREATED)
+    def add_additional_options(self, options):
+        """
+        Add additional options for the command line program.
+        These options are put before the arguments automatically
+        determined by the respective :class:`LocalApp` subclass.
+
+        This method is focused on advanced users, who have knowledge on
+        the available options of the command line program and the
+        options already used by the :class:`LocalApp` subclasses.
+        Ignoring the already used options may result in conflicting
+        CLI arguments and potential unexpected results.
+        It is recommended to use this method only, when the respective
+        :class:`LocalApp` subclass does not provide a method to set the
+        desired option.
+        
+        Parameters
+        ----------
+        options : list of str
+            A list of strings representing the command line options.
+        
+        Notes
+        -----
+        In order to see which options the command line execution used,
+        try the :meth:`get_command()` method.
+
+        Examples
+        --------
+
+        >>> seq1 = ProteinSequence("BIQTITE")
+        >>> seq2 = ProteinSequence("TITANITE")
+        >>> seq3 = ProteinSequence("BISMITE")
+        >>> seq4 = ProteinSequence("IQLITE")
+        >>> # Run application without additional arguments
+        >>> app = ClustalOmegaApp([seq1, seq2, seq3, seq4])
+        >>> app.start()
+        >>> app.join()
+        >>> print(app.get_command())
+        clustalo --in ...fa --out ...fa --force --output-order=tree-order --seqtype Protein --guidetree-out ...tree
+        >>> # Run application with additional argument
+        >>> app = ClustalOmegaApp([seq1, seq2, seq3, seq4])
+        >>> app.add_additional_options(["--full"])
+        >>> app.start()
+        >>> app.join()
+        >>> print(app.get_command())
+        clustalo --full --in ...fa --out ...fa --force --output-order=tree-order --seqtype Protein --guidetree-out ...tree
+        """
+        self._options += options
+    
+    @requires_state(
+        AppState.RUNNING | \
+        AppState.CANCELLED | \
+        AppState.FINISHED | \
+        AppState.JOINED
+    )
+    def get_command(self):
+        """
+        Get the executed command.
+
+        Cannot be called until the application has been started.
+        
+        Returns
+        -------
+        command : str
+            The executed command.
+        
+        Examples
+        --------
+        
+        >>> seq1 = ProteinSequence("BIQTITE")
+        >>> seq2 = ProteinSequence("TITANITE")
+        >>> seq3 = ProteinSequence("BISMITE")
+        >>> seq4 = ProteinSequence("IQLITE")
+        >>> app = ClustalOmegaApp([seq1, seq2, seq3, seq4])
+        >>> app.start()
+        >>> print(app.get_command())
+        clustalo --in ...fa --out ...fa --force --output-order=tree-order --seqtype Protein --guidetree-out ...tree
+        """
+        return " ".join(self._command)
+
+    
+    @requires_state(AppState.CREATED)
+    def set_exec_dir(self, exec_dir):
+        """
+        Set the directory where the application should be executed.
+        If not set, it will be executed in the working directory at the
+        time the application was created. 
+        
+        PROTECTED: Do not call from outside.
+        
+        Parameters
+        ----------
+        exec_dir : str
+            The execution directory.
+        """
+        self._exec_dir = exec_dir
+    
+    @requires_state(AppState.RUNNING | AppState.FINISHED)
+    def get_process(self):
+        """
+        Get the `Popen` instance.
+        
+        PROTECTED: Do not call from outside.
+        
+        Returns
+        -------
+        process : Popen
+            The `Popen` instance
+        """
+        return self._process
+    
+    @requires_state(AppState.FINISHED | AppState.JOINED)
+    def get_exit_code(self):
+        """
+        Get the exit code of the process.
+        
+        PROTECTED: Do not call from outside.
+        
+        Returns
+        -------
+        code : int
+            The exit code.
+        """
+        return self._process.returncode
+    
+    @requires_state(AppState.FINISHED | AppState.JOINED)
+    def get_stdout(self):
+        """
+        Get the STDOUT pipe content of the process.
+        
+        PROTECTED: Do not call from outside.
+        
+        Returns
+        -------
+        stdout : str
+            The standard output.
+        """
+        return self._stdout
+    
+    @requires_state(AppState.FINISHED | AppState.JOINED)
+    def get_stderr(self):
+        """
+        Get the STDERR pipe content of the process.
+        
+        PROTECTED: Do not call from outside.
+        
+        Returns
+        -------
+        stdout : str
+            The standard error.
+        """
+        return self._stderr
+
+    def run(self):
+        cwd = getcwd()
+        chdir(self._exec_dir) 
+        self._command = [self._bin_path] + self._options + self._arguments
+        self._process = Popen(
+            self._command, stdin=self._stdin_file, stdout=PIPE, stderr=PIPE,
+            encoding="UTF-8"
+        )
+        chdir(cwd)
+    
+    def is_finished(self):
+        code = self._process.poll()
+        if code == None:
+            return False
+        else:
+            self._stdout, self._stderr = self._process.communicate()
+            return True
+    
+    @requires_state(AppState.RUNNING | AppState.FINISHED)
+    def join(self, timeout=None):
+        # Override method as repetitive calls of 'is_finished()'
+        # are not necessary as 'communicate()' already waits for the
+        # finished application
+        try:
+            self._stdout, self._stderr = self._process.communicate(
+                timeout=timeout
+            )
+        except TimeoutExpired:
+            self.cancel()
+            raise TimeoutError(
+                f"The application expired its timeout ({timeout:.1f} s)"
+            )
+        self._state = AppState.FINISHED
+        
+        try:
+            self.evaluate()
+        except AppStateError:
+            raise
+        except:
+            self._state = AppState.CANCELLED
+            raise
+        else:
+            self._state = AppState.JOINED
+        self.clean_up()
+    
+    
+    def wait_interval(self):
+        # Not used in this implementation of 'join()'
+        raise NotImplementedError()
+    
+    def evaluate(self):
+        super().evaluate()
+        # Check if applicaion terminated correctly
+        exit_code = self.get_exit_code()
+        if exit_code != 0:
+            err_msg = self.get_stderr().replace("\n", " ")
+            raise SubprocessError(
+                f"'{self._bin_path}' returned with exit code {exit_code}: "
+                f"{err_msg}"
+            )
+    
+    def clean_up(self):
+        if self.get_app_state() == AppState.CANCELLED:
+            self._process.kill()
+
+
+def cleanup_tempfile(temp_file):
+    """
+    Close a :class:`NamedTemporaryFile` and delete it manually,
+    if `delete` is set to ``False``.
+    This function is a small helper function intended for usage in
+    `LocalApp` subclasses. 
+
+    The manual deletion is necessary, as Windows does not allow to open
+    a :class:`NamedTemporaryFile` as second time
+    (e.g. by the file name), if `delete` is set to ``True``.
+
+    Parameters
+    ----------
+    temp_file : NamedTemporaryFile
+        The temporary file to be closed and deleted.
+    """
+    temp_file.close()
+    if not temp_file.delete:
+        remove(temp_file.name)

biotite/application/mafft/__init__.py

@@ -0,0 +1,12 @@
+# 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 multiple sequence alignments using MAFFT.
+"""
+
+__name__ = "biotite.application.mafft"
+__author__ = "Patrick Kunzmann"
+
+from .app import *

biotite/application/mafft/app.py

@@ -0,0 +1,122 @@
+# 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.mafft"
+__author__ = "Patrick Kunzmann"
+__all__ = ["MafftApp"]
+
+import re
+import os
+from ..msaapp import MSAApp
+from ..application import AppState, requires_state
+from ...sequence.sequence import Sequence
+from ...sequence.seqtypes import NucleotideSequence, ProteinSequence
+from ...sequence.io.fasta.file import FastaFile
+from ...sequence.align.alignment import Alignment
+from ...sequence.phylo.tree import Tree
+
+
+_prefix_pattern = re.compile(r"\d*_")
+
+
+
+class MafftApp(MSAApp):
+    """
+    Perform a multiple sequence alignment using MAFFT.
+    
+    Parameters
+    ----------
+    sequences : list of Sequence
+        The sequences to be aligned.
+    bin_path : str, optional
+        Path of the MUSCLE binary.
+    matrix : SubstitutionMatrix, optional
+        A custom substitution matrix.
+    
+    Examples
+    --------
+
+    >>> seq1 = ProteinSequence("BIQTITE")
+    >>> seq2 = ProteinSequence("TITANITE")
+    >>> seq3 = ProteinSequence("BISMITE")
+    >>> seq4 = ProteinSequence("IQLITE")
+    >>> app = MafftApp([seq1, seq2, seq3, seq4])
+    >>> app.start()
+    >>> app.join()
+    >>> alignment = app.get_alignment()
+    >>> print(alignment)
+    -BIQTITE
+    TITANITE
+    -BISMITE
+    --IQLITE
+    """
+    
+    def __init__(self, sequences, bin_path="mafft", matrix=None):
+        super().__init__(sequences, bin_path, matrix)
+        self._tree = None
+        self._out_tree_file_name = self.get_input_file_path() + ".tree"
+    
+    def run(self):
+        args = [
+            "--quiet",
+            "--auto",
+            "--treeout",
+            # Get the reordered alignment in order for
+            # get_alignment_order() to work properly 
+            "--reorder",
+        ]
+        if self.get_seqtype() == "protein":
+            args += ["--amino"]
+        else:
+            args += ["--nuc"]
+        if self.get_matrix_file_path() is not None:
+            args += ["--aamatrix", self.get_matrix_file_path()]
+        args += [self.get_input_file_path()]
+        self.set_arguments(args)
+        super().run()
+    
+    def evaluate(self):
+        with open(self.get_output_file_path(), "w") as f:
+            # MAFFT outputs alignment to stdout
+            # -> write stdout to output file name
+            f.write(self.get_stdout())
+        super().evaluate()
+        with open(self._out_tree_file_name, "r") as file:
+            raw_newick = file.read().replace("\n", "")
+            # Mafft uses sequences label in the form '<n>_<seqname>'
+            # Only the <seqname> is required
+            # -> remove the '<n>_' prefix
+            newick = re.sub(_prefix_pattern, "", raw_newick)
+            self._tree = Tree.from_newick(newick)
+    
+    def clean_up(self):
+        os.remove(self._out_tree_file_name)
+
+    @requires_state(AppState.JOINED)
+    def get_guide_tree(self):
+        """
+        Get the guide tree created for the progressive alignment.
+        
+        Returns
+        -------
+        tree : Tree
+            The guide tree.
+        """
+        return self._tree
+    
+    @staticmethod
+    def supports_nucleotide():
+        return True
+    
+    @staticmethod
+    def supports_protein():
+        return True
+    
+    @staticmethod
+    def supports_custom_nucleotide_matrix():
+        return True
+    
+    @staticmethod
+    def supports_custom_protein_matrix():
+        return True