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

gbcms/core/kernel.py

@@ -0,0 +1,126 @@
+"""
+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
+
+
+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/input.py

@@ -0,0 +1,222 @@
+"""
+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
+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
+
+
+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:
+                    print(f"DEBUG: Failed to fetch {chrom} and chr{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()