allelix 2.2.1__tar.gz → 2.2.3__tar.gz

{allelix-2.2.1 → allelix-2.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 2.2.1
+Version: 2.2.3
 Summary: Open-source genotype analysis toolkit. Format-agnostic ingestion, database-agnostic annotation, offline-first.
 Author: Allelix
 Maintainer-email: dial481 <dial481@users.noreply.github.com>
@@ -190,8 +190,10 @@ disease findings. Wherever you write them via `--output <path>`,
 that's where they sit until you delete them. Allelix doesn't
 auto-clean and won't warn you when you write to `/tmp/` or any
 other shared location. Treat the files as personal data: read them,
-move them somewhere you control, or delete when you're done. A
-data-lifecycle subcommand is planned for v2.1.
+move them somewhere you control, or delete when you're done.
+`allelix db clean` (shipped in v2.2.0) handles the cache side of
+the lifecycle; output reports are still the user's responsibility
+to manage.
 
 ## Configuration
 

{allelix-2.2.1 → allelix-2.2.3}/README.md

@@ -151,8 +151,10 @@ disease findings. Wherever you write them via `--output <path>`,
 that's where they sit until you delete them. Allelix doesn't
 auto-clean and won't warn you when you write to `/tmp/` or any
 other shared location. Treat the files as personal data: read them,
-move them somewhere you control, or delete when you're done. A
-data-lifecycle subcommand is planned for v2.1.
+move them somewhere you control, or delete when you're done.
+`allelix db clean` (shipped in v2.2.0) handles the cache side of
+the lifecycle; output reports are still the user's responsibility
+to manage.
 
 ## Configuration
 

{allelix-2.2.1 → allelix-2.2.3}/allelix/annotators/clinvar.py

@@ -685,6 +685,12 @@ class ClinVarAnnotator(Annotator):
                 ]
                 if len(matches) == 1:
                     ref, alt, rsid = matches[0]
+                    # GH #128: stash the pre-resolution pseudo-rsID
+                    # for audit / debug before stamping. Debug-only —
+                    # see Variant.original_rsid docstring; the
+                    # serialization-guard test asserts this never
+                    # reaches public output.
+                    v.original_rsid = v.rsid
                     v.rsid = rsid
                     resolved[(v.chromosome, v.position, ref, alt)] = rsid
         return resolved

{allelix-2.2.1 → allelix-2.2.3}/allelix/annotators/gnomad.py

@@ -76,6 +76,24 @@ class GnomadAnnotator(Annotator):
                     f"gnomAD cache not found at {self._db_path}. Run `allelix db update` first."
                 )
             self._conn = sqlite3.connect(self._db_path)
+            # GH #134: lazy-create the position index on caches built before
+            # the index landed (anything <= v2.2.1). The index is required
+            # for ``bulk_resolve_rsids_from_positions`` (GH #128) to perform
+            # well — without it that method scans the full 57M-row
+            # ``gnomad_frequencies`` table per query, which is the root
+            # cause of the ~2x analyze slowdown on rsID-less WGS VCFs
+            # observed at the v2.2.2 ship gate. ``CREATE INDEX IF NOT
+            # EXISTS`` is a no-op once the index is in place (microseconds
+            # to check the schema); the one-time build cost on first run
+            # against a pre-v2.2.2 cache is a few minutes against the 57M
+            # rows but only happens once per cache. Doing this here in
+            # ``_connection`` rather than as a schema migration avoids
+            # forcing every user to re-download the 2.7 GB compressed
+            # cache for what's a transparent index addition.
+            self._conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_gnomad_position ON gnomad_frequencies(chrom, pos)"
+            )
+            self._conn.commit()
         return self._conn
 
     def setup(self) -> None:
@@ -198,6 +216,79 @@ class GnomadAnnotator(Annotator):
                 result.setdefault(rsid, []).append((chrom, pos, ref, alt))
         return result
 
+    def bulk_resolve_rsids_from_positions(
+        self, positions: set[tuple[str, int]]
+    ) -> dict[tuple[str, int], list[tuple[str, str, str]]]:
+        """Reverse-lookup rsIDs by ``(chromosome, position)``.
+
+        Counterpart to :meth:`bulk_resolve_coordinates` for the GH #128
+        flow: a VCF variant arriving with an empty ID column (DeepVariant
+        gVCFs, GIAB GRCh38 benchmarks, anything that doesn't stamp dbSNP
+        IDs) is parsed as a positional pseudo-ID. The ClinVar resolver
+        (:meth:`allelix.annotators.clinvar.ClinVarAnnotator.bulk_resolve_rsids`)
+        recovers an rsID only for variants in ClinVar's curated subset —
+        which excludes most pharmacogenomic, GWAS-only, and SNPedia-only
+        rsIDs commonly found in wellness panels. This method fills the
+        gap by querying ``gnomad_frequencies`` (keyed on the full dbSNP
+        rsID universe with published allele frequencies).
+
+        Returns ``{(chrom, pos): [(ref, alt, rsid), ...]}``. Multi-allelic
+        positions return multiple rows; the caller is responsible for
+        applying carrier-rule disambiguation (matching the user's allele
+        pair as a subset of ``{ref, alt}`` and abstaining on ties — same
+        pattern as the ClinVar resolver).
+
+        Bare chromosomes are expected on both the input set and the
+        ``gnomad_frequencies.chrom`` column — Allelix normalizes all
+        internal chromosome identifiers to bare form
+        (:func:`allelix.parsers._helpers.normalize_chromosome`).
+        """
+        if not positions:
+            return {}
+        conn = self._connection()
+        result: dict[tuple[str, int], list[tuple[str, str, str]]] = {}
+        # Issue a single combined SQL statement per chunk using SQLite's
+        # row-value ``(chrom, pos) IN ((?, ?), ...)`` form instead of
+        # grouping by chromosome and issuing one statement per
+        # (chrom, chunk) pair. On WGS input each batch touches all ~24
+        # chromosomes; the per-chrom shape was a 24x query multiplier
+        # the ``idx_gnomad_position`` index could not amortize away. The
+        # row-value IN form keeps the same carrier-rule contract — both
+        # ``chrom`` and ``pos`` must match the input pair simultaneously
+        # — and the ``idx_gnomad_position`` covering index on
+        # ``(chrom, pos)`` serves the lookup directly.
+        #
+        # Each input pair binds 2 SQLite parameters (chrom + pos), so
+        # the chunk size is ``_BULK_BATCH_SIZE // 2`` to stay inside the
+        # 999-param convention every other annotator and gnomAD's own
+        # multi-param queries respect (``bulk_lookup_by_alt`` does the
+        # same 2-param shape with the same ``// 2``;
+        # ``bulk_lookup_by_position`` uses ``// 4`` for its 4-param
+        # shape, same convention scaled). Net effective batch size:
+        # 450 pairs x 2 = 900 params per chunk.
+        chunk_pairs = _BULK_BATCH_SIZE // 2
+        position_list = list(positions)
+        for i in range(0, len(position_list), chunk_pairs):
+            batch = position_list[i : i + chunk_pairs]
+            placeholders = ",".join("(?, ?)" for _ in batch)
+            params: list[str | int] = []
+            for chrom, pos in batch:
+                params.append(chrom)
+                params.append(pos)
+            rows = conn.execute(
+                f"SELECT chrom, pos, ref, alt, rsid FROM gnomad_frequencies"
+                f" WHERE (chrom, pos) IN ({placeholders})",
+                params,
+            ).fetchall()
+            for c, p, ref, alt, rsid in rows:
+                if not rsid:
+                    continue
+                result.setdefault((c, p), []).append((ref, alt, rsid))
+        # Deterministic ordering for the carrier-rule pass.
+        for rows in result.values():
+            rows.sort()
+        return result
+
     def bulk_lookup_by_alt(self, keys: set[tuple[str, str]]) -> dict[tuple[str, str], float]:
         """Return ``{(rsid, alt): af}`` for exact allele matches."""
         if not keys:

{allelix-2.2.1 → allelix-2.2.3}/allelix/cli/utility.py

@@ -20,6 +20,7 @@ from allelix.cli._options import (
     _SAMPLE_OPT,
 )
 from allelix.databases import resolve_data_dir
+from allelix.models import NO_CALL_MARKER
 
 if TYPE_CHECKING:
     from allelix.models import Variant
@@ -67,7 +68,21 @@ def stats(file_path: Path, fmt: str | None, sample: str | None) -> None:
     summary.add_column("Value", style="green")
     summary.add_row("Format", parser.display_name)
     summary.add_row("Sample ID", metadata["sample_id"] or "(unknown)")
-    summary.add_row("Build", metadata["build"])
+    # ``metadata["build"]`` is blank on every VCF that doesn't declare
+    # ``##reference=`` in the header — i.e. most caller outputs
+    # (DeepVariant / DRAGEN / GIAB GRCh38 benchmark). A blank cell read
+    # as broken on the v2.2.1 battery; ``stats`` deliberately does not
+    # run build detection (that's an ``analyze`` job per the protocol),
+    # so the honest display when no header build is declared is an em
+    # dash plus the chr-prefix hint when available. The user can run
+    # ``analyze`` to get the real detected build.
+    if metadata["build"]:
+        build_display = metadata["build"]
+    elif metadata.get("chr_prefix_observed"):
+        build_display = "— (chr-prefixed contigs; run `analyze` to confirm)"
+    else:
+        build_display = "—"
+    summary.add_row("Build", build_display)
     summary.add_row("Total SNPs", f"{total:,}")
     summary.add_row("No-calls", f"{no_calls:,} ({_helpers._percent(no_calls, total)})")
     summary.add_row("Heterozygous", f"{het:,} ({_helpers._percent(het, total)})")
@@ -136,28 +151,90 @@ def extract(
     found = _try_tabix_extract(file_path, wanted, sample, data_dir)
     if found is None:
         # Sequential fallback — works for any parser.
-        found = _sequential_extract(parser, file_path, wanted)
+        found = _sequential_extract(parser, file_path, wanted, data_dir)
         _maybe_print_vcf_index_hint(file_path)
 
     _render_extract_table(file_path, wanted, found)
 
 
 def _sequential_extract(
-    parser: GenotypeParser, file_path: Path, wanted: set[str]
+    parser: GenotypeParser,
+    file_path: Path,
+    wanted: set[str],
+    data_dir: Path | None = None,
 ) -> dict[str, Variant]:
     """Stream the file once; collect Variants whose rsID is in ``wanted``.
 
     Streaming early-exit once all wanted rsIDs are found — for arrays
     that yield <1 M variants this is fast enough on any input.
+
+    GH #128: for VCF inputs the parser may emit a positional pseudo-ID
+    (``chr1:11856378:G:A``) when the row's ID column is empty — every
+    modern caller (DeepVariant, DRAGEN, GIAB GRCh38 benchmark) emits
+    these. The rsID-only fast path on the iterator misses them. To
+    cover the rsID-less VCF case, the function pre-resolves the wanted
+    set's coordinates via gnomAD (when ready) and matches variants by
+    ``(chrom, pos, ref, alt)`` whenever the rsID match misses. The
+    ``ref + alt-in-alleles`` rule matches the tabix path's correctness
+    contract and the resolver's carrier-rule disambiguation.
     """
+    from allelix.annotators.gnomad import GnomadAnnotator
+
     counter, stderr_handler, snapshot = _helpers._wire_parser_logging()
     found: dict[str, Variant] = {}
+    # Pre-resolve wanted → (chrom, pos, ref, alt) → rsid via gnomAD so
+    # the iterator can cover rsID-less VCFs by coord-matching. ``data_dir``
+    # is optional only because tests construct mock parsers without a
+    # configured cache; production CLI invocations always reach
+    # ``resolve_data_dir`` (which defaults to the standard cache
+    # location when the user didn't pass ``--data-dir``). The if-test
+    # below gates only on gnomAD readiness, not on whether the user
+    # explicitly opted in.
+    coord_to_rsid: dict[tuple[str, int, str, str], str] = {}
+    try:
+        resolved_data_dir = resolve_data_dir(data_dir)
+    except (OSError, ValueError):
+        resolved_data_dir = None
+    if resolved_data_dir is not None:
+        gnomad = GnomadAnnotator(resolved_data_dir)
+        try:
+            if gnomad.is_ready():
+                coord_map = gnomad.bulk_resolve_coordinates(wanted)
+                for rsid, entries in coord_map.items():
+                    for chrom, pos, ref, alt in entries:
+                        coord_to_rsid[(chrom, pos, ref, alt)] = rsid
+        finally:
+            gnomad.close()
     try:
         for variant in parser.parse(file_path):
             if variant.rsid in wanted:
                 found[variant.rsid] = variant
                 if len(found) == len(wanted):
                     break
+                continue
+            # rsID fast path missed — try coord match for the rsID-less
+            # VCF case. Requires ref populated; non-VCF parsers (arrays)
+            # don't carry ref but always stamp rsIDs in the file, so
+            # they never reach this branch.
+            if not coord_to_rsid or variant.ref is None:
+                continue
+            matched_rsid: str | None = None
+            for alt in (variant.allele1, variant.allele2):
+                if alt in (NO_CALL_MARKER, variant.ref):
+                    continue
+                key = (variant.chromosome, variant.position, variant.ref, alt)
+                candidate = coord_to_rsid.get(key)
+                if candidate is None or candidate in found or candidate not in wanted:
+                    continue
+                matched_rsid = candidate
+                break
+            if matched_rsid is None:
+                continue
+            variant.original_rsid = variant.rsid
+            variant.rsid = matched_rsid
+            found[matched_rsid] = variant
+            if len(found) == len(wanted):
+                break
     finally:
         _helpers._unwire_parser_logging(counter, stderr_handler, snapshot)
     return found
@@ -247,7 +324,7 @@ def _execute_tabix_extract(  # pragma: no cover
         for rsid, coords in coord_map.items():
             if rsid in found or not coords:
                 continue
-            for chrom, pos, _ref, _alt in coords:
+            for chrom, pos, ref, alt in coords:
                 # gnomAD chromosomes are bare ('1', 'X'); the VCF might
                 # use 'chr1'. Try both.
                 for chrom_candidate in (chrom, f"chr{chrom}"):
@@ -259,9 +336,31 @@ def _execute_tabix_extract(  # pragma: no cover
                         variant = _parse_data_line(row, sample_idx)
                         if variant is None:
                             continue
-                        if variant.rsid == rsid:
+                        # GH #128: match the tabix-fetched row to the
+                        # gnomAD record by (ref, alt) rather than by
+                        # rsID equality. On rsID-stamped VCFs (e.g. GIAB
+                        # GRCh37, 23andMe) the parser populates
+                        # ``variant.rsid`` with the file's ID column and
+                        # the prior equality check happened to work; on
+                        # rsID-less VCFs (DeepVariant gVCFs, GIAB GRCh38
+                        # benchmark, Sequencing.com DRAGEN output)
+                        # ``variant.rsid`` is a positional pseudo-ID and
+                        # the equality check silently discarded every
+                        # tabix-fetched row. Ref+alt match is correct on
+                        # both — that's what the gnomAD coord was
+                        # resolved against.
+                        if variant.ref == ref and alt in (
+                            variant.allele1,
+                            variant.allele2,
+                        ):
                             # _parse_data_line already normalizes chromosome;
-                            # no re-normalization needed.
+                            # no re-normalization needed. Stash + stamp
+                            # so the displayed table shows the requested
+                            # rsID rather than the pseudo-ID, with audit
+                            # preserved per Variant.original_rsid.
+                            if variant.rsid != rsid:
+                                variant.original_rsid = variant.rsid
+                                variant.rsid = rsid
                             found[rsid] = variant
                             break
                     if rsid in found:

{allelix-2.2.1 → allelix-2.2.3}/allelix/databases/schema.py

@@ -127,6 +127,8 @@ CREATE TABLE IF NOT EXISTS gnomad_frequencies (
 );
 
 CREATE INDEX IF NOT EXISTS idx_gnomad_rsid ON gnomad_frequencies(rsid);
+CREATE INDEX IF NOT EXISTS idx_gnomad_position
+    ON gnomad_frequencies(chrom, pos);
 """
     + _DATABASE_VERSIONS_TABLE
 )

{allelix-2.2.1 → allelix-2.2.3}/allelix/models.py

@@ -47,6 +47,27 @@ class Variant:
     allele2: str
     build: str = DEFAULT_BUILD
     ref: str | None = None
+    # GH #128: pre-resolution rsID stashed when a resolver
+    # (`ClinVarAnnotator.bulk_resolve_rsids` or
+    # `GnomadAnnotator.bulk_resolve_rsids_from_positions`, both invoked
+    # in ``_pipeline._flush()``) recovers the real ``rs...`` ID for a
+    # variant that arrived without one — e.g. a DeepVariant gVCF row
+    # whose ID column is ``.``, parsed as a positional pseudo-ID like
+    # ``chr1:11856378:G:A``. The stamp rewrites ``rsid`` to the
+    # recovered value so every downstream call site that compares
+    # ``v.rsid`` against a requested set (panel coverage, high-value
+    # match, extract, PLINK ref/alt, GWAS must-include) works
+    # transparently; ``original_rsid`` holds the pre-stamp value
+    # purely for audit / debug.
+    #
+    # **DEBUG-ONLY — do not branch production logic on this field.**
+    # Reading ``original_rsid`` outside of logging, debugging, or
+    # ``__repr__``-style introspection couples production behavior to
+    # provenance metadata and turns this into an unintended API
+    # surface. The serialization-guard test in
+    # ``tests/test_original_rsid_never_serializes.py`` asserts this
+    # field never reaches JSON / HTML / ``--diff`` output.
+    original_rsid: str | None = None
 
     def __post_init__(self) -> None:
         """Normalize allele case at construction (GH #14, ADR-0035).

{allelix-2.2.1 → allelix-2.2.3}/allelix/parsers/twentythreeandme.py

@@ -42,7 +42,26 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
-_CANONICAL_PREFIX = "# This data file generated by 23andMe"
+# Known canonical first-line banner variants 23andMe wraps raw exports in.
+# The original v2/v3/v4-era exports used the verbatim ``generated by`` form;
+# the June 2026 v5 export prose was edited to ``is generated by`` (with a
+# trailing period in some samples). Match either; future vendor banner
+# edits get a new entry here.
+#
+# Why a tuple of exact prefixes instead of a loose ``"23andMe" in line``
+# substring match: a bare substring check false-positives on transcoded
+# fixtures and third-party tool output. Files that strip the canonical
+# banner entirely (WGSExtract output, Genetic Lifehacks converter output,
+# privacy-conscious users who delete the comment block) are out of scope
+# for this parser by design — they are handled by ``GenericTsvParser`` at
+# the end of the dispatch chain (planned, see GH #146 / GH #127). That
+# two-layer design keeps banner-bearing 23andMe files attributed to
+# "23andMe" and banner-less 23andMe-shape files attributed to "generic-tsv"
+# without guessing a vendor.
+_CANONICAL_PREFIXES: tuple[str, ...] = (
+    "# This data file generated by 23andMe",
+    "# This data file is generated by 23andMe",
+)
 SNIFF_LINE_LIMIT = 50
 EXPECTED_COLUMNS = 4
 
@@ -58,10 +77,13 @@ class TwentyThreeAndMeParser(GenotypeParser):
     def can_parse(self, file_path: Path) -> bool:
         """Recognize a real 23andMe export by its canonical first-line header.
 
-        Real exports start with ``# This data file generated by 23andMe at: ...``.
+        Real exports start with one of the variants in ``_CANONICAL_PREFIXES``:
+        the historical ``# This data file generated by 23andMe at: ...`` form
+        or the June 2026 v5 ``# This data file is generated by 23andMe.`` form.
         Some files have user-prepended comments before the canonical line; the
-        fallback loop scans up to ``SNIFF_LINE_LIMIT`` comment lines. A bare
-        "23andMe" mention without the canonical prefix is rejected.
+        scan loop reads up to ``SNIFF_LINE_LIMIT`` comment lines. A bare
+        "23andMe" substring mention without one of the canonical prefixes is
+        rejected (see ``_CANONICAL_PREFIXES`` rationale).
         """
         try:
             with file_path.open("r", encoding="utf-8") as fh:
@@ -71,7 +93,7 @@ class TwentyThreeAndMeParser(GenotypeParser):
                         return False
                     if not line.startswith("#"):
                         return False
-                    if line.startswith(_CANONICAL_PREFIX):
+                    if any(line.startswith(p) for p in _CANONICAL_PREFIXES):
                         return True
         except (OSError, UnicodeDecodeError):
             return False

{allelix-2.2.1 → allelix-2.2.3}/allelix/parsers/vcf.py

@@ -90,6 +90,15 @@ def format_sample_list(samples: list[str], max_shown: int = 10) -> str:
     return ", ".join(samples[:max_shown]) + f", ... and {len(samples) - max_shown} more"
 
 
+# GH #126: how many leading non-blank lines ``can_parse`` will scan for
+# ``##fileformat=VCF`` before giving up. 10 covers every real-world
+# preamble shape we've encountered (BOM-on-its-own-line edge cases,
+# tool banners, blank-line prefixes) without making the negative-case
+# cost meaningful — non-VCF inputs reject after reading ~10 short
+# lines (a handful of KB).
+_PREAMBLE_SCAN_LINES = 10
+
+
 class VcfParser(GenotypeParser):
     """Streaming parser for VCF 4.x and gVCF files.
 
@@ -133,7 +142,7 @@ class VcfParser(GenotypeParser):
     # ── Public API ──────────────────────────────────────────────
 
     def can_parse(self, file_path: Path) -> bool:
-        """True if the first non-blank line is ``##fileformat=VCF...``.
+        """True if a leading non-blank line is ``##fileformat=VCF...``.
 
         GH #121: catches ``UnicodeDecodeError`` and ``EOFError`` (corrupt
         gzip / truncated BGZF) on top of ``OSError`` so format sniffing
@@ -143,14 +152,45 @@ class VcfParser(GenotypeParser):
         binary garbage or a truncated tabix index masquerading as a
         ``.vcf.gz`` would otherwise still leak a traceback at the
         ``read`` boundary in ``gzip.open``.
+
+        GH #126: scan multiple leading non-blank lines (capped at
+        :data:`_PREAMBLE_SCAN_LINES`) instead of insisting
+        ``##fileformat=VCF`` appears on line 1. Real-world VCF
+        producers occasionally prepend a non-standard line — a
+        tool-banner comment, a blank line wrapped by a downstream
+        post-processor, an editor's "edited by …" annotation — and
+        rejecting the file on first-line-mismatch read as broken
+        when the actual format was fine. The scan terminates the
+        moment a line starts with ``##fileformat=VCF`` (success) or
+        we've consumed the cap without finding it (failure). A line
+        starting with ``#CHROM`` (the data-header line) also
+        terminates the scan as failure — we're past the metadata
+        block and ``##fileformat`` clearly never appeared.
+
+        The UTF-8 BOM that prompted the original bug report is
+        stripped structurally by ``_open_vcf``'s ``utf-8-sig`` codec
+        (also GH #126), so the BOM never reaches this loop. The
+        multi-line scan complements that by covering the other class
+        of preamble quirks the BOM hypothesis doesn't explain.
         """
         try:
             with _open_vcf(file_path) as handle:
+                scanned = 0
                 for line in handle:
                     stripped = line.strip()
                     if not stripped:
                         continue
-                    return stripped.startswith("##fileformat=VCF")
+                    if stripped.startswith("##fileformat=VCF"):
+                        return True
+                    # ``#CHROM`` is the data-header line; if we hit it
+                    # before ``##fileformat`` we know the metadata
+                    # block doesn't contain the declaration and the
+                    # file isn't a VCF we can claim.
+                    if stripped.startswith("#CHROM"):
+                        return False
+                    scanned += 1
+                    if scanned >= _PREAMBLE_SCAN_LINES:
+                        return False
         except (OSError, UnicodeDecodeError, EOFError):
             return False
         return False
@@ -304,13 +344,27 @@ def _read_header(handle: TextIO) -> _VcfHeader:
 
     Returns parsed metadata. After this call the handle is positioned
     at the first data line (or EOF).
+
+    GH #126: tolerates a small preamble of single-``#`` comment lines
+    BEFORE the first ``##fileformat`` declaration, symmetric with
+    :meth:`VcfParser.can_parse`'s scan. Some upstream tools and
+    post-processors prepend a banner (e.g. ``# Generated by …``)
+    that's not a VCF metadata line but is also not the data block.
+    The scan caps at :data:`_PREAMBLE_SCAN_LINES` non-blank lines —
+    if no ``##`` declaration appears within that window we treat the
+    first non-comment / non-blank line as the start of data,
+    preserving the original behavior on inputs that genuinely lack
+    a header.
     """
     header = _VcfHeader()
+    preamble_scanned = 0
+    saw_meta = False
     for line in handle:
         stripped = line.rstrip("\n").rstrip("\r")
         if not stripped:
             continue
         if stripped.startswith("##"):
+            saw_meta = True
             _absorb_meta_line(stripped, header)
             continue
         if stripped.startswith("#CHROM"):
@@ -321,6 +375,15 @@ def _read_header(handle: TextIO) -> _VcfHeader:
             if len(cols) > 9:
                 header.samples = cols[9:]
             return header
+        # GH #126: single-``#`` comment lines before any ``##`` metadata
+        # are treated as preamble (banner / post-processor annotation)
+        # up to the scan cap. Once we've seen at least one ``##`` line
+        # the header block is "real" and a stray non-``##`` line is
+        # treated as data per the original behavior.
+        if not saw_meta and stripped.startswith("#"):
+            preamble_scanned += 1
+            if preamble_scanned < _PREAMBLE_SCAN_LINES:
+                continue
         # Reaching a data line before #CHROM means no column header.
         # Return what we have; samples is empty.
         return header
@@ -551,7 +614,7 @@ def _lookup_allele(gt_index: str, ref: str, alts: list[str]) -> str | None:
 
 
 def _open_vcf(file_path: Path) -> TextIO:
-    """Open a ``.vcf`` or ``.vcf.gz`` file in text mode.
+    r"""Open a ``.vcf`` or ``.vcf.gz`` file in text mode.
 
     Sniffs the gzip magic bytes ``1f 8b`` so the parser works on any
     extension (e.g., files named ``foo.txt`` containing valid VCF
@@ -570,6 +633,20 @@ def _open_vcf(file_path: Path) -> TextIO:
     belt-and-braces guard for the case where ``errors="replace"`` is
     ever lifted.
 
+    GH #126: ``encoding="utf-8-sig"`` (was ``utf-8``). The ``-sig``
+    variant transparently strips a leading UTF-8 BOM (``\\xef\\xbb\\xbf``)
+    when present and behaves identically to plain ``utf-8`` on
+    unprefixed input. Real-world Sequencing.com / DRAGEN VCFs are
+    reported to ship with a UTF-8 BOM under some download flows, and
+    the BOM defeated ``can_parse``'s ``startswith("##fileformat=VCF")``
+    check: ``\\ufeff##fileformat=VCFv4.2`` does not start with
+    ``##fileformat=VCF``. Switching the codec is zero-risk on
+    BOM-less input (the codec falls through to standard utf-8) and
+    fixes the BOM case structurally — no per-call lstrip, no
+    encoding-detection guess. Same swap on both the gzip and plain
+    text paths so the fix applies regardless of how the file was
+    delivered.
+
     Returns ``typing.TextIO`` rather than the concrete ``io.TextIOBase``
     so mypy-strict callers see the ``__enter__`` / ``__exit__`` protocol
     on the returned handle.
@@ -577,5 +654,5 @@ def _open_vcf(file_path: Path) -> TextIO:
     with open(file_path, "rb") as raw:
         magic = raw.read(2)
     if magic == b"\x1f\x8b":
-        return gzip.open(file_path, "rt", encoding="utf-8", errors="replace")
-    return open(file_path, encoding="utf-8", errors="replace")
+        return gzip.open(file_path, "rt", encoding="utf-8-sig", errors="replace")
+    return open(file_path, encoding="utf-8-sig", errors="replace")

{allelix-2.2.1 → allelix-2.2.3}/allelix/reports/_pipeline.py

@@ -546,6 +546,40 @@ def run_analysis(
                     )
                     for (chrom, pos, ref, alt), rsid in resolution.items():
                         resolved_coords[rsid] = (chrom, pos, ref, alt)
+            # GH #128: second-pass resolution against gnomAD for any variant
+            # still rsidless after ClinVar's pass. ClinVar carries the
+            # clinically-curated subset of dbSNP; gnomAD's frequencies table
+            # is keyed on the full dbSNP rsID universe, so pharmacogenomic
+            # / GWAS-only / SNPedia-only rsIDs (which never make it into
+            # ClinVar) get recovered here. Same carrier-rule disambiguation
+            # as the ClinVar resolver: unique consistent (ref, alt) match
+            # against the user's allele pair, abstain on ties.
+            if gnomad is not None and gnomad.is_ready():
+                still_rsidless = [v for v in batch_buf if not v.rsid.startswith("rs")]
+                if still_rsidless:
+                    positions = {
+                        (v.chromosome, v.position)
+                        for v in still_rsidless
+                        if not v.is_no_call and v.chromosome and v.position > 0
+                    }
+                    gnomad_rows = gnomad.bulk_resolve_rsids_from_positions(positions)
+                    for v in still_rsidless:
+                        rows = gnomad_rows.get((v.chromosome, v.position))
+                        if not rows:
+                            continue
+                        user_alleles = {v.allele1, v.allele2}
+                        matches = [
+                            (ref, alt, rsid)
+                            for ref, alt, rsid in rows
+                            if ref != alt and user_alleles.issubset({ref, alt})
+                        ]
+                        if len(matches) == 1:
+                            ref, alt, rsid = matches[0]
+                            # Same audit stash as the ClinVar resolver
+                            # (clinvar.py:bulk_resolve_rsids). Debug-only.
+                            v.original_rsid = v.rsid
+                            v.rsid = rsid
+                            resolved_coords[rsid] = (v.chromosome, v.position, ref, alt)
             # ADR-0035 PR 4: populate Variant.ref for array data via gnomAD's
             # rsid → forward-REF map. VCF inputs already carry ref (PR 1).
             # Annotators downstream (ClinVar / PharmGKB strand-aware carrier