bioseqkit documentation

bioseqkit is a lightweight, dependency-free biological sequence processing toolkit: pure-Python FASTA/FASTQ parsing, statistics, transformations, k-mer / minimizer analysis and FAI-like random-access indexing.

Contents

• Quickstart

API reference

Sequence file I/O.

Pure-Python, streaming FASTA/FASTQ parsers implemented with the iterator/generator pattern so that arbitrarily large files can be processed with constant memory. Both plain-text and gzip-compressed files are supported transparently (detected by the .gz extension or the gzip magic bytes).

class bioseqkit.io.FastaRecord(id, description, sequence)

A single FASTA record.

Parameters:

• id (str)

• description (str)

• sequence (str)

class bioseqkit.io.FastqRecord(id, description, sequence, quality)

A single FASTQ record, carrying Phred quality string.

Parameters:

• id (str)

• description (str)

• sequence (str)

• quality (str)

phred_scores(offset=33)

Decode the ASCII quality string into integer Phred scores.

Parameters:

offset (int)

Return type:

list[int]

bioseqkit.io.open_text(path)

Open path as a text stream, transparently handling gzip files.

Parameters:

path (str)

Return type:

IO[str]

bioseqkit.io.parse_fasta(source)

Stream FastaRecord objects from a FASTA file or text stream.

Blank lines are ignored. Sequence lines are concatenated so multi-line records are handled. Raises ValueError on malformed input.

Parameters:

source (str | IO[str])

Return type:

Iterator[FastaRecord]

bioseqkit.io.parse_fastq(source)

Stream FastqRecord objects from a FASTQ file or text stream.

Parameters:

source (str | IO[str])

Return type:

Iterator[FastqRecord]

bioseqkit.io.write_fasta(records, handle, width=70)

Write records to a text handle, wrapping sequences at width columns.

Returns the number of records written. width <= 0 disables wrapping.

Parameters:

• records (Iterable[FastaRecord])

• handle (IO[str])

• width (int)

Return type:

int

Sequence statistics.

Length distribution, GC content, N-base ratio and base-composition matrix, computed with the Python standard library only.

class bioseqkit.stats.SeqStats(n_seqs=0, total_length=0, min_length=0, max_length=0, lengths=<factory>, gc_content=0.0, n_ratio=0.0, base_counts=<factory>)

Aggregate statistics over a collection of sequences.

Parameters:

• n_seqs (int)

• total_length (int)

• min_length (int)

• max_length (int)

• lengths (list[int])

• gc_content (float)

• n_ratio (float)

• base_counts (dict[str, int])

n50()

Return the N50 of the length distribution.

Return type:

int

bioseqkit.stats.base_composition(sequence)

Return a per-base count dictionary (upper-cased keys).

Parameters:

sequence (str)

Return type:

dict[str, int]

bioseqkit.stats.gc_content(sequence)

Fraction of G/C bases (case-insensitive). Returns 0.0 for empty input.

Parameters:

sequence (str)

Return type:

float

bioseqkit.stats.n_ratio(sequence)

Fraction of ambiguous N bases (case-insensitive).

Parameters:

sequence (str)

Return type:

float

bioseqkit.stats.sequence_stats(sequences)

Compute aggregate SeqStats over an iterable of sequences.

Parameters:

sequences (Iterable[str])

Return type:

SeqStats

Sequence transformations: reverse complement and translation.

Implements DNA reverse complement and the standard genetic code, including six-frame translation (three forward frames + three reverse-complement frames).

class bioseqkit.transform.Frame(strand, offset, protein)

One of the six reading frames of a sequence.

Parameters:

• strand (str)

• offset (int)

• protein (str)

bioseqkit.transform.back_transcribe(sequence)

Reverse-transcribe an RNA sequence into DNA by replacing U with T.

Parameters:

sequence (str)

Return type:

str

bioseqkit.transform.complement(sequence)

Return the base-wise complement (IUPAC aware, preserves length).

Parameters:

sequence (str)

Return type:

str

bioseqkit.transform.reverse_complement(sequence)

Return the reverse complement of a DNA sequence.

Parameters:

sequence (str)

Return type:

str

bioseqkit.transform.six_frame_translation(sequence, unknown='X')

Return all six reading-frame translations of sequence.

Frames +1/+2/+3 translate the forward strand at offsets 0/1/2; frames -1/-2/-3 translate the reverse complement at offsets 0/1/2.

Parameters:

• sequence (str)

• unknown (str)

Return type:

list[Frame]

bioseqkit.transform.transcribe(sequence)

Transcribe a DNA sequence into RNA by replacing T with U.

Case is preserved. This mirrors the coding (sense) strand convention, where the RNA has the same sequence as the template’s complement.

Parameters:

sequence (str)

Return type:

str

bioseqkit.transform.translate(sequence, unknown='X')

Translate a nucleotide sequence in reading frame 0.

U is treated as T. Incomplete trailing codons are dropped. Unknown codons map to unknown.

Parameters:

• sequence (str)

• unknown (str)

Return type:

str

k-mer analysis: counting, top-k, canonical k-mers, parallel counting and minimizers.

bioseqkit.kmer.canonical_kmer(kmer)

Return the lexicographically smaller of a k-mer and its reverse complement.

Parameters:

kmer (str)

Return type:

str

bioseqkit.kmer.count_kmers(sequence, k, canonical=False, skip_ambiguous=True)

Count k-mers in a single sequence.

If canonical is True, a k-mer and its reverse complement are merged. If skip_ambiguous is True, k-mers containing bases outside ACGT are skipped.

Parameters:

• sequence (str)

• k (int)

• canonical (bool)

• skip_ambiguous (bool)

Return type:

Counter[str]

bioseqkit.kmer.count_kmers_parallel(sequences, k, canonical=False, skip_ambiguous=True, workers=4)

Count k-mers across sequences using a process pool, then merge counts.

Each input sequence is split into overlapping chunks that are distributed to worker processes; the per-chunk counters are summed into a single result.

Parameters:

• sequences (Iterable[str])

• k (int)

• canonical (bool)

• skip_ambiguous (bool)

• workers (int)

Return type:

Counter[str]

bioseqkit.kmer.iter_kmers(sequence, k)

Yield successive k-mers of length k from sequence.

Parameters:

• sequence (str)

• k (int)

Return type:

Iterator[str]

bioseqkit.kmer.minimizers(sequence, k, w, canonical=True)

Compute (position, minimizer) pairs over a sliding window.

For each window of w consecutive k-mers, the lexicographically smallest (canonical, by default) k-mer is selected. Consecutive duplicate minimizers are collapsed, mirroring minimap2/Mash behaviour.

Parameters:

• sequence (str)

• k (int)

• w (int)

• canonical (bool)

Return type:

list[tuple[int, str]]

bioseqkit.kmer.top_kmers(counts, n=10)

Return the n most common (k-mer, count) pairs.

Parameters:

• counts (Counter[str])

• n (int)

Return type:

list[tuple[str, int]]

FAI-like FASTA indexing for random access.

Mirrors the samtools faidx (*.fai) format so that arbitrary sub-sequences can be fetched without reading the whole file. Each index line holds: name, sequence length, byte offset of the first base, number of bases per line and number of bytes per line (including the newline).

class bioseqkit.index.FaidxIndex(fasta_path, records)

An in-memory FASTA index bound to a plain-text FASTA file.

Parameters:

• fasta_path (str)

• records (dict[str, FaidxRecord])

fetch(name, start=None, end=None)

Fetch a sub-sequence using 1-based inclusive start/end.

With no coordinates the whole sequence is returned.

Parameters:

• name (str)

• start (int | None)

• end (int | None)

Return type:

str

class bioseqkit.index.FaidxRecord(name: 'str', length: 'int', offset: 'int', linebases: 'int', linewidth: 'int')

Parameters:

• name (str)

• length (int)

• offset (int)

• linebases (int)

• linewidth (int)

bioseqkit.index.build_faidx(fasta_path)

Scan a plain-text FASTA file and build a FaidxIndex.

Raises ValueError for gzip files (which are not seekable by base) or for records with inconsistent line lengths.

Parameters:

fasta_path (str)

Return type:

FaidxIndex

bioseqkit.index.fetch(fasta_path, region)

Convenience: build/load index and fetch a region in one call.

Parameters:

• fasta_path (str)

• region (str)

Return type:

str

bioseqkit.index.parse_region(region)

Parse a chr:start-end region string (1-based, inclusive).

chr alone returns the whole sequence.

Parameters:

region (str)

Return type:

tuple[str, int | None, int | None]

Indices

• Index

• Module Index