biotite 1.5.0__cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

biotite/sequence/io/__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 reading and writing sequence related data.
+"""
+
+__name__ = "biotite.sequence.io"
+__author__ = "Patrick Kunzmann"
+
+from .general import *

biotite/sequence/io/fasta/__init__.py

@@ -0,0 +1,22 @@
+# 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 subpackage is used for reading and writing sequence objects
+using the popular FASTA format.
+
+This package contains the :class:`FastaFile`, which provides a
+dictionary like interface to FASTA files, where the header lines are
+keys and the strings containing sequence data are the corresponding
+values.
+
+Furthermore, the package contains convenience functions for
+getting/setting directly :class:`Sequence` objects, rather than strings.
+"""
+
+__name__ = "biotite.sequence.io.fasta"
+__author__ = "Patrick Kunzmann"
+
+from .convert import *
+from .file import *

biotite/sequence/io/fasta/convert.py

@@ -0,0 +1,283 @@
+# 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.sequence.io.fasta"
+__author__ = "Patrick Kunzmann"
+
+import warnings
+from collections import OrderedDict
+from biotite.sequence.align.alignment import Alignment
+from biotite.sequence.alphabet import AlphabetError, LetterAlphabet
+from biotite.sequence.seqtypes import NucleotideSequence, ProteinSequence
+
+__all__ = [
+    "get_sequence",
+    "get_sequences",
+    "set_sequence",
+    "set_sequences",
+    "get_alignment",
+    "set_alignment",
+]
+
+
+def get_sequence(fasta_file, header=None, seq_type=None):
+    """
+    Get a sequence from a :class:`FastaFile` instance.
+
+    The type of sequence is guessed from the sequence string:
+    First, a conversion into a :class:`NucleotideSequence` and
+    second a conversion into a :class:`ProteinSequence` is tried.
+
+    Parameters
+    ----------
+    fasta_file : FastaFile
+        The :class:`FastaFile` to be accessed.
+    header : str, optional
+        The header to get the sequence from. By default, the first
+        sequence of the file is returned.
+    seq_type : Class, optional
+        The :class:`Sequence` subclass contained in the file. If not
+        set, biotite will attempt to automatically detect whether a
+        nucleotide or protein sequence is present.
+
+    Returns
+    -------
+    sequence : NucleotideSequence or ProteinSequence
+        The requested sequence in the `FastaFile`.
+        :class:`NucleotideSequence` if the sequence string fits the
+        corresponding alphabet, :class:`ProteinSequence` otherwise.
+
+    Raises
+    ------
+    ValueError
+        If the sequence data can be neither converted into a
+        :class:`NucleotideSequence` nor a :class:`ProteinSequence`.
+    """
+    if header is not None:
+        seq_str = fasta_file[header]
+    else:
+        # Return first (and probably only) sequence of file
+        seq_str = None
+        for seq_str in fasta_file.values():
+            break
+        if seq_str is None:
+            raise ValueError("File does not contain any sequences")
+    # Determine the sequence type:
+    # If NucleotideSequence can be created it is a DNA sequence,
+    # otherwise protein sequence
+    return _convert_to_sequence(seq_str, seq_type)
+
+
+def get_sequences(fasta_file, seq_type=None):
+    """
+    Get dictionary from a :class:`FastaFile` instance,
+    where headers are keys and sequences are values.
+
+    The type of sequence is guessed from the sequence string:
+    First, a conversion into a :class:`NucleotideSequence` and
+    second a conversion into a :class:`ProteinSequence` is tried.
+
+    Parameters
+    ----------
+    fasta_file : FastaFile
+        The :class:`FastaFile` to be accessed.
+    seq_type : Class, optional
+        The :class:`Sequence` subclass contained in the file. If not
+        set, biotite will attempt to automatically detect whether a
+        nucleotide or protein sequence is present.
+
+    Returns
+    -------
+    seq_dict : dict
+        A dictionary that maps headers to
+        :class:`NucleotideSequence` and/or :class:`ProteinSequence`
+        instances as values.
+
+    Raises
+    ------
+    ValueError
+        If at least on of the sequence strings can be neither converted
+        into a :class:`NucleotideSequence` nor a
+        :class:`ProteinSequence`.
+    """
+    seq_dict = OrderedDict()
+    for header, seq_str in fasta_file.items():
+        seq_dict[header] = _convert_to_sequence(seq_str, seq_type)
+    return seq_dict
+
+
+def set_sequence(fasta_file, sequence, header=None, as_rna=False):
+    """
+    Set a sequence in a :class:`FastaFile` instance.
+
+    Parameters
+    ----------
+    fasta_file : FastaFile
+        The :class:`FastaFile` to be accessed.
+    sequence : Sequence
+        The sequence to be set.
+    header : str, optional
+        The header for the sequence. Default is ``'sequence'``.
+    as_rna : bool, optional
+        If set to true, ``'T'`` will be replaced by ``'U'``,
+        if a :class:`NucleotideSequence` was given.
+
+    Raises
+    ------
+    ValueError
+        If the sequence's alphabet uses symbols other than single
+        characters.
+    """
+    if header is None:
+        header = "sequence"
+    fasta_file[header] = _convert_to_string(sequence, as_rna)
+
+
+def set_sequences(fasta_file, sequence_dict, as_rna=False):
+    """
+    Set sequences in a :class:`FastaFile` instance from a dictionary.
+
+    Parameters
+    ----------
+    fasta_file : FastaFile
+        The :class:`FastaFile` to be accessed.
+    sequence_dict : dict
+        A dictionary containing the sequences to be set.
+        Header are keys, :class:`Sequence` instances are values.
+    as_rna : bool, optional
+        If set to true, ``'T'`` will be replaced by ``'U'``,
+        if a :class:`NucleotideSequence` was given.
+
+    Raises
+    ------
+    ValueError
+        If the sequences alphabets uses symbols other than single
+        characters.
+    """
+    for header, sequence in sequence_dict.items():
+        fasta_file[header] = _convert_to_string(sequence, as_rna)
+
+
+def get_alignment(fasta_file, additional_gap_chars=("_",), seq_type=None):
+    """
+    Get an alignment from a :class:`FastaFile` instance.
+
+    Parameters
+    ----------
+    fasta_file : FastaFile
+        The :class:`FastaFile` to be accessed.
+    additional_gap_chars : str, optional
+        The characters to be treated as gaps.
+    seq_type : Class, optional
+        The :class:`Sequence` subclass contained in the file. If not
+        set, biotite will attempt to automatically detect whether a
+        nucleotide or protein sequence is present.
+
+    Returns
+    -------
+    alignment : Alignment
+        The alignment from the :class:`FastaFile`.
+    """
+    seq_strings = list(fasta_file.values())
+    # Replace additional gap symbols with default gap symbol ('-')
+    for char in additional_gap_chars:
+        for i, seq_str in enumerate(seq_strings):
+            seq_strings[i] = seq_str.replace(char, "-")
+    # Remove gaps for creation of sequences
+    sequences = [
+        _convert_to_sequence(seq_str.replace("-", ""), seq_type)
+        for seq_str in seq_strings
+    ]
+    trace = Alignment.trace_from_strings(seq_strings)
+    return Alignment(sequences, trace, score=None)
+
+
+def set_alignment(fasta_file, alignment, seq_names):
+    """
+    Fill a :class:`FastaFile` with gapped sequence strings from an
+    alignment.
+
+    Parameters
+    ----------
+    fasta_file : FastaFile
+        The :class:`FastaFile` to be accessed.
+    alignment : Alignment
+        The alignment to be set.
+    seq_names : iterable object of str
+        The names for the sequences in the alignment.
+        Must have the same length as the sequence count in `alignment`.
+    """
+    gapped_seq_strings = alignment.get_gapped_sequences()
+    if len(gapped_seq_strings) != len(seq_names):
+        raise ValueError(
+            f"Alignment has {len(gapped_seq_strings)} sequences, "
+            f"but {len(seq_names)} names were given"
+        )
+    for i in range(len(gapped_seq_strings)):
+        fasta_file[seq_names[i]] = gapped_seq_strings[i]
+
+
+def _convert_to_sequence(seq_str, seq_type=None):
+    # Set manually selected sequence type
+    if seq_type is not None:
+        # Do preprocessing as done without manual selection
+        if seq_type == NucleotideSequence:
+            seq_str = _process_nucleotide_sequence(seq_str)
+        elif seq_type == ProteinSequence:
+            if "U" in seq_str:
+                warnings.warn(
+                    "ProteinSequence objects do not support selenocysteine "
+                    "(U), occurrences were substituted by cysteine (C)"
+                )
+            seq_str = _process_protein_sequence(seq_str)
+        # Return the converted sequence
+        return seq_type(seq_str)
+
+    # Attempt to automatically determine sequence type
+
+    try:
+        return NucleotideSequence(_process_nucleotide_sequence(seq_str))
+    except AlphabetError:
+        pass
+    try:
+        prot_seq = ProteinSequence(_process_protein_sequence(seq_str))
+        # Raise Warning after conversion into 'ProteinSequence'
+        # to wait for potential 'AlphabetError'
+        if "U" in seq_str:
+            warnings.warn(
+                "ProteinSequence objects do not support selenocysteine (U), "
+                "occurrences were substituted by cysteine (C)"
+            )
+        return prot_seq
+    except AlphabetError:
+        raise ValueError(
+            "FASTA data cannot be converted either to "
+            "'NucleotideSequence' nor to 'ProteinSequence'"
+        )
+
+
+def _process_protein_sequence(x):
+    """
+    Replace selenocysteine with cysteine and pyrrolysine with lysine.
+    """
+    return x.upper().replace("U", "C").replace("O", "K")
+
+
+def _process_nucleotide_sequence(x):
+    """
+    For nucleotides uracil is represented by thymine and there is only
+    one letter for completely unknown nucleotides
+    """
+    return x.upper().replace("U", "T").replace("X", "N")
+
+
+def _convert_to_string(sequence, as_rna):
+    if not isinstance(sequence.get_alphabet(), LetterAlphabet):
+        raise ValueError(
+            "Only sequences using single letter alphabets can be stored in a FASTA file"
+        )
+    if isinstance(sequence, NucleotideSequence) and as_rna:
+        return str(sequence).replace("T", "U")
+    else:
+        return str(sequence)

biotite/sequence/io/fasta/file.py

@@ -0,0 +1,265 @@
+# 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.sequence.io.fasta"
+__author__ = "Patrick Kunzmann"
+__all__ = ["FastaFile"]
+
+from collections import OrderedDict
+from collections.abc import MutableMapping
+from biotite.file import InvalidFileError, TextFile, wrap_string
+
+
+class FastaFile(TextFile, MutableMapping):
+    """
+    This class represents a file in FASTA format.
+
+    A FASTA file contains so called *header* lines, beginning with
+    ``>``, that describe following sequence.
+    The corresponding sequence starts at the line after the header line
+    and ends at the next header line or at the end of file.
+    The header along with its sequence forms an entry.
+
+    This class is used in a dictionary like manner, implementing the
+    :class:`MutableMapping` interface:
+    Headers (without the leading ``>``) are used as keys,
+    and strings containing the sequences are the corresponding values.
+    Entries can be accessed using indexing,
+    ``del`` deletes the entry at the given index.
+
+    Parameters
+    ----------
+    chars_per_line : int, optional
+        The number characters in a line containing sequence data
+        after which a line break is inserted.
+        Only relevant, when adding sequences to a file.
+        Default is 80.
+
+    Examples
+    --------
+
+    >>> import os.path
+    >>> file = FastaFile()
+    >>> file["seq1"] = "ATACT"
+    >>> print(file["seq1"])
+    ATACT
+    >>> file["seq2"] = "AAAATT"
+    >>> print(file)
+    >seq1
+    ATACT
+    >seq2
+    AAAATT
+    >>> print(dict(file.items()))
+    {'seq1': 'ATACT', 'seq2': 'AAAATT'}
+    >>> for header, seq in file.items():
+    ...     print(header, seq)
+    seq1 ATACT
+    seq2 AAAATT
+    >>> del file["seq1"]
+    >>> print(dict(file.items()))
+    {'seq2': 'AAAATT'}
+    >>> file.write(os.path.join(path_to_directory, "test.fasta"))
+    """
+
+    def __init__(self, chars_per_line=80):
+        super().__init__()
+        self._chars_per_line = chars_per_line
+        self._entries = OrderedDict()
+
+    @classmethod
+    def read(cls, file, chars_per_line=80):
+        """
+        Read a FASTA file.
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be read.
+            Alternatively a file path can be supplied.
+        chars_per_line : int, optional
+            The number characters in a line containing sequence data
+            after which a line break is inserted.
+            Only relevant, when adding sequences to a file.
+            Default is 80.
+
+        Returns
+        -------
+        file_object : FastaFile
+            The parsed file.
+        """
+        file = super().read(file, chars_per_line)
+        # Filter out empty and comment lines
+        file.lines = [
+            line for line in file.lines if len(line.strip()) != 0 and line[0] != ";"
+        ]
+        if len(file.lines) == 0:
+            raise InvalidFileError("File is empty or contains only comments")
+        file._find_entries()
+        return file
+
+    def __setitem__(self, header, seq_str):
+        if not isinstance(header, str):
+            raise IndexError("'FastaFile' only supports header strings as keys")
+        if not isinstance(seq_str, str):
+            raise TypeError("'FastaFile' only supports sequence strings as values")
+        # Create lines for new header and sequence (with line breaks)
+        new_lines = [">" + header.replace("\n", "").strip()] + wrap_string(
+            seq_str, width=self._chars_per_line
+        )
+        if header in self:
+            # Delete lines of entry corresponding to the header,
+            # if existing
+            del self[header]
+            self.lines += new_lines
+            self._find_entries()
+        else:
+            # Simply append lines
+            # Add entry in a more efficient way than '_find_entries()'
+            # for this simple case
+            self._entries[header] = (len(self.lines), len(self.lines) + len(new_lines))
+            self.lines += new_lines
+
+    def __getitem__(self, header):
+        if not isinstance(header, str):
+            raise IndexError("'FastaFile' only supports header strings as keys")
+        start, stop = self._entries[header]
+        # Concatenate sequence string from following lines
+        seq_string = "".join([line.strip() for line in self.lines[start + 1 : stop]])
+        return seq_string
+
+    def __delitem__(self, header):
+        start, stop = self._entries[header]
+        del self.lines[start:stop]
+        del self._entries[header]
+        self._find_entries()
+
+    def __len__(self):
+        return len(self._entries)
+
+    def __iter__(self):
+        return self._entries.__iter__()
+
+    def __contains__(self, identifer):
+        return identifer in self._entries
+
+    def _find_entries(self):
+        if len(self.lines) > 0 and self.lines[0][0] != ">":
+            raise InvalidFileError(
+                f"File starts with '{self.lines[0][0]}' instead of '>'"
+            )
+
+        header_i = []
+        for i, line in enumerate(self.lines):
+            if line[0] == ">":
+                header_i.append(i)
+
+        self._entries = OrderedDict()
+        for j in range(len(header_i)):
+            # Remove leading '>' from header
+            header = self.lines[header_i[j]].strip()[1:]
+            start = header_i[j]
+            if j < len(header_i) - 1:
+                # Header in mid or start of file
+                # -> stop is start of next header
+                stop = header_i[j + 1]
+            else:
+                # Last header -> entry stops at end of file
+                stop = len(self.lines)
+            self._entries[header] = (start, stop)
+
+    @staticmethod
+    def read_iter(file):
+        """
+        Create an iterator over each sequence of the given FASTA file.
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be read.
+            Alternatively a file path can be supplied.
+
+        Yields
+        ------
+        header : str
+            The header of the current sequence.
+        seq_str : str
+            The current sequence as string.
+
+        Notes
+        -----
+        This approach gives the same results as
+        `FastaFile.read(file).items()`, but is slightly faster and much
+        more memory efficient.
+        """
+        header = None
+        seq_str_list = []
+        for line in TextFile.read_iter(file):
+            line = line.strip()
+            # Ignore empty and comment lines
+            if len(line) == 0 or line[0] == ";":
+                continue
+            if line[0] == ">":
+                # New entry
+                # -> yield previous entry
+                if header is not None:
+                    yield header, "".join(seq_str_list)
+                # Track new header and reset sequence
+                header = line[1:]
+                seq_str_list = []
+            else:
+                seq_str_list.append(line)
+        # Yield final entry
+        if header is not None:
+            yield header, "".join(seq_str_list)
+
+    @staticmethod
+    def write_iter(file, items, chars_per_line=80):
+        """
+        Iterate over the given `items` and write each item into
+        the specified `file`.
+
+        In contrast to :meth:`write()`, the lines of text are not stored
+        in an intermediate :class:`TextFile`, but are directly written
+        to the file.
+        Hence, this static method may save a large amount of memory if
+        a large file should be written, especially if the `items`
+        are provided as generator.
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be written to.
+            Alternatively a file path can be supplied.
+        items : generator or array-like of tuple(str, str)
+            The entries to be written into the file.
+            Each entry consists of an header string and a sequence
+            string.
+        chars_per_line : int, optional
+            The number characters in a line containing sequence data
+            after which a line break is inserted.
+            Only relevant, when adding sequences to a file.
+            Default is 80.
+
+        Notes
+        -----
+        This method does not test, whether the given identifiers are
+        unambiguous.
+        """
+
+        def line_generator():
+            for item in items:
+                header, seq_str = item
+                if not isinstance(header, str):
+                    raise IndexError("'FastaFile' only supports header strings")
+                if not isinstance(seq_str, str):
+                    raise TypeError("'FastaFile' only supports sequence strings")
+
+                # Yield header line
+                yield ">" + header.replace("\n", "").strip()
+
+                # Yield sequence line(s)
+                for line in wrap_string(seq_str, width=chars_per_line):
+                    yield line
+
+        TextFile.write_iter(file, line_generator())

biotite/sequence/io/fastq/__init__.py

@@ -0,0 +1,19 @@
+# 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 subpackage is used for reading and writing sequencing data
+using the popular FASTQ format.
+
+This package contains the :class:`FastqFile`, which provides a
+dictionary like interface to FASTQ files, with the sequence identifer
+strings being the keys and the sequences and quality scores being the
+values.
+"""
+
+__name__ = "biotite.sequence.io.fastq"
+__author__ = "Patrick Kunzmann"
+
+from .convert import *
+from .file import *