quantnado 0.3.2__tar.gz

quantnado-0.3.2/.github/workflows/build-container.yml

@@ -0,0 +1,36 @@
+name: Build CI Container
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'pyproject.toml'
+      - 'Dockerfile'
+      - '.github/workflows/build-container.yml'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ghcr.io/milne-group/quantnado-ci:latest

quantnado-0.3.2/.github/workflows/deploy-docs.yml

@@ -0,0 +1,48 @@
+name: Build and Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - id: cache-id
+        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_OUTPUT
+
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ steps.cache-id.outputs.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install OS dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc git cmake make libtool g++ perl coreutils \
+            libcurl4-openssl-dev libbz2-dev liblzma-dev zlib1g-dev
+
+      - name: Install package with docs dependencies
+        run: |
+          pip install mkdocs mkdocs-material mkdocstrings mkdocstrings-python pymdown-extensions
+          SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0 pip install -e . --no-deps
+
+      - name: Build
+        run: mkdocs build
+
+      - name: Deploy
+        run: mkdocs gh-deploy --force

quantnado-0.3.2/.github/workflows/pypi.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip --no-cache-dir
+        pip install build --no-cache-dir
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@release/v1

quantnado-0.3.2/.github/workflows/python-tests.yml

@@ -0,0 +1,25 @@
+name: Run Python Tests
+
+on:
+  push
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.13'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[dev]"
+
+      - name: Run tests
+        run: pytest tests

quantnado-0.3.2/.gitignore

@@ -0,0 +1,25 @@
+.DS_Store
+.vscode
+.vscode/
+*__pycache__/
+*.bed
+*.egg-info/
+*.log
+*.sh
+*.zarr
+*/_version.py
+build/
+data/
+epiquant/
+example/*.log
+example/combined_metadata.csv
+example/figures/
+logs/
+modality
+my_test/
+notebooks/
+site/
+sps*
+test_dataset.ipynb
+test_output/
+202*

quantnado-0.3.2/Dockerfile

@@ -0,0 +1,26 @@
+FROM python:3.13-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    g++ \
+    make \
+    zlib1g-dev \
+    libbz2-dev \
+    liblzma-dev \
+    libcurl4-openssl-dev \
+    libssl-dev \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml ./
+# Dummy package so pip can resolve extras without the full source
+RUN mkdir -p quantnado && touch quantnado/__init__.py
+
+ENV SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0
+
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir ".[dev]"
+
+WORKDIR /workspace

quantnado-0.3.2/LICENSE

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

quantnado-0.3.2/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: quantnado
+Version: 0.3.2
+Summary: Dataset generation and peak calling for multi-modal Next-Generation Sequencing data
+Author: Alastair Smith
+Author-email: Catherine Chahrour <catherine.chahrour@imm.ox.ac.uk>
+License-Expression: MIT
+Requires-Python: <3.14,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bamnado
+Requires-Dist: crested
+Requires-Dist: dask-ml<2027,>=2025
+Requires-Dist: dask>=2026
+Requires-Dist: icechunk>=1.1
+Requires-Dist: loguru>=0.7
+Requires-Dist: numpy<3.0,>=2.0
+Requires-Dist: pandas<4.0,>=3.0
+Requires-Dist: pyBigWig>=0.3
+Requires-Dist: pyranges==0.1.4
+Requires-Dist: pysam>=0.23
+Requires-Dist: seaborn>=0.13
+Requires-Dist: sparse>=0.18
+Requires-Dist: tqdm>=4.67
+Requires-Dist: typer>=0.24
+Requires-Dist: xarray>=2026
+Requires-Dist: zarr<4.0,>=3.0
+Provides-Extra: dev
+Requires-Dist: mkdocs-material; extra == "dev"
+Requires-Dist: mkdocs>=1.6; extra == "dev"
+Requires-Dist: mkdocstrings-python; extra == "dev"
+Requires-Dist: mkdocstrings; extra == "dev"
+Requires-Dist: pymdown-extensions; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: ipykernel; extra == "dev"
+Requires-Dist: pysam; extra == "dev"
+Requires-Dist: crested; extra == "dev"
+Dynamic: license-file
+
+# QuantNado
+
+**Dataset generation and peak calling for multi-modal Next-Generation Sequencing data.**
+
+[![CI](https://github.com/Milne-Group/QuantNado/actions/workflows/python-tests.yml/badge.svg)](https://github.com/Milne-Group/QuantNado/actions/workflows/python-tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/quantnado)](https://pypi.org/project/quantnado)
+[![Docs](https://img.shields.io/badge/docs-milne--group.github.io-blue)](https://milne-group.github.io/QuantNado/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue)](https://pypi.org/project/quantnado)
+
+QuantNado provides efficient Zarr-backed storage and analysis of genomic signal from BAM and bigWig files, with support for signal reduction, feature counting, dimensionality reduction, and quantile-based peak calling.
+
+---
+
+## Installation
+
+```bash
+pip install quantnado
+```
+
+Requires Python 3.12 or 3.13.
+
+---
+
+## Quick Start
+
+### Create a dataset from BAM files
+
+```python
+from quantnado import QuantNado
+
+qn = QuantNado.from_bam_files(
+    bam_files=["sample1.bam", "sample2.bam", "sample3.bam"],
+    store_path="dataset.zarr",
+    metadata="samples.csv",  # optional
+)
+```
+
+### Load and analyse an existing dataset
+
+```python
+from quantnado import QuantNado
+
+qn = QuantNado.open("dataset.zarr")
+
+# Aggregate signal over genomic ranges
+promoter_signal = qn.reduce("promoters.bed", reduction="mean")
+print(promoter_signal["mean"].shape)  # (n_promoters, n_samples)
+
+# PCA on reduced signal
+pca_obj, transformed = qn.pca(promoter_signal["mean"], n_components=10)
+print(transformed.shape)  # (n_samples, 10)
+
+# Generate a count matrix for DESeq2
+counts, features = qn.feature_counts("genes.gtf", feature_type="gene")
+counts.to_csv("counts.csv")
+
+# Extract signal over a specific region
+region = qn.extract_region("chr1:1000-5000")
+print(region.shape)  # (n_samples, 4000)
+```
+
+---
+
+## Command-line Interface
+
+QuantNado installs a `quantnado` command with two subcommands.
+
+### `create-dataset` — build a Zarr dataset from BAM files
+
+```bash
+quantnado create-dataset sample1.bam sample2.bam sample3.bam \
+  --output dataset.zarr \
+  --chromsizes hg38.chrom.sizes \
+  --metadata samples.csv \
+  --max-workers 8
+```
+
+### `call-peaks` — call quantile-based peaks from bigWig files
+
+```bash
+quantnado call-peaks \
+  --bigwig-dir path/to/bigwigs/ \
+  --output-dir peaks/ \
+  --chromsizes hg38.chrom.sizes \
+  --quantile 0.98
+```
+
+Run `quantnado --help` or `quantnado <subcommand> --help` for full option listings.
+
+---
+
+## API Reference
+
+Full documentation is available at [milne-group.github.io/QuantNado](https://milne-group.github.io/QuantNado/).
+
+### `QuantNado`
+
+| Method / Property | Description |
+|---|---|
+| `QuantNado.from_bam_files(bam_files, store_path, ...)` | Create a new dataset from BAM files |
+| `QuantNado.open(store_path, read_only=True)` | Open an existing dataset |
+| `.reduce(ranges, reduction="mean")` | Aggregate signal over genomic ranges (BED) |
+| `.feature_counts(gtf_file, feature_type="gene")` | Generate a DESeq2-compatible count matrix |
+| `.pca(data, n_components=10)` | Run PCA on a signal matrix |
+| `.extract_region(region)` | Extract raw signal for a genomic region |
+| `.to_xarray(chromosomes)` | Load dataset as lazy xarray DataArrays |
+| `.samples` | List of sample names |
+| `.metadata` | Sample metadata (DataFrame) |
+| `.chromosomes` | Available chromosome names |
+| `.chromsizes` | Chromosome sizes (dict) |
+| `.store_path` | Path to the underlying Zarr store |
+
+---
+
+## Requirements
+
+| Dependency | Purpose |
+|---|---|
+| `zarr`, `icechunk` | Zarr v3 storage backend |
+| `xarray`, `dask` | Lazy array operations |
+| `pandas`, `numpy` | Data structures |
+| `pysam`, `bamnado` | BAM file I/O |
+| `pyBigWig` | bigWig I/O |
+| `pyranges` | Genomic range operations |
+| `scikit-learn` (via `dask-ml`) | PCA |
+| `typer`, `loguru` | CLI and logging |
+
+Optional extras for deep learning-based peak calling:
+
+```bash
+pip install "quantnado[ml]"
+```
+
+Installs `torch`, `modisco-lite`, and `crested`.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

quantnado-0.3.2/README.md

@@ -0,0 +1,141 @@
+# QuantNado
+
+**Dataset generation and peak calling for multi-modal Next-Generation Sequencing data.**
+
+[![CI](https://github.com/Milne-Group/QuantNado/actions/workflows/python-tests.yml/badge.svg)](https://github.com/Milne-Group/QuantNado/actions/workflows/python-tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/quantnado)](https://pypi.org/project/quantnado)
+[![Docs](https://img.shields.io/badge/docs-milne--group.github.io-blue)](https://milne-group.github.io/QuantNado/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue)](https://pypi.org/project/quantnado)
+
+QuantNado provides efficient Zarr-backed storage and analysis of genomic signal from BAM and bigWig files, with support for signal reduction, feature counting, dimensionality reduction, and quantile-based peak calling.
+
+---
+
+## Installation
+
+```bash
+pip install quantnado
+```
+
+Requires Python 3.12 or 3.13.
+
+---
+
+## Quick Start
+
+### Create a dataset from BAM files
+
+```python
+from quantnado import QuantNado
+
+qn = QuantNado.from_bam_files(
+    bam_files=["sample1.bam", "sample2.bam", "sample3.bam"],
+    store_path="dataset.zarr",
+    metadata="samples.csv",  # optional
+)
+```
+
+### Load and analyse an existing dataset
+
+```python
+from quantnado import QuantNado
+
+qn = QuantNado.open("dataset.zarr")
+
+# Aggregate signal over genomic ranges
+promoter_signal = qn.reduce("promoters.bed", reduction="mean")
+print(promoter_signal["mean"].shape)  # (n_promoters, n_samples)
+
+# PCA on reduced signal
+pca_obj, transformed = qn.pca(promoter_signal["mean"], n_components=10)
+print(transformed.shape)  # (n_samples, 10)
+
+# Generate a count matrix for DESeq2
+counts, features = qn.feature_counts("genes.gtf", feature_type="gene")
+counts.to_csv("counts.csv")
+
+# Extract signal over a specific region
+region = qn.extract_region("chr1:1000-5000")
+print(region.shape)  # (n_samples, 4000)
+```
+
+---
+
+## Command-line Interface
+
+QuantNado installs a `quantnado` command with two subcommands.
+
+### `create-dataset` — build a Zarr dataset from BAM files
+
+```bash
+quantnado create-dataset sample1.bam sample2.bam sample3.bam \
+  --output dataset.zarr \
+  --chromsizes hg38.chrom.sizes \
+  --metadata samples.csv \
+  --max-workers 8
+```
+
+### `call-peaks` — call quantile-based peaks from bigWig files
+
+```bash
+quantnado call-peaks \
+  --bigwig-dir path/to/bigwigs/ \
+  --output-dir peaks/ \
+  --chromsizes hg38.chrom.sizes \
+  --quantile 0.98
+```
+
+Run `quantnado --help` or `quantnado <subcommand> --help` for full option listings.
+
+---
+
+## API Reference
+
+Full documentation is available at [milne-group.github.io/QuantNado](https://milne-group.github.io/QuantNado/).
+
+### `QuantNado`
+
+| Method / Property | Description |
+|---|---|
+| `QuantNado.from_bam_files(bam_files, store_path, ...)` | Create a new dataset from BAM files |
+| `QuantNado.open(store_path, read_only=True)` | Open an existing dataset |
+| `.reduce(ranges, reduction="mean")` | Aggregate signal over genomic ranges (BED) |
+| `.feature_counts(gtf_file, feature_type="gene")` | Generate a DESeq2-compatible count matrix |
+| `.pca(data, n_components=10)` | Run PCA on a signal matrix |
+| `.extract_region(region)` | Extract raw signal for a genomic region |
+| `.to_xarray(chromosomes)` | Load dataset as lazy xarray DataArrays |
+| `.samples` | List of sample names |
+| `.metadata` | Sample metadata (DataFrame) |
+| `.chromosomes` | Available chromosome names |
+| `.chromsizes` | Chromosome sizes (dict) |
+| `.store_path` | Path to the underlying Zarr store |
+
+---
+
+## Requirements
+
+| Dependency | Purpose |
+|---|---|
+| `zarr`, `icechunk` | Zarr v3 storage backend |
+| `xarray`, `dask` | Lazy array operations |
+| `pandas`, `numpy` | Data structures |
+| `pysam`, `bamnado` | BAM file I/O |
+| `pyBigWig` | bigWig I/O |
+| `pyranges` | Genomic range operations |
+| `scikit-learn` (via `dask-ml`) | PCA |
+| `typer`, `loguru` | CLI and logging |
+
+Optional extras for deep learning-based peak calling:
+
+```bash
+pip install "quantnado[ml]"
+```
+
+Installs `torch`, `modisco-lite`, and `crested`.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

quantnado-0.3.2/docs/api/bamstore.md

@@ -0,0 +1,4 @@
+::: quantnado.dataset.bam.BamStore
+    options:
+      show_source: true
+      show_root_heading: true

quantnado-0.3.2/docs/api/quantnado.md

@@ -0,0 +1,4 @@
+::: quantnado.api.QuantNado
+    options:
+      show_source: true
+      show_root_heading: true

quantnado-0.3.2/docs/basic_usage.md

@@ -0,0 +1,134 @@
+# Basic Usage
+
+Common workflows and analysis patterns with QuantNado.
+
+## Creating Datasets
+
+### From Single BAM File
+
+```bash
+quantnado create-dataset sample.bam \
+  --output sample.zarr \
+  --chromsizes hg38.chrom.sizes
+```
+
+### From Multiple BAM Files
+
+Process all BAM files in a directory:
+
+```bash
+quantnado create-dataset results/aligned/*.bam \
+  --output my_cohort.zarr \
+  --chromsizes hg38.chrom.sizes \
+  --max-workers 8
+```
+
+### With Sample Metadata
+
+Create a CSV with sample information (`metadata.csv`):
+
+```
+sample_id,condition,replicate
+sample1,control,1
+sample2,control,2
+sample3,treatment,1
+sample4,treatment,2
+```
+
+Then:
+
+```bash
+quantnado create-dataset *.bam \
+  --output dataset.zarr \
+  --chromsizes hg38.chrom.sizes \
+  --metadata metadata.csv
+```
+
+## Peak Calling
+
+### Basic Peak Calling
+
+```bash
+quantnado call-peaks \
+  --bigwig-dir ./bigwigs/ \
+  --output-dir ./peaks/ \
+  --chromsizes hg38.chrom.sizes \
+  --quantile 0.98
+```
+
+Output: One BED file per sample in `./peaks/`
+
+### Filtering and Merging
+
+```bash
+quantnado call-peaks \
+  --bigwig-dir ./bigwigs/ \
+  --output-dir ./peaks/ \
+  --chromsizes hg38.chrom.sizes \
+  --quantile 0.95 \
+  --merge  # Merge overlapping peaks
+```
+
+## Python API
+
+### Loading a Dataset
+
+```python
+from quantnado import QuantNado
+
+# Open existing dataset
+qn = QuantNado.open("my_dataset.zarr")
+
+# Check samples
+print(qn.samples)
+print(qn.metadata)
+```
+
+### Accessing Data
+
+```python
+# Get data for a specific region (returns xarray DataArray)
+region_data = qn.extract_region("chr1:1000000-2000000")
+
+# Get all chromosomes as a dict of lazy xarray DataArrays
+all_chroms = qn.to_xarray()
+chr1_data = all_chroms["chr1"]
+
+# Compute and convert to pandas DataFrame
+df = chr1_data.to_dataframe(name="signal")
+```
+
+### Creating Datasets Programmatically
+
+```python
+from quantnado import BamStore
+import pandas as pd
+
+# Create from BAM files
+store = BamStore.from_bam_files(
+    bam_files=["sample1.bam", "sample2.bam"],
+    chromsizes="hg38.chrom.sizes",
+    store_path="dataset.zarr",
+    max_workers=8
+)
+
+# Add metadata
+metadata = pd.DataFrame({
+    "sample_id": ["sample1", "sample2"],
+    "condition": ["control", "treatment"]
+})
+store.set_metadata(metadata)
+```
+
+## Common Issues
+
+**Q: How long does dataset creation take?**  
+A: Depends on BAM file size (typically 20 min - 2 hours for whole-genome). Use `--max-workers` to parallelize.
+
+**Q: Can I resume interrupted dataset creation?**
+A: Yes. Pass `--resume` to the CLI (or `resume=True` in Python) and QuantNado will skip already-completed samples. Without this flag the default behaviour is `--overwrite`, which deletes any existing store at that path.
+
+**Q: What genomic coordinates are supported?**  
+A: Any coordinates in your chromsizes file. Supports human, mouse, yeast, etc.
+
+See [Troubleshooting](troubleshooting.md) for more help.