biotite 0.41.1__cp312-cp312-macosx_10_16_arm64.whl

biotite/sequence/io/fasta/convert.py

@@ -0,0 +1,273 @@
+# 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 ...sequence import Sequence
+from ...alphabet import AlphabetError, LetterAlphabet
+from ...seqtypes import NucleotideSequence, ProteinSequence
+from ...align.alignment import Alignment
+
+__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):
+
+    # Define preprocessing of preimplemented sequence types
+
+    # Replace selenocysteine with cysteine
+    # and pyrrolysine with lysine
+    process_protein_sequence = (
+        lambda x : x.upper().replace("U", "C").replace("O", "K")
+    )
+    # For nucleotides uracil is represented by thymine and there is only
+    # one letter for completely unknown nucleotides
+    process_nucleotide_sequence = (
+        lambda x : x.upper().replace("U","T").replace("X","N")
+    )
+
+    # 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 _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,278 @@
+# 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 ....file import TextFile, InvalidFileError, wrap_string
+from collections import OrderedDict
+from collections.abc import MutableMapping
+
+
+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 .file import *
+from .convert import *

biotite/sequence/io/fastq/convert.py

@@ -0,0 +1,120 @@
+# 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.fastq"
+__author__ = "Patrick Kunzmann"
+
+from collections import OrderedDict
+from ...sequence import Sequence
+from ...alphabet import AlphabetError, LetterAlphabet
+from ...seqtypes import NucleotideSequence
+from ...align.alignment import Alignment
+
+__all__ = ["get_sequence", "get_sequences", "set_sequence", "set_sequences"]
+
+
+def get_sequence(fastq_file, header=None):
+    """
+    Get a sequence and quality scores from a `FastqFile` instance.
+    
+    Parameters
+    ----------
+    fastq_file : FastqFile
+        The `FastqFile` to be accessed.
+    header : str, optional
+        The identifier to get the sequence and scores from.
+        By default, the first sequence of the file is returned.
+    
+    Returns
+    -------
+    sequence : NucleotideSequence
+        The requested sequence.
+    scores : ndarray, dtype=int
+        The requested scores.
+    """
+    if header is not None:
+        seq_str, scores = fastq_file[header]
+    else:
+        # Return first (and probably only) sequence of file
+        seq_str = None
+        scores = None
+        for seq_str, scores in fastq_file.values():
+            break
+        if seq_str is None:
+            raise ValueError("File does not contain any sequences")
+    processed_seq_str = seq_str.replace("U","T").replace("X","N")
+    return NucleotideSequence(processed_seq_str), scores
+
+
+def get_sequences(fastq_file):
+    """
+    Get a dictionary from a `FastqFile` instance,
+    where identifiers are keys and sequence-score-tuples are values.
+    
+    Parameters
+    ----------
+    fastq_file : FastqFile
+        The `Fastqile` to be accessed.
+    
+    Returns
+    -------
+    seq_dict : dict
+        A dictionary containing identifiers as keys and
+        (`NucleotideSequence`, `ndarray`) tuples as values.
+    """
+    seq_dict = OrderedDict()
+    for header, (seq_str, scores) in fastq_file.items():
+        processed_seq_str = seq_str.replace("U","T").replace("X","N")
+        seq_dict[header] = NucleotideSequence(processed_seq_str), scores
+    return seq_dict
+
+
+def set_sequence(fastq_file, sequence, scores, header=None, as_rna=False):
+    """
+    Set a sequence and a quality score array in a `FastqFile` instance.
+    
+    Parameters
+    ----------
+    fastq_file : FastqFile
+        The `FastqFile` to be accessed.
+    sequence : NucleotideSequence
+        The sequence to be set.
+    scores : ndarray, dtype=int
+        The quality scores to be set.
+    header : str, optional
+        The identifier for the sequence. Default is 'sequence'.
+    as_rna : bool, optional
+        If set to true, the sequence symbol ``'T'`` will be replaced
+        by ``'U'``.
+    """
+    if header is None:
+        header = "sequence"
+    fastq_file[header] = _convert_to_string(sequence, as_rna), scores
+
+
+def set_sequences(fastq_file, sequence_dict, as_rna=False):
+    """
+    Set sequences in a `FastqFile` instance from a dictionary.
+    
+    Parameters
+    ----------
+    fastq_file : FastqFile
+        The `FastqFile` to be accessed.
+    sequence_dict : dict
+        A dictionary containing the sequences and scores to be set.
+        Identifiers are keys,
+        (`NucleotideSequence`, `ndarray`) tuples are values.
+    as_rna : bool, optional
+        If set to true, the sequence symbol ``'T'`` will be replaced
+        by ``'U'``.
+    """
+    for header, (sequence, scores) in sequence_dict.items():
+        fastq_file[header] = _convert_to_string(sequence, as_rna), scores
+
+
+def _convert_to_string(sequence, as_rna):
+    if as_rna:
+        return(str(sequence).replace("T", "U"))
+    else:
+        return(str(sequence))