supremo-lite 0.5.4__tar.gz → 1.0.0__tar.gz

{supremo_lite-0.5.4 → supremo_lite-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supremo_lite
-Version: 0.5.4
+Version: 1.0.0
 Summary: A lightweight memory first, model agnostic version of SuPreMo
 License: MIT
 License-File: LICENSE
@@ -42,13 +42,10 @@ For the latest features and bug fixes:
 
 ```bash
 # Install directly latest release
-pip install supremo_lite
+pip install supremo-lite
 
 # Or install a specific version/tag
 pip install git+https://github.com/gladstone-institutes/supremo_lite.git@v0.5.0
-
-# Or install from a specific branch
-pip install git+https://github.com/gladstone-institutes/supremo_lite.git@main
 ```
 
 ### Dependencies
@@ -60,7 +57,7 @@ Required dependencies will be installed automatically:
 
 Optional dependencies:
 - `torch` - For PyTorch tensor support (automatically detected)
-- [https://github.com/gladstone-institutes/brisket](brisket) - Cython powered faster 1 hot encoding for DNA sequences (automatically detected)
+- [brisket](https://github.com/gladstone-institutes/brisket) - Cython powered faster 1 hot encoding for DNA sequences (automatically detected)
 
 ## Quick Start
 
@@ -214,3 +211,4 @@ Interested in contributing? Check out the contributing guidelines. Please note t
 ## Credits
 
 `supremo_lite` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).
+

{supremo_lite-0.5.4 → supremo_lite-1.0.0}/README.md

@@ -20,13 +20,10 @@ For the latest features and bug fixes:
 
 ```bash
 # Install directly latest release
-pip install supremo_lite
+pip install supremo-lite
 
 # Or install a specific version/tag
 pip install git+https://github.com/gladstone-institutes/supremo_lite.git@v0.5.0
-
-# Or install from a specific branch
-pip install git+https://github.com/gladstone-institutes/supremo_lite.git@main
 ```
 
 ### Dependencies
@@ -38,7 +35,7 @@ Required dependencies will be installed automatically:
 
 Optional dependencies:
 - `torch` - For PyTorch tensor support (automatically detected)
-- [https://github.com/gladstone-institutes/brisket](brisket) - Cython powered faster 1 hot encoding for DNA sequences (automatically detected)
+- [brisket](https://github.com/gladstone-institutes/brisket) - Cython powered faster 1 hot encoding for DNA sequences (automatically detected)
 
 ## Quick Start
 
@@ -191,4 +188,4 @@ Interested in contributing? Check out the contributing guidelines. Please note t
 
 ## Credits
 
-`supremo_lite` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).
+`supremo_lite` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).

{supremo_lite-0.5.4 → supremo_lite-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "supremo_lite"
-version = "0.5.4"
+version = "1.0.0"
 description = "A lightweight memory first, model agnostic version of SuPreMo"
 authors = ["Natalie Gill", "Sean Whalen"]
 license = "MIT"

{supremo_lite-0.5.4 → supremo_lite-1.0.0}/src/supremo_lite/__init__.py

@@ -42,7 +42,11 @@ from .personalize import (
 )
 
 # Import mutagenesis functions
-from .mutagenesis import get_sm_sequences, get_sm_subsequences
+from .mutagenesis import (
+    get_sm_sequences,
+    get_sm_subsequences,
+    get_scrambled_subsequences,
+)
 
 # Import prediction alignment functions
 from .prediction_alignment import align_predictions_by_coordinate
@@ -52,7 +56,7 @@ from .prediction_alignment import align_predictions_by_coordinate
 # This allows users who don't have PyTorch to still use the main package
 
 # Version
-__version__ = "0.5.4"
+__version__ = "1.0.0"
 # Package metadata
 __description__ = (
     "A module for generating personalized genome sequences and in-silico mutagenesis"

{supremo_lite-0.5.4 → supremo_lite-1.0.0}/src/supremo_lite/mock_models/testmodel_2d.py

@@ -126,9 +126,13 @@ if TORCH_AVAILABLE:
             )
 
             # Crop bins from all edges to focus loss function
-            y_hat = y_hat[
-                :, :, self.crop_bins : -self.crop_bins, self.crop_bins : -self.crop_bins
-            ]
+            if self.crop_bins > 0:
+                y_hat = y_hat[
+                    :,
+                    :,
+                    self.crop_bins : -self.crop_bins,
+                    self.crop_bins : -self.crop_bins,
+                ]
 
             # Return full contact matrix
             return y_hat

{supremo_lite-0.5.4 → supremo_lite-1.0.0}/src/supremo_lite/mutagenesis.py

@@ -19,6 +19,94 @@ except ImportError:
     pass  # Already handled in core
 
 
+def _kmer_shuffle(sequence: str, k: int = 1, random_state=None) -> str:
+    """
+    Shuffle a sequence by k-mer chunks, preserving k-mer composition.
+
+    Breaks the sequence into non-overlapping k-mers and shuffles these chunks.
+    This preserves the k-mer frequency counts in the shuffled sequence:
+    - k=1: Shuffle individual nucleotides (preserves mononucleotide/GC composition)
+    - k=2: Shuffle 2-mers (preserves dinucleotide frequencies)
+    - k=3: Shuffle 3-mers (preserves trinucleotide frequencies)
+
+    Note: If sequence length is not divisible by k, the remainder bases are
+    treated as a partial k-mer and shuffled along with the complete k-mers.
+
+    Args:
+        sequence: Input DNA sequence string (ACGT only)
+        k: Size of k-mers to shuffle (default: 1)
+        random_state: Optional numpy random state or seed for reproducibility
+
+    Returns:
+        Shuffled sequence with preserved k-mer composition
+
+    Raises:
+        ValueError: If k < 1
+    """
+    if k < 1:
+        raise ValueError(f"k must be >= 1, got {k}")
+
+    if len(sequence) < k:
+        return sequence
+
+    # Handle random state
+    if random_state is None:
+        rng = np.random.default_rng()
+    elif isinstance(random_state, (int, np.integer)):
+        rng = np.random.default_rng(random_state)
+    else:
+        rng = random_state
+
+    seq = sequence.upper()
+
+    # Calculate how many complete k-mers we can make
+    n_complete_kmers = len(seq) // k
+    kmer_portion_len = n_complete_kmers * k
+
+    # Split into k-mers
+    kmers = [seq[i : i + k] for i in range(0, kmer_portion_len, k)]
+
+    # Include leftover bases as an additional chunk to shuffle
+    leftover = seq[kmer_portion_len:]
+    if leftover:
+        kmers.append(leftover)
+
+    # Shuffle all chunks (including leftover if present)
+    rng.shuffle(kmers)
+
+    return "".join(kmers)
+
+
+def _scramble_region(
+    sequence: str, start: int, end: int, k: int = 1, random_state=None
+) -> str:
+    """
+    Scramble a specific region within a sequence using k-mer shuffle.
+
+    Args:
+        sequence: Full sequence string
+        start: Start position of region to scramble (0-based)
+        end: End position of region to scramble (exclusive)
+        k: Size of k-mers to shuffle (default: 1 for mononucleotide shuffle)
+        random_state: Optional random state for reproducibility
+
+    Returns:
+        Sequence with the specified region scrambled
+    """
+    if start < 0 or end > len(sequence) or start >= end:
+        raise ValueError(
+            f"Invalid region [{start}, {end}) for sequence of length {len(sequence)}"
+        )
+
+    prefix = sequence[:start]
+    region = sequence[start:end]
+    suffix = sequence[end:]
+
+    scrambled_region = _kmer_shuffle(region, k=k, random_state=random_state)
+
+    return prefix + scrambled_region + suffix
+
+
 def _read_bed_file(bed_regions: Union[str, pd.DataFrame]) -> pd.DataFrame:
     """
     Read BED file or validate BED DataFrame format.
@@ -146,7 +234,15 @@ def get_sm_sequences(chrom, start, end, reference_fasta, encoder=None):
 
     # Create a DataFrame for the metadata
     metadata_df = pd.DataFrame(
-        metadata, columns=["chrom", "window_start", "window_end", "variant_pos0", "ref", "alt"]
+        metadata,
+        columns=[
+            "chrom",
+            "window_start",
+            "window_end",
+            "variant_offset0",
+            "ref",
+            "alt",
+        ],
     )
 
     return ref_1h, alt_seqs_stacked, metadata_df
@@ -239,9 +335,7 @@ def get_sm_subsequences(
             )
     elif not has_bed:
         # Neither approach was specified
-        raise ValueError(
-            "Must provide either (anchor + anchor_radius) or bed_regions."
-        )
+        raise ValueError("Must provide either (anchor + anchor_radius) or bed_regions.")
 
     alt_seqs = []
     metadata = []
@@ -331,7 +425,11 @@ def get_sm_subsequences(
 
                 # Adjust window to stay within chromosome bounds
                 chrom_obj = reference_fasta[chrom]
-                chrom_len = len(chrom_obj) if hasattr(chrom_obj, '__len__') else len(chrom_obj.seq)
+                chrom_len = (
+                    len(chrom_obj)
+                    if hasattr(chrom_obj, "__len__")
+                    else len(chrom_obj.seq)
+                )
                 if window_start < 0:
                     window_start = 0
                     window_end = min(seq_len, chrom_len)
@@ -377,13 +475,17 @@ def get_sm_subsequences(
                         # Create a clone and substitute the base
                         if TORCH_AVAILABLE and isinstance(region_1h, torch.Tensor):
                             alt_1h = region_1h.clone()
-                            alt_1h[:, i] = torch.tensor(nt_to_1h[alt], dtype=alt_1h.dtype)
+                            alt_1h[:, i] = torch.tensor(
+                                nt_to_1h[alt], dtype=alt_1h.dtype
+                            )
                         else:
                             alt_1h = region_1h.copy()
                             alt_1h[:, i] = nt_to_1h[alt]
 
                         alt_seqs.append(alt_1h)
-                        metadata.append([chrom, window_start, window_end, i, ref_nt, alt])
+                        metadata.append(
+                            [chrom, window_start, window_end, i, ref_nt, alt]
+                        )
 
         # If no regions were processed, create empty ref_1h
         if ref_1h is None:
@@ -408,7 +510,263 @@ def get_sm_subsequences(
 
     # Create a DataFrame for the metadata
     metadata_df = pd.DataFrame(
-        metadata, columns=["chrom", "window_start", "window_end", "variant_pos0", "ref", "alt"]
+        metadata,
+        columns=[
+            "chrom",
+            "window_start",
+            "window_end",
+            "variant_offset0",
+            "ref",
+            "alt",
+        ],
     )
 
     return ref_1h, alt_seqs_stacked, metadata_df
+
+
+def get_scrambled_subsequences(
+    chrom: str,
+    seq_len: int,
+    reference_fasta,
+    bed_regions: Union[str, pd.DataFrame],
+    n_scrambles: int = 1,
+    kmer_size: int = 1,
+    encoder=None,
+    auto_map_chromosomes: bool = False,
+    random_state=None,
+):
+    """
+    Generate sequences with BED-defined regions scrambled using k-mer shuffle.
+
+    This function creates control sequences where specific regions (defined by BED file)
+    are scrambled while preserving (k-1)-mer frequencies. Useful for generating
+    negative controls that maintain sequence composition properties.
+
+    Args:
+        chrom: Chromosome name
+        seq_len: Total sequence length for each window
+        reference_fasta: Reference genome object (pyfaidx.Fasta or dict-like)
+        bed_regions: BED file path or DataFrame defining regions to scramble.
+                    BED format: chrom, start, end (0-based, half-open intervals).
+                    Each BED region is scrambled within its centered seq_len window.
+        n_scrambles: Number of scrambled versions to generate per region (default: 1)
+        kmer_size: Size of k-mers to shuffle (default: 1).
+                   - kmer_size=1: Shuffle individual nucleotides (preserves length only)
+                   - kmer_size=2: Shuffle 2-mers (preserves mononucleotide composition)
+                   - kmer_size=3: Shuffle 3-mers (preserves dinucleotide frequencies)
+                   Higher values preserve more local sequence context.
+        encoder: Optional custom encoding function
+        auto_map_chromosomes: Automatically map chromosome names between reference
+                             and BED file (e.g., 'chr1' <-> '1'). Default: False.
+        random_state: Random seed or numpy random generator for reproducibility.
+
+    Returns:
+        Tuple of (ref_seqs, scrambled_seqs, metadata):
+        - ref_seqs: One-hot encoded reference sequences, shape (N, 4, seq_len)
+        - scrambled_seqs: Scrambled sequences, shape (N * n_scrambles, 4, seq_len)
+        - metadata: DataFrame with columns:
+            - chrom: Chromosome name
+            - window_start: Start of sequence window (0-based)
+            - window_end: End of sequence window (0-based, exclusive)
+            - scramble_start: Start of scrambled region within window (0-based)
+            - scramble_end: End of scrambled region within window (0-based, exclusive)
+            - scramble_idx: Index of this scramble (0 to n_scrambles-1)
+            - ref: Original/reference sequence in scrambled region
+            - alt: Scrambled/alternate sequence in that region
+
+    Raises:
+        ValueError: If bed_regions is not provided, has invalid format, or kmer_size < 1
+    """
+    if bed_regions is None:
+        raise ValueError("bed_regions is required for get_scrambled_subsequences()")
+
+    if kmer_size < 1:
+        raise ValueError(f"kmer_size must be >= 1, got {kmer_size}")
+
+    # Handle random state
+    if random_state is None:
+        rng = np.random.default_rng()
+    elif isinstance(random_state, (int, np.integer)):
+        rng = np.random.default_rng(random_state)
+    else:
+        rng = random_state
+
+    # Parse BED file
+    bed_df = _read_bed_file(bed_regions)
+
+    # Apply chromosome name matching
+    ref_chroms = {chrom}
+    bed_chroms = set(bed_df["chrom"].unique())
+
+    mapping, unmatched = match_chromosomes_with_report(
+        ref_chroms,
+        bed_chroms,
+        verbose=False,
+        auto_map_chromosomes=auto_map_chromosomes,
+    )
+
+    if mapping:
+        bed_df = apply_chromosome_mapping(bed_df, mapping)
+
+    # Filter to target chromosome
+    chrom_bed_regions = bed_df[bed_df["chrom"] == chrom].copy()
+
+    if len(chrom_bed_regions) == 0:
+        warnings.warn(
+            f"No BED regions found for chromosome {chrom}. "
+            f"Returning original unshuffled sequence."
+        )
+        # Return original sequence (unshuffled) centered on chromosome
+        chrom_obj = reference_fasta[chrom]
+        if hasattr(chrom_obj, "__len__"):
+            chrom_len = len(chrom_obj)
+        else:
+            chrom_len = len(str(chrom_obj))
+
+        # Center window on chromosome
+        chrom_center = chrom_len // 2
+        window_start = max(0, chrom_center - seq_len // 2)
+        window_end = min(chrom_len, window_start + seq_len)
+
+        # Adjust if we hit the end
+        if window_end - window_start < seq_len:
+            window_start = max(0, window_end - seq_len)
+
+        # Get reference sequence
+        ref_seq_obj = reference_fasta[chrom][window_start:window_end]
+        if hasattr(ref_seq_obj, "seq"):
+            ref_seq = str(ref_seq_obj.seq)
+        else:
+            ref_seq = str(ref_seq_obj)
+
+        ref_1h = encode_seq(ref_seq, encoder)
+
+        if TORCH_AVAILABLE and isinstance(ref_1h, torch.Tensor):
+            ref_stacked = torch.stack([ref_1h])
+            # Return same sequence for all "scrambled" outputs (but unshuffled)
+            scrambled_stacked = torch.stack([ref_1h] * n_scrambles)
+        else:
+            ref_stacked = np.stack([ref_1h])
+            scrambled_stacked = np.stack([ref_1h] * n_scrambles)
+
+        # Create metadata indicating no scrambling occurred
+        meta_rows = []
+        for i in range(n_scrambles):
+            meta_rows.append(
+                {
+                    "chrom": chrom,
+                    "window_start": window_start,
+                    "window_end": window_end,
+                    "scramble_start": 0,
+                    "scramble_end": 0,  # Empty region indicates no scrambling
+                    "scramble_idx": i,
+                    "ref": ref_seq,
+                    "alt": ref_seq,  # Same as ref when no scrambling
+                }
+            )
+
+        return ref_stacked, scrambled_stacked, pd.DataFrame(meta_rows)
+
+    ref_sequences = []
+    scrambled_sequences = []
+    metadata = []
+
+    # Process each BED region
+    for _, bed_region in chrom_bed_regions.iterrows():
+        region_start = int(bed_region["start"])
+        region_end = int(bed_region["end"])
+        region_center = (region_start + region_end) // 2
+
+        # Calculate sequence window centered on BED region
+        window_start = region_center - seq_len // 2
+        window_end = window_start + seq_len
+
+        # Adjust window to stay within chromosome bounds
+        chrom_obj = reference_fasta[chrom]
+        chrom_len = len(chrom_obj) if hasattr(chrom_obj, "__len__") else len(chrom_obj)
+
+        if window_start < 0:
+            window_start = 0
+            window_end = min(seq_len, chrom_len)
+        elif window_end > chrom_len:
+            window_end = chrom_len
+            window_start = max(0, chrom_len - seq_len)
+
+        # Get reference sequence
+        ref_seq_obj = reference_fasta[chrom][window_start:window_end]
+        if hasattr(ref_seq_obj, "seq"):
+            ref_seq = str(ref_seq_obj.seq)
+        else:
+            ref_seq = str(ref_seq_obj)
+
+        if len(ref_seq) != seq_len:
+            warnings.warn(
+                f"Region {chrom}:{region_start}-{region_end} produces sequence of length "
+                f"{len(ref_seq)} instead of {seq_len}. Skipping."
+            )
+            continue
+
+        # Calculate scramble region relative to window
+        scramble_start_rel = max(0, region_start - window_start)
+        scramble_end_rel = min(seq_len, region_end - window_start)
+
+        if scramble_start_rel >= scramble_end_rel:
+            warnings.warn(
+                f"BED region {chrom}:{region_start}-{region_end} is outside window bounds. Skipping."
+            )
+            continue
+
+        # Store reference sequence
+        ref_1h = encode_seq(ref_seq, encoder)
+        ref_sequences.append(ref_1h)
+
+        # Get original region sequence for metadata
+        original_region = ref_seq[scramble_start_rel:scramble_end_rel]
+
+        # Generate n_scrambles scrambled versions
+        for scramble_idx in range(n_scrambles):
+            scrambled_seq = _scramble_region(
+                ref_seq,
+                scramble_start_rel,
+                scramble_end_rel,
+                k=kmer_size,
+                random_state=rng,
+            )
+
+            scrambled_1h = encode_seq(scrambled_seq, encoder)
+            scrambled_sequences.append(scrambled_1h)
+
+            scrambled_region = scrambled_seq[scramble_start_rel:scramble_end_rel]
+
+            metadata.append(
+                {
+                    "chrom": chrom,
+                    "window_start": window_start,
+                    "window_end": window_end,
+                    "scramble_start": scramble_start_rel,
+                    "scramble_end": scramble_end_rel,
+                    "scramble_idx": scramble_idx,
+                    "ref": original_region,
+                    "alt": scrambled_region,
+                }
+            )
+
+    # Stack sequences
+    if ref_sequences:
+        if TORCH_AVAILABLE and isinstance(ref_sequences[0], torch.Tensor):
+            ref_stacked = torch.stack(ref_sequences)
+            scrambled_stacked = torch.stack(scrambled_sequences)
+        else:
+            ref_stacked = np.stack(ref_sequences)
+            scrambled_stacked = np.stack(scrambled_sequences)
+    else:
+        if TORCH_AVAILABLE:
+            ref_stacked = torch.empty((0, 4, seq_len), dtype=torch.float32)
+            scrambled_stacked = torch.empty((0, 4, seq_len), dtype=torch.float32)
+        else:
+            ref_stacked = np.empty((0, 4, seq_len), dtype=np.float32)
+            scrambled_stacked = np.empty((0, 4, seq_len), dtype=np.float32)
+
+    metadata_df = pd.DataFrame(metadata)
+
+    return ref_stacked, scrambled_stacked, metadata_df

{supremo_lite-0.5.4 → supremo_lite-1.0.0}/src/supremo_lite/personalize.py

@@ -42,7 +42,7 @@ IUPAC_CODES = {
     "D": "[AGT]",
     "H": "[ACT]",
     "V": "[ACG]",
-    "N": "[ACGT]"
+    "N": "[ACGT]",
 }
 
 
@@ -2811,6 +2811,7 @@ def get_pam_disrupting_alt_sequences(
         ...     ref, vcf, seq_len=50, max_pam_distance=10, n_chunks=5):
         ...     predictions = model.predict(alt_seqs, ref_seqs)
     """
+
     # Helper function to find PAM sites in a sequence
     def _find_pam_sites(sequence, pam_pattern):
         """Find all PAM site positions in a sequence using IUPAC codes.
@@ -2830,7 +2831,7 @@ def get_pam_disrupting_alt_sequences(
                 pat_base = pat_upper[j]
 
                 # Sequence 'N' (padding or unknown) matches any pattern base
-                if seq_base == 'N':
+                if seq_base == "N":
                     continue  # Always matches
 
                 # Get allowed bases for this pattern position
@@ -3003,9 +3004,7 @@ def get_pam_disrupting_alt_sequences(
         ref_allele = var.get("ref", "")
         alt_allele = var.get("alt", "")
         is_indel = (
-            len(ref_allele) != len(alt_allele)
-            or ref_allele == "-"
-            or alt_allele == "-"
+            len(ref_allele) != len(alt_allele) or ref_allele == "-" or alt_allele == "-"
         )
 
         truly_disrupted_pam_sites = []
@@ -3053,8 +3052,12 @@ def get_pam_disrupting_alt_sequences(
         # For each disrupted PAM site, create a metadata entry
         for pam_site_pos in truly_disrupted_pam_sites:
             # Extract PAM sequences
-            ref_pam_seq = ref_window_seq[pam_site_pos : pam_site_pos + len(pam_sequence)]
-            alt_pam_seq = modified_window[pam_site_pos : pam_site_pos + len(pam_sequence)]
+            ref_pam_seq = ref_window_seq[
+                pam_site_pos : pam_site_pos + len(pam_sequence)
+            ]
+            alt_pam_seq = modified_window[
+                pam_site_pos : pam_site_pos + len(pam_sequence)
+            ]
 
             # Calculate distance from variant to PAM
             pam_distance = abs(pam_site_pos - variant_pos_in_window)
@@ -3063,12 +3066,14 @@ def get_pam_disrupting_alt_sequences(
             pam_disrupting_variants_list.append(var)
 
             # Store PAM-specific metadata
-            pam_metadata_list.append({
-                'pam_site_pos': pam_site_pos,
-                'pam_ref_sequence': ref_pam_seq,
-                'pam_alt_sequence': alt_pam_seq,
-                'pam_distance': pam_distance
-            })
+            pam_metadata_list.append(
+                {
+                    "pam_site_pos": pam_site_pos,
+                    "pam_ref_sequence": ref_pam_seq,
+                    "pam_alt_sequence": alt_pam_seq,
+                    "pam_distance": pam_distance,
+                }
+            )
 
     # If no PAM-disrupting variants found, yield empty results
     if not pam_disrupting_variants_list:
@@ -3076,7 +3081,9 @@ def get_pam_disrupting_alt_sequences(
         return
 
     # Create DataFrame with filtered PAM-disrupting variants
-    filtered_variants_df = pd.DataFrame(pam_disrupting_variants_list).reset_index(drop=True)
+    filtered_variants_df = pd.DataFrame(pam_disrupting_variants_list).reset_index(
+        drop=True
+    )
     pam_metadata_df = pd.DataFrame(pam_metadata_list)
 
     # Call get_alt_ref_sequences with the filtered variants
@@ -3087,12 +3094,13 @@ def get_pam_disrupting_alt_sequences(
         encode,
         n_chunks,
         encoder,
-        auto_map_chromosomes
+        auto_map_chromosomes,
     ):
         # Merge PAM-specific metadata with base metadata
         # Both should have the same number of rows since we created one entry per PAM site
-        enriched_metadata = pd.concat([base_metadata.reset_index(drop=True),
-                                       pam_metadata_df], axis=1)
+        enriched_metadata = pd.concat(
+            [base_metadata.reset_index(drop=True), pam_metadata_df], axis=1
+        )
 
         # Yield the chunk with enriched metadata
         yield (alt_seqs, ref_seqs, enriched_metadata)

{supremo_lite-0.5.4 → supremo_lite-1.0.0}/src/supremo_lite/prediction_alignment.py

@@ -40,19 +40,49 @@ class VariantPosition:
     svlen: int  # Length of structural variant (base pairs, signed for DEL/INS)
     variant_type: str  # Type of variant ('SNV', 'INS', 'DEL', 'DUP', 'INV', 'BND')
 
-    def get_bin_positions(self, bin_size: int) -> Tuple[int, int, int]:
+    def get_bin_positions(
+        self, bin_size: int, window_start: int, crop_length: int
+    ) -> Tuple[int, int, int]:
         """
-        Convert base pair positions to bin indices.
+        Convert base pair positions to bin indices relative to window.
 
         Args:
             bin_size: Number of base pairs per prediction bin
+            window_start: Start position of the sequence window (0-based genomic coord).
+            crop_length: Number of base pairs cropped from each edge by the model.
+                        This accounts for edge bases removed before prediction.
 
         Returns:
-            Tuple of (ref_bin, alt_start_bin, alt_end_bin)
+            Tuple of (ref_bin, alt_start_bin, alt_end_bin) as bin indices
+            relative to the prediction vector. For centered masking, these
+            represent the center and extent of the masked region.
+
+        Notes:
+            - Positions are calculated relative to window_start, not absolute genomic coords
+            - crop_length accounts for edge bases removed before prediction
+            - Masked bins are centered on the variant position
         """
-        ref_bin = int(np.ceil(self.ref_pos / bin_size))
-        alt_start_bin = int(np.ceil(self.alt_pos / bin_size))
-        alt_end_bin = int(np.ceil((self.alt_pos + abs(self.svlen)) / bin_size))
+        # Calculate positions relative to window
+        rel_ref_pos = self.ref_pos - window_start
+        rel_alt_pos = self.alt_pos - window_start
+
+        # Account for cropping (bases removed from start of window before prediction)
+        rel_ref_pos -= crop_length
+        rel_alt_pos -= crop_length
+
+        # Convert to bin indices using floor division (not ceil!)
+        ref_bin_center = rel_ref_pos // bin_size
+        alt_bin_center = rel_alt_pos // bin_size
+
+        # Calculate number of bins to mask
+        svlen_bins = int(np.ceil(abs(self.svlen) / bin_size))
+        half_bins = svlen_bins // 2
+
+        # Center the masked region on the variant
+        ref_bin = ref_bin_center - half_bins
+        alt_start_bin = alt_bin_center - half_bins
+        alt_end_bin = alt_bin_center + (svlen_bins - half_bins)
+
         return ref_bin, alt_start_bin, alt_end_bin
 
 
@@ -71,24 +101,27 @@ class PredictionAligner1D:
     Args:
         target_size: Expected number of bins in the prediction output
         bin_size: Number of base pairs per prediction bin (model-specific)
+        crop_length: Number of base pairs cropped from each edge by the model
 
     Example:
-        >>> aligner = PredictionAligner1D(target_size=896, bin_size=128)
+        >>> aligner = PredictionAligner1D(target_size=896, bin_size=128, crop_length=0)
         >>> ref_aligned, alt_aligned = aligner.align_predictions(
         ...     ref_pred, alt_pred, 'INS', variant_position
         ... )
     """
 
-    def __init__(self, target_size: int, bin_size: int):
+    def __init__(self, target_size: int, bin_size: int, crop_length: int):
         """
         Initialize the 1D prediction aligner.
 
         Args:
             target_size: Expected number of bins in prediction (e.g., 896 for Enformer)
             bin_size: Base pairs per bin (e.g., 128 for Enformer)
+            crop_length: Number of base pairs cropped from each edge by the model
         """
         self.target_size = target_size
         self.bin_size = bin_size
+        self.crop_length = crop_length
 
     def align_predictions(
         self,
@@ -96,6 +129,7 @@ class PredictionAligner1D:
         alt_pred: Union[np.ndarray, "torch.Tensor"],
         svtype: str,
         var_pos: VariantPosition,
+        window_start: int = 0,
     ) -> Tuple[Union[np.ndarray, "torch.Tensor"], Union[np.ndarray, "torch.Tensor"]]:
         """
         Main entry point for 1D prediction alignment.
@@ -105,6 +139,8 @@ class PredictionAligner1D:
             alt_pred: Alternate prediction vector (length N)
             svtype: Variant type ('DEL', 'DUP', 'INS', 'INV', 'SNV')
             var_pos: Variant position information
+            window_start: Start position of sequence window (0-based genomic coord).
+                         Required for correct bin calculation. Defaults to 0.
 
         Returns:
             Tuple of (aligned_ref, aligned_alt) vectors with NaN masking applied
@@ -120,10 +156,12 @@ class PredictionAligner1D:
 
         if svtype_normalized in ["DEL", "DUP", "INS"]:
             return self._align_indel_predictions(
-                ref_pred, alt_pred, svtype_normalized, var_pos
+                ref_pred, alt_pred, svtype_normalized, var_pos, window_start
             )
         elif svtype_normalized == "INV":
-            return self._align_inversion_predictions(ref_pred, alt_pred, var_pos)
+            return self._align_inversion_predictions(
+                ref_pred, alt_pred, var_pos, window_start
+            )
         elif svtype_normalized in ["SNV", "MNV"]:
             # SNVs don't change coordinates, direct alignment
             is_torch = TORCH_AVAILABLE and torch.is_tensor(ref_pred)
@@ -140,18 +178,22 @@ class PredictionAligner1D:
         alt_pred: Union[np.ndarray, "torch.Tensor"],
         svtype: str,
         var_pos: VariantPosition,
+        window_start: int = 0,
     ) -> Tuple[Union[np.ndarray, "torch.Tensor"], Union[np.ndarray, "torch.Tensor"]]:
         """
         Align predictions for insertions, deletions, and duplications.
 
         Strategy:
         1. For DEL: Swap REF/ALT (deletion removes from REF)
-        2. Insert NaN bins in shorter sequence
+        2. Insert NaN bins in shorter sequence (centered on variant)
         3. Crop edges to maintain target size
         4. For DEL: Swap back
 
         This ensures that positions present in one sequence but not the other
         are marked with NaN, enabling fair comparison of overlapping regions.
+
+        Args:
+            window_start: Start position of sequence window (0-based genomic coord)
         """
         is_torch = TORCH_AVAILABLE and torch.is_tensor(ref_pred)
 
@@ -170,8 +212,10 @@ class PredictionAligner1D:
                 var_pos.alt_pos, var_pos.ref_pos, var_pos.svlen, svtype
             )
 
-        # Get bin positions
-        ref_bin, alt_start_bin, alt_end_bin = var_pos.get_bin_positions(self.bin_size)
+        # Get bin positions (window-relative, centered)
+        ref_bin, alt_start_bin, alt_end_bin = var_pos.get_bin_positions(
+            self.bin_size, window_start, self.crop_length
+        )
         bins_to_add = alt_end_bin - alt_start_bin
 
         # Insert NaN bins in REF where variant exists in ALT
@@ -248,6 +292,7 @@ class PredictionAligner1D:
         ref_pred: Union[np.ndarray, "torch.Tensor"],
         alt_pred: Union[np.ndarray, "torch.Tensor"],
         var_pos: VariantPosition,
+        window_start: int = 0,
     ) -> Tuple[Union[np.ndarray, "torch.Tensor"], Union[np.ndarray, "torch.Tensor"]]:
         """
         Align predictions for inversions.
@@ -259,6 +304,9 @@ class PredictionAligner1D:
         For strand-aware models, inversions can significantly affect predictions
         because regulatory elements now appear on the opposite strand. We mask
         the inverted region to focus comparison on unaffected flanking sequences.
+
+        Args:
+            window_start: Start position of sequence window (0-based genomic coord)
         """
         is_torch = TORCH_AVAILABLE and torch.is_tensor(ref_pred)
 
@@ -270,7 +318,9 @@ class PredictionAligner1D:
             ref_np = ref_pred.copy()
             alt_np = alt_pred.copy()
 
-        var_start, _, var_end = var_pos.get_bin_positions(self.bin_size)
+        var_start, _, var_end = var_pos.get_bin_positions(
+            self.bin_size, window_start, self.crop_length
+        )
 
         # Mask inverted region in both REF and ALT
         ref_np[var_start : var_end + 1] = np.nan
@@ -373,19 +423,23 @@ class PredictionAligner2D:
         target_size: Expected matrix dimension (NxN)
         bin_size: Number of base pairs per matrix bin (model-specific)
         diag_offset: Number of diagonal bins to mask (model-specific)
+        crop_length: Number of base pairs cropped from each edge by the model
 
     Example:
         >>> aligner = PredictionAligner2D(
         ...     target_size=448,
         ...     bin_size=2048,
-        ...     diag_offset=2
+        ...     diag_offset=2,
+        ...     crop_length=0
         ... )
         >>> ref_aligned, alt_aligned = aligner.align_predictions(
         ...     ref_matrix, alt_matrix, 'DEL', variant_position
         ... )
     """
 
-    def __init__(self, target_size: int, bin_size: int, diag_offset: int):
+    def __init__(
+        self, target_size: int, bin_size: int, diag_offset: int, crop_length: int
+    ):
         """
         Initialize the 2D prediction aligner.
 
@@ -393,10 +447,12 @@ class PredictionAligner2D:
             target_size: Matrix dimension (e.g., 448 for Akita)
             bin_size: Base pairs per bin (e.g., 2048 for Akita)
             diag_offset: Diagonal masking offset (e.g., 2 for Akita)
+            crop_length: Number of base pairs cropped from each edge by the model
         """
         self.target_size = target_size
         self.bin_size = bin_size
         self.diag_offset = diag_offset
+        self.crop_length = crop_length
 
     def align_predictions(
         self,
@@ -404,6 +460,7 @@ class PredictionAligner2D:
         alt_pred: Union[np.ndarray, "torch.Tensor"],
         svtype: str,
         var_pos: VariantPosition,
+        window_start: int = 0,
     ) -> Tuple[Union[np.ndarray, "torch.Tensor"], Union[np.ndarray, "torch.Tensor"]]:
         """
         Main entry point for 2D matrix alignment.
@@ -413,6 +470,8 @@ class PredictionAligner2D:
             alt_pred: Alternate prediction matrix (NxN)
             svtype: Variant type ('DEL', 'DUP', 'INS', 'INV', 'SNV')
             var_pos: Variant position information
+            window_start: Start position of sequence window (0-based genomic coord).
+                         Required for correct bin calculation. Defaults to 0.
 
         Returns:
             Tuple of (aligned_ref, aligned_alt) matrices with NaN masking applied
@@ -428,10 +487,12 @@ class PredictionAligner2D:
 
         if svtype_normalized in ["DEL", "DUP", "INS"]:
             return self._align_indel_matrices(
-                ref_pred, alt_pred, svtype_normalized, var_pos
+                ref_pred, alt_pred, svtype_normalized, var_pos, window_start
             )
         elif svtype_normalized == "INV":
-            return self._align_inversion_matrices(ref_pred, alt_pred, var_pos)
+            return self._align_inversion_matrices(
+                ref_pred, alt_pred, var_pos, window_start
+            )
         elif svtype_normalized in ["SNV", "MNV"]:
             # SNVs don't change coordinates, direct alignment
             is_torch = TORCH_AVAILABLE and torch.is_tensor(ref_pred)
@@ -448,15 +509,19 @@ class PredictionAligner2D:
         alt_pred: Union[np.ndarray, "torch.Tensor"],
         svtype: str,
         var_pos: VariantPosition,
+        window_start: int = 0,
     ) -> Tuple[Union[np.ndarray, "torch.Tensor"], Union[np.ndarray, "torch.Tensor"]]:
         """
         Align matrices for insertions, deletions, and duplications.
 
         Strategy:
         1. For DEL: Swap REF/ALT (deletion removes from REF)
-        2. Insert NaN bins (rows AND columns) in shorter matrix
+        2. Insert NaN bins (rows AND columns) in shorter matrix (centered on variant)
         3. Crop edges to maintain target size
         4. For DEL: Swap back
+
+        Args:
+            window_start: Start position of sequence window (0-based genomic coord)
         """
         is_torch = TORCH_AVAILABLE and torch.is_tensor(ref_pred)
 
@@ -475,8 +540,10 @@ class PredictionAligner2D:
                 var_pos.alt_pos, var_pos.ref_pos, var_pos.svlen, svtype
             )
 
-        # Get bin positions
-        ref_bin, alt_start_bin, alt_end_bin = var_pos.get_bin_positions(self.bin_size)
+        # Get bin positions (window-relative, centered)
+        ref_bin, alt_start_bin, alt_end_bin = var_pos.get_bin_positions(
+            self.bin_size, window_start, self.crop_length
+        )
         bins_to_add = alt_end_bin - alt_start_bin
 
         # Insert NaN bins in REF where variant exists in ALT
@@ -541,6 +608,7 @@ class PredictionAligner2D:
         ref_pred: Union[np.ndarray, "torch.Tensor"],
         alt_pred: Union[np.ndarray, "torch.Tensor"],
         var_pos: VariantPosition,
+        window_start: int = 0,
     ) -> Tuple[Union[np.ndarray, "torch.Tensor"], Union[np.ndarray, "torch.Tensor"]]:
         """
         Align matrices for inversions.
@@ -556,6 +624,9 @@ class PredictionAligner2D:
 
         The same NaN pattern is mirrored to ALT so both matrices have identical
         masked regions, enabling fair comparison of the unaffected areas.
+
+        Args:
+            window_start: Start position of sequence window (0-based genomic coord)
         """
         is_torch = TORCH_AVAILABLE and torch.is_tensor(ref_pred)
 
@@ -567,7 +638,9 @@ class PredictionAligner2D:
             ref_np = ref_pred.copy()
             alt_np = alt_pred.copy()
 
-        var_start, _, var_end = var_pos.get_bin_positions(self.bin_size)
+        var_start, _, var_end = var_pos.get_bin_positions(
+            self.bin_size, window_start, self.crop_length
+        )
 
         # Mask inverted region in REF (cross-pattern: rows + columns)
         ref_np[var_start : var_end + 1, :] = np.nan
@@ -802,6 +875,7 @@ def align_predictions_by_coordinate(
     metadata_row: dict,
     bin_size: int,
     prediction_type: str,
+    crop_length: int,
     matrix_size: Optional[int] = None,
     diag_offset: int = 0,
 ) -> Tuple[Union[np.ndarray, "torch.Tensor"], Union[np.ndarray, "torch.Tensor"]]:
@@ -812,7 +886,7 @@ def align_predictions_by_coordinate(
     vectors (e.g., chromatin accessibility, TF binding) and 2D matrices (e.g., Hi-C contact maps),
     routing to the appropriate alignment strategy based on variant type.
 
-    IMPORTANT: Model-specific parameters (bin_size, matrix_size) must be explicitly
+    IMPORTANT: Model-specific parameters (bin_size, crop_length, matrix_size) must be explicitly
     provided by the user. There are no defaults because these vary across different models.
 
     Args:
@@ -824,10 +898,13 @@ def align_predictions_by_coordinate(
             - 'variant_pos0': Variant position (0-based, absolute genomic coordinate)
             - 'svlen': Length of structural variant (optional, for symbolic alleles)
         bin_size: Number of base pairs per prediction bin (REQUIRED, model-specific)
-            Examples: 2048 for Akita
+            Examples: 2048 for Akita, 128 for Enformer
         prediction_type: Type of predictions ("1D" or "2D")
             - "1D": Vector predictions (chromatin accessibility, TF binding, etc.)
             - "2D": Matrix predictions (Hi-C contact maps, Micro-C, etc.)
+        crop_length: Number of base pairs cropped from each edge by the model (REQUIRED)
+            This accounts for edge bases removed before prediction.
+            Examples: 0 for models without cropping
         matrix_size: Size of contact matrix (REQUIRED for 2D type)
             Examples: 448 for Akita
         diag_offset: Number of diagonal bins to mask (default: 0 for no masking)
@@ -849,7 +926,8 @@ def align_predictions_by_coordinate(
         ...     metadata_row={'variant_type': 'INS', 'window_start': 0,
         ...                   'variant_pos0': 500, 'svlen': 100},
         ...     bin_size=128,
-        ...     prediction_type="1D"
+        ...     prediction_type="1D",
+        ...     crop_length=0
         ... )
 
     Example (2D contact maps with diagonal masking):
@@ -860,6 +938,7 @@ def align_predictions_by_coordinate(
         ...                   'variant_pos0': 50000, 'svlen': -2048},
         ...     bin_size=2048,
         ...     prediction_type="2D",
+        ...     crop_length=0,
         ...     matrix_size=448,
         ...     diag_offset=2  # Optional: use 0 if no diagonal masking
         ... )
@@ -872,6 +951,7 @@ def align_predictions_by_coordinate(
         ...                   'variant_pos0': 1000, 'svlen': 500},
         ...     bin_size=1000,
         ...     prediction_type="2D",
+        ...     crop_length=0,
         ...     matrix_size=512
         ...     # diag_offset defaults to 0 (no masking)
         ... )
@@ -937,7 +1017,9 @@ def align_predictions_by_coordinate(
         # Handle multi-target predictions [n_targets, n_bins]
         if ndim > 1:
             target_size = ref_preds.shape[-1]  # Number of bins
-            aligner = PredictionAligner1D(target_size=target_size, bin_size=bin_size)
+            aligner = PredictionAligner1D(
+                target_size=target_size, bin_size=bin_size, crop_length=crop_length
+            )
 
             # Align each target separately
             n_targets = ref_preds.shape[0]
@@ -948,7 +1030,7 @@ def align_predictions_by_coordinate(
                 ref_target = ref_preds[target_idx]
                 alt_target = alt_preds[target_idx]
                 ref_aligned, alt_aligned = aligner.align_predictions(
-                    ref_target, alt_target, variant_type, var_pos
+                    ref_target, alt_target, variant_type, var_pos, window_start
                 )
                 ref_aligned_list.append(ref_aligned)
                 alt_aligned_list.append(alt_aligned)
@@ -965,9 +1047,11 @@ def align_predictions_by_coordinate(
         else:
             # Single target prediction [n_bins]
             target_size = len(ref_preds)
-            aligner = PredictionAligner1D(target_size=target_size, bin_size=bin_size)
+            aligner = PredictionAligner1D(
+                target_size=target_size, bin_size=bin_size, crop_length=crop_length
+            )
             return aligner.align_predictions(
-                ref_preds, alt_preds, variant_type, var_pos
+                ref_preds, alt_preds, variant_type, var_pos, window_start
             )
     else:  # 2D
         # Check if predictions are 1D (flattened upper triangular) or 2D (full matrix)
@@ -989,10 +1073,13 @@ def align_predictions_by_coordinate(
 
             # Align matrices
             aligner = PredictionAligner2D(
-                target_size=matrix_size, bin_size=bin_size, diag_offset=diag_offset
+                target_size=matrix_size,
+                bin_size=bin_size,
+                diag_offset=diag_offset,
+                crop_length=crop_length,
             )
             aligned_ref_matrix, aligned_alt_matrix = aligner.align_predictions(
-                ref_matrix, alt_matrix, variant_type, var_pos
+                ref_matrix, alt_matrix, variant_type, var_pos, window_start
             )
 
             # Convert back to flattened format
@@ -1007,8 +1094,11 @@ def align_predictions_by_coordinate(
         else:
             # Already 2D matrices
             aligner = PredictionAligner2D(
-                target_size=matrix_size, bin_size=bin_size, diag_offset=diag_offset
+                target_size=matrix_size,
+                bin_size=bin_size,
+                diag_offset=diag_offset,
+                crop_length=crop_length,
             )
             return aligner.align_predictions(
-                ref_preds, alt_preds, variant_type, var_pos
+                ref_preds, alt_preds, variant_type, var_pos, window_start
             )

{supremo_lite-0.5.4 → supremo_lite-1.0.0}/src/supremo_lite/variant_utils.py

@@ -5,6 +5,7 @@ This module provides functions for reading variants from VCF files
 and other related operations.
 """
 
+import gzip
 import io
 import pandas as pd
 import numpy as np
@@ -14,6 +15,22 @@ from typing import Dict, Optional, List, Tuple, Union
 from dataclasses import dataclass
 
 
+def _open_vcf(path: str, mode: str = "rt"):
+    """
+    Open a VCF file, automatically detecting gzip compression.
+
+    Args:
+        path: Path to VCF file (may be .vcf or .vcf.gz)
+        mode: File mode. Use 'rt' for text reading (default).
+
+    Returns:
+        File handle (context manager compatible)
+    """
+    if path.endswith(".gz"):
+        return gzip.open(path, mode)
+    return open(path, mode.replace("t", "") if "t" in mode else mode)
+
+
 @dataclass
 class BreakendVariant:
     """
@@ -625,13 +642,15 @@ def _count_vcf_header_lines(path: str) -> int:
     - Lines starting with ## (metadata)
     - Line starting with #CHROM (column header)
 
+    Supports both uncompressed (.vcf) and gzip-compressed (.vcf.gz) files.
+
     Args:
         path: Path to VCF file
 
     Returns:
         Number of lines to skip (all ## lines + the #CHROM line)
     """
-    with open(path, "r") as f:
+    with _open_vcf(path, "rt") as f:
         header_count = 0
         for line in f:
             if line.startswith("##"):
@@ -648,6 +667,8 @@ def read_vcf(path, include_info=True, classify_variants=True):
     """
     Read VCF file into pandas DataFrame with enhanced variant classification.
 
+    Supports both uncompressed (.vcf) and gzip-compressed (.vcf.gz) files.
+
     Args:
         path: Path to VCF file
         include_info: Whether to include INFO field (default: True)
@@ -656,11 +677,21 @@ def read_vcf(path, include_info=True, classify_variants=True):
     Returns:
         DataFrame with columns: chrom, pos1, id, ref, alt, [info], [variant_type]
 
+    Raises:
+        FileNotFoundError: If VCF file does not exist
+        ValueError: If VCF file has invalid format or no valid header
+
     Notes:
         - INFO field parsing enables structural variant classification
         - variant_type column uses VCF 4.2 compliant classification
         - Compatible with existing code expecting basic 5-column format
     """
+    import os
+
+    # Validate file exists
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"VCF file not found: {path}")
+
     # Determine columns to read based on parameters
     if include_info:
         usecols = [0, 1, 2, 3, 4, 7]  # Include INFO field
@@ -670,12 +701,38 @@ def read_vcf(path, include_info=True, classify_variants=True):
         base_columns = ["chrom", "pos1", "id", "ref", "alt"]
 
     # Count header lines for VCF line tracking (needed for vcf_line column)
-    header_count = _count_vcf_header_lines(path)
+    try:
+        header_count = _count_vcf_header_lines(path)
+    except Exception as e:
+        raise ValueError(f"Failed to parse VCF header in {path}: {e}")
+
+    if header_count == 0:
+        raise ValueError(
+            f"VCF file {path} appears to have no header lines. "
+            "Valid VCF files must start with ##fileformat or #CHROM header."
+        )
 
     # Read VCF using pandas with comment='#' to skip all header lines automatically
-    df = pd.read_table(
-        path, comment="#", header=None, names=base_columns, usecols=usecols
-    )
+    try:
+        df = pd.read_table(
+            path,
+            comment="#",
+            header=None,
+            names=base_columns,
+            usecols=usecols,
+            on_bad_lines="warn",
+        )
+    except pd.errors.EmptyDataError:
+        warnings.warn(f"VCF file {path} contains no data rows after header.")
+        empty_cols = base_columns + (["variant_type"] if classify_variants else [])
+        return pd.DataFrame(columns=empty_cols)
+
+    # Handle empty DataFrame
+    if len(df) == 0:
+        warnings.warn(f"VCF file {path} contains no variant records.")
+        if classify_variants:
+            df["variant_type"] = pd.Series(dtype=str)
+        return df
 
     # Add VCF line numbers for debugging (1-indexed, accounting for header lines)
     # Line number = header_lines + 1 (for 1-indexing) + row_index
@@ -683,9 +740,22 @@ def read_vcf(path, include_info=True, classify_variants=True):
 
     # Validate that pos1 column is numeric
     if not pd.api.types.is_numeric_dtype(df["pos1"]):
-        raise ValueError(
-            f"Position column (second column) must be numeric, got {df['pos1'].dtype}"
-        )
+        # Try to convert, providing helpful error message
+        try:
+            df["pos1"] = pd.to_numeric(df["pos1"], errors="coerce")
+            invalid_rows = df[df["pos1"].isna()]
+            if len(invalid_rows) > 0:
+                warnings.warn(
+                    f"Found {len(invalid_rows)} rows with non-numeric positions in {path}. "
+                    f"First invalid at VCF line {invalid_rows.iloc[0]['vcf_line']}. "
+                    "These rows will be removed."
+                )
+                df = df.dropna(subset=["pos1"])
+                df["pos1"] = df["pos1"].astype(int)
+        except Exception as e:
+            raise ValueError(
+                f"Position column must be numeric in {path}, conversion failed: {e}"
+            )
 
     # Filter out multiallelic variants (ALT alleles containing commas)
     df = _filter_multiallelic_variants(df)
@@ -775,6 +845,8 @@ def get_vcf_chromosomes(path):
     """
     Get list of chromosomes in VCF file without loading all variants.
 
+    Supports both uncompressed (.vcf) and gzip-compressed (.vcf.gz) files.
+
     Args:
         path: Path to VCF file
 
@@ -782,7 +854,7 @@ def get_vcf_chromosomes(path):
         Set of chromosome names found in the VCF file
     """
     chromosomes = set()
-    with open(path, "r") as f:
+    with _open_vcf(path, "rt") as f:
         for line in f:
             if line.startswith("##"):
                 continue
@@ -800,6 +872,8 @@ def read_vcf_chromosome(
     """
     Read VCF file for a specific chromosome only with enhanced variant classification.
 
+    Supports both uncompressed (.vcf) and gzip-compressed (.vcf.gz) files.
+
     Args:
         path: Path to VCF file
         target_chromosome: Chromosome name to filter for
@@ -813,7 +887,7 @@ def read_vcf_chromosome(
     chromosome_lines = []
     header_line = None
 
-    with open(path, "r") as f:
+    with _open_vcf(path, "rt") as f:
         for line in f:
             if line.startswith("##"):
                 continue