py-gbcms 2.2.0__cp311-cp311-macosx_11_0_arm64.whl

gbcms/__init__.py

@@ -0,0 +1,23 @@
+"""
+gbcms (Get Base Counts Multi-Sample) - A tool for counting bases at variant positions.
+
+This package provides a command-line interface and Python API for genotyping
+variants in BAM files using a high-performance Rust counting engine.
+
+Example usage:
+    $ gbcms run -v variants.vcf -b sample.bam -f reference.fa -o output/
+"""
+
+__version__ = "2.2.0"
+
+from .models.core import GbcmsConfig, OutputFormat, Variant, VariantType
+from .pipeline import Pipeline
+
+__all__ = [
+    "__version__",
+    "GbcmsConfig",
+    "OutputFormat",
+    "Pipeline",
+    "Variant",
+    "VariantType",
+]

gbcms/_rs.pyi

@@ -0,0 +1,49 @@
+# Type stubs for the Rust extension module (gbcms._rs)
+# This file tells mypy about the types in the native extension
+
+class Variant:
+    chrom: str
+    pos: int
+    ref_allele: str
+    alt_allele: str
+    variant_type: str
+
+    def __init__(
+        self,
+        chrom: str,
+        pos: int,
+        ref_allele: str,
+        alt_allele: str,
+        variant_type: str,
+    ) -> None: ...
+
+class BaseCounts:
+    chrom: str
+    pos: int
+    ref: str
+    alt: str
+    dp: int
+    rd: int
+    ad: int
+    rd_fwd: int
+    rd_rev: int
+    ad_fwd: int
+    ad_rev: int
+    dp_fragment: int
+    rd_fragment: int
+    ad_fragment: int
+    sb_pvalue: float
+
+def count_bam(
+    bam_path: str,
+    variants: list[Variant],
+    min_mapq: int = 20,
+    min_baseq: int = 0,
+    filter_duplicates: bool = True,
+    filter_secondary: bool = False,
+    filter_supplementary: bool = False,
+    filter_qc_failed: bool = False,
+    filter_improper_pair: bool = False,
+    filter_indel: bool = False,
+    threads: int = 1,
+) -> list[BaseCounts]: ...

gbcms/cli.py

@@ -0,0 +1,204 @@
+"""
+CLI Entry Point: Exposes the gbcms functionality via command line.
+"""
+
+import logging
+from pathlib import Path
+
+import typer
+
+from .models.core import (
+    GbcmsConfig,
+    OutputConfig,
+    OutputFormat,
+    QualityThresholds,
+    ReadFilters,
+)
+from .pipeline import Pipeline
+from .utils import setup_logging
+
+__all__ = ["app", "run"]
+
+logger = logging.getLogger(__name__)
+
+app = typer.Typer(help="gbcms: Get Base Counts Multi-Sample")
+
+
+@app.callback()
+def main():
+    """
+    gbcms: Get Base Counts Multi-Sample
+    """
+    pass
+
+
+@app.command()
+def run(
+    # Input options
+    variant_file: Path = typer.Option(
+        ..., "--variants", "-v", help="Path to VCF or MAF file containing variants"
+    ),
+    bam_files: list[Path] | None = typer.Option(
+        None, "--bam", "-b", help="Path to BAM file(s). Can be specified multiple times."
+    ),
+    bam_list: Path | None = typer.Option(
+        None, "--bam-list", "-L", help="File containing list of BAM paths (one per line)"
+    ),
+    reference: Path = typer.Option(..., "--fasta", "-f", help="Path to reference FASTA file"),
+    # Output options
+    output_dir: Path = typer.Option(
+        ..., "--output-dir", "-o", help="Directory to write output files"
+    ),
+    output_format: OutputFormat = typer.Option(
+        OutputFormat.VCF, "--format", help="Output format (vcf or maf)"
+    ),
+    output_suffix: str = typer.Option(
+        "", "--suffix", "-S", help="Suffix to append to output filename (e.g. '.genotyped')"
+    ),
+    # Quality thresholds
+    min_mapq: int = typer.Option(20, "--min-mapq", help="Minimum mapping quality"),
+    min_baseq: int = typer.Option(0, "--min-baseq", help="Minimum base quality"),
+    # Read filters
+    filter_duplicates: bool = typer.Option(True, help="Filter duplicate reads"),
+    filter_secondary: bool = typer.Option(False, help="Filter secondary alignments"),
+    filter_supplementary: bool = typer.Option(False, help="Filter supplementary alignments"),
+    filter_qc_failed: bool = typer.Option(False, help="Filter reads failing QC"),
+    filter_improper_pair: bool = typer.Option(False, help="Filter improperly paired reads"),
+    filter_indel: bool = typer.Option(False, help="Filter reads containing indels"),
+    # Performance
+    threads: int = typer.Option(
+        1, "--threads", "-t", help="Number of threads for parallel processing"
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-V", help="Enable verbose debug logging"),
+):
+    """
+    Run gbcms on one or more BAM files.
+    """
+    # Configure logging
+    setup_logging(verbose=verbose)
+
+    # Parse BAM inputs
+    bams_dict = _parse_bam_inputs(bam_files, bam_list)
+
+    if not bams_dict:
+        logger.error("No valid BAM files provided via --bam or --bam-list")
+        raise typer.Exit(code=1)
+
+    logger.info("Found %d BAM file(s) to process", len(bams_dict))
+
+    try:
+        # Build nested config objects
+        output_config = OutputConfig(
+            directory=output_dir,
+            format=output_format,
+            suffix=output_suffix,
+        )
+
+        quality_config = QualityThresholds(
+            min_mapping_quality=min_mapq,
+            min_base_quality=min_baseq,
+        )
+
+        filter_config = ReadFilters(
+            duplicates=filter_duplicates,
+            secondary=filter_secondary,
+            supplementary=filter_supplementary,
+            qc_failed=filter_qc_failed,
+            improper_pair=filter_improper_pair,
+            indel=filter_indel,
+        )
+
+        config = GbcmsConfig(
+            variant_file=variant_file,
+            bam_files=bams_dict,
+            reference_fasta=reference,
+            output=output_config,
+            quality=quality_config,
+            filters=filter_config,
+            threads=threads,
+        )
+
+        pipeline = Pipeline(config)
+        pipeline.run()
+
+    except Exception as e:
+        logger.exception("Pipeline failed: %s", e)
+        raise typer.Exit(code=1) from e
+
+
+def _parse_bam_inputs(bam_files: list[Path] | None, bam_list: Path | None) -> dict[str, Path]:
+    """
+    Parse BAM inputs from direct arguments and/or BAM list file.
+
+    Args:
+        bam_files: List of BAM paths (optionally with sample_id:path format).
+        bam_list: Path to file containing BAM paths (one per line).
+
+    Returns:
+        Dictionary mapping sample names to BAM paths.
+    """
+    bams_dict: dict[str, Path] = {}
+
+    # 1. Process direct BAM arguments
+    if bam_files:
+        for bam_arg in bam_files:
+            sample_name, bam_path = _parse_bam_arg(bam_arg)
+
+            if not bam_path.exists():
+                logger.error("BAM file not found: %s", bam_path)
+                continue
+
+            bams_dict[sample_name] = bam_path
+
+    # 2. Process BAM list file
+    if bam_list:
+        if not bam_list.exists():
+            logger.error("BAM list file not found: %s", bam_list)
+            return bams_dict
+
+        try:
+            with open(bam_list) as f:
+                for line in f:
+                    line = line.strip()
+                    if not line or line.startswith("#"):
+                        continue
+
+                    parts = line.split()
+                    if len(parts) >= 2:
+                        sample_name = parts[0]
+                        bam_path = Path(parts[1])
+                    else:
+                        bam_path = Path(parts[0])
+                        sample_name = bam_path.stem
+
+                    if not bam_path.exists():
+                        logger.warning("BAM file from list not found: %s", bam_path)
+                        continue
+
+                    bams_dict[sample_name] = bam_path
+
+        except Exception as e:
+            logger.error("Error reading BAM list file %s: %s", bam_list, e)
+
+    return bams_dict
+
+
+def _parse_bam_arg(bam_arg: Path) -> tuple[str, Path]:
+    """
+    Parse a BAM argument that may be in sample_id:path format.
+
+    Args:
+        bam_arg: Path object (may contain sample_id:path as string).
+
+    Returns:
+        Tuple of (sample_name, bam_path).
+    """
+    bam_str = str(bam_arg)
+    if ":" in bam_str:
+        parts = bam_str.split(":", 1)
+        return parts[0], Path(parts[1])
+    return bam_arg.stem, bam_arg
+
+
+if __name__ == "__main__":
+    app()

gbcms/core/__init__.py

@@ -0,0 +1,9 @@
+"""
+Core module for gbcms.
+
+Provides the coordinate transformation kernel for handling VCF/MAF coordinates.
+"""
+
+from .kernel import CoordinateKernel
+
+__all__ = ["CoordinateKernel"]

gbcms/core/kernel.py

@@ -0,0 +1,128 @@
+"""
+Coordinate Kernel: The source of truth for genomic coordinate systems.
+
+Handles conversion between:
+- VCF (1-based)
+- MAF (1-based)
+- Internal (0-based, half-open [start, end))
+
+Ensures consistent representation of variants:
+- SNPs: 0-based index of the base.
+- Insertions: 0-based index of the ANCHOR base (preceding the insertion).
+- Deletions: 0-based index of the ANCHOR base (preceding the deletion).
+"""
+
+from gbcms.models.core import Variant, VariantType
+
+__all__ = ["CoordinateKernel"]
+
+
+class CoordinateKernel:
+    """
+    Stateless utility for coordinate transformations and normalization.
+    """
+
+    @staticmethod
+    def vcf_to_internal(
+        chrom: str, pos: int, ref: str, alt: str, original_id: str | None = None
+    ) -> Variant:
+        """
+        Convert VCF coordinates (1-based) to internal normalized Variant.
+
+        Args:
+            chrom: Chromosome name
+            pos: 1-based position from VCF
+            ref: Reference allele
+            alt: Alternate allele
+            original_id: Optional VCF ID
+
+        Returns:
+            Normalized Variant object
+        """
+        norm_chrom = CoordinateKernel.normalize_chromosome(chrom)
+
+        # Determine variant type and internal position
+        if len(ref) == 1 and len(alt) == 1:
+            vtype = VariantType.SNP
+            # SNP: VCF POS is the base itself.
+            # 1-based 10 -> 0-based 9
+            internal_pos = pos - 1
+
+        elif len(ref) == 1 and len(alt) > 1:
+            vtype = VariantType.INSERTION
+            # Insertion: VCF POS is the base BEFORE the insertion (the anchor).
+            # VCF: POS=10, REF=A, ALT=AT (Insertion of T after A at 10)
+            # Internal: 0-based index of the ANCHOR base.
+            # 1-based 10 -> 0-based 9
+            internal_pos = pos - 1
+
+        elif len(ref) > 1 and len(alt) == 1:
+            vtype = VariantType.DELETION
+            # Deletion: VCF POS is the base BEFORE the deletion (the anchor).
+            # VCF: POS=10, REF=AT, ALT=A (Deletion of T after A at 10)
+            # Internal POS: 0-based index of the ANCHOR base.
+            # 1-based 10 -> 0-based 9
+            internal_pos = pos - 1
+
+        else:
+            vtype = VariantType.COMPLEX
+            # Complex: Treat start as 0-based index of first ref base
+            internal_pos = pos - 1
+
+        return Variant(
+            chrom=norm_chrom,
+            pos=internal_pos,
+            ref=ref,
+            alt=alt,
+            variant_type=vtype,
+            original_id=original_id,
+        )
+
+    @staticmethod
+    def maf_to_internal(chrom: str, start_pos: int, end_pos: int, ref: str, alt: str) -> Variant:
+        """
+        Convert MAF coordinates (1-based inclusive) to internal normalized Variant.
+
+        MAF coordinates are generally 1-based inclusive [start, end].
+        """
+        norm_chrom = CoordinateKernel.normalize_chromosome(chrom)
+
+        # Handle MAF indels which often use '-'
+        if ref == "-" or alt == "-":
+            # MAF Insertion: Start_Position is the base BEFORE the insertion (anchor).
+            # ref='-', alt='T' -> VCF-like would be ref='A', alt='AT' (requires lookup)
+            # But if we just want to represent it internally:
+            if ref == "-":  # Insertion
+                vtype = VariantType.INSERTION
+                # MAF Start_Position is usually the flanking base 0 or 1?
+                # Standard MAF: Start_Position is the base BEFORE the insertion.
+                internal_pos = start_pos - 1
+            else:  # Deletion
+                vtype = VariantType.DELETION
+                # MAF Start_Position is the first deleted base? Or anchor?
+                # Usually first deleted base.
+                # We need to convert to anchor-based for consistency if possible,
+                # OR handle MAF-style internally.
+                # Let's assume we want VCF-style anchor-based internally.
+                # This effectively requires a reference lookup to get the anchor base.
+                # For now, we will mark it as needing normalization or handle it in the engine.
+                internal_pos = start_pos - 1
+
+        elif len(ref) == len(alt) == 1:
+            vtype = VariantType.SNP
+            internal_pos = start_pos - 1
+
+        else:
+            vtype = VariantType.COMPLEX
+            internal_pos = start_pos - 1
+
+        return Variant(chrom=norm_chrom, pos=internal_pos, ref=ref, alt=alt, variant_type=vtype)
+
+    @staticmethod
+    def normalize_chromosome(chrom: str) -> str:
+        """
+        Normalize chromosome name (remove 'chr' prefix).
+        """
+        if chrom.lower().startswith("chr"):
+            return chrom[3:]
+        return chrom

gbcms/io/__init__.py

@@ -0,0 +1,18 @@
+"""
+I/O module for gbcms.
+
+Provides readers and writers for variant files (VCF, MAF format).
+"""
+
+from .input import MafReader, ReferenceChecker, VariantReader, VcfReader
+from .output import MafWriter, OutputWriter, VcfWriter
+
+__all__ = [
+    "MafReader",
+    "MafWriter",
+    "OutputWriter",
+    "ReferenceChecker",
+    "VariantReader",
+    "VcfReader",
+    "VcfWriter",
+]

gbcms/io/input.py

@@ -0,0 +1,227 @@
+"""
+Input Adapters: Handling VCF and MAF inputs.
+
+This module provides classes to read variants from VCF and MAF files,
+converting them into the internal normalized representation using CoordinateKernel.
+"""
+
+import csv
+import logging
+from collections.abc import Iterator
+from pathlib import Path
+
+import pysam
+from pydantic import ValidationError
+
+from ..core.kernel import CoordinateKernel
+from ..models.core import Variant
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["VariantReader", "VcfReader", "MafReader", "ReferenceChecker"]
+
+
+class VariantReader:
+    """Abstract base class for variant readers."""
+
+    def __iter__(self) -> Iterator[Variant]:
+        raise NotImplementedError
+
+
+class VcfReader(VariantReader):
+    """Reads variants from a VCF file."""
+
+    def __init__(self, path: Path):
+        self.path = path
+        self._vcf = pysam.VariantFile(str(path))
+
+    def __iter__(self) -> Iterator[Variant]:
+        for record in self._vcf:
+            # VCF coordinates are 1-based
+            # pysam converts them to 0-based automatically?
+            # pysam.VariantFile returns 0-based pos (start)
+            # BUT CoordinateKernel.vcf_to_internal expects 1-based VCF POS.
+            # Let's check pysam documentation or behavior.
+            # pysam record.pos is 0-based. record.start is 0-based.
+            # The VCF file itself has 1-based POS.
+            # If we use record.pos + 1, we get the VCF POS.
+
+            # Handle multiple ALTs
+            for alt in record.alts or []:
+                # VCF POS is record.pos (1-based) or record.start + 1
+                if not record.ref:
+                    continue  # Skip if no REF
+
+                yield CoordinateKernel.vcf_to_internal(
+                    chrom=record.chrom,
+                    pos=record.pos,
+                    ref=record.ref,
+                    alt=alt,
+                    original_id=record.id,
+                )
+
+    def close(self):
+        self._vcf.close()
+
+
+class MafReader(VariantReader):
+    """Reads variants from a MAF file."""
+
+    def __init__(self, path: Path, fasta_path: Path | None = None):
+        self.path = path
+        self.fasta = pysam.FastaFile(str(fasta_path)) if fasta_path else None
+
+    def __iter__(self) -> Iterator[Variant]:
+        with open(self.path) as f:
+            # Skip comments
+            while True:
+                pos = f.tell()
+                line = f.readline()
+                if not line.startswith("#"):
+                    f.seek(pos)
+                    break
+
+            reader = csv.DictReader(f, delimiter="\t")
+
+            for row in reader:
+                try:
+                    chrom = row["Chromosome"]
+                    start_pos = int(row["Start_Position"])
+                    ref = row["Reference_Allele"]
+                    alt = row["Tumor_Seq_Allele2"]  # Standard MAF alt column
+
+                    # Normalize Indels if FASTA is available
+                    if self.fasta and (ref == "-" or alt == "-"):
+                        if ref == "-":  # Insertion
+                            # MAF Start_Position is the base BEFORE the insertion (anchor)
+                            # 1-based coordinate
+                            anchor_pos_1based = start_pos
+                            anchor_pos_0based = anchor_pos_1based - 1
+
+                            # Fetch anchor base
+                            # Try normalized and original chromosome names
+                            norm_chrom = CoordinateKernel.normalize_chromosome(chrom)
+                            try:
+                                anchor_base = self.fasta.fetch(
+                                    norm_chrom, anchor_pos_0based, anchor_pos_0based + 1
+                                ).upper()
+                            except (KeyError, ValueError):
+                                try:
+                                    anchor_base = self.fasta.fetch(
+                                        chrom, anchor_pos_0based, anchor_pos_0based + 1
+                                    ).upper()
+                                except (KeyError, ValueError):
+                                    # If both fail, we can't normalize. Skip or raise?
+                                    # For now, skip/log
+                                    continue
+
+                            # VCF Style:
+                            # POS = anchor_pos_1based
+                            # REF = anchor_base
+                            # ALT = anchor_base + inserted_seq
+                            vcf_pos = anchor_pos_1based
+                            vcf_ref = anchor_base
+                            vcf_alt = anchor_base + alt
+
+                        else:  # Deletion (alt == '-')
+                            # MAF Start_Position is the FIRST DELETED base
+                            # Anchor is the base before that
+                            first_deleted_1based = start_pos
+                            anchor_pos_1based = first_deleted_1based - 1
+                            anchor_pos_0based = anchor_pos_1based - 1
+
+                            # Fetch anchor base
+                            norm_chrom = CoordinateKernel.normalize_chromosome(chrom)
+                            try:
+                                anchor_base = self.fasta.fetch(
+                                    norm_chrom, anchor_pos_0based, anchor_pos_0based + 1
+                                ).upper()
+                            except (KeyError, ValueError):
+                                try:
+                                    anchor_base = self.fasta.fetch(
+                                        chrom, anchor_pos_0based, anchor_pos_0based + 1
+                                    ).upper()
+                                except (KeyError, ValueError):
+                                    continue
+
+                            # VCF Style:
+                            # POS = anchor_pos_1based
+                            # REF = anchor_base + deleted_seq
+                            # ALT = anchor_base
+                            vcf_pos = anchor_pos_1based
+                            vcf_ref = anchor_base + ref
+                            vcf_alt = anchor_base
+
+                        yield CoordinateKernel.vcf_to_internal(
+                            chrom=chrom, pos=vcf_pos, ref=vcf_ref, alt=vcf_alt
+                        ).model_copy(update={"metadata": row})
+                    else:
+                        # Fallback to old behavior or direct mapping for SNPs
+                        # For SNPs, MAF Start_Position == VCF POS
+                        if len(ref) == len(alt) == 1 and ref != "-" and alt != "-":
+                            yield CoordinateKernel.vcf_to_internal(
+                                chrom=chrom, pos=start_pos, ref=ref, alt=alt
+                            ).model_copy(update={"metadata": row})
+                        else:
+                            # Fallback for complex/unhandled without FASTA
+                            # This might fail in Rust engine if it expects anchor
+                            yield CoordinateKernel.maf_to_internal(
+                                chrom=chrom,
+                                start_pos=start_pos,
+                                end_pos=int(row["End_Position"]),
+                                ref=ref,
+                                alt=alt,
+                            ).model_copy(update={"metadata": row})
+
+                except (KeyError, ValueError, ValidationError):
+                    # Log warning or skip malformed lines
+                    continue
+
+    def close(self):
+        if self.fasta:
+            self.fasta.close()
+
+
+class ReferenceChecker:
+    """
+    Utility to check variants against a reference FASTA.
+    Ensures that the REF allele matches the genome.
+    """
+
+    def __init__(self, fasta_path: Path):
+        self.fasta = pysam.FastaFile(str(fasta_path))
+
+    def validate(self, variant: Variant) -> bool:
+        """
+        Check if variant REF matches reference genome.
+        """
+        # Variant pos is 0-based.
+        # Fetch sequence of length REF
+        try:
+            # Try normalized and potentially 'chr' prefixed chromosome names
+            chrom = variant.chrom
+            # chrom is already normalized (e.g. "1") by CoordinateKernel
+
+            ref_seq = None
+            try:
+                ref_seq = self.fasta.fetch(chrom, variant.pos, variant.pos + len(variant.ref))
+            except (ValueError, KeyError):
+                try:
+                    # Try adding 'chr' prefix
+                    ref_seq = self.fasta.fetch(
+                        f"chr{chrom}", variant.pos, variant.pos + len(variant.ref)
+                    )
+                except (ValueError, KeyError) as e:
+                    logger.debug("Failed to fetch %s and chr%s: %s", chrom, chrom, e)
+                    return False
+
+            if ref_seq is None:
+                return False
+
+            return ref_seq.upper() == variant.ref.upper()
+
+        except Exception:
+            return False
+
+    def close(self):
+        self.fasta.close()