bioseqkit 0.1.0__py3-none-any.whl

bioseqkit/__init__.py

@@ -0,0 +1,57 @@
+"""bioseqkit: a lightweight, dependency-free biological sequence toolkit.
+
+The package provides pure-Python FASTA/FASTQ parsing, sequence statistics,
+transformations (reverse complement, six-frame translation), k-mer analysis,
+minimizer sampling and FAI-like random-access indexing.
+"""
+
+from bioseqkit.io import (
+    FastaRecord,
+    FastqRecord,
+    parse_fasta,
+    parse_fastq,
+    write_fasta,
+)
+from bioseqkit.stats import (
+    SeqStats,
+    base_composition,
+    gc_content,
+    n_ratio,
+    sequence_stats,
+)
+from bioseqkit.transform import reverse_complement, six_frame_translation, translate
+from bioseqkit.kmer import (
+    canonical_kmer,
+    count_kmers,
+    count_kmers_parallel,
+    minimizers,
+    top_kmers,
+)
+from bioseqkit.index import FaidxIndex, build_faidx, fetch
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FastaRecord",
+    "FastqRecord",
+    "parse_fasta",
+    "parse_fastq",
+    "write_fasta",
+    "SeqStats",
+    "sequence_stats",
+    "gc_content",
+    "n_ratio",
+    "base_composition",
+    "reverse_complement",
+    "translate",
+    "six_frame_translation",
+    "count_kmers",
+    "count_kmers_parallel",
+    "top_kmers",
+    "canonical_kmer",
+    "minimizers",
+    "FaidxIndex",
+    "build_faidx",
+    "fetch",
+    "__version__",
+]

bioseqkit/cli.py

@@ -0,0 +1,140 @@
+"""Command-line interface for bioseqkit.
+
+Implemented with :mod:`argparse` (standard library) to keep the core package
+dependency-free. Sub-commands: ``stats``, ``revcomp``, ``translate``,
+``kmer``, ``minimizer``, ``index`` and ``fetch``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Sequence
+
+from bioseqkit import __version__
+from bioseqkit.index import build_faidx, fetch as fetch_region
+from bioseqkit.io import FastaRecord, parse_fasta, write_fasta
+from bioseqkit.kmer import count_kmers, count_kmers_parallel, minimizers, top_kmers
+from bioseqkit.stats import sequence_stats
+from bioseqkit.transform import reverse_complement, six_frame_translation
+
+
+def _read_sequences(path: str) -> list[FastaRecord]:
+    return list(parse_fasta(path))
+
+
+def cmd_stats(args: argparse.Namespace) -> int:
+    records = _read_sequences(args.input)
+    stats = sequence_stats(rec.sequence for rec in records)
+    print(json.dumps(stats.as_dict(), indent=2))
+    return 0
+
+
+def cmd_revcomp(args: argparse.Namespace) -> int:
+    out = [
+        FastaRecord(rec.id, (rec.description + " revcomp").strip(), reverse_complement(rec.sequence))
+        for rec in _read_sequences(args.input)
+    ]
+    write_fasta(out, sys.stdout)
+    return 0
+
+
+def cmd_translate(args: argparse.Namespace) -> int:
+    out: list[FastaRecord] = []
+    for rec in _read_sequences(args.input):
+        for frame in six_frame_translation(rec.sequence):
+            out.append(FastaRecord(f"{rec.id}_frame{frame.name}", "", frame.protein))
+    write_fasta(out, sys.stdout)
+    return 0
+
+
+def cmd_kmer(args: argparse.Namespace) -> int:
+    seqs = [rec.sequence for rec in _read_sequences(args.input)]
+    if args.threads and args.threads > 1:
+        counts = count_kmers_parallel(seqs, args.k, canonical=args.canonical, workers=args.threads)
+    else:
+        counts = sum(
+            (count_kmers(s, args.k, canonical=args.canonical) for s in seqs),
+            start=type(count_kmers("", args.k))(),
+        )
+    for kmer, count in top_kmers(counts, args.top):
+        print(f"{kmer}\t{count}")
+    return 0
+
+
+def cmd_minimizer(args: argparse.Namespace) -> int:
+    for rec in _read_sequences(args.input):
+        for pos, mm in minimizers(rec.sequence, args.k, args.w, canonical=not args.no_canonical):
+            print(f"{rec.id}\t{pos}\t{mm}")
+    return 0
+
+
+def cmd_index(args: argparse.Namespace) -> int:
+    index = build_faidx(args.input)
+    path = index.write()
+    print(f"Wrote index: {path} ({len(index.records)} sequences)")
+    return 0
+
+
+def cmd_fetch(args: argparse.Namespace) -> int:
+    seq = fetch_region(args.input, args.region)
+    name = args.region
+    print(f">{name}")
+    for i in range(0, len(seq), 70):
+        print(seq[i : i + 70])
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="bioseqkit", description=__doc__.split("\n")[0])
+    parser.add_argument("--version", action="version", version=f"bioseqkit {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("stats", help="sequence statistics (JSON)")
+    p.add_argument("input", help="FASTA/FASTA.gz file")
+    p.set_defaults(func=cmd_stats)
+
+    p = sub.add_parser("revcomp", help="reverse complement")
+    p.add_argument("input")
+    p.set_defaults(func=cmd_revcomp)
+
+    p = sub.add_parser("translate", help="six-frame translation")
+    p.add_argument("input")
+    p.set_defaults(func=cmd_translate)
+
+    p = sub.add_parser("kmer", help="k-mer frequency analysis")
+    p.add_argument("input")
+    p.add_argument("-k", type=int, default=5, help="k-mer size (default 5)")
+    p.add_argument("--top", type=int, default=10, help="report top-N k-mers")
+    p.add_argument("--canonical", action="store_true", help="merge reverse-complement k-mers")
+    p.add_argument("-t", "--threads", type=int, default=1, help="parallel worker processes")
+    p.set_defaults(func=cmd_kmer)
+
+    p = sub.add_parser("minimizer", help="minimizer sampling")
+    p.add_argument("input")
+    p.add_argument("-k", type=int, default=15, help="k-mer size (default 15)")
+    p.add_argument("-w", type=int, default=10, help="window size (default 10)")
+    p.add_argument("--no-canonical", action="store_true", help="disable canonical k-mers")
+    p.set_defaults(func=cmd_minimizer)
+
+    p = sub.add_parser("index", help="build a FAI-like index")
+    p.add_argument("input")
+    p.set_defaults(func=cmd_index)
+
+    p = sub.add_parser("fetch", help="fetch a sub-sequence (chr:start-end)")
+    p.add_argument("input")
+    p.add_argument("region", help="region string, e.g. chr1:1000-2000")
+    p.set_defaults(func=cmd_fetch)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

bioseqkit/entrez.py

@@ -0,0 +1,39 @@
+"""Optional NCBI Entrez download helper.
+
+Fetches reference sequences from the NCBI E-utilities ``efetch`` endpoint using
+only the standard library (``urllib``), so no third-party HTTP client is
+required. Network access is required at call time.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+import urllib.request
+
+__all__ = ["efetch_fasta"]
+
+_EFETCH = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi"
+
+
+def efetch_fasta(
+    accession: str,
+    db: str = "nuccore",
+    email: str | None = None,
+    api_key: str | None = None,
+    timeout: float = 30.0,
+) -> str:
+    """Download a FASTA record from NCBI by accession and return it as text."""
+    params = {
+        "db": db,
+        "id": accession,
+        "rettype": "fasta",
+        "retmode": "text",
+    }
+    if email:
+        params["email"] = email
+    if api_key:
+        params["api_key"] = api_key
+    url = f"{_EFETCH}?{urllib.parse.urlencode(params)}"
+    req = urllib.request.Request(url, headers={"User-Agent": "bioseqkit/0.1"})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+        return resp.read().decode("utf-8")

bioseqkit/index.py

@@ -0,0 +1,164 @@
+"""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).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+__all__ = ["FaidxRecord", "FaidxIndex", "build_faidx", "fetch", "parse_region"]
+
+
+@dataclass(frozen=True)
+class FaidxRecord:
+    name: str
+    length: int
+    offset: int
+    linebases: int
+    linewidth: int
+
+    def to_line(self) -> str:
+        return f"{self.name}\t{self.length}\t{self.offset}\t{self.linebases}\t{self.linewidth}"
+
+    @classmethod
+    def from_line(cls, line: str) -> "FaidxRecord":
+        name, length, offset, linebases, linewidth = line.rstrip("\n").split("\t")
+        return cls(name, int(length), int(offset), int(linebases), int(linewidth))
+
+
+class FaidxIndex:
+    """An in-memory FASTA index bound to a plain-text FASTA file."""
+
+    def __init__(self, fasta_path: str, records: dict[str, FaidxRecord]):
+        self.fasta_path = fasta_path
+        self.records = records
+
+    def names(self) -> list[str]:
+        return list(self.records)
+
+    def write(self, fai_path: str | None = None) -> str:
+        path = fai_path or self.fasta_path + ".fai"
+        with open(path, "w") as fh:
+            for rec in self.records.values():
+                fh.write(rec.to_line() + "\n")
+        return path
+
+    @classmethod
+    def load(cls, fasta_path: str, fai_path: str | None = None) -> "FaidxIndex":
+        path = fai_path or fasta_path + ".fai"
+        records: dict[str, FaidxRecord] = {}
+        with open(path) as fh:
+            for line in fh:
+                if line.strip():
+                    rec = FaidxRecord.from_line(line)
+                    records[rec.name] = rec
+        return cls(fasta_path, records)
+
+    def fetch(self, name: str, start: int | None = None, end: int | None = None) -> str:
+        """Fetch a sub-sequence using 1-based inclusive ``start``/``end``.
+
+        With no coordinates the whole sequence is returned.
+        """
+        if name not in self.records:
+            raise KeyError(f"Sequence {name!r} not found in index")
+        rec = self.records[name]
+        s = 0 if start is None else start - 1
+        e = rec.length if end is None else end
+        if s < 0 or e > rec.length or s > e:
+            raise ValueError(f"Region out of bounds for {name} (length {rec.length})")
+        newline_bytes = rec.linewidth - rec.linebases
+        with open(self.fasta_path, "rb") as fh:
+            start_line, start_col = divmod(s, rec.linebases)
+            byte_start = rec.offset + start_line * rec.linewidth + start_col
+            fh.seek(byte_start)
+            n_bases = e - s
+            # Read enough bytes to cover the requested bases plus newlines.
+            n_lines = (start_col + n_bases) // rec.linebases
+            n_read = n_bases + n_lines * newline_bytes + rec.linewidth
+            raw = fh.read(n_read)
+        seq = raw.replace(b"\n", b"").replace(b"\r", b"").decode("ascii")
+        return seq[:n_bases]
+
+
+def build_faidx(fasta_path: str) -> FaidxIndex:
+    """Scan a plain-text FASTA file and build a :class:`FaidxIndex`.
+
+    Raises :class:`ValueError` for gzip files (which are not seekable by base)
+    or for records with inconsistent line lengths.
+    """
+    if fasta_path.endswith(".gz"):
+        raise ValueError("faidx requires an uncompressed FASTA file")
+    records: dict[str, FaidxRecord] = {}
+    with open(fasta_path, "rb") as fh:
+        name: str | None = None
+        length = 0
+        offset = 0
+        linebases = 0
+        linewidth = 0
+        line_lengths: list[int] = []
+        pos = 0
+
+        def flush() -> None:
+            nonlocal name
+            if name is not None:
+                _validate_lines(name, line_lengths)
+                records[name] = FaidxRecord(name, length, offset, linebases, linewidth)
+
+        for raw in fh:
+            if raw.startswith(b">"):
+                flush()
+                header = raw[1:].decode("ascii", "replace").strip()
+                name = header.split()[0] if header else ""
+                length = 0
+                linebases = 0
+                linewidth = 0
+                line_lengths = []
+                offset = pos + len(raw)
+            else:
+                stripped = raw.rstrip(b"\r\n")
+                if name is not None:
+                    if linebases == 0:
+                        linebases = len(stripped)
+                        linewidth = len(raw)
+                    line_lengths.append(len(stripped))
+                    length += len(stripped)
+            pos += len(raw)
+        flush()
+    return FaidxIndex(fasta_path, records)
+
+
+def _validate_lines(name: str, line_lengths: list[int]) -> None:
+    if len(line_lengths) > 1:
+        body = line_lengths[:-1]
+        if len(set(body)) > 1:
+            raise ValueError(f"Inconsistent line lengths in record {name!r}; cannot index")
+        if line_lengths[-1] > body[0]:
+            raise ValueError(f"Last line longer than others in record {name!r}")
+
+
+def parse_region(region: str) -> tuple[str, int | None, int | None]:
+    """Parse a ``chr:start-end`` region string (1-based, inclusive).
+
+    ``chr`` alone returns the whole sequence.
+    """
+    if ":" not in region:
+        return region, None, None
+    name, span = region.rsplit(":", 1)
+    span = span.replace(",", "")
+    if "-" in span:
+        start_s, end_s = span.split("-", 1)
+        return name, int(start_s), int(end_s)
+    return name, int(span), int(span)
+
+
+def fetch(fasta_path: str, region: str) -> str:
+    """Convenience: build/load index and fetch a region in one call."""
+    fai_path = fasta_path + ".fai"
+    index = FaidxIndex.load(fasta_path) if os.path.exists(fai_path) else build_faidx(fasta_path)
+    name, start, end = parse_region(region)
+    return index.fetch(name, start, end)

bioseqkit/io.py

@@ -0,0 +1,182 @@
+"""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).
+"""
+
+from __future__ import annotations
+
+import gzip
+import io as _io
+from dataclasses import dataclass
+from typing import IO, Iterable, Iterator
+
+__all__ = [
+    "FastaRecord",
+    "FastqRecord",
+    "open_text",
+    "parse_fasta",
+    "parse_fastq",
+    "write_fasta",
+]
+
+
+@dataclass(frozen=True)
+class FastaRecord:
+    """A single FASTA record."""
+
+    id: str
+    description: str
+    sequence: str
+
+    def __len__(self) -> int:
+        return len(self.sequence)
+
+
+@dataclass(frozen=True)
+class FastqRecord:
+    """A single FASTQ record, carrying Phred quality string."""
+
+    id: str
+    description: str
+    sequence: str
+    quality: str
+
+    def __len__(self) -> int:
+        return len(self.sequence)
+
+    def phred_scores(self, offset: int = 33) -> list[int]:
+        """Decode the ASCII quality string into integer Phred scores."""
+        return [ord(c) - offset for c in self.quality]
+
+
+def _is_gzip(path: str) -> bool:
+    if path.endswith(".gz"):
+        return True
+    try:
+        with open(path, "rb") as fh:
+            return fh.read(2) == b"\x1f\x8b"
+    except OSError:
+        return False
+
+
+def open_text(path: str) -> IO[str]:
+    """Open ``path`` as a text stream, transparently handling gzip files."""
+    if _is_gzip(path):
+        return gzip.open(path, "rt")
+    return open(path, "rt")
+
+
+def _split_header(header: str) -> tuple[str, str]:
+    header = header.strip()
+    if not header:
+        return "", ""
+    parts = header.split(None, 1)
+    seq_id = parts[0]
+    description = parts[1] if len(parts) > 1 else ""
+    return seq_id, description
+
+
+def parse_fasta(source: str | IO[str]) -> Iterator[FastaRecord]:
+    """Stream :class:`FastaRecord` objects from a FASTA file or text stream.
+
+    Blank lines are ignored. Sequence lines are concatenated so multi-line
+    records are handled. Raises :class:`ValueError` on malformed input.
+    """
+    handle, own = _as_handle(source)
+    try:
+        seq_id: str | None = None
+        description = ""
+        chunks: list[str] = []
+        started = False
+        for raw in handle:
+            line = raw.rstrip("\r\n")
+            if not line.strip():
+                continue
+            if line.startswith(">"):
+                started = True
+                if seq_id is not None:
+                    yield FastaRecord(seq_id, description, "".join(chunks))
+                seq_id, description = _split_header(line[1:])
+                chunks = []
+            else:
+                if not started:
+                    raise ValueError("FASTA sequence data before any '>' header")
+                chunks.append(line.strip())
+        if seq_id is not None:
+            yield FastaRecord(seq_id, description, "".join(chunks))
+    finally:
+        if own:
+            handle.close()
+
+
+def parse_fastq(source: str | IO[str]) -> Iterator[FastqRecord]:
+    """Stream :class:`FastqRecord` objects from a FASTQ file or text stream."""
+    handle, own = _as_handle(source)
+    try:
+        it = iter(handle)
+        while True:
+            header = _next_nonblank(it)
+            if header is None:
+                break
+            if not header.startswith("@"):
+                raise ValueError(f"FASTQ header must start with '@': {header!r}")
+            seq_line = _require(it, "sequence")
+            plus = _require(it, "'+' separator")
+            if not plus.startswith("+"):
+                raise ValueError(f"FASTQ separator must start with '+': {plus!r}")
+            qual_line = _require(it, "quality")
+            if len(seq_line) != len(qual_line):
+                raise ValueError(
+                    "FASTQ sequence and quality length mismatch "
+                    f"({len(seq_line)} vs {len(qual_line)})"
+                )
+            seq_id, description = _split_header(header[1:])
+            yield FastqRecord(seq_id, description, seq_line, qual_line)
+    finally:
+        if own:
+            handle.close()
+
+
+def write_fasta(records: Iterable[FastaRecord], handle: IO[str], width: int = 70) -> int:
+    """Write records to a text handle, wrapping sequences at ``width`` columns.
+
+    Returns the number of records written. ``width <= 0`` disables wrapping.
+    """
+    n = 0
+    for rec in records:
+        header = rec.id if not rec.description else f"{rec.id} {rec.description}"
+        handle.write(f">{header}\n")
+        seq = rec.sequence
+        if width and width > 0:
+            for i in range(0, len(seq), width):
+                handle.write(seq[i : i + width] + "\n")
+        else:
+            handle.write(seq + "\n")
+        n += 1
+    return n
+
+
+def _as_handle(source: str | IO[str]) -> tuple[IO[str], bool]:
+    if isinstance(source, str):
+        return open_text(source), True
+    if isinstance(source, (_io.TextIOBase,)) or hasattr(source, "read"):
+        return source, False
+    raise TypeError(f"Unsupported source type: {type(source)!r}")
+
+
+def _next_nonblank(it: Iterator[str]) -> str | None:
+    for raw in it:
+        line = raw.rstrip("\r\n")
+        if line.strip():
+            return line
+    return None
+
+
+def _require(it: Iterator[str], what: str) -> str:
+    try:
+        return next(it).rstrip("\r\n")
+    except StopIteration as exc:  # noqa: F841
+        raise ValueError(f"Truncated FASTQ record: missing {what} line") from None

bioseqkit/kmer.py

@@ -0,0 +1,141 @@
+"""k-mer analysis: counting, top-k, canonical k-mers, parallel counting and minimizers."""
+
+from __future__ import annotations
+
+from collections import Counter
+from concurrent.futures import ProcessPoolExecutor
+from typing import Iterable, Iterator
+
+from bioseqkit.transform import reverse_complement
+
+__all__ = [
+    "iter_kmers",
+    "count_kmers",
+    "count_kmers_parallel",
+    "top_kmers",
+    "canonical_kmer",
+    "minimizers",
+]
+
+
+def iter_kmers(sequence: str, k: int) -> Iterator[str]:
+    """Yield successive k-mers of length ``k`` from ``sequence``."""
+    if k <= 0:
+        raise ValueError("k must be a positive integer")
+    for i in range(len(sequence) - k + 1):
+        yield sequence[i : i + k]
+
+
+def canonical_kmer(kmer: str) -> str:
+    """Return the lexicographically smaller of a k-mer and its reverse complement."""
+    rc = reverse_complement(kmer)
+    return kmer if kmer <= rc else rc
+
+
+def count_kmers(
+    sequence: str,
+    k: int,
+    canonical: bool = False,
+    skip_ambiguous: bool = True,
+) -> Counter[str]:
+    """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.
+    """
+    counts: Counter[str] = Counter()
+    seq = sequence.upper()
+    valid = set("ACGT")
+    for kmer in iter_kmers(seq, k):
+        if skip_ambiguous and not set(kmer) <= valid:
+            continue
+        counts[canonical_kmer(kmer) if canonical else kmer] += 1
+    return counts
+
+
+def _count_chunk(args: tuple[str, int, bool, bool]) -> Counter[str]:
+    sequence, k, canonical, skip_ambiguous = args
+    return count_kmers(sequence, k, canonical, skip_ambiguous)
+
+
+def _chunk_sequence(sequence: str, n_chunks: int, k: int) -> list[str]:
+    """Split a sequence into ``n_chunks`` overlapping chunks (overlap = k - 1).
+
+    The overlap guarantees k-mers spanning chunk boundaries are still counted.
+    """
+    n = len(sequence)
+    if n_chunks <= 1 or n < 2 * k:
+        return [sequence]
+    size = max(k, n // n_chunks)
+    chunks: list[str] = []
+    start = 0
+    while start < n:
+        end = min(n, start + size)
+        chunks.append(sequence[start : min(n, end + k - 1)])
+        start = end
+    return chunks
+
+
+def count_kmers_parallel(
+    sequences: Iterable[str],
+    k: int,
+    canonical: bool = False,
+    skip_ambiguous: bool = True,
+    workers: int = 4,
+) -> Counter[str]:
+    """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.
+    """
+    chunks: list[str] = []
+    for seq in sequences:
+        chunks.extend(_chunk_sequence(seq.upper(), workers, k))
+    if not chunks:
+        return Counter()
+    if workers <= 1 or len(chunks) == 1:
+        total: Counter[str] = Counter()
+        for chunk in chunks:
+            total += count_kmers(chunk, k, canonical, skip_ambiguous)
+        return total
+
+    tasks = [(chunk, k, canonical, skip_ambiguous) for chunk in chunks]
+    total = Counter()
+    with ProcessPoolExecutor(max_workers=workers) as pool:
+        for partial in pool.map(_count_chunk, tasks):
+            total += partial
+    return total
+
+
+def top_kmers(counts: Counter[str], n: int = 10) -> list[tuple[str, int]]:
+    """Return the ``n`` most common (k-mer, count) pairs."""
+    return counts.most_common(n)
+
+
+def minimizers(sequence: str, k: int, w: int, canonical: bool = True) -> list[tuple[int, str]]:
+    """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.
+    """
+    if k <= 0 or w <= 0:
+        raise ValueError("k and w must be positive integers")
+    seq = sequence.upper()
+    kmers = list(iter_kmers(seq, k))
+    if not kmers:
+        return []
+    keyed = [canonical_kmer(km) if canonical else km for km in kmers]
+    result: list[tuple[int, str]] = []
+    last: tuple[int, str] | None = None
+    n_windows = max(1, len(kmers) - w + 1)
+    for start in range(n_windows):
+        window = keyed[start : start + w]
+        best_val = min(window)
+        best_pos = start + window.index(best_val)
+        picked = (best_pos, best_val)
+        if picked != last:
+            result.append(picked)
+            last = picked
+    return result

bioseqkit/stats.py

@@ -0,0 +1,111 @@
+"""Sequence statistics.
+
+Length distribution, GC content, N-base ratio and base-composition matrix,
+computed with the Python standard library only.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass, field
+from typing import Iterable
+
+__all__ = [
+    "SeqStats",
+    "gc_content",
+    "n_ratio",
+    "base_composition",
+    "sequence_stats",
+]
+
+
+def gc_content(sequence: str) -> float:
+    """Fraction of G/C bases (case-insensitive). Returns 0.0 for empty input."""
+    if not sequence:
+        return 0.0
+    gc = 0
+    for base in sequence:
+        if base in "GCgc":
+            gc += 1
+    return gc / len(sequence)
+
+
+def n_ratio(sequence: str) -> float:
+    """Fraction of ambiguous ``N`` bases (case-insensitive)."""
+    if not sequence:
+        return 0.0
+    n = sequence.count("N") + sequence.count("n")
+    return n / len(sequence)
+
+
+def base_composition(sequence: str) -> dict[str, int]:
+    """Return a per-base count dictionary (upper-cased keys)."""
+    return dict(Counter(sequence.upper()))
+
+
+@dataclass
+class SeqStats:
+    """Aggregate statistics over a collection of sequences."""
+
+    n_seqs: int = 0
+    total_length: int = 0
+    min_length: int = 0
+    max_length: int = 0
+    lengths: list[int] = field(default_factory=list)
+    gc_content: float = 0.0
+    n_ratio: float = 0.0
+    base_counts: dict[str, int] = field(default_factory=dict)
+
+    @property
+    def mean_length(self) -> float:
+        return self.total_length / self.n_seqs if self.n_seqs else 0.0
+
+    def n50(self) -> int:
+        """Return the N50 of the length distribution."""
+        if not self.lengths:
+            return 0
+        half = self.total_length / 2
+        acc = 0
+        for length in sorted(self.lengths, reverse=True):
+            acc += length
+            if acc >= half:
+                return length
+        return 0
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "n_seqs": self.n_seqs,
+            "total_length": self.total_length,
+            "min_length": self.min_length,
+            "max_length": self.max_length,
+            "mean_length": round(self.mean_length, 3),
+            "n50": self.n50(),
+            "gc_content": round(self.gc_content, 6),
+            "n_ratio": round(self.n_ratio, 6),
+            "base_counts": self.base_counts,
+        }
+
+
+def sequence_stats(sequences: Iterable[str]) -> SeqStats:
+    """Compute aggregate :class:`SeqStats` over an iterable of sequences."""
+    stats = SeqStats()
+    gc = 0
+    n_bases = 0
+    counts: Counter[str] = Counter()
+    for seq in sequences:
+        length = len(seq)
+        stats.n_seqs += 1
+        stats.total_length += length
+        stats.lengths.append(length)
+        upper = seq.upper()
+        counts.update(upper)
+        gc += upper.count("G") + upper.count("C")
+        n_bases += upper.count("N")
+    if stats.lengths:
+        stats.min_length = min(stats.lengths)
+        stats.max_length = max(stats.lengths)
+    if stats.total_length:
+        stats.gc_content = gc / stats.total_length
+        stats.n_ratio = n_bases / stats.total_length
+    stats.base_counts = dict(counts)
+    return stats

bioseqkit/transform.py

@@ -0,0 +1,95 @@
+"""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).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = [
+    "reverse_complement",
+    "complement",
+    "translate",
+    "six_frame_translation",
+    "Frame",
+    "CODON_TABLE",
+]
+
+_COMPLEMENT = str.maketrans(
+    "ACGTUNacgtunRYSWKMBDHVryswkmbdhv",
+    "TGCAANtgcaanYRSWMKVHDByrswmkvhdb",
+)
+
+# Standard genetic code (NCBI transl_table=1).
+CODON_TABLE: dict[str, str] = {
+    "TTT": "F", "TTC": "F", "TTA": "L", "TTG": "L",
+    "CTT": "L", "CTC": "L", "CTA": "L", "CTG": "L",
+    "ATT": "I", "ATC": "I", "ATA": "I", "ATG": "M",
+    "GTT": "V", "GTC": "V", "GTA": "V", "GTG": "V",
+    "TCT": "S", "TCC": "S", "TCA": "S", "TCG": "S",
+    "CCT": "P", "CCC": "P", "CCA": "P", "CCG": "P",
+    "ACT": "T", "ACC": "T", "ACA": "T", "ACG": "T",
+    "GCT": "A", "GCC": "A", "GCA": "A", "GCG": "A",
+    "TAT": "Y", "TAC": "Y", "TAA": "*", "TAG": "*",
+    "CAT": "H", "CAC": "H", "CAA": "Q", "CAG": "Q",
+    "AAT": "N", "AAC": "N", "AAA": "K", "AAG": "K",
+    "GAT": "D", "GAC": "D", "GAA": "E", "GAG": "E",
+    "TGT": "C", "TGC": "C", "TGA": "*", "TGG": "W",
+    "CGT": "R", "CGC": "R", "CGA": "R", "CGG": "R",
+    "AGT": "S", "AGC": "S", "AGA": "R", "AGG": "R",
+    "GGT": "G", "GGC": "G", "GGA": "G", "GGG": "G",
+}
+
+
+def complement(sequence: str) -> str:
+    """Return the base-wise complement (IUPAC aware, preserves length)."""
+    return sequence.translate(_COMPLEMENT)
+
+
+def reverse_complement(sequence: str) -> str:
+    """Return the reverse complement of a DNA sequence."""
+    return sequence.translate(_COMPLEMENT)[::-1]
+
+
+def translate(sequence: str, unknown: str = "X") -> str:
+    """Translate a nucleotide sequence in reading frame 0.
+
+    ``U`` is treated as ``T``. Incomplete trailing codons are dropped.
+    Unknown codons map to ``unknown``.
+    """
+    seq = sequence.upper().replace("U", "T")
+    protein: list[str] = []
+    for i in range(0, len(seq) - 2, 3):
+        codon = seq[i : i + 3]
+        protein.append(CODON_TABLE.get(codon, unknown))
+    return "".join(protein)
+
+
+@dataclass(frozen=True)
+class Frame:
+    """One of the six reading frames of a sequence."""
+
+    strand: str  # '+' or '-'
+    offset: int  # 0, 1 or 2
+    protein: str
+
+    @property
+    def name(self) -> str:
+        return f"{self.strand}{self.offset + 1}"
+
+
+def six_frame_translation(sequence: str, unknown: str = "X") -> list[Frame]:
+    """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.
+    """
+    frames: list[Frame] = []
+    forward = sequence.upper().replace("U", "T")
+    reverse = reverse_complement(forward)
+    for strand, seq in (("+", forward), ("-", reverse)):
+        for offset in range(3):
+            frames.append(Frame(strand, offset, translate(seq[offset:], unknown)))
+    return frames

bioseqkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: bioseqkit
+Version: 0.1.0
+Summary: A lightweight, dependency-free biological sequence processing toolkit (FASTA/FASTQ, stats, k-mer, minimizer, indexing).
+Author-email: Jilai Cheng <chengjilai@sjtu.edu.cn>
+License: MIT
+License-File: LICENSE
+Keywords: bioinformatics,fasta,fastq,kmer,minimizer,sequence
+Requires-Python: >=3.10
+Provides-Extra: docs
+Requires-Dist: myst-parser>=2.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Provides-Extra: net
+Requires-Dist: requests>=2.28; extra == 'net'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7; extra == 'viz'
+Requires-Dist: seaborn>=0.12; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# bioseqkit
+
+A lightweight, **dependency-free** biological sequence processing toolkit built
+from scratch in pure Python. `bioseqkit` implements FASTA/FASTQ parsing,
+sequence statistics, transformations, k-mer / minimizer analysis and FAI-like
+random-access indexing, exposed both as a Python API and a command-line tool.
+
+The project is a teaching implementation for **BIO2502 (Programming Languages
+for Biological Computing)**: it deliberately re-implements the low-level I/O,
+streaming and indexing logic instead of relying on Biopython, so the core
+design patterns of bioinformatics data handling are made explicit.
+
+## Features
+
+- **Streaming FASTA/FASTQ parsers** (`io`) — generator based, constant memory,
+  transparent gzip support, Phred quality decoding.
+- **Statistics** (`stats`) — length distribution, N50, GC content, N-base
+  ratio, base-composition matrix.
+- **Transformations** (`transform`) — reverse complement (IUPAC aware) and
+  six-frame translation with the standard genetic code.
+- **k-mer analysis** (`kmer`) — counting, top-k, canonical k-mers,
+  **multi-process** parallel counting, and **minimizer** sampling.
+- **FAI-like indexing** (`index`) — `samtools faidx`-compatible index for
+  `chr:start-end` random access without scanning the whole file.
+- **CLI** (`cli`) — `stats`, `revcomp`, `translate`, `kmer`, `minimizer`,
+  `index`, `fetch`.
+- **NCBI download** (`entrez`) — fetch reference sequences via E-utilities
+  (standard-library HTTP only).
+
+## Project layout
+
+```
+bioseqkit/
+├── pyproject.toml          # src-layout, PEP 621 metadata, console script
+├── README.md
+├── LICENSE
+├── environment.yml         # conda environment
+├── requirements.txt
+├── src/bioseqkit/
+│   ├── __init__.py         # public API
+│   ├── io.py               # FASTA/FASTQ parsers
+│   ├── stats.py            # sequence statistics
+│   ├── transform.py        # revcomp + six-frame translation
+│   ├── kmer.py             # k-mer / minimizer (serial + parallel)
+│   ├── index.py            # FAI-like random-access index
+│   ├── entrez.py           # NCBI download helper
+│   └── cli.py              # argparse CLI
+├── tests/                  # pytest suite (io/stats/transform/kmer/index/cli)
+├── examples/
+│   ├── demo.ipynb          # Jupyter demo (stats, GC, k-mer spectrum, ...)
+│   └── example_data/sample.fa
+├── docs/                   # Sphinx documentation
+└── .github/workflows/ci.yml
+```
+
+## Installation
+
+Requires Python >= 3.10. The core package has **no runtime dependencies**.
+
+```bash
+# with uv (recommended)
+uv pip install -e .
+
+# or plain pip
+pip install -e .
+
+# with optional extras (plots for the notebook / NCBI download / docs)
+pip install -e ".[viz,net,docs]"
+```
+
+## Command-line usage
+
+```bash
+bioseqkit stats    examples/example_data/sample.fa      # JSON statistics
+bioseqkit revcomp  examples/example_data/sample.fa      # reverse complement
+bioseqkit translate examples/example_data/sample.fa     # six-frame translation
+bioseqkit kmer     examples/example_data/sample.fa -k 5 --top 10 --canonical
+bioseqkit kmer     examples/example_data/sample.fa -k 5 -t 4   # parallel
+bioseqkit minimizer examples/example_data/sample.fa -k 15 -w 10
+bioseqkit index    examples/example_data/sample.fa      # write *.fai
+bioseqkit fetch    examples/example_data/sample.fa seq2:1-16
+```
+
+## Python API
+
+```python
+import bioseqkit as bsk
+
+for rec in bsk.parse_fasta("examples/example_data/sample.fa"):
+    print(rec.id, len(rec), bsk.gc_content(rec.sequence))
+
+print(bsk.reverse_complement("ATGC"))            # -> GCAT
+print(bsk.translate("ATGGCCTAA"))                # -> MA*
+
+counts = bsk.count_kmers("ACGTACGTACGT", k=3, canonical=True)
+print(bsk.top_kmers(counts, 3))
+
+idx = bsk.build_faidx("examples/example_data/sample.fa")
+print(idx.fetch("seq2", 1, 16))
+```
+
+## Testing
+
+```bash
+uv run --with pytest pytest -q      # 39 tests
+```
+
+Continuous integration (GitHub Actions) runs `ruff` linting and the `pytest`
+suite on Python 3.10–3.12 for every push.
+
+## Data sources
+
+- NCBI Nucleotide: <https://www.ncbi.nlm.nih.gov/nucleotide/>
+- UCSC Genome Browser: <https://genome.ucsc.edu/>
+
+The bundled `examples/example_data/sample.fa` is a small synthetic sequence for
+offline testing; `demo.ipynb` will download real data from NCBI when a network
+connection is available and fall back to the bundled file otherwise.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

bioseqkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+bioseqkit/__init__.py,sha256=WPNQec42lcU4LJpPE8jM8Y_fFk1bOGL6MtpVhf7JXzY,1261
+bioseqkit/cli.py,sha256=5lUd-el13pi7ZYis5RQQJbtPz_OecZbNTN5IDKpwn3k,4938
+bioseqkit/entrez.py,sha256=33vTm0Lv7m--P_OdiIw_5wj8zgrrvAebKP--PQnT1oM,1144
+bioseqkit/index.py,sha256=y9KcvGW6ndoKgYLP34sGsCNkSbZ2uf3jU3R2yeUEqCo,6038
+bioseqkit/io.py,sha256=_YXwA2tI6xamdHf1sEdHKczpP8SY7YAiEQNPrgenSFM,5586
+bioseqkit/kmer.py,sha256=JFsAF6BXEfgcb3Dq9NBHVoI7vapI34ctMvS8rFUnZM8,4557
+bioseqkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bioseqkit/stats.py,sha256=QHwkda7nP-ithSaB30QTsXZdR_WrUOQIoWqPYpgAthw,3176
+bioseqkit/transform.py,sha256=lU66dRisQUEpRNHSZC9maz4mAXmcHBr1QnLGFfo5Dug,3110
+bioseqkit-0.1.0.dist-info/METADATA,sha256=o4-fLIUZweJ9NMeDV57QqXvesFYp-_5EyXL4Sch4vfc,5228
+bioseqkit-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+bioseqkit-0.1.0.dist-info/entry_points.txt,sha256=xZmtCloPHVsircuQzpq51XSbYxc4zCLrgtf2SVcva6U,49
+bioseqkit-0.1.0.dist-info/licenses/LICENSE,sha256=8TV7QZtAVFsQL2J6cdUiz2zWvFiWzf7vJ4ix5o3bzK8,1068
+bioseqkit-0.1.0.dist-info/RECORD,,

bioseqkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

bioseqkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bioseqkit = bioseqkit.cli:main

bioseqkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jilai Cheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.