biotite 1.5.0__cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

biotite/sequence/io/fastq/convert.py

@@ -0,0 +1,117 @@
+# 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 biotite.sequence.seqtypes import NucleotideSequence
+
+__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)

biotite/sequence/io/fastq/file.py

@@ -0,0 +1,507 @@
+# 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 collections.abc import MutableMapping
+from numbers import Integral
+import numpy as np
+from biotite.file import InvalidFileError, TextFile, wrap_string
+
+__all__ = ["FastqFile"]
+
+
+_OFFSETS = {
+    "Sanger": 33,
+    "Solexa": 64,
+    "Illumina-1.3": 64,
+    "Illumina-1.5": 64,
+    "Illumina-1.8": 33,
+}
+
+
+class FastqFile(TextFile, MutableMapping):
+    """
+    This class represents a file in FASTQ format.
+
+    A FASTQ file stores one or multiple sequences (base calls) along
+    with sequencing quality scores.
+    Each sequence is associated with an identifer string,
+    beginning with an ``@``.
+
+    The quality scores are encoded as ASCII characters,
+    with each actual score being the ASCII code subtracted by an
+    `offset` value.
+    The offset is format dependent.
+    As the offset is not reliably deducible from the file contets, it
+    must be provided explicitly, either as number or format
+    (e.g. ``'Illumina-1.8'``).
+
+    Similar to the :class:`FastaFile` class, this class implements the
+    :class:`MutableMapping` interface:
+    An identifier string (without the leading ``@``) is used as index
+    to get and set the corresponding sequence and quality.
+    ``del`` removes an entry in the file.
+
+    Parameters
+    ----------
+    offset : int or {'Sanger', 'Solexa', 'Illumina-1.3', 'Illumina-1.5', 'Illumina-1.8'}
+        This value is added to the quality score to obtain the
+        ASCII code.
+        Can either be directly the value, or a string that indicates
+        the score format.
+    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.
+        By default each sequence (and score string)
+        is put into one line.
+
+    Examples
+    --------
+
+    >>> import os.path
+    >>> file = FastqFile(offset="Sanger")
+    >>> file["seq1"] = str(NucleotideSequence("ATACT")), [0,3,10,7,12]
+    >>> file["seq2"] = str(NucleotideSequence("TTGTAGG")), [15,13,24,21,28,38,35]
+    >>> print(file)
+    @seq1
+    ATACT
+    +
+    !$+(-
+    @seq2
+    TTGTAGG
+    +
+    0.96=GD
+    >>> sequence, scores = file["seq1"]
+    >>> print(sequence)
+    ATACT
+    >>> print(scores)
+    [ 0  3 10  7 12]
+    >>> del file["seq1"]
+    >>> print(file)
+    @seq2
+    TTGTAGG
+    +
+    0.96=GD
+    >>> file.write(os.path.join(path_to_directory, "test.fastq"))
+    """
+
+    def __init__(self, offset, chars_per_line=None):
+        super().__init__()
+        self._chars_per_line = chars_per_line
+        self._entries = OrderedDict()
+        self._offset = _convert_offset(offset)
+
+    @classmethod
+    def read(cls, file, offset, chars_per_line=None):
+        """
+        Read a FASTQ file.
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be read.
+            Alternatively a file path can be supplied.
+        offset : int or {'Sanger', 'Solexa', 'Illumina-1.3', 'Illumina-1.5', 'Illumina-1.8'}
+            This value is added to the quality score to obtain the
+            ASCII code.
+            Can either be directly the value, or a string that indicates
+            the score format.
+        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.
+            By default each sequence (and score string)
+            is put into one line.
+
+        Returns
+        -------
+        file_object : FastqFile
+            The parsed file.
+        """
+        file = super().read(file, offset, chars_per_line)
+        # Remove leading and trailing whitespace in all lines
+        file.lines = [line.strip() for line in file.lines]
+        # Filter out empty lines
+        file.lines = [line for line in file.lines if len(line) != 0]
+        if len(file.lines) == 0:
+            raise InvalidFileError("File is empty")
+        file._find_entries()
+        return file
+
+    def get_seq_string(self, identifier):
+        """
+        Get the string representing the sequence for the specified
+        identifier.
+
+        Parameters
+        ----------
+        identifier : str
+            The identifier of the sequence.
+
+        Returns
+        -------
+        sequence : str
+            The sequence corresponding to the identifier.
+        """
+        if not isinstance(identifier, str):
+            raise IndexError("'FastqFile' only supports identifier strings as keys")
+        seq_start, seq_stop, score_start, score_stop = self._entries[identifier]
+        # Concatenate sequence string from the sequence lines
+        seq_str = "".join(self.lines[seq_start:seq_stop])
+        return seq_str
+
+    def get_quality(self, identifier):
+        """
+        Get the quality scores for the specified identifier.
+
+        Parameters
+        ----------
+        identifier : str
+            The identifier of the quality scores.
+
+        Returns
+        -------
+        scores : ndarray, dtype=int
+            The quality scores corresponding to the identifier.
+        """
+        if not isinstance(identifier, str):
+            raise IndexError("'FastqFile' only supports identifier strings as keys")
+        seq_start, seq_stop, score_start, score_stop = self._entries[identifier]
+        # Concatenate sequence string from the score lines
+        return _score_str_to_scores(
+            "".join(self.lines[score_start:score_stop]), self._offset
+        )
+
+    def __setitem__(self, identifier, item):
+        sequence, scores = item
+        if len(sequence) != len(scores):
+            raise ValueError(
+                f"Sequence has length {len(sequence)}, "
+                f"but score length is {len(scores)}"
+            )
+        if not isinstance(identifier, str):
+            raise IndexError("'FastqFile' only supports strings as identifier")
+        # Delete lines of entry corresponding to the identifier,
+        # if already existing
+        if identifier in self:
+            del self[identifier]
+
+        # Create new lines
+        # Start with identifier line
+        new_lines = ["@" + identifier.replace("\n", "").strip()]
+        # Append new lines with sequence string (with line breaks)
+        seq_start_i = len(new_lines)
+        if self._chars_per_line is None:
+            new_lines.append(str(sequence))
+        else:
+            new_lines += wrap_string(sequence, width=self._chars_per_line)
+        seq_stop_i = len(new_lines)
+        # Append sequence-score separator
+        new_lines += ["+"]
+        # Append scores
+        score_chars = _scores_to_score_str(scores, self._offset)
+        score_start_i = len(new_lines)
+        if self._chars_per_line is None:
+            new_lines.append(score_chars)
+        else:
+            new_lines += wrap_string(score_chars, width=self._chars_per_line)
+        score_stop_i = len(new_lines)
+
+        if identifier in self:
+            # Delete lines of entry corresponding to the header,
+            # if existing
+            del self[identifier]
+            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[identifier] = (
+                len(self.lines) + seq_start_i,
+                len(self.lines) + seq_stop_i,
+                len(self.lines) + score_start_i,
+                len(self.lines) + score_stop_i,
+            )
+            self.lines += new_lines
+
+    def __getitem__(self, identifier):
+        return self.get_seq_string(identifier), self.get_quality(identifier)
+
+    def __delitem__(self, identifier):
+        seq_start, seq_stop, score_start, score_stop = self._entries[identifier]
+        del self.lines[seq_start - 1 : score_stop]
+        del self._entries[identifier]
+        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):
+        self._entries = OrderedDict()
+        in_sequence = False
+        # Record if the parser is currently in a quality score section,
+        # as the '@' character at the start of a line may also be a
+        # score instead of the start of an identifier
+        in_scores = False
+        seq_len = 0
+        score_len = 0
+        seq_start_i = None
+        seq_stop_i = None
+        score_start_i = None
+        score_stop_i = None
+        identifier = None
+        for i, line in enumerate(self.lines):
+            if not in_scores and not in_sequence and line[0] == "@":
+                # Identifier line
+                identifier = line[1:]
+                seq_start_i = i + 1
+                # Next line is sequence
+                in_sequence = True
+                # Reset
+                seq_len = 0
+                score_len = 0
+            elif in_sequence:
+                if line[0] == "+":
+                    # End of sequence start of scores
+                    in_sequence = False
+                    in_scores = True
+                    seq_stop_i = i
+                    score_start_i = i + 1
+                else:
+                    # Still in sequence
+                    seq_len += len(line)
+            elif in_scores:
+                score_len += len(line)
+                if score_len < seq_len:
+                    # Scores have not ended yet
+                    pass
+                elif score_len == seq_len:
+                    # End of scores
+                    # -> End of entry
+                    score_stop_i = i + 1
+                    in_scores = False
+                    # Record this entry
+                    self._entries[identifier] = (
+                        seq_start_i,
+                        seq_stop_i,
+                        score_start_i,
+                        score_stop_i,
+                    )
+                else:  # score_len > seq_len
+                    raise InvalidFileError(
+                        f"The amount of scores is not equal to the sequence "
+                        f"length for the sequence in line {seq_start_i + 1} "
+                    )
+            else:
+                raise InvalidFileError(f"Line {i + 1} in FASTQ file is invalid")
+        # At the end of the file, the last sequence or score block
+        # must have properly ended
+        if in_sequence or in_scores:
+            raise InvalidFileError("The last entry in the file is incomplete")
+
+    @staticmethod
+    def read_iter(file, offset):
+        """
+        Create an iterator over each sequence (and corresponding scores)
+        of the given FASTQ file.
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be read.
+            Alternatively a file path can be supplied.
+        offset : int or {'Sanger', 'Solexa', 'Illumina-1.3', 'Illumina-1.5', 'Illumina-1.8'}
+            This value that is added to the quality score to obtain the
+            ASCII code.
+            Can either be directly the value, or a string that indicates
+            the score format.
+
+        Yields
+        ------
+        identifier : str
+            The identifier of the current sequence.
+        sequence : tuple(str, ndarray)
+            The current sequence as string and its corresponding quality
+            scores as :class:`ndarray`.
+
+        Notes
+        -----
+        This approach gives the same results as
+        `FastqFile.read(file, offset).items()`, but is slightly faster
+        and much more memory efficient.
+        """
+        offset = _convert_offset(offset)
+
+        identifier = None
+        seq_str_list = []
+        score_str_list = []
+        in_sequence = False
+        in_scores = False
+        seq_len = 0
+        score_len = 0
+
+        for line in TextFile.read_iter(file):
+            line = line.strip()
+            # Ignore empty lines
+            if len(line) == 0:
+                continue
+
+            if not in_scores and not in_sequence and line[0] == "@":
+                # Track new entry
+                identifier = line[1:]
+                in_sequence = True
+                # Reset
+                seq_len = 0
+                score_len = 0
+                seq_str_list = []
+                score_str_list = []
+
+            elif in_sequence:
+                if line[0] == "+":
+                    # End of sequence start of scores
+                    in_sequence = False
+                    in_scores = True
+                else:
+                    # Still in sequence
+                    seq_len += len(line)
+                    seq_str_list.append(line)
+
+            elif in_scores:
+                score_len += len(line)
+                score_str_list.append(line)
+                if score_len < seq_len:
+                    pass
+                elif score_len == seq_len:
+                    # End of scores
+                    # -> End of entry
+                    in_scores = False
+                    # yield this entry
+                    scores = _score_str_to_scores("".join(score_str_list), offset)
+                    yield identifier, ("".join(seq_str_list), scores)
+                else:  # score_len > seq_len
+                    raise InvalidFileError(
+                        "The amount of scores is not equal to the sequence length"
+                    )
+
+            else:
+                raise InvalidFileError("FASTQ file is invalid")
+
+    @staticmethod
+    def write_iter(file, items, offset, chars_per_line=None):
+        """
+        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, tuple(str, ndarray))
+            The entries to be written into the file.
+            Each entry consists of an identifier string and a tuple
+            containing a sequence (as string) and a score array.
+        offset : int or {'Sanger', 'Solexa', 'Illumina-1.3', 'Illumina-1.5', 'Illumina-1.8'}
+            This value is added to the quality score to obtain the
+            ASCII code.
+            Can either be directly the value, or a string that indicates
+            the score format.
+        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.
+            By default each sequence (and score string)
+            is put into one line.
+
+        Notes
+        -----
+        This method does not test, whether the given identifiers are
+        unambiguous.
+        """
+        offset = _convert_offset(offset)
+
+        def line_generator():
+            for item in items:
+                identifier, (sequence, scores) = item
+                if len(sequence) != len(scores):
+                    raise ValueError(
+                        f"Sequence has length {len(sequence)}, "
+                        f"but score length is {len(scores)}"
+                    )
+                if not isinstance(identifier, str):
+                    raise IndexError("'FastqFile' only supports strings as identifier")
+
+                # Yield identifier line
+                yield "@" + identifier.replace("\n", "").strip()
+
+                # Yield sequence line(s)
+                if chars_per_line is None:
+                    yield str(sequence)
+                else:
+                    for line in wrap_string(sequence, width=chars_per_line):
+                        yield line
+
+                # Yield separator
+                yield "+"
+
+                # Yield scores
+                score_chars = _scores_to_score_str(scores, offset)
+                if chars_per_line is None:
+                    yield score_chars
+                else:
+                    for line in wrap_string(score_chars, width=chars_per_line):
+                        yield line
+
+        TextFile.write_iter(file, line_generator())
+
+
+def _score_str_to_scores(score_str, offset):
+    """
+    Convert an ASCII string into actual score values.
+    """
+    scores = np.frombuffer(bytearray(score_str, encoding="ascii"), dtype=np.int8)
+    scores -= offset
+    return scores
+
+
+def _scores_to_score_str(scores, offset):
+    """
+    Convert score values into an ASCII string.
+    """
+    scores = np.asarray(scores) + offset
+    return scores.astype(np.int8, copy=False).tobytes().decode("ascii")
+
+
+def _convert_offset(offset_val_or_string):
+    """
+    If the given offset is a string return the corresponding numerical
+    value.
+    """
+    if isinstance(offset_val_or_string, Integral):
+        return offset_val_or_string
+    elif isinstance(offset_val_or_string, str):
+        return _OFFSETS[offset_val_or_string]
+    else:
+        raise TypeError(
+            f"The offset must be either an integer or a string "
+            f"indicating the format, not {type(offset_val_or_string).__name__}"
+        )

biotite/sequence/io/genbank/__init__.py

@@ -0,0 +1,17 @@
+# 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/writing information
+(especially sequence features) from/to files in the *GenBank*
+and *GenPept* format.
+"""
+
+__name__ = "biotite.sequence.io.genbank"
+__author__ = "Patrick Kunzmann"
+
+from .annotation import *
+from .file import *
+from .metadata import *
+from .sequence import *