bioseqkit 0.1.0__tar.gz

bioseqkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[viz]" pytest ruff
+      - name: Lint
+        run: ruff check src tests
+      - name: Test
+        run: pytest -q

bioseqkit-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Generated artifacts
+*.fai
+.pytest_cache/
+.ruff_cache/
+docs/_build/
+.ipynb_checkpoints/

bioseqkit-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

bioseqkit-0.1.0/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.

bioseqkit-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,122 @@
+# 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/docs/conf.py

@@ -0,0 +1,19 @@
+"""Sphinx configuration for bioseqkit."""
+
+project = "bioseqkit"
+author = "Jilai Cheng"
+release = "0.1.0"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "myst_parser",
+]
+
+autodoc_typehints = "description"
+templates_path = ["_templates"]
+exclude_patterns = ["_build"]
+
+html_theme = "alabaster"
+source_suffix = {".rst": "restructuredtext", ".md": "markdown"}

bioseqkit-0.1.0/docs/index.rst

@@ -0,0 +1,36 @@
+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.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   quickstart
+
+API reference
+-------------
+
+.. automodule:: bioseqkit.io
+   :members:
+
+.. automodule:: bioseqkit.stats
+   :members:
+
+.. automodule:: bioseqkit.transform
+   :members:
+
+.. automodule:: bioseqkit.kmer
+   :members:
+
+.. automodule:: bioseqkit.index
+   :members:
+
+Indices
+-------
+
+* :ref:`genindex`
+* :ref:`modindex`

bioseqkit-0.1.0/docs/quickstart.md

@@ -0,0 +1,21 @@
+# Quickstart
+
+Install the package and run the CLI:
+
+```bash
+pip install -e .
+bioseqkit stats examples/example_data/sample.fa
+```
+
+Use the Python API:
+
+```python
+import bioseqkit as bsk
+
+records = list(bsk.parse_fasta("examples/example_data/sample.fa"))
+stats = bsk.sequence_stats(r.sequence for r in records)
+print(stats.as_dict())
+
+print(bsk.reverse_complement("ATGC"))          # GCAT
+print(bsk.count_kmers("ACGTACGT", 3).most_common(3))
+```

bioseqkit-0.1.0/environment.yml

@@ -0,0 +1,17 @@
+name: bioseqkit
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - python>=3.10
+  - pip
+  - matplotlib
+  - seaborn
+  - jupyter
+  - pip:
+      - -e .
+      - pytest
+      - pytest-benchmark
+      - ruff
+      - sphinx
+      - myst-parser

bioseqkit-0.1.0/examples/demo.ipynb

@@ -0,0 +1,222 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# bioseqkit demo\n",
+    "\n",
+    "This notebook demonstrates the core features of **bioseqkit** on a real\n",
+    "sequence. It tries to download the *E. coli* K-12 MG1655 genome region (or\n",
+    "the human mitochondrion `chrM`) from NCBI; if there is no network access it\n",
+    "falls back to the bundled `example_data/sample.fa`.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 1. Load data (NCBI with local fallback)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "import bioseqkit as bsk\n",
+    "\n",
+    "DATA = Path('example_data/sample.fa')\n",
+    "records = list(bsk.parse_fasta(str(DATA)))\n",
+    "\n",
+    "# Optional: fetch a real genome from NCBI (needs internet).\n",
+    "try:\n",
+    "    from bioseqkit.entrez import efetch_fasta\n",
+    "    import io\n",
+    "    fasta_text = efetch_fasta('NC_012920.1', email='you@example.com')  # human chrM\n",
+    "    records = list(bsk.parse_fasta(io.StringIO(fasta_text)))\n",
+    "    print('Downloaded from NCBI:', records[0].id, records[0].description)\n",
+    "except Exception as exc:\n",
+    "    print('Using local example data (no network):', exc)\n",
+    "\n",
+    "for r in records:\n",
+    "    print(r.id, len(r), r.description)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. Basic statistics"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "stats = bsk.sequence_stats(r.sequence for r in records)\n",
+    "import json\n",
+    "print(json.dumps(stats.as_dict(), indent=2))\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 3. GC content & length distribution"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "gc = [bsk.gc_content(r.sequence) for r in records]\n",
+    "lengths = [len(r) for r in records]\n",
+    "\n",
+    "fig, axes = plt.subplots(1, 2, figsize=(10, 4))\n",
+    "axes[0].bar([r.id for r in records], gc, color='steelblue')\n",
+    "axes[0].set_ylabel('GC content'); axes[0].set_title('GC content per sequence')\n",
+    "axes[1].bar([r.id for r in records], lengths, color='indianred')\n",
+    "axes[1].set_ylabel('length (bp)'); axes[1].set_title('Sequence length')\n",
+    "plt.tight_layout(); plt.show()\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 4. k-mer spectrum"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from collections import Counter\n",
+    "k = 4\n",
+    "counts = Counter()\n",
+    "for r in records:\n",
+    "    counts += bsk.count_kmers(r.sequence, k, canonical=True)\n",
+    "\n",
+    "print('Top-10 canonical %d-mers:' % k)\n",
+    "for kmer, c in bsk.top_kmers(counts, 10):\n",
+    "    print(f'  {kmer}\\t{c}')\n",
+    "\n",
+    "# k-mer spectrum: histogram of k-mer multiplicities\n",
+    "spectrum = Counter(counts.values())\n",
+    "xs = sorted(spectrum)\n",
+    "plt.figure(figsize=(6, 4))\n",
+    "plt.bar(xs, [spectrum[x] for x in xs], color='seagreen')\n",
+    "plt.xlabel('k-mer multiplicity'); plt.ylabel('# distinct k-mers')\n",
+    "plt.title(f'{k}-mer spectrum'); plt.tight_layout(); plt.show()\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 5. Six-frame translation vs. known CDS"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "seq = records[0].sequence\n",
+    "for frame in bsk.six_frame_translation(seq):\n",
+    "    print(frame.name, frame.protein[:60])\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 6. Minimizer distribution"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mins = bsk.minimizers(records[0].sequence, k=8, w=5)\n",
+    "positions = [p for p, _ in mins]\n",
+    "print(f'{len(mins)} minimizers selected from {len(records[0])} bp')\n",
+    "plt.figure(figsize=(8, 2))\n",
+    "plt.eventplot(positions, colors='black')\n",
+    "plt.xlabel('position (bp)'); plt.title('Minimizer positions'); plt.yticks([])\n",
+    "plt.tight_layout(); plt.show()\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 7. Random access with the FAI-like index"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from bioseqkit.index import build_faidx\n",
+    "idx = build_faidx(str(DATA))\n",
+    "name = idx.names()[0]\n",
+    "print('Index records:', idx.names())\n",
+    "print('Fetch', name, '1-20:', idx.fetch(name, 1, 20))\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 8. Multithreaded k-mer benchmark\n",
+    "Compare single-process vs. multi-process k-mer counting on a larger sequence."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import time\n",
+    "big = (records[0].sequence * 2000)\n",
+    "print(f'sequence length: {len(big):,} bp')\n",
+    "\n",
+    "t0 = time.perf_counter(); c1 = bsk.count_kmers(big, 8, canonical=True); t1 = time.perf_counter()\n",
+    "c4 = bsk.count_kmers_parallel([big], 8, canonical=True, workers=4); t2 = time.perf_counter()\n",
+    "print(f'serial:   {t1 - t0:.3f}s')\n",
+    "print(f'parallel: {t2 - t1:.3f}s  (identical result: {c1 == c4})')\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.x"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

bioseqkit-0.1.0/examples/example_data/sample.fa

@@ -0,0 +1,5 @@
+>seq1 synthetic demo sequence
+ATGGCCATTGTAATGGGCCGCTGAAAGGGTGCCCGATAGACGTACGTACGTACGTACGTAC
+GTACGTACGTACGGCCTTAAGGCCTTAAGGCCNNNNACGTACGTACGTACGTACGTACGTA
+>seq2 gc-rich fragment
+GGGGCCCCGGGGCCCCGGGGCCCCGGGGCCCCATATATATATATGCGCGCGCGCGCGCGCG

bioseqkit-0.1.0/homework.md

@@ -0,0 +1,3 @@
+课程项目报告(typst)，需包含摘要、背景、项目设计、测试结果、讨论、参考文献
+项目代码需要完整、规范的结构，以及详细的说明README.md
+录制的介绍项目视频，包含项目介绍和演示，格式为mp4