deamtools 0.1.1__tar.gz

deamtools-0.1.1/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+# uv's project environment. uv.lock IS committed — it pins the dev environment.
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+docs/_build/
+*.bam
+*.bai
+*.bw
+*.fa
+*.fai
+
+# /export-generated transcripts (claude-code local command output)
+*-local-command-caveat*.txt

deamtools-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zhijian Li
+
+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.

deamtools-0.1.1/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.5
+Name: deamtools
+Version: 0.1.1
+Summary: A Python command-line toolkit for deamination-based chromatin signal analysis.
+Project-URL: Homepage, https://github.com/lzj1769/deamTools
+Project-URL: Repository, https://github.com/lzj1769/deamTools
+Project-URL: Issues, https://github.com/lzj1769/deamTools/issues
+Project-URL: Documentation, https://lzj1769.github.io/deamTools
+Author: Zhijian Li
+License: MIT
+License-File: LICENSE
+Keywords: accessibility,bioinformatics,chromatin,command-line,deamination,epigenomics,footprinting,genomics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.12
+Requires-Dist: logomaker>=0.8
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: moods-python==1.9.4.1
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2
+Requires-Dist: pybigwig>=0.3.22
+Requires-Dist: pysam>=0.22
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: myst-parser>=2; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=2; extra == 'docs'
+Requires-Dist: sphinx>=7; extra == 'docs'
+Provides-Extra: seq2edit
+Requires-Dist: torch>=2.0; extra == 'seq2edit'
+Description-Content-Type: text/markdown
+
+# DeamTools
+
+A Python command-line toolkit for deaminase-based chromatin accessibility analysis.
+
+DeamTools quantifies cytosine deamination (C→T) events in aligned sequencing reads and converts them into BigWig coverage tracks for genome-browser visualisation and downstream signal analysis. It is designed for deaminase-based assays — such as CHEESE-seq, DamID variants, or any method that uses a deaminase to mark accessible chromatin — where single-base C→T editing events serve as the accessibility signal.
+
+## How it works
+
+For each aligned read, DeamTools scans reference cytosine positions covered by the read and records positions where a C→T (forward strand) or G→A (reverse strand) conversion is observed. These per-base editing counts are accumulated genome-wide and written as a BigWig file.
+
+## Installation
+
+**Requirements:** Python ≥ 3.12, `samtools` (for indexing BAM/FASTA files).
+
+```bash
+git clone https://github.com/lzj1769/deamTools.git
+cd deamTools
+pip install .
+```
+
+For development (adds pytest, ruff, black, mypy):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```bash
+# 1. Sort and index your BAM file
+samtools sort -o sample.sorted.bam sample.bam
+samtools index sample.sorted.bam
+
+# 2. Index the reference FASTA
+samtools faidx hg38.fa
+
+# 3. Convert to BigWig
+deamtools bam2bw \
+    --bam sample.sorted.bam \
+    --fasta hg38.fa \
+    --out_dir results \
+    --out_name sample
+```
+
+## Commands
+
+### Global options
+
+```
+deamtools [--version] [--log_level LEVEL] <command>
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--version` | — | Print version and exit |
+| `--log_level` | `INFO` | Verbosity: `DEBUG`, `INFO`, `WARNING`, or `ERROR` |
+
+---
+
+### `bam2bw` — BAM to BigWig
+
+Convert a coordinate-sorted BAM file to a per-base BigWig track of C→T deamination counts.
+
+```
+deamtools bam2bw --bam FILE --fasta FILE --out_dir DIR --out_name NAME [options]
+```
+
+#### Required arguments
+
+| Argument | Description |
+|---|---|
+| `--bam FILE` | Coordinate-sorted BAM file. Must be indexed (`.bai`). |
+| `--fasta FILE` | Reference FASTA file. Must be indexed with `samtools faidx` (`.fai`). |
+| `--out_dir DIR` | Output directory. Created automatically if it does not exist. |
+| `--out_name NAME` | Base name (without extension) for the output. Writes `<out_dir>/<out_name>.bw`. |
+
+#### Optional arguments
+
+| Argument | Default | Description |
+|---|---|---|
+| `--chrom_sizes FILE` | *(from BAM header)* | Tab-delimited chromosome sizes file (`chrom\tsize`). If omitted, sizes are inferred from the BAM header. |
+| `--regions FILE` | *(whole genome)* | BED file of regions to restrict analysis to. Overlapping intervals are merged automatically. |
+| `--extend_size INT` | `0` | Symmetrically extend each detected editing site by INT base pairs before writing to the BigWig. Useful for smoothing sparse signals or defining accessible windows around editing events. |
+| `--min_mapq INT` | `20` | Minimum read mapping quality. Reads below this threshold are skipped. |
+| `--min_baseq INT` | `20` | Minimum base quality at a position. Bases below this threshold are not counted. |
+| `--threads INT` | `1` | Number of threads for parallel chromosome processing. |
+
+Reads that are unmapped, duplicate, QC-failed, secondary, or supplementary are always excluded regardless of quality thresholds.
+
+#### Examples
+
+```bash
+# Whole-genome run with default quality thresholds
+deamtools bam2bw \
+    --bam sample.bam \
+    --fasta hg38.fa \
+    --out_dir results \
+    --out_name sample
+
+# Restrict to peaks, use stricter filters, run on 4 threads
+deamtools bam2bw \
+    --bam sample.bam \
+    --fasta hg38.fa \
+    --regions peaks.bed \
+    --min_mapq 30 \
+    --min_baseq 30 \
+    --threads 4 \
+    --out_dir results \
+    --out_name sample_peaks
+
+# Extend each editing site by 50 bp in both directions
+deamtools bam2bw \
+    --bam sample.bam \
+    --fasta hg38.fa \
+    --extend_size 50 \
+    --out_dir results \
+    --out_name sample_extended
+
+# Provide an explicit chromosome sizes file and enable debug logging
+deamtools --log_level DEBUG bam2bw \
+    --bam sample.bam \
+    --fasta hg38.fa \
+    --chrom_sizes hg38.chrom.sizes \
+    --out_dir results \
+    --out_name sample
+```
+
+## Running tests
+
+```bash
+pytest                    # run all tests
+pytest -v                 # verbose output
+pytest tests/test_bam2bw.py  # run a specific test file
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

deamtools-0.1.1/README.md

@@ -0,0 +1,138 @@
+# DeamTools
+
+A Python command-line toolkit for deaminase-based chromatin accessibility analysis.
+
+DeamTools quantifies cytosine deamination (C→T) events in aligned sequencing reads and converts them into BigWig coverage tracks for genome-browser visualisation and downstream signal analysis. It is designed for deaminase-based assays — such as CHEESE-seq, DamID variants, or any method that uses a deaminase to mark accessible chromatin — where single-base C→T editing events serve as the accessibility signal.
+
+## How it works
+
+For each aligned read, DeamTools scans reference cytosine positions covered by the read and records positions where a C→T (forward strand) or G→A (reverse strand) conversion is observed. These per-base editing counts are accumulated genome-wide and written as a BigWig file.
+
+## Installation
+
+**Requirements:** Python ≥ 3.12, `samtools` (for indexing BAM/FASTA files).
+
+```bash
+git clone https://github.com/lzj1769/deamTools.git
+cd deamTools
+pip install .
+```
+
+For development (adds pytest, ruff, black, mypy):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```bash
+# 1. Sort and index your BAM file
+samtools sort -o sample.sorted.bam sample.bam
+samtools index sample.sorted.bam
+
+# 2. Index the reference FASTA
+samtools faidx hg38.fa
+
+# 3. Convert to BigWig
+deamtools bam2bw \
+    --bam sample.sorted.bam \
+    --fasta hg38.fa \
+    --out_dir results \
+    --out_name sample
+```
+
+## Commands
+
+### Global options
+
+```
+deamtools [--version] [--log_level LEVEL] <command>
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--version` | — | Print version and exit |
+| `--log_level` | `INFO` | Verbosity: `DEBUG`, `INFO`, `WARNING`, or `ERROR` |
+
+---
+
+### `bam2bw` — BAM to BigWig
+
+Convert a coordinate-sorted BAM file to a per-base BigWig track of C→T deamination counts.
+
+```
+deamtools bam2bw --bam FILE --fasta FILE --out_dir DIR --out_name NAME [options]
+```
+
+#### Required arguments
+
+| Argument | Description |
+|---|---|
+| `--bam FILE` | Coordinate-sorted BAM file. Must be indexed (`.bai`). |
+| `--fasta FILE` | Reference FASTA file. Must be indexed with `samtools faidx` (`.fai`). |
+| `--out_dir DIR` | Output directory. Created automatically if it does not exist. |
+| `--out_name NAME` | Base name (without extension) for the output. Writes `<out_dir>/<out_name>.bw`. |
+
+#### Optional arguments
+
+| Argument | Default | Description |
+|---|---|---|
+| `--chrom_sizes FILE` | *(from BAM header)* | Tab-delimited chromosome sizes file (`chrom\tsize`). If omitted, sizes are inferred from the BAM header. |
+| `--regions FILE` | *(whole genome)* | BED file of regions to restrict analysis to. Overlapping intervals are merged automatically. |
+| `--extend_size INT` | `0` | Symmetrically extend each detected editing site by INT base pairs before writing to the BigWig. Useful for smoothing sparse signals or defining accessible windows around editing events. |
+| `--min_mapq INT` | `20` | Minimum read mapping quality. Reads below this threshold are skipped. |
+| `--min_baseq INT` | `20` | Minimum base quality at a position. Bases below this threshold are not counted. |
+| `--threads INT` | `1` | Number of threads for parallel chromosome processing. |
+
+Reads that are unmapped, duplicate, QC-failed, secondary, or supplementary are always excluded regardless of quality thresholds.
+
+#### Examples
+
+```bash
+# Whole-genome run with default quality thresholds
+deamtools bam2bw \
+    --bam sample.bam \
+    --fasta hg38.fa \
+    --out_dir results \
+    --out_name sample
+
+# Restrict to peaks, use stricter filters, run on 4 threads
+deamtools bam2bw \
+    --bam sample.bam \
+    --fasta hg38.fa \
+    --regions peaks.bed \
+    --min_mapq 30 \
+    --min_baseq 30 \
+    --threads 4 \
+    --out_dir results \
+    --out_name sample_peaks
+
+# Extend each editing site by 50 bp in both directions
+deamtools bam2bw \
+    --bam sample.bam \
+    --fasta hg38.fa \
+    --extend_size 50 \
+    --out_dir results \
+    --out_name sample_extended
+
+# Provide an explicit chromosome sizes file and enable debug logging
+deamtools --log_level DEBUG bam2bw \
+    --bam sample.bam \
+    --fasta hg38.fa \
+    --chrom_sizes hg38.chrom.sizes \
+    --out_dir results \
+    --out_name sample
+```
+
+## Running tests
+
+```bash
+pytest                    # run all tests
+pytest -v                 # verbose output
+pytest tests/test_bam2bw.py  # run a specific test file
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

deamtools-0.1.1/pyproject.toml

@@ -0,0 +1,106 @@
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "deamtools"
+version = "0.1.1"
+description = "A Python command-line toolkit for deamination-based chromatin signal analysis."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [
+  { name = "Zhijian Li" }
+]
+keywords = [
+  "genomics",
+  "epigenomics",
+  "chromatin",
+  "accessibility",
+  "deamination",
+  "footprinting",
+  "bioinformatics",
+  "command-line",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Environment :: Console",
+  "Operating System :: OS Independent",
+]
+
+dependencies = [
+  "numpy>=1.26",
+  "pandas>=2.2",
+  "matplotlib>=3.8",
+  "logomaker>=0.8",
+  "pysam>=0.22",
+  "pyBigWig>=0.3.22",
+  "MOODS-python==1.9.4.1",
+]
+
+[project.optional-dependencies]
+seq2edit = [
+  "torch>=2.0",
+]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+  "ruff>=0.5.0",
+  "black>=24.0",
+  "mypy>=1.10",
+]
+docs = [
+  "sphinx>=7",
+  "myst-parser>=2",
+  "sphinx-rtd-theme>=2",
+]
+
+[project.scripts]
+deamtools = "deamtools.cli.main:main"
+
+[project.urls]
+Homepage = "https://github.com/lzj1769/deamTools"
+Repository = "https://github.com/lzj1769/deamTools"
+Issues = "https://github.com/lzj1769/deamTools/issues"
+Documentation = "https://lzj1769.github.io/deamTools"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/deamtools"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/tests",
+  "/README.md",
+  "/LICENSE",
+  "/pyproject.toml",
+]
+
+[tool.black]
+line-length = 88
+target-version = ["py312"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-q"
+
+[tool.mypy]
+python_version = "3.12"
+warn_unused_configs = true
+disallow_untyped_defs = false
+ignore_missing_imports = true

deamtools-0.1.1/src/deamtools/__main__.py

@@ -0,0 +1,5 @@
+from deamtools.cli.main import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

deamtools-0.1.1/src/deamtools/align/__init__.py

@@ -0,0 +1,6 @@
+"""Deamination-aware alignment using a bwa-meth-style strategy."""
+
+from deamtools.align.align import run_align
+from deamtools.align.index import run_index
+
+__all__ = ["run_align", "run_index"]