py-gbcms 2.2.0__cp312-cp312-manylinux_2_28_x86_64.whl

gbcms/pipeline.py

@@ -0,0 +1,257 @@
+"""
+Pipeline Orchestrator: Manages the execution flow of gbcms.
+
+This module handles:
+1. Reading variants from input (VCF/MAF).
+2. Iterating over samples (BAM files).
+3. Running the Rust-based counting engine for each sample.
+4. Writing results to per-sample output files.
+"""
+
+import logging
+import time
+from pathlib import Path
+
+import pysam
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TaskProgressColumn,
+    TextColumn,
+    TimeRemainingColumn,
+)
+
+from gbcms import _rs as gbcms_rs
+
+from .core.kernel import CoordinateKernel
+from .io.input import MafReader, ReferenceChecker, VariantReader, VcfReader
+from .io.output import MafWriter, VcfWriter
+from .models.core import GbcmsConfig, OutputFormat, Variant
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["Pipeline"]
+
+
+class Pipeline:
+    """Main pipeline for processing BAM files and counting bases at variant positions."""
+
+    def __init__(self, config: GbcmsConfig):
+        """
+        Initialize the pipeline.
+
+        Args:
+            config: Configuration object with input/output paths and filter settings.
+        """
+        self.config = config
+        self.console = Console()
+        self._stats = {"samples_processed": 0, "total_variants": 0, "total_time": 0.0}
+
+    def run(self) -> dict:
+        """
+        Execute the pipeline.
+
+        Returns:
+            Dictionary with processing statistics.
+        """
+        start_time = time.perf_counter()
+        logger.info("Starting gbcms pipeline")
+        logger.info("Output directory: %s", self.config.output.directory)
+
+        # 1. Load Variants
+        logger.debug("Loading variants from %s", self.config.variant_file)
+        variants = self._load_variants()
+        logger.info("Loaded %d variants", len(variants))
+
+        if not variants:
+            logger.error("No variants found. Exiting.")
+            return self._stats
+
+        # 2. Validate Variants against Reference
+        logger.debug("Validating variants against reference genome")
+        valid_variants = self._validate_variants(variants)
+        logger.info("Valid variants: %d / %d", len(valid_variants), len(variants))
+
+        if not valid_variants:
+            logger.error("No valid variants remaining after validation. Exiting.")
+            return self._stats
+
+        variants = valid_variants
+        self._stats["total_variants"] = len(variants)
+
+        # 3. Prepare Rust Variants
+        rs_variants = [
+            gbcms_rs.Variant(v.chrom, v.pos, v.ref, v.alt, v.variant_type.value) for v in variants
+        ]
+
+        # 4. Process Each Sample
+        self.config.output.directory.mkdir(parents=True, exist_ok=True)
+        samples = list(self.config.bam_files.items())
+
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            TaskProgressColumn(),
+            TimeRemainingColumn(),
+            console=self.console,
+        ) as progress:
+            task = progress.add_task("[cyan]Processing samples...", total=len(samples))
+
+            for sample_name, bam_path in samples:
+                progress.update(task, description=f"[cyan]Processing {sample_name}...")
+                self._process_sample(sample_name, bam_path, variants, rs_variants)
+                progress.advance(task)
+
+        # Calculate total time
+        self._stats["total_time"] = time.perf_counter() - start_time
+        logger.info(
+            "Pipeline completed: %d samples, %.2fs",
+            self._stats["samples_processed"],
+            self._stats["total_time"],
+        )
+
+        return self._stats
+
+    def _process_sample(
+        self,
+        sample_name: str,
+        bam_path: Path,
+        variants: list[Variant],
+        rs_variants: list,
+    ) -> None:
+        """
+        Process a single sample.
+
+        Args:
+            sample_name: Name of the sample.
+            bam_path: Path to BAM file.
+            variants: List of normalized variants.
+            rs_variants: List of Rust variant objects.
+        """
+        sample_start = time.perf_counter()
+        logger.debug("Processing sample: %s (%s)", sample_name, bam_path)
+
+        # Validate BAM Header
+        if not self._validate_bam_header(bam_path, variants):
+            logger.warning(
+                "BAM %s may not contain variant chromosomes. Proceeding anyway.",
+                sample_name,
+            )
+
+        try:
+            # Run Rust Engine with nested config accessors
+            rust_start = time.perf_counter()
+            counts_list = gbcms_rs.count_bam(
+                str(bam_path),
+                rs_variants,
+                min_mapq=self.config.quality.min_mapping_quality,
+                min_baseq=self.config.quality.min_base_quality,
+                filter_duplicates=self.config.filters.duplicates,
+                filter_secondary=self.config.filters.secondary,
+                filter_supplementary=self.config.filters.supplementary,
+                filter_qc_failed=self.config.filters.qc_failed,
+                filter_improper_pair=self.config.filters.improper_pair,
+                filter_indel=self.config.filters.indel,
+                threads=self.config.threads,
+            )
+            rust_time = time.perf_counter() - rust_start
+            logger.debug("Rust count_bam completed in %.3fs", rust_time)
+
+            # Write Output
+            self._write_output(sample_name, variants, counts_list)
+            self._stats["samples_processed"] += 1
+
+            sample_time = time.perf_counter() - sample_start
+            logger.debug("Sample %s completed in %.3fs", sample_name, sample_time)
+
+        except Exception as e:
+            logger.error("Error processing sample %s: %s", sample_name, e)
+
+    def _load_variants(self) -> list[Variant]:
+        """Load variants based on file extension."""
+        path = self.config.variant_file
+        reader: VariantReader
+
+        suffix = path.suffix.lower()
+        if suffix in [".vcf", ".gz"]:
+            reader = VcfReader(path)
+        elif suffix == ".maf":
+            reader = MafReader(path, fasta_path=self.config.reference_fasta)
+        else:
+            raise ValueError(f"Unsupported variant file format: {suffix}")
+
+        variants = list(reader)
+        if hasattr(reader, "close"):
+            reader.close()
+
+        return variants
+
+    def _validate_variants(self, variants: list[Variant]) -> list[Variant]:
+        """Validate variants against reference genome."""
+        checker = ReferenceChecker(self.config.reference_fasta)
+        valid_variants = []
+        invalid_count = 0
+
+        for v in variants:
+            if checker.validate(v):
+                valid_variants.append(v)
+            else:
+                invalid_count += 1
+                if invalid_count <= 5:
+                    logger.warning(
+                        "Invalid variant (REF mismatch): %s:%d %s>%s",
+                        v.chrom,
+                        v.pos,
+                        v.ref,
+                        v.alt,
+                    )
+
+        if invalid_count > 5:
+            logger.warning("... and %d more invalid variants.", invalid_count - 5)
+
+        checker.close()
+        return valid_variants
+
+    def _validate_bam_header(self, bam_path: Path, variants: list[Variant]) -> bool:
+        """Check if BAM header contains chromosomes from variants."""
+        try:
+            with pysam.AlignmentFile(str(bam_path), "rb") as bam:
+                bam_chroms = set(bam.references)
+
+            norm_bam_chroms = {CoordinateKernel.normalize_chromosome(c) for c in bam_chroms}
+
+            if variants:
+                v = variants[0]
+                norm_v_chrom = CoordinateKernel.normalize_chromosome(v.chrom)
+                if norm_v_chrom not in norm_bam_chroms:
+                    return False
+            return True
+        except Exception as e:
+            logger.warning("Could not validate BAM header: %s", e)
+            return True
+
+    def _write_output(
+        self,
+        sample_name: str,
+        variants: list[Variant],
+        counts_list: list[gbcms_rs.BaseCounts],
+    ) -> None:
+        """Write results to output file."""
+        ext = "vcf" if self.config.output.format == OutputFormat.VCF else "maf"
+        suffix = self.config.output.suffix
+        output_path = self.config.output.directory / f"{sample_name}{suffix}.{ext}"
+
+        writer: VcfWriter | MafWriter
+        if self.config.output.format == OutputFormat.VCF:
+            writer = VcfWriter(output_path, sample_name=sample_name)
+        else:
+            writer = MafWriter(output_path)
+
+        for v, counts in zip(variants, counts_list, strict=True):
+            writer.write(v, counts, sample_name=sample_name)
+
+        writer.close()
+        logger.debug("Results written to %s", output_path)

gbcms/utils/__init__.py

@@ -0,0 +1,14 @@
+"""
+Utility modules for gbcms.
+
+Provides logging, timing, and other shared utilities.
+"""
+
+from .logging import get_logger, log_call, setup_logging, timed
+
+__all__ = [
+    "get_logger",
+    "log_call",
+    "setup_logging",
+    "timed",
+]

gbcms/utils/logging.py

@@ -0,0 +1,123 @@
+"""
+Logging utilities for gbcms.
+
+Provides centralized logging configuration with dual output:
+- Structured logging via Python logging module
+- Rich console output for interactive use
+"""
+
+import logging
+import time
+from collections.abc import Callable
+from contextlib import contextmanager
+from functools import wraps
+from typing import Any
+
+from rich.console import Console
+from rich.logging import RichHandler
+
+__all__ = [
+    "setup_logging",
+    "get_logger",
+    "timed",
+    "log_call",
+]
+
+# Module-level console for rich output
+_console = Console()
+
+
+def setup_logging(verbose: bool = False, log_file: str | None = None) -> None:
+    """
+    Configure logging for gbcms.
+
+    Args:
+        verbose: If True, set log level to DEBUG. Otherwise INFO.
+        log_file: Optional path to write logs to file.
+    """
+    log_level = logging.DEBUG if verbose else logging.INFO
+
+    handlers: list[logging.Handler] = [
+        RichHandler(
+            console=_console,
+            rich_tracebacks=True,
+            markup=True,
+            show_path=verbose,
+        )
+    ]
+
+    if log_file:
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setFormatter(
+            logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+        )
+        handlers.append(file_handler)
+
+    logging.basicConfig(
+        level=log_level,
+        format="%(message)s",
+        datefmt="[%X]",
+        handlers=handlers,
+        force=True,  # Override existing config
+    )
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger instance for the given module name."""
+    return logging.getLogger(name)
+
+
+@contextmanager
+def timed(operation: str, logger: logging.Logger | None = None):
+    """
+    Context manager for timing operations.
+
+    Args:
+        operation: Description of the operation being timed.
+        logger: Logger to use. If None, uses root logger.
+
+    Example:
+        with timed("Loading variants", logger):
+            variants = load_variants()
+    """
+    log = logger or logging.getLogger(__name__)
+    start = time.perf_counter()
+    log.debug("Starting: %s", operation)
+    try:
+        yield
+    finally:
+        elapsed = time.perf_counter() - start
+        log.debug("Completed: %s (%.3fs)", operation, elapsed)
+
+
+def log_call(logger: logging.Logger | None = None) -> Callable:
+    """
+    Decorator to log function calls with timing.
+
+    Args:
+        logger: Logger to use. If None, uses function's module logger.
+
+    Example:
+        @log_call()
+        def process_sample(sample_name: str) -> dict:
+            ...
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            log = logger or logging.getLogger(func.__module__)
+            log.debug("Calling %s", func.__name__)
+            start = time.perf_counter()
+            try:
+                result = func(*args, **kwargs)
+                elapsed = time.perf_counter() - start
+                log.debug("%s completed (%.3fs)", func.__name__, elapsed)
+                return result
+            except Exception as e:
+                log.error("%s failed: %s", func.__name__, e)
+                raise
+
+        return wrapper
+
+    return decorator

py_gbcms-2.2.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: py-gbcms
+Version: 2.2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Dist: pysam>=0.21.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pytest>=7.4.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0 ; extra == 'dev'
+Requires-Dist: pytest-mock>=3.11.0 ; extra == 'dev'
+Requires-Dist: black>=23.0.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.5.0 ; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0 ; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.0.0 ; extra == 'dev'
+Provides-Extra: all
+Provides-Extra: dev
+Provides-Extra: fast
+License-File: LICENSE
+Summary: Python implementation of GetBaseCountsMultiSample (gbcms) for calculating base counts in BAM files
+Keywords: bioinformatics,genomics,bam,vcf,maf,base-counts,gbcms
+Author-email: MSK-ACCESS <shahr2@mskcc.org>
+License: AGPL-3.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Bug Tracker, https://github.com/msk-access/py-gbcms/issues
+Project-URL: Documentation, https://github.com/msk-access/py-gbcms#readme
+Project-URL: Homepage, https://github.com/msk-access/py-gbcms
+Project-URL: Repository, https://github.com/msk-access/py-gbcms
+
+# py-gbcms
+
+**Complete orientation-aware counting system for genomic variants**
+
+[![Tests](https://github.com/msk-access/py-gbcms/workflows/Tests/badge.svg)](https://github.com/msk-access/py-gbcms/actions)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+## Features
+
+- 🚀 **High Performance**: Rust-powered core engine with multi-threading
+- 🧬 **Complete Variant Support**: SNP, MNP, insertion, deletion, and complex variants (DelIns, SNP+Indel)
+- 📊 **Orientation-Aware**: Forward and reverse strand analysis with fragment counting
+- 🔬 **Statistical Analysis**: Fisher's exact test for strand bias
+- 📁 **Flexible I/O**: VCF and MAF input/output formats
+- 🎯 **Quality Filters**: 7 configurable read filtering options
+
+## Installation
+
+**Quick install:**
+```bash
+pip install py-gbcms
+```
+
+**From source (requires Rust):**
+```bash
+git clone https://github.com/msk-access/py-gbcms.git
+cd py-gbcms
+pip install .
+```
+
+**Docker:**
+```bash
+docker pull ghcr.io/msk-access/py-gbcms:2.1.0
+```
+
+📖 **Full documentation:** https://msk-access.github.io/py-gbcms/
+
+---
+
+## Usage
+
+`py-gbcms` can be used in two ways:
+
+### 🔧 Option 1: Standalone CLI (1-10 samples)
+
+**Best for:** Quick analysis, local processing, direct control
+
+```bash
+gbcms run \
+    --variants variants.vcf \
+    --bam sample1.bam \
+    --fasta reference.fa \
+    --output-dir results/
+```
+
+**Output:** `results/sample1.vcf`
+
+**Learn more:**
+- 📘 [CLI Quick Start](https://cmo-ci.gitbook.io/py-gbcms/quick-start)
+- 📖 [CLI Reference](https://cmo-ci.gitbook.io/py-gbcms/cli_features)
+
+---
+
+### 🔄 Option 2: Nextflow Workflow (10+ samples, HPC)
+
+**Best for:** Many samples, HPC clusters (SLURM), reproducible pipelines
+
+```bash
+nextflow run nextflow/main.nf \
+    --input samplesheet.csv \
+    --variants variants.vcf \
+    --fasta reference.fa \
+    -profile slurm
+```
+
+**Features:**
+- ✅ Automatic parallelization across samples
+- ✅ SLURM/HPC integration
+- ✅ Container support (Docker/Singularity)
+- ✅ Resume failed runs
+
+**Learn more:**
+- 🔄 [Nextflow Workflow Guide](https://cmo-ci.gitbook.io/py-gbcms/nextflow)
+- 📋 [Usage Patterns Comparison](https://cmo-ci.gitbook.io/py-gbcms/workflows)
+
+---
+
+## Which Should I Use?
+
+| Scenario | Recommendation |
+|----------|----------------|
+| 1-10 samples, local machine | **CLI** |
+| 10+ samples, HPC cluster | **Nextflow** |
+| Quick ad-hoc analysis | **CLI** |
+| Production pipeline | **Nextflow** |
+| Need auto-parallelization | **Nextflow** |
+| Full manual control | **CLI** |
+
+---
+
+## Quick Examples
+
+### CLI: Single Sample
+```bash
+gbcms run \
+    --variants variants.vcf \
+    --bam tumor.bam \
+    --fasta hg19.fa \
+    --output-dir results/ \
+    --threads 4
+```
+
+### CLI: Multiple Samples (Sequential)
+```bash
+gbcms run \
+    --variants variants.vcf \
+    --bam-list samples.txt \
+    --fasta hg19.fa \
+    --output-dir results/
+```
+
+### Nextflow: Many Samples (Parallel)
+```bash
+# samplesheet.csv:
+# sample,bam,bai
+# tumor1,/path/to/tumor1.bam,
+# tumor2,/path/to/tumor2.bam,
+
+nextflow run nextflow/main.nf \
+    --input samplesheet.csv \
+    --variants variants.vcf \
+    --fasta hg19.fa \
+    --outdir results \
+    -profile slurm
+```
+
+---
+
+## Documentation
+
+📚 **Full Documentation:** https://cmo-ci.gitbook.io/py-gbcms/
+
+**Quick Links:**
+- [Installation](https://cmo-ci.gitbook.io/py-gbcms/installation)
+- [CLI Quick Start](https://cmo-ci.gitbook.io/py-gbcms/quick-start)
+- [Nextflow Workflow](https://cmo-ci.gitbook.io/py-gbcms/nextflow)
+- [CLI Reference](https://cmo-ci.gitbook.io/py-gbcms/cli_features)
+- [Input & Output Formats](https://cmo-ci.gitbook.io/py-gbcms/input_output)
+- [Architecture](https://cmo-ci.gitbook.io/py-gbcms/architecture)
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
+
+To contribute to documentation, see the [`gh-pages` branch](https://github.com/msk-access/py-gbcms/tree/gh-pages).
+
+---
+
+## Citation
+
+If you use `py-gbcms` in your research, please cite:
+
+```
+[Citation to be added]
+```
+
+---
+
+## License
+
+AGPL-3.0 - see [LICENSE](LICENSE) for details.
+
+---
+
+## Support
+
+- 🐛 **Issues:** https://github.com/msk-access/py-gbcms/issues
+- 💬 **Discussions:** https://github.com/msk-access/py-gbcms/discussions
+

py_gbcms-2.2.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+gbcms/__init__.py,sha256=eZ9tInanaAhEP5eXrtEBBrG09ADJA93dZHsTqTtT8-c,582
+gbcms/_rs.cpython-312-x86_64-linux-gnu.so,sha256=kMZxk9EXJ11C0Rso1r4DC7qxmoLmKeJqdV3vYlHiOWE,2691713
+gbcms/_rs.pyi,sha256=pQwrF9cgCSYeIQXsdE40z9Rxwv4-I-7JynE96kOoNEE,1029
+gbcms/cli.py,sha256=BHlC0_79wuhKtdpLGWYLPVDApwwHEAWg7euA6nHnb7I,6246
+gbcms/core/__init__.py,sha256=YY_0MvtbIOb_0I8cZg9DTNVN3xVn7qFohm4qzBO4vKU,182
+gbcms/core/kernel.py,sha256=lZYW2gurzG-Egq04CVoFFCn3-GnYN0VC1dyP8QMP5QQ,4697
+gbcms/io/__init__.py,sha256=0P3ag3XKQp7ldfdEM9iyLa814bQSXjWRN-uIXFJsiWM,374
+gbcms/io/input.py,sha256=FjKBl5ENcAJapkiXLHLBu0eXrIeChPTFZ_2AtwOPGeU,9115
+gbcms/io/output.py,sha256=MgWmqkETkqJ6aega3bDBNJvgYlB5W4fkliuWBLHd320,12224
+gbcms/models/__init__.py,sha256=w30KiqKJgW1mKhVf8Erhv5sNhsKdmBKjy5V8sSdCaLo,454
+gbcms/models/core.py,sha256=oP1_S4QldiqSIcVuELIVSCT0wHpLRGxDthfcFJxRHjo,5334
+gbcms/pipeline.py,sha256=kbFceb4Mro0C2ptgpo8R0h6mskHSpG8zRYVs49DaEDs,8869
+gbcms/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gbcms/utils/__init__.py,sha256=BVT4l3YAuDUYzcYhNBRLCh-iogqJTVfAIhuFSdujRoQ,238
+gbcms/utils/logging.py,sha256=oVrosypHiJumUBWZM-Dj8JBIZfP418xhtlKvLxJNAlc,3263
+gbcms.libs/libbz2-a1e77c99.so.1,sha256=DaMHVzhlKReUBcnfEqhZnzle2gdIDp7wPz4BLI-zf6g,75049
+gbcms.libs/libcrypto-bfee2032.so.1.1,sha256=vENxnY50N4f5NMoJR5ElTBXei4_x6ZjNLP7oMzBioo8,3215921
+gbcms.libs/libssl-658e53cd.so.1.1,sha256=59sUdvtjU-6lBFU6e8nNeH96zgPwWQ9GIIuaOUUOASs,666857
+py_gbcms-2.2.0.dist-info/METADATA,sha256=8W3KKx9EKQZFiuG-Jr55IgXzhxOnrY9VZMuKIRG2fvg,5863
+py_gbcms-2.2.0.dist-info/WHEEL,sha256=-bb09_PJZyKYDRWofYMyCwQSwDvJ5qTYPgEDkxiuUjI,109
+py_gbcms-2.2.0.dist-info/entry_points.txt,sha256=Yqzc4l1V0IO3dDpKe9O3sYlPyR1b3zAQEPtoaSl_Ftg,38
+py_gbcms-2.2.0.dist-info/licenses/LICENSE,sha256=5vLuih3k9yufKSXoR5qVWOhALHC8WXbSXjrOo9ZK3cs,34797
+py_gbcms-2.2.0.dist-info/RECORD,,

py_gbcms-2.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.11.5)
+Root-Is-Purelib: false
+Tag: cp312-cp312-manylinux_2_28_x86_64

py_gbcms-2.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gbcms=gbcms.cli:app