py-gbcms 2.0.0__py3-none-any.whl → 2.1.1__py3-none-any.whl

gbcms/pipeline.py

@@ -0,0 +1,212 @@
+"""
+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.
+"""
+
+from pathlib import Path
+
+import pysam
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TaskProgressColumn,
+    TextColumn,
+    TimeRemainingColumn,
+)
+
+import 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
+
+
+class Pipeline:
+    def __init__(self, config: GbcmsConfig):
+        self.config = config
+        self.console = Console()
+
+    def run(self):
+        """Execute the pipeline."""
+        self.console.print("[bold blue]Starting gbcms pipeline[/bold blue]")
+        self.console.print(f"Output directory: {self.config.output_dir}")
+
+        # 1. Load Variants
+        with self.console.status("[bold green]Loading variants...[/bold green]"):
+            variants = self._load_variants()
+
+        self.console.print(f"Loaded [bold]{len(variants)}[/bold] variants.")
+
+        if not variants:
+            self.console.print("[bold red]No variants found. Exiting.[/bold red]")
+            return
+
+        # 2. Validate Variants against Reference
+        with self.console.status(
+            "[bold green]Validating variants against reference...[/bold green]"
+        ):
+            valid_variants = self._validate_variants(variants)
+
+        self.console.print(f"Valid variants: [bold]{len(valid_variants)}[/bold] / {len(variants)}")
+
+        if not valid_variants:
+            self.console.print(
+                "[bold red]No valid variants remaining after validation. Exiting.[/bold red]"
+            )
+            return
+
+        variants = valid_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_dir.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}...")
+
+                # Validate BAM Header
+                if not self._validate_bam_header(bam_path, variants):
+                    self.console.print(
+                        f"[yellow]Warning: BAM {sample_name} may not contain variant chromosomes. Proceeding anyway...[/yellow]"
+                    )
+
+                try:
+                    # Run Rust Engine
+                    counts_list = gbcms_rs.count_bam(
+                        str(bam_path),
+                        rs_variants,
+                        min_mapq=self.config.min_mapping_quality,
+                        min_baseq=self.config.min_base_quality,
+                        filter_duplicates=self.config.filter_duplicates,
+                        filter_secondary=self.config.filter_secondary,
+                        filter_supplementary=self.config.filter_supplementary,
+                        filter_qc_failed=self.config.filter_qc_failed,
+                        filter_improper_pair=self.config.filter_improper_pair,
+                        filter_indel=self.config.filter_indel,
+                        threads=self.config.threads,
+                    )
+
+                    # Write Output
+                    self._write_output(sample_name, variants, counts_list)
+
+                except Exception as e:
+                    self.console.print(
+                        f"[bold red]Error processing sample {sample_name}: {e}[/bold red]"
+                    )
+                    # Continue to next sample
+
+                progress.advance(task)
+
+        self.console.print("[bold green]Pipeline completed successfully.[/bold green]")
+
+    def _load_variants(self) -> list[Variant]:
+        """Load variants based on file extension."""
+        path = self.config.variant_file
+        reader: VariantReader
+
+        if path.suffix.lower() in [".vcf", ".gz"]:  # .vcf.gz handled by pysam
+            reader = VcfReader(path)
+        elif path.suffix.lower() == ".maf":
+            reader = MafReader(path, fasta_path=self.config.reference_fasta)
+        else:
+            raise ValueError(f"Unsupported variant file format: {path.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:  # Log first few failures
+                    self.console.print(
+                        f"[yellow]Invalid variant (REF mismatch): {v.chrom}:{v.pos} {v.ref}>{v.alt}[/yellow]"
+                    )
+
+        if invalid_count > 5:
+            self.console.print(
+                f"[yellow]... and {invalid_count - 5} more invalid variants.[/yellow]"
+            )
+
+        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)
+
+            # Check a few variants
+            # We need to handle chr prefix normalization
+            # BAM might have 'chr1', variant '1', or vice versa.
+
+            # Normalize BAM chroms
+            norm_bam_chroms = {CoordinateKernel.normalize_chromosome(c) for c in bam_chroms}
+
+            # Check first variant as a heuristic
+            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:
+            self.console.print(f"[yellow]Could not validate BAM header: {e}[/yellow]")
+            return True  # Assume ok if we can't check
+
+    def _write_output(
+        self, sample_name: str, variants: list[Variant], counts_list: list[gbcms_rs.BaseCounts]
+    ):
+        """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_dir / 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
+        ):  # Changed 'results' to 'counts_list'
+            writer.write(v, counts, sample_name=sample_name)
+
+        writer.close()
+
+        # self.console.print(f"Results written to {output_path}")

py_gbcms-2.1.1.dist-info/METADATA

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: py-gbcms
+Version: 2.1.1
+Summary: Python implementation of GetBaseCountsMultiSample (gbcms) for calculating base counts in BAM files
+Project-URL: Homepage, https://github.com/msk-access/py-gbcms
+Project-URL: Repository, https://github.com/msk-access/py-gbcms
+Project-URL: Documentation, https://github.com/msk-access/py-gbcms#readme
+Project-URL: Bug Tracker, https://github.com/msk-access/py-gbcms/issues
+Author-email: MSK-ACCESS <shahr2@mskcc.org>
+License: AGPL-3.0
+License-File: LICENSE
+Keywords: bam,base-counts,bioinformatics,gbcms,genomics,maf,vcf
+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-Python: >=3.10
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pysam>=0.21.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: all
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.11.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
+Provides-Extra: fast
+Description-Content-Type: text/markdown
+
+# 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.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+gbcms/__init__.py,sha256=zPJIgPGcoSNiD0qme18OnYJYE3A9VVytlhO-V5DaAW0,22
+gbcms/cli.py,sha256=P7ZhQBbsXJ88E2yqhJt_cu3xavTs1m2Mr2HKqZNp3Yc,5709
+gbcms/pipeline.py,sha256=ebPReb_MfdsiSXqxNGd8Q-dJUzKY2SeaxLSctZUHW54,7832
+gbcms/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gbcms/core/kernel.py,sha256=Sl53XS4uwUDHJyerbYWC6FfKhm14q494IlwON2c62vk,4665
+gbcms/io/input.py,sha256=VBBqhTlVF_S2vxEUXnqJ1sSGG3u_XthQB1VpoFPZxIU,8982
+gbcms/io/output.py,sha256=3nwIXD_d6f4pbYNVr3hxeNKFkeZLGkv_qQC8g7bxjMk,12603
+gbcms/models/core.py,sha256=klUbEFJVMmug94R8nnB9IMpLP4Q0CqGXc1BFS18LWzM,3788
+py_gbcms-2.1.1.dist-info/METADATA,sha256=LzEXVLw8njg-IOt5mxv3pT__aVWATnoDUmYyO7eKf6w,5826
+py_gbcms-2.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+py_gbcms-2.1.1.dist-info/entry_points.txt,sha256=AAg3yd8-c7jlb-FDGiFJXSNFVAhqO44zMLJQVFv8oWQ,40
+py_gbcms-2.1.1.dist-info/licenses/LICENSE,sha256=5vLuih3k9yufKSXoR5qVWOhALHC8WXbSXjrOo9ZK3cs,34797
+py_gbcms-2.1.1.dist-info/RECORD,,

gbcms/config.py

@@ -1,98 +0,0 @@
-"""Configuration classes and enums for GetBaseCounts."""
-
-import os
-from dataclasses import dataclass
-from enum import IntEnum
-
-
-class CountType(IntEnum):
-    """Enumeration for different count types."""
-
-    DP = 0  # Total depth
-    RD = 1  # Reference depth
-    AD = 2  # Alternate depth
-    DPP = 3  # Positive strand depth
-    RDP = 4  # Positive strand reference depth
-    ADP = 5  # Positive strand alternate depth
-    DPF = 6  # Fragment depth
-    RDF = 7  # Fragment reference depth
-    ADF = 8  # Fragment alternate depth
-
-
-@dataclass
-class Config:
-    """Configuration for base counting."""
-
-    fasta_file: str
-    bam_files: dict[str, str]  # sample_name -> bam_path
-    variant_files: list[str]
-    output_file: str
-
-    # Optional parameters
-    mapping_quality_threshold: int = 20
-    base_quality_threshold: int = 0
-    filter_duplicate: bool = True
-    filter_improper_pair: bool = False
-    filter_qc_failed: bool = False
-    filter_indel: bool = False
-    filter_non_primary: bool = False
-    output_positive_count: bool = True
-    output_negative_count: bool = False
-    output_fragment_count: bool = False
-    fragment_fractional_weight: bool = False
-    max_block_size: int = 10000
-    max_block_dist: int = 100000
-    num_threads: int = 1
-    backend: str = "joblib"  # Parallelization backend
-    input_is_maf: bool = False
-    input_is_vcf: bool = False
-    output_maf: bool = False
-    generic_counting: bool = False
-    max_warning_per_type: int = 3
-
-    def __post_init__(self) -> None:
-        """Validate configuration."""
-        if not os.path.exists(self.fasta_file):
-            raise FileNotFoundError(f"Reference FASTA file not found: {self.fasta_file}")
-
-        fai_file = f"{self.fasta_file}.fai"
-        if not os.path.exists(fai_file):
-            raise FileNotFoundError(
-                f"Reference FASTA index not found: {fai_file}. "
-                f"Please index with: samtools faidx {self.fasta_file}"
-            )
-
-        for sample, bam_path in self.bam_files.items():
-            if not os.path.exists(bam_path):
-                raise FileNotFoundError(f"BAM file not found for sample {sample}: {bam_path}")
-
-            # Check for BAM index
-            bai_file1 = bam_path.replace(".bam", ".bai")
-            bai_file2 = f"{bam_path}.bai"
-            if not os.path.exists(bai_file1) and not os.path.exists(bai_file2):
-                raise FileNotFoundError(
-                    f"BAM index not found for {bam_path}. "
-                    f"Please index with: samtools index {bam_path}"
-                )
-
-        for variant_file in self.variant_files:
-            if not os.path.exists(variant_file):
-                raise FileNotFoundError(f"Variant file not found: {variant_file}")
-
-        if self.input_is_maf and self.input_is_vcf:
-            raise ValueError("--maf and --vcf are mutually exclusive")
-
-        if not self.input_is_maf and not self.input_is_vcf:
-            raise ValueError("Either --maf or --vcf must be specified")
-
-        if self.input_is_vcf and self.output_maf:
-            raise ValueError("--omaf can only be used with --maf input")
-
-        if self.num_threads < 1:
-            raise ValueError("Number of threads must be at least 1")
-
-        if self.max_block_size < 1:
-            raise ValueError("max_block_size must be at least 1")
-
-        if self.max_block_dist < 1:
-            raise ValueError("max_block_dist must be at least 1")