countmut 0.0.1__tar.gz

countmut-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ye Chang
+
+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.

countmut-0.0.1/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: countmut
+Version: 0.0.1
+Summary: Ultra-fast strand-aware mutation counter
+Author-email: Ye Chang <yech1990@gmail.com>
+License-Expression: MIT
+Keywords: bioinformatics,bam,pileup,mutation,bisulfite,sequencing,genomics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pysam>=0.21.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich-click>=1.6.0
+Requires-Dist: numpy>=1.21.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.14.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Dynamic: license-file
+
+# CountMut 🧬
+
+[![CI](https://github.com/y9c/countmut/actions/workflows/ci.yml/badge.svg)](https://github.com/y9c/countmut/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/countmut.svg)](https://badge.fury.io/py/countmut)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Ultra-fast strand-aware mutation counter**
+
+CountMut counts mutations from bisulfite sequencing /  BAM files with parallel processing, quality-based mate overlap deduplication, and optimized file I/O.
+
+## Features
+
+- 🚀 **Ultra-Fast**: Direct FASTA index reading, shared file handles, BGZF multi-threading
+- 🧬 **Bisulfite Support**: NS, Zf, Yf tag filtering for conversion analysis
+- 🎯 **Accurate**: Quality-based mate overlap deduplication prevents double-counting
+- ⚡ **Parallel**: Multi-threaded genomic window processing
+- 🔧 **Flexible**: Configurable filtering, strand-specific processing, auto-indexing
+
+## Installation
+
+```bash
+pip install countmut
+```
+
+## Quick Start
+
+```bash
+# Basic usage - auto-creates indices if needed
+countmut -i input.bam -r reference.fa -o mutations.tsv
+
+# Count T→C mutations (common in bisulfite sequencing)
+countmut -i input.bam -r reference.fa -o mutations.tsv --ref-base T --mut-base C
+
+# With custom threads and filtering
+countmut -i input.bam -r reference.fa -o mutations.tsv -t 8 --max-unc 5 --min-con 2
+```
+
+## Key Options
+
+```bash
+Required:
+  -i, --input PATH           Input BAM file
+  -r, --reference PATH       Reference FASTA file
+
+Output:
+  -o, --output PATH          Output TSV file (default: stdout)
+
+Mutation:
+  --ref-base TEXT            Reference base [default: A]
+  --mut-base TEXT            Mutation base [default: G]
+  --strand [both|forward|reverse]  Strand processing [default: both]
+  --region TEXT              Specific region (e.g., 'chr1:1000000-2000000')
+
+Performance:
+  -t, --threads INTEGER      Number of threads [default: auto]
+  -b, --bin-size INTEGER     Genomic bin size [default: 10000]
+
+Filtering (Bisulfite):
+  --pad INTEGER              Motif window padding [default: 15]
+  --trim-start INTEGER       Trim 5' bases [default: 2]
+  --trim-end INTEGER         Trim 3' bases [default: 2]
+  --max-unc INTEGER          Max unconverted (Zf) [default: 3]
+  --min-con INTEGER          Min converted (Yf) [default: 1]
+  --max-sub INTEGER          Max substitutions (NS) [default: 1]
+```
+
+**Note**: BAM must have NS, Zf, and Yf tags for bisulfite analysis.
+
+## Output Format
+
+TSV file with columns:
+- `chrom`, `pos`, `strand`, `motif` - Position and context
+- `u0`, `d0` - Drop counts (trimmed/unmapped bases)
+- `u1`, `d1` - Clean counts (converted reads)
+- `u2`, `d2` - Unconverted counts
+
+## Performance
+
+Real-world test (3 rRNA genes, 17k reads):
+- **Before optimization**: 16.7s
+- **After optimization**: 4.5s (3.7x faster)
+- **Startup**: 0.2s vs 3.2s (16x faster FASTA index loading)
+
+## Python API
+
+```python
+from countmut import count_mutations
+
+success = count_mutations(
+    samfile="input.bam",
+    reffile="reference.fa",
+    output_file="mutations.tsv",
+    ref_base="T",
+    mut_base="C",
+    threads=8,
+    max_unc=3,
+    min_con=1,
+    max_sub=1
+)
+```
+
+## Requirements
+
+- Python 3.10+
+- pysam, rich, click, rich-click, numpy
+- BAM files: coordinate-sorted with `.bai` index (auto-created if missing)
+- FASTA files: with `.fai` index (auto-created if missing)
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/y9c/countmut.git
+cd countmut
+uv sync --dev
+
+# Run tests
+uv run pytest tests/ -v
+
+# Lint
+uv run ruff check .
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file.
+
+## Citation
+
+If you use CountMut in your research, please cite:
+
+```
+Ye Chang. (2025). CountMut: Ultra-fast parallel mutation counter for bisulfite sequencing.
+GitHub: https://github.com/y9c/countmut
+```
+
+## Contact
+
+- **Author**: Ye Chang
+- **Email**: yech1990@gmail.com
+- **Issues**: https://github.com/y9c/countmut/issues
+
+---
+
+**Version 0.0.1** | **MIT License**

countmut-0.0.1/README.md

@@ -0,0 +1,146 @@
+# CountMut 🧬
+
+[![CI](https://github.com/y9c/countmut/actions/workflows/ci.yml/badge.svg)](https://github.com/y9c/countmut/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/countmut.svg)](https://badge.fury.io/py/countmut)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Ultra-fast strand-aware mutation counter**
+
+CountMut counts mutations from bisulfite sequencing /  BAM files with parallel processing, quality-based mate overlap deduplication, and optimized file I/O.
+
+## Features
+
+- 🚀 **Ultra-Fast**: Direct FASTA index reading, shared file handles, BGZF multi-threading
+- 🧬 **Bisulfite Support**: NS, Zf, Yf tag filtering for conversion analysis
+- 🎯 **Accurate**: Quality-based mate overlap deduplication prevents double-counting
+- ⚡ **Parallel**: Multi-threaded genomic window processing
+- 🔧 **Flexible**: Configurable filtering, strand-specific processing, auto-indexing
+
+## Installation
+
+```bash
+pip install countmut
+```
+
+## Quick Start
+
+```bash
+# Basic usage - auto-creates indices if needed
+countmut -i input.bam -r reference.fa -o mutations.tsv
+
+# Count T→C mutations (common in bisulfite sequencing)
+countmut -i input.bam -r reference.fa -o mutations.tsv --ref-base T --mut-base C
+
+# With custom threads and filtering
+countmut -i input.bam -r reference.fa -o mutations.tsv -t 8 --max-unc 5 --min-con 2
+```
+
+## Key Options
+
+```bash
+Required:
+  -i, --input PATH           Input BAM file
+  -r, --reference PATH       Reference FASTA file
+
+Output:
+  -o, --output PATH          Output TSV file (default: stdout)
+
+Mutation:
+  --ref-base TEXT            Reference base [default: A]
+  --mut-base TEXT            Mutation base [default: G]
+  --strand [both|forward|reverse]  Strand processing [default: both]
+  --region TEXT              Specific region (e.g., 'chr1:1000000-2000000')
+
+Performance:
+  -t, --threads INTEGER      Number of threads [default: auto]
+  -b, --bin-size INTEGER     Genomic bin size [default: 10000]
+
+Filtering (Bisulfite):
+  --pad INTEGER              Motif window padding [default: 15]
+  --trim-start INTEGER       Trim 5' bases [default: 2]
+  --trim-end INTEGER         Trim 3' bases [default: 2]
+  --max-unc INTEGER          Max unconverted (Zf) [default: 3]
+  --min-con INTEGER          Min converted (Yf) [default: 1]
+  --max-sub INTEGER          Max substitutions (NS) [default: 1]
+```
+
+**Note**: BAM must have NS, Zf, and Yf tags for bisulfite analysis.
+
+## Output Format
+
+TSV file with columns:
+- `chrom`, `pos`, `strand`, `motif` - Position and context
+- `u0`, `d0` - Drop counts (trimmed/unmapped bases)
+- `u1`, `d1` - Clean counts (converted reads)
+- `u2`, `d2` - Unconverted counts
+
+## Performance
+
+Real-world test (3 rRNA genes, 17k reads):
+- **Before optimization**: 16.7s
+- **After optimization**: 4.5s (3.7x faster)
+- **Startup**: 0.2s vs 3.2s (16x faster FASTA index loading)
+
+## Python API
+
+```python
+from countmut import count_mutations
+
+success = count_mutations(
+    samfile="input.bam",
+    reffile="reference.fa",
+    output_file="mutations.tsv",
+    ref_base="T",
+    mut_base="C",
+    threads=8,
+    max_unc=3,
+    min_con=1,
+    max_sub=1
+)
+```
+
+## Requirements
+
+- Python 3.10+
+- pysam, rich, click, rich-click, numpy
+- BAM files: coordinate-sorted with `.bai` index (auto-created if missing)
+- FASTA files: with `.fai` index (auto-created if missing)
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/y9c/countmut.git
+cd countmut
+uv sync --dev
+
+# Run tests
+uv run pytest tests/ -v
+
+# Lint
+uv run ruff check .
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file.
+
+## Citation
+
+If you use CountMut in your research, please cite:
+
+```
+Ye Chang. (2025). CountMut: Ultra-fast parallel mutation counter for bisulfite sequencing.
+GitHub: https://github.com/y9c/countmut
+```
+
+## Contact
+
+- **Author**: Ye Chang
+- **Email**: yech1990@gmail.com
+- **Issues**: https://github.com/y9c/countmut/issues
+
+---
+
+**Version 0.0.1** | **MIT License**

countmut-0.0.1/countmut/__init__.py

@@ -0,0 +1,27 @@
+"""
+CountMut - Fast, parallel mutation counting from BAM pileup data
+
+This package provides efficient mutation counting functionality with:
+- Parallel processing using genomic windows
+- Bisulfite conversion analysis
+- Rich logging and progress tracking
+- Modern CLI interface
+
+Author: Ye Chang
+Date: 2025-10-23
+"""
+
+from .cli import main
+from .core import count_mutations
+from .utils import format_duration, get_output_headers, write_output
+
+__author__ = "Ye Chang"
+__email__ = "yech1990@gmail.com"
+
+__all__ = [
+    "count_mutations",
+    "format_duration",
+    "get_output_headers",
+    "main",
+    "write_output",
+]