Bio Seq Objects

Version Compatibility

Reference examples tested with: BioPython 1.83+

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Seq Objects

Create and manipulate biological sequence objects using Biopython.

"Create a sequence object" -> Wrap a raw string in a typed sequence container for biological operations.

• Immutable: Seq('ATGC') (BioPython) - string-like, supports complement/translate
• Mutable: MutableSeq('ATGC') (BioPython) - supports in-place edits
• Annotated: SeqRecord(Seq(...), id=...) (BioPython) - adds metadata for file I/O

The governing principle: no alphabet, no validation

Bio.Alphabet was removed entirely in Biopython 1.78 (2020-09-04). Seq and SeqRecord lost their .alphabet attribute, and any old-style construction fails LOUD: from Bio.Alphabet import IUPAC raises ImportError, and Seq('ACGT', IUPAC.unambiguous_dna) raises TypeError. Molecule type now lives as a SeqRecord annotation, record.annotations['molecule_type'] = 'DNA', consumed by the GenBank/EMBL writers.

The consequence governs everything downstream: no Seq operation validates its alphabet anymore. A protein passed to reverse_complement() or transcribe() returns silent garbage rather than an error. Sibling skills (transcription-translation, reverse-complement) inherit this - the burden is on the caller to track what kind of molecule a Seq holds.

Required Imports

from Bio.Seq import Seq, MutableSeq
from Bio.SeqRecord import SeqRecord

Core Objects

Seq - Immutable Sequence

Immutable and behaves like str since 1.78: indexing, slicing, +, *, .upper(), in, .count(), .find() all work. In-place edits raise: seq[0] = 'A' -> TypeError (LOUD). Use MutableSeq for edits.

seq = Seq('ATGCGATCGATCG')

len(seq)           # length
seq[0]             # first base
seq[0:10]          # slice (returns Seq)
str(seq)           # text form (see bytes note below)
'ATG' in seq       # membership test
seq.count('G')     # count occurrences
seq.find('ATG')    # position (-1 if not found)
seq.upper()        # uppercase (returns Seq)
seq * 3            # repeat

Since 1.79 Seq is backed by bytes (and MutableSeq by bytearray), NOT a str subclass. Use str(seq) for text and bytes(seq) for bytes. isinstance(seq, str) is always False - code that type-checks with isinstance(x, str) to detect sequences silently skips every Seq; test isinstance(x, (Seq, MutableSeq)) instead.

MutableSeq - Mutable Sequence

A bytearray-backed sequence for in-place editing; required when an operation needs inplace=True.

mut_seq = MutableSeq('ATGCGATCG')
mut_seq[0] = 'C'              # modify single position
mut_seq[0:3] = 'GGG'          # replace slice
mut_seq.append('A')           # add to end
mut_seq.insert(0, 'G')        # insert at position
mut_seq.pop()                 # remove and return last
mut_seq.remove('G')           # remove first occurrence
mut_seq.reverse()             # reverse in place

Convert between types (a MutableSeq is unhashable and cannot be a dict key or used in SeqIO.write, so cast back to Seq when done editing):

seq = Seq(mut_seq)            # MutableSeq -> Seq
mut_seq = MutableSeq(seq)     # Seq -> MutableSeq

Undefined and partially-defined sequences

UndefinedSequenceError (added 1.79, a subclass of ValueError) models a sequence whose length is known but whose content is not - produced by lazy/partial file parsers. A Seq(None, length=20) reports len() == 20 but raises on any attempt to read the bytes.

undef = Seq(None, length=20)
len(undef)            # 20 - fine
str(undef)            # raises UndefinedSequenceError (subclass of ValueError)

partial = Seq({3: 'ACGT'}, length=10)   # only positions 3-6 defined
str(partial[3:7])     # 'ACGT' - defined region reads fine
str(partial)          # raises - undefined positions

Note: complement()/reverse_complement() on an undefined Seq return self rather than crash, but any read of the bytes raises. Guard reads of records from lazy parsers with try/except UndefinedSequenceError only where content access is genuinely optional.

SeqRecord - Annotated Sequence

Sequence plus metadata for file I/O and analysis.

record = SeqRecord(Seq('ATGCGATCG'), id='gene1', name='example_gene', description='An example gene sequence')

record.seq                 # the Seq object
record.id                  # identifier string
record.name                # name string
record.description         # description string
record.features            # list of SeqFeature objects
record.annotations         # dict (organism, molecule_type, topology, ...)
record.letter_annotations  # per-letter annotations (e.g. phred_quality)
record.dbxrefs             # database cross-references