biotite 1.5.0__cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

biotite/application/dssp/app.py

@@ -0,0 +1,216 @@
+# 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 subprocess import SubprocessError
+from tempfile import NamedTemporaryFile
+import numpy as np
+from biotite.application.application import AppState, requires_state
+from biotite.application.localapp import LocalApp, cleanup_tempfile, get_version
+from biotite.structure.error import BadStructureError
+from biotite.structure.filter import filter_amino_acids
+from biotite.structure.io.pdbx.cif import CIFCategory, CIFColumn, CIFFile
+from biotite.structure.io.pdbx.component import MaskValue
+from biotite.structure.io.pdbx.convert import set_structure
+from biotite.structure.repair import create_continuous_res_ids
+from biotite.structure.residues import get_residue_starts
+
+
+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' 'P' 'P'
+     'P' 'C']
+    """
+
+    def __init__(self, atom_array, bin_path="mkdssp"):
+        super().__init__(bin_path)
+
+        if not np.all(filter_amino_acids(atom_array)):
+            raise BadStructureError("The input structure must contain only amino acids")
+        self._array = atom_array.copy()
+        # DSSP requires also the
+        # 'occupancy', 'b_factor' and 'charge' fields
+        # -> Add these placeholder values
+        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)
+            )
+        # DSSP>=4 complains about the `pdbx_poly_seq_scheme` category,
+        # if `seq_id` does not start at 1
+        self._array.res_id = create_continuous_res_ids(self._array)
+
+        try:
+            # The parameters have changed in version 4
+            self._new_cli = get_version(bin_path)[0] >= 4
+        except SubprocessError:
+            # In older versions, the no version is returned with `--version`
+            # -> a SubprocessError is raised
+            self._new_cli = False
+        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.block["pdbx_poly_seq_scheme"] = _create_pdbx_poly_seq_scheme(
+            self._array, in_file.block["atom_site"]["label_entity_id"].as_array(str)
+        )
+        in_file.write(self._in_file)
+        self._in_file.flush()
+        if self._new_cli:
+            self.set_arguments([self._in_file.name, self._out_file.name])
+        else:
+            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()
+
+
+def _create_pdbx_poly_seq_scheme(atom_array, entity_ids):
+    """
+    Create the ``pdbx_poly_seq_scheme`` category, as required by DSSP.
+
+    Parameters
+    ----------
+    atom_array : AtomArray
+        The atom array to create the category from.
+    entity_ids : ndarray, dtype=str
+        The entity IDs for each atoms.
+
+    Returns
+    -------
+    pdbx_poly_seq_scheme : CIFCategory
+        The ``pdbx_poly_seq_scheme`` category.
+    """
+    res_start_indices = get_residue_starts(atom_array)
+    chain_id = atom_array.chain_id[res_start_indices]
+    res_name = atom_array.res_name[res_start_indices]
+    res_id = atom_array.res_id[res_start_indices]
+    ins_code = atom_array.ins_code[res_start_indices]
+    hetero = atom_array.hetero[res_start_indices]
+    entity_id = entity_ids[res_start_indices]
+
+    poly_seq_scheme = CIFCategory()
+    poly_seq_scheme["asym_id"] = chain_id
+    poly_seq_scheme["entity_id"] = entity_id
+    poly_seq_scheme["seq_id"] = res_id
+    poly_seq_scheme["mon_id"] = res_name
+    poly_seq_scheme["ndb_seq_num"] = res_id
+    poly_seq_scheme["pdb_seq_num"] = res_id
+    poly_seq_scheme["auth_seq_num"] = res_id
+    poly_seq_scheme["pdb_mon_id"] = res_name
+    poly_seq_scheme["auth_mon_id"] = res_name
+    poly_seq_scheme["pdb_strand_id"] = chain_id
+    poly_seq_scheme["pdb_ins_code"] = CIFColumn(
+        ins_code, np.where(ins_code == "", MaskValue.MISSING, MaskValue.PRESENT)
+    )
+    poly_seq_scheme["hetero"] = np.where(hetero, "y", "n")
+
+    return poly_seq_scheme

biotite/application/localapp.py

@@ -0,0 +1,342 @@
+# 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
+import re
+import subprocess
+from os import chdir, getcwd, remove
+from pathlib import Path
+from subprocess import PIPE, Popen, SubprocessError, TimeoutExpired
+from biotite.application.application import (
+    Application,
+    AppState,
+    AppStateError,
+    requires_state,
+)
+
+
+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 is 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}: {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()
+    try:
+        remove(temp_file.name)
+    except FileNotFoundError:
+        # File was already deleted, e.g. due to `TemporaryFile(delete=True)`
+        pass
+
+
+def get_version(bin_path, version_option="--version"):
+    """
+    Get the version of a locally installed application.
+
+    Parameters
+    ----------
+    bin_path : str or Path
+        Path of the application.
+    version_option : str, optional
+        The command line option to get the version.
+
+    Returns
+    -------
+    major, minor : int
+        The major and minor version number.
+    """
+    output = subprocess.run(
+        [bin_path, version_option], capture_output=True, text=True
+    ).stdout
+    # Find matches for version string containing major and minor version
+    match = re.search(r"\d+\.\d+", output)
+    if match is None:
+        raise subprocess.SubprocessError(
+            f"Could not determine '{Path(bin_path).name}' version "
+            f"from the string '{output}'"
+        )
+    version_string = match.group(0)
+    splitted = version_string.split(".")
+    return int(splitted[0]), int(splitted[1])

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,116 @@
+# 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 os
+import re
+from biotite.application.application import AppState, requires_state
+from biotite.application.msaapp import MSAApp
+from biotite.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