biotite 1.5.0__cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

biotite/sequence/io/genbank/metadata.py

@@ -0,0 +1,336 @@
+# 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.
+
+"""
+Functions for obtaining metadata fields of a GenBank file.
+"""
+
+__name__ = "biotite.sequence.io.genbank"
+__author__ = "Patrick Kunzmann, Natasha Jaffe"
+__all__ = [
+    "get_locus",
+    "get_definition",
+    "get_accession",
+    "get_version",
+    "get_gi",
+    "get_db_link",
+    "get_source",
+    "set_locus",
+]
+
+from biotite.file import InvalidFileError
+
+
+def get_locus(gb_file):
+    """
+    Parse the *LOCUS* field of a GenBank or GenPept file.
+
+    Parameters
+    ----------
+    gb_file : GenBankFile
+        The GenBank file to read the *LOCUS* field from.
+
+    Returns
+    -------
+    name : str
+        The locus name.
+    length : int
+        Sequence length.
+    mol_type : str, optional
+        The molecule type.
+        Usually one of ``'DNA'``, ``'RNA'``, ``'Protein'`` or ``''``.
+    is_circular : bool, optional
+        True, if the sequence is circular, false otherwise.
+    division : str, optional
+        The GenBank division to which the file belongs.
+    date : str, optional
+        The date of last modification.
+
+    Examples
+    --------
+
+    >>> import os.path
+    >>> file = GenBankFile.read(os.path.join(path_to_sequences, "ec_bl21.gb"))
+    >>> name, length, mol_type, is_circular, division, date = get_locus(file)
+    >>> print(name)
+    CP001509
+    >>> print(length)
+    4558953
+    >>> print(mol_type)
+    DNA
+    >>> print(is_circular)
+    True
+    >>> print(division)
+    BCT
+    >>> print(date)
+    16-FEB-2017
+    """
+    lines, _ = _expect_single_field(gb_file, "LOCUS")
+    # 'LOCUS' field has only one line
+    locus_info = lines[0]
+
+    fields = str(locus_info).split()
+
+    # The first field will always be the ID
+    name = fields[0]
+
+    # The second field will always be the length followed
+    # by units (eg 1224 aa)
+    length = int(fields[1])
+
+    # The third field *should* be the molecular type
+    # but sometimes this is missing.  This gets tricky
+    # because sometimes the next field, circular/linear,
+    # is missing, too. The field after that, division,
+    # is a 3 letter all caps token. Unfortunately, mol_type
+    # is also often a 3 letter all caps token (eg DNA)!
+    # Fortunately, GenBank publishes the set list of divisions
+    # here: https://www.ncbi.nlm.nih.gov/genbank/samplerecord ,
+    # so we can check against that set when determining whether
+    # the current token represents the molecular type.
+    divisions = (
+        "PRI",  # primate sequences
+        "ROD",  # rodent sequences
+        "MAM",  # other mammalian sequences
+        "VRT",  # other vertebrate sequences
+        "INV",  # invertebrate sequences
+        "PLN",  # plant, fungal, and algal sequences
+        "BCT",  # bacterial sequences
+        "VRL",  # viral sequences
+        "PHG",  # bacteriophage sequences
+        "SYN",  # synthetic sequences
+        "UNA",  # unannotated sequences
+        "EST",  # EST sequences (expressed sequence tags)
+        "PAT",  # patent sequences
+        "STS",  # STS sequences (sequence tagged sites)
+        "GSS",  # GSS sequences (genome survey sequences)
+        "HTG",  # HTG sequences (high-throughput genomic sequences)
+        "HTC",  # unfinished high-throughput cDNA sequencing
+        "ENV",  # environmental sampling sequences
+        "CON",
+    )
+
+    # NOTE: Remember that fields[2] is the unit for length,
+    #       eg bp or aa, so we move to fields[3] here.
+    if fields[3] not in ("linear", "circular") and fields[3] not in divisions:
+        mol_type = fields[3]
+        next_idx = 4
+    else:
+        mol_type = None
+        next_idx = 3
+
+    # The next field should be the token 'linear' or 'circular',
+    # but sometimes this is missing
+    if "linear" == fields[next_idx]:
+        is_circular = False
+        next_idx += 1
+    elif "circular" == fields[next_idx]:
+        is_circular = True
+        next_idx += 1
+    else:
+        is_circular = False
+
+    # The next field should be the division
+    if fields[next_idx] in divisions:
+        division = fields[next_idx]
+        next_idx += 1
+
+    # The last field is a date in the format DD-M-YYYY
+    date = fields[next_idx]
+
+    return name, length, mol_type, is_circular, division, date
+
+
+def get_definition(gb_file):
+    """
+    Parse the *DEFINITION* field of a GenBank or GenPept file.
+
+    Parameters
+    ----------
+    gb_file : GenBankFile
+        The GenBank file to read the *DEFINITION* field from.
+
+    Returns
+    -------
+    definition : str
+        Content of the *DEFINITION* field.
+
+    Examples
+    --------
+
+    >>> import os.path
+    >>> file = GenBankFile.read(os.path.join(path_to_sequences, "ec_bl21.gb"))
+    >>> print(get_definition(file))
+    Escherichia coli BL21(DE3), complete genome.
+    """
+    lines, _ = _expect_single_field(gb_file, "DEFINITION")
+    return " ".join([line.strip() for line in lines])
+
+
+def get_accession(gb_file):
+    """
+    Parse the *ACCESSION* field of a GenBank or GenPept file.
+
+    Parameters
+    ----------
+    gb_file : GenBankFile
+        The GenBank file to read the *ACCESSION* field from.
+
+    Returns
+    -------
+    accession : str
+        The accession ID of the file.
+
+    Examples
+    --------
+
+    >>> import os.path
+    >>> file = GenBankFile.read(os.path.join(path_to_sequences, "ec_bl21.gb"))
+    >>> print(get_accession(file))
+    CP001509
+    """
+    lines, _ = _expect_single_field(gb_file, "ACCESSION")
+    # 'ACCESSION' field has only one line
+    return lines[0]
+
+
+def get_version(gb_file):
+    """
+    Parse the version from the *VERSION* field of a GenBank or GenPept
+    file.
+
+    Parameters
+    ----------
+    gb_file : GenBankFile
+        The GenBank file to read the *VERSION* field from.
+
+    Returns
+    -------
+    version : str
+        Content of the *VERSION* field. Does not include GI.
+    """
+    lines, _ = _expect_single_field(gb_file, "VERSION")
+    # 'VERSION' field has only one line
+    return lines[0].split()[0]
+
+
+def get_gi(gb_file):
+    """
+    Parse the GI from the *VERSION* field of a GenBank or GenPept
+    file.
+
+    Parameters
+    ----------
+    gb_file : GenBankFile
+        The GenBank file to read the *VERSION* field from.
+
+    Returns
+    -------
+    gi : str
+        The GI of the file.
+    """
+    lines, _ = _expect_single_field(gb_file, "VERSION")
+    # 'VERSION' field has only one line
+    version_info = lines[0].split()
+    if len(version_info) < 2 or "GI" not in version_info[1]:
+        raise InvalidFileError("File does not contain GI")
+    # Truncate GI
+    return int(version_info[1][3:])
+
+
+def get_db_link(gb_file):
+    """
+    Parse the *DBLINK* field of a GenBank or GenPept file.
+
+    Parameters
+    ----------
+    gb_file : GenBankFile
+        The GenBank file to read the *DBLINK* field from.
+
+    Returns
+    -------
+    link_dict : dict
+        A dictionary storing the database links, with the database
+        name as key, and the corresponding ID as value.
+
+    Examples
+    --------
+
+    >>> import os.path
+    >>> file = GenBankFile.read(os.path.join(path_to_sequences, "ec_bl21.gb"))
+    >>> for key, val in get_db_link(file).items():
+    ...     print(key, ":", val)
+    BioProject : PRJNA20713
+    BioSample : SAMN02603478
+    """
+    lines, _ = _expect_single_field(gb_file, "DBLINK")
+    link_dict = {}
+    for line in lines:
+        key, value = line.split(":")
+        link_dict[key.strip()] = value.strip()
+    return link_dict
+
+
+def get_source(gb_file):
+    """
+    Parse the *SOURCE* field of a GenBank or GenPept file.
+
+    Parameters
+    ----------
+    gb_file : GenBankFile
+        The GenBank file to read the *SOURCE* field from.
+
+    Returns
+    -------
+    accession : str
+        The name of the source organism.
+    """
+    lines, _ = _expect_single_field(gb_file, "SOURCE")
+    # 'SOURCE' field has only one line
+    return lines[0]
+
+
+def _expect_single_field(gb_file, name):
+    fields = gb_file.get_fields(name)
+    if len(fields) == 0:
+        raise InvalidFileError(f"File has no '{name}' field")
+    if len(fields) > 1:
+        raise InvalidFileError(f"File has multiple '{name}' fields")
+    return fields[0]
+
+
+def set_locus(
+    gb_file, name, length, mol_type=None, is_circular=False, division=None, date=None
+):
+    """
+    Set the *LOCUS* field of a GenBank file.
+
+    Parameters
+    ----------
+    gb_file : GenBankFile
+        The GenBank file to be edited.
+    name : str
+        The locus name.
+    length : int
+        Sequence length.
+    mol_type : str, optional
+        The molecule type.
+        Usually one of ``'DNA'``, ``'RNA'``, ``'Protein'`` or ``''``.
+    is_circular : bool, optional
+        True, if the sequence is circular, false otherwise.
+    division : str, optional
+        The GenBank division to which the file belongs.
+    date : str, optional
+        The date of last modification.
+    """
+    mol_type = "" if mol_type is None else mol_type
+    restype_abbr = "aa" if mol_type in ["", "Protein"] else "bp"
+    circularity = "circular" if is_circular else "linear"
+    division = "" if division is None else division
+    date = "" if date is None else date
+    line = (
+        f"{name:18} {length:>9} {restype_abbr} {mol_type:^10} "
+        f"{circularity:8} {division:3} {date:11}"
+    )
+    gb_file.set_field("LOCUS", [line])

biotite/sequence/io/genbank/sequence.py

@@ -0,0 +1,173 @@
+# 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.
+
+"""
+Functions for converting a sequence from/to a GenBank file.
+"""
+
+__name__ = "biotite.sequence.io.genbank"
+__author__ = "Patrick Kunzmann"
+__all__ = [
+    "get_raw_sequence",
+    "get_sequence",
+    "get_annotated_sequence",
+    "set_sequence",
+    "set_annotated_sequence",
+]
+
+import re
+from biotite.file import InvalidFileError
+from biotite.sequence.annotation import AnnotatedSequence
+from biotite.sequence.io.genbank.annotation import get_annotation, set_annotation
+from biotite.sequence.seqtypes import NucleotideSequence, ProteinSequence
+
+_SYMBOLS_PER_CHUNK = 10
+_SEQ_CHUNKS_PER_LINE = 6
+_SYMBOLS_PER_LINE = _SYMBOLS_PER_CHUNK * _SEQ_CHUNKS_PER_LINE
+
+
+def get_raw_sequence(gb_file):
+    """
+    Get the raw sequence string from the *ORIGIN* field
+    of a GenBank file.
+
+    Parameters
+    ----------
+    gb_file : GenBankFile
+        The GenBank file to read the *ORIGIN* field from.
+
+    Returns
+    -------
+    seq_str: str
+        The unaltered sequence as string.
+        Sequence positions and whitespace characters are removed.
+    """
+    fields = gb_file.get_fields("ORIGIN")
+    if len(fields) == 0:
+        raise InvalidFileError("File has no 'ORIGIN' field")
+    if len(fields) > 1:
+        raise InvalidFileError("File has multiple 'ORIGIN' fields")
+    lines, _ = fields[0]
+    return _field_to_seq_string(lines)
+
+
+def get_sequence(gb_file, format="gb"):
+    """
+    Get the sequence from the *ORIGIN* field of a GenBank file.
+
+    Parameters
+    ----------
+    gb_file : GenBankFile
+        The GenBank file to read the *ORIGIN* field from.
+    format : {'gb', 'gp'}
+        Indicates whether the file is a GenBank or a GenPept file.
+        Depending on this parameter a :class:`NucleotideSequence` or a
+        :class:`ProteinSequence` is returned.
+
+    Returns
+    -------
+    sequence : NucleotideSequence or ProteinSequence
+        The reference sequence in the file.
+    """
+    return _convert_seq_str(get_raw_sequence(gb_file), format)
+
+
+def get_annotated_sequence(gb_file, format="gb", include_only=None):
+    """
+    Get an annotated sequence by combining the *ANNOTATION* and
+    *ORIGIN* fields of a GenBank file.
+
+    Parameters
+    ----------
+    gb_file : GenBankFile
+        The GenBank file to read the fields from.
+    format : {'gb', 'gp'}
+        Whether the file is a *GenBank* or *GenPept* file.
+    include_only : iterable object of str, optional
+        List of names of feature keys, which should included
+        in the annotation. By default all features are included.
+
+    Returns
+    -------
+    annot_seq : AnnotatedSequence
+        The annotated sequence.
+    """
+    fields = gb_file.get_fields("ORIGIN")
+    if len(fields) == 0:
+        raise InvalidFileError("File has no 'ORIGIN' field")
+    if len(fields) > 1:
+        raise InvalidFileError("File has multiple 'ORIGIN' fields")
+    lines, _ = fields[0]
+    sequence = _convert_seq_str(_field_to_seq_string(lines), format)
+    seq_start = _get_seq_start(lines)
+    annotation = get_annotation(gb_file, include_only)
+    return AnnotatedSequence(annotation, sequence, sequence_start=seq_start)
+
+
+def _field_to_seq_string(origin_content):
+    seq_str = "".join(origin_content)
+    # Remove numbers and emtpy spaces
+    regex = re.compile("[0-9]| ")
+    seq_str = regex.sub("", seq_str)
+    return seq_str
+
+
+def _convert_seq_str(seq_str, format):
+    if len(seq_str) == 0:
+        raise InvalidFileError("The file's 'ORIGIN' field is empty")
+    if format == "gb":
+        return NucleotideSequence(seq_str.replace("U", "T").replace("X", "N"))
+    elif format == "gp":
+        return ProteinSequence(seq_str.replace("U", "C").replace("O", "K"))
+    else:
+        raise ValueError(f"Unknown format '{format}'")
+
+
+def _get_seq_start(origin_content):
+    # Start of sequence is the sequence position indicator
+    # at the beginning of the first line
+    return int(origin_content[0].split()[0])
+
+
+def set_sequence(gb_file, sequence, sequence_start=1):
+    """
+    Set the *ORIGIN* field of a GenBank file with a sequence.
+
+    Parameters
+    ----------
+    gb_file : GenBankFile
+        The GenBank file to be edited.
+    sequence : str or NucleotideSequence or ProteinSequence
+        The sequence that is put into the GenBank file.
+    sequence_start : int, optional
+        The number of the first base of the sequence.
+    """
+    lines = []
+    seq_str = str(sequence).lower()
+    line = "{:>9d}".format(sequence_start)
+    for i in range(0, len(sequence), _SYMBOLS_PER_CHUNK):
+        # New line after 5 sequence chunks
+        if i != 0 and i % _SYMBOLS_PER_LINE == 0:
+            lines.append(line)
+            line = "{:>9d}".format(sequence_start + i)
+        line += " " + str(seq_str[i : i + _SYMBOLS_PER_CHUNK])
+    # Append last line
+    lines.append(line)
+    gb_file.set_field("ORIGIN", lines)
+
+
+def set_annotated_sequence(gb_file, annot_sequence):
+    """
+    Set the *FEATURES* and *ORIGIN* fields of a GenBank file with the
+    annotation and sequence of an annotated sequence.
+
+    Parameters
+    ----------
+    gb_file : GenBankFile
+        The GenBank file to be edited.
+    annot_sequence : AnnotatedSequence
+        The annotated sequence that is put into the GenBank file.
+    """
+    set_annotation(gb_file, annot_sequence.annotation)
+    set_sequence(gb_file, annot_sequence.sequence, annot_sequence.sequence_start)

biotite/sequence/io/general.py

@@ -0,0 +1,201 @@
+# 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 module contains a convenience function for loading sequences from
+general sequence files.
+"""
+
+__name__ = "biotite.sequence.io"
+__author__ = "Patrick Kunzmann"
+__all__ = ["load_sequence", "save_sequence", "load_sequences", "save_sequences"]
+
+import os.path
+from collections import OrderedDict
+import numpy as np
+from biotite.sequence.seqtypes import NucleotideSequence
+
+
+def load_sequence(file_path):
+    """
+    Load a sequence from a sequence file without the need
+    to manually instantiate a :class:`File` object.
+
+    Internally this function uses a :class:`File` object, based on the
+    file extension.
+
+    Parameters
+    ----------
+    file_path : str
+        The path to the sequence file.
+
+    Returns
+    -------
+    sequence : Sequence
+        The first sequence in the file.
+    """
+    # We only need the suffix here
+    filename, suffix = os.path.splitext(file_path)
+    if suffix in [".fasta", ".fa", ".mpfa", ".fna", ".fsa"]:
+        from biotite.sequence.io.fasta import FastaFile, get_sequence
+
+        file = FastaFile.read(file_path)
+        return get_sequence(file)
+    elif suffix in [".fastq", ".fq"]:
+        from biotite.sequence.io.fastq import FastqFile
+
+        # Quality scores are irrelevant for this function
+        # -> Offset is irrelevant
+        file = FastqFile.read(file_path, offset="Sanger")
+        # Get first sequence
+        for seq_str, scores in file.values():
+            sequence = NucleotideSequence(seq_str)
+            break
+        return sequence
+    elif suffix in [".gb", ".gbk", ".gp"]:
+        from biotite.sequence.io.genbank import GenBankFile, get_sequence
+
+        format = "gp" if suffix == ".gp" else "gb"
+        file = GenBankFile.read(file_path)
+        return get_sequence(file, format)
+    else:
+        raise ValueError(f"Unknown file format '{suffix}'")
+
+
+def save_sequence(file_path, sequence):
+    """
+    Save a sequence into a sequence file without the need
+    to manually instantiate a :class:`File` object.
+
+    Internally this function uses a :class:`File` object, based on the
+    given file extension.
+
+    Parameters
+    ----------
+    file_path : str
+        The path to structure file.
+    sequence : Sequence
+        The sequence to be saved.
+    """
+    # We only need the suffix here
+    filename, suffix = os.path.splitext(file_path)
+    if suffix in [".fasta", ".fa", ".mpfa", ".fna", ".fsa"]:
+        from biotite.sequence.io.fasta import FastaFile, set_sequence
+
+        file = FastaFile()
+        set_sequence(file, sequence)
+        file.write(file_path)
+    elif suffix in [".fastq", ".fq"]:
+        from biotite.sequence.io.fastq import FastqFile
+
+        # Quality scores are irrelevant for this function
+        # -> Offset is irrelevant
+        file = FastqFile(offset="Sanger")
+        # Scores are set to 0 since no score information is supplied
+        scores = np.zeros(len(sequence))
+        file["sequence"] = str(sequence), scores
+        file.write(file_path)
+    elif suffix in [".gb", ".gbk", ".gp"]:
+        from biotite.sequence.io.genbank import GenBankFile, set_locus, set_sequence
+
+        file = GenBankFile()
+        set_locus(file, "sequence", len(sequence))
+        set_sequence(file, sequence)
+        file.write(file_path)
+    else:
+        raise ValueError(f"Unknown file format '{suffix}'")
+
+
+def load_sequences(file_path):
+    """
+    Load multiple sequences from a sequence file without the need
+    to manually instantiate a :class:`File` object.
+
+    Internally this function uses a :class:`File` object, based on the
+    file extension.
+
+    Parameters
+    ----------
+    file_path : str
+        The path to the sequence file.
+
+    Returns
+    -------
+    sequences : dict of (str, Sequence)
+        The sequences in the file.
+        This dictionary maps each header name to
+        the respective sequence.
+    """
+    # We only need the suffix here
+    filename, suffix = os.path.splitext(file_path)
+    if suffix in [".fasta", ".fa", ".mpfa", ".fna", ".fsa"]:
+        from biotite.sequence.io.fasta import FastaFile, get_sequences
+
+        file = FastaFile.read(file_path)
+        return get_sequences(file)
+    elif suffix in [".fastq", ".fq"]:
+        from biotite.sequence.io.fastq import FastqFile
+
+        # Quality scores are irrelevant for this function
+        # -> Offset is irrelevant
+        file = FastqFile.read(file_path, offset="Sanger")
+        return {
+            identifier: NucleotideSequence(seq_str)
+            for identifier, (seq_str, scores) in file.items()
+        }
+    elif suffix in [".gb", ".gbk", ".gp"]:
+        from biotite.sequence.io.genbank import MultiFile, get_definition, get_sequence
+
+        file = MultiFile.read(file_path)
+        format = "gp" if suffix == ".gp" else "gb"
+        sequences = OrderedDict()
+        for f in file:
+            sequences[get_definition(f)] = get_sequence(f, format)
+        return sequences
+    else:
+        raise ValueError(f"Unknown file format '{suffix}'")
+
+
+def save_sequences(file_path, sequences):
+    """
+    Save multiple sequences into a sequence file without the need
+    to manually instantiate a :class:`File` object.
+
+    Internally this function uses a :class:`File` object, based on the
+    given file extension.
+
+    Parameters
+    ----------
+    file_path : str
+        The path to structure file.
+    sequences : dict of (str, Sequence)
+        The sequences to be saved. The dictionary maps a header name
+        to asequence.
+    """
+    # We only need the suffix here
+    filename, suffix = os.path.splitext(file_path)
+    if suffix in [".fasta", ".fa", ".mpfa", ".fna", ".fsa"]:
+        from biotite.sequence.io.fasta import FastaFile, set_sequences
+
+        file = FastaFile()
+        set_sequences(file, sequences)
+        file.write(file_path)
+    elif suffix in [".fastq", ".fq"]:
+        from biotite.sequence.io.fastq import FastqFile
+
+        # Quality scores are irrelevant for this function
+        # -> Offset is irrelevant
+        file = FastqFile(offset="Sanger")
+        for identifier, sequence in sequences.items():
+            # Scores are set to 0 since no score information is supplied
+            scores = np.zeros(len(sequence))
+            file["identifer"] = str(sequence), scores
+        file.write(file_path)
+    elif suffix in [".gb", ".gbk", ".gp"]:
+        raise NotImplementedError(
+            "Writing GenBank files containing multiple records is currently "
+            "not supported"
+        )
+    else:
+        raise ValueError(f"Unknown file format '{suffix}'")