allelix 2.4.1__tar.gz → 2.4.2__tar.gz

{allelix-2.4.1/allelix.egg-info → allelix-2.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 2.4.1
+Version: 2.4.2
 Summary: Open-source genotype analysis toolkit. Format-agnostic ingestion, database-agnostic annotation, offline-first.
 Author: Allelix
 Maintainer-email: dial481 <dial481@users.noreply.github.com>

{allelix-2.4.1 → allelix-2.4.2}/allelix/annotators/__init__.py

@@ -54,9 +54,14 @@ def get_annotators(
         data_dir,
         clinvar_ref_provider=clinvar.reference_for,
         palindromic_provider=rsid_identity.palindromic_rsids,
+        normal_allele_provider=clinvar.normal_allele_for,
     )
     gwas = GWASCatalogAnnotator(data_dir, filter_traits=gwas_filter_traits)
-    snpedia = SNPediaAnnotator(data_dir, clinvar_ref_provider=clinvar.reference_for)
+    snpedia = SNPediaAnnotator(
+        data_dir,
+        clinvar_ref_provider=clinvar.reference_for,
+        normal_allele_provider=clinvar.normal_allele_for,
+    )
     gnomad = GnomadAnnotator(data_dir)
     alphamissense = AlphaMissenseAnnotator(data_dir)
     cadd = CaddAnnotator(data_dir, full_mode=cadd_full)

{allelix-2.4.1 → allelix-2.4.2}/allelix/annotators/_resolution.py

@@ -129,11 +129,18 @@ def resolve_rsidless(
 
 
 def _populate_ref_from_identity(identity: RsidIdentityAnnotator, variants: list[Variant]) -> None:
-    """Set ``Variant.ref`` from the identity table's REF at the variant's locus.
+    """Set ``Variant.ref`` from the identity table's REF for the call's own rsID.
 
-    Only for calls that carry an rsID, and only when the locus has a single
-    REF of the call's shape: single-base for single-base calls (an indel
-    row's anchor REF can share the position), any length otherwise.
+    Only for calls that carry an rsID, only from the identity rows of that
+    rsID at the variant's locus, and only when those rows give a single REF
+    of the call's shape: single-base for single-base calls (an indel row's
+    anchor REF can share the position), any length otherwise.
+
+    A call whose rsID the identity table does not hold (a withdrawn or
+    merged ID) gets no REF, even when another rsID's rows sit at the same
+    position: nothing confirms that the other rsID is the same variant.
+    Such a call keeps ``ref`` None, and ClinVar matches it by locus only
+    when ClinVar holds its rsID.
 
     A call without an rsID (array vendor probes such as 23andMe
     ``i5000123``) never gets a REF from position alone. The REF at a locus
@@ -154,9 +161,9 @@ def _populate_ref_from_identity(identity: RsidIdentityAnnotator, variants: list[
     ]
     for build in {v.build for v in pending}:
         group = [v for v in pending if v.build == build]
-        refs_at = identity.refs_at_loci(build, {variant_locus(v) for v in group})
+        rows_at = identity.alleles_at_loci(build, {variant_locus(v) for v in group})
         for v in group:
-            refs = refs_at.get(variant_locus(v), set())
+            refs = {ref for ref, _alt, rsid in rows_at.get(variant_locus(v), []) if rsid == v.rsid}
             if len(v.allele1) <= 1 and len(v.allele2) <= 1:
                 refs = {r for r in refs if len(r) == 1}
             if len(refs) == 1:

{allelix-2.4.1 → allelix-2.4.2}/allelix/annotators/base.py

@@ -10,6 +10,7 @@ from enum import Enum, auto
 from typing import TYPE_CHECKING, ClassVar
 
 from allelix.parsers._helpers import normalize_chromosome
+from allelix.utils.allele import derive_alt_from_diploid
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator
@@ -95,6 +96,32 @@ def is_clinvar_homref(
     return ref is not None and len(ref) == 1 and variant.allele1 == ref and variant.allele2 == ref
 
 
+def carried_alt(
+    variant: Variant,
+    allele1: str,
+    allele2: str,
+    normal_allele_provider: Callable[[str, str], str | None] | None,
+) -> tuple[str, bool]:
+    """The non-normal allele of a matched genotype, for per-genotype sources.
+
+    Returns ``(alt, reference_carries_alt)``. The alt is derived against the
+    normal allele, which is ``variant.ref`` except where the build's
+    reference carries a ClinVar variant allele: there
+    ``normal_allele_provider`` (``ClinVarAnnotator.normal_allele_for``) gives
+    the normal allele from the other build (C at F5 rs6025 on GRCh37, whose
+    reference is the Leiden T). The alt is then the same on both builds,
+    and it can equal ``variant.ref``, which the Annotation is told through
+    ``reference_carries_alt``.
+    """
+    normal = variant.ref
+    if normal is not None and normal_allele_provider is not None and variant.rsid.startswith("rs"):
+        other = normal_allele_provider(variant.rsid, variant.build)
+        if other is not None and len(other) == 1 and other != normal:
+            normal = other
+    alt = derive_alt_from_diploid(normal, allele1, allele2)
+    return alt, bool(alt) and alt == variant.ref
+
+
 class Annotator(ABC):
     """Base class for all reference database annotators.
 

{allelix-2.4.1 → allelix-2.4.2}/allelix/annotators/clinvar.py

@@ -36,6 +36,7 @@ from allelix.utils.allele import (
     resolve_rsid_at_locus,
     strand_aware_carrier_match,
 )
+from allelix.utils.build_detect import BUILD_GRCH37, BUILD_GRCH38
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Iterator
@@ -248,6 +249,10 @@ class ClinVarAnnotator(Annotator):
         # consults this as its primary non-finding filter. Built lazily
         # on first lookup per build.
         self._ref_lookups: dict[str, dict[str, str]] = {}
+        # Per build, the rsIDs where ``reference_for`` gives the normal
+        # allele from the other build (the build's reference carries a
+        # ClinVar variant allele), with that allele.
+        self._normal_alleles: dict[str, dict[str, str]] = {}
 
     def _connection(self, build: str) -> sqlite3.Connection | None:
         """Return a lazy connection to the per-build cache, or None if missing.
@@ -383,6 +388,15 @@ class ClinVarAnnotator(Annotator):
             return False
         return True
 
+    def _cache_is_current(self, build: str) -> bool:
+        """True when ``build``'s cache carries the current interpreter-version tag."""
+        if build not in self._db_paths:
+            return False
+        info = get_database_info(self._db_paths[build], clinvar_record_name(build))
+        return info is not None and info.get("local_version_tag") == (
+            f"iv:{CLINVAR_INTERPRETER_VERSION}"
+        )
+
     def version(self) -> str | None:
         """Composite version string across managed builds.
 
@@ -413,6 +427,7 @@ class ClinVarAnnotator(Annotator):
             conn.close()
         self._conns.clear()
         self._ref_lookups.clear()
+        self._normal_alleles.clear()
 
     def reference_for(self, rsid: str, build: str) -> str | None:
         """Return ClinVar's single-base REF allele for `rsid` in `build`, or None.
@@ -426,6 +441,15 @@ class ClinVarAnnotator(Annotator):
         skipped — array-based parsers can't call indels, so a multi-base
         REF can't validly suppress a single-base genotype.
 
+        Where this build's reference carries a ClinVar variant allele (a
+        REF == ALT row, F5 c.1601G>A on GRCh37), a homozygous-reference
+        call is the variant genotype. There the normal allele is returned
+        instead: the REF of the same ClinVar variant on the other build,
+        when that row is a single-base REF != ALT (C for F5), so the same
+        call is a non-finding on both builds. Without such a row (only one
+        build's cache installed, or REF == ALT on both builds) it returns
+        None and nothing is suppressed.
+
         Returns None when ClinVar has no data for the rsid in this build
         (or has only indel REFs). Callers fall through to secondary tiers.
         """
@@ -449,17 +473,72 @@ class ClinVarAnnotator(Annotator):
         # so peak memory is one row + the dict, not the entire result set
         # twice.
         cursor = conn.execute(
-            "SELECT DISTINCT rsid, ref FROM clinvar_variants WHERE length(ref) = 1"
+            "SELECT DISTINCT rsid, ref, alt, allele_id FROM clinvar_variants WHERE length(ref) = 1"
         )
         out: dict[str, str] = {}
-        for rsid, ref in cursor:
+        # rsID -> VariationIDs whose row is REF == ALT: this build's
+        # reference carries their variant allele.
+        reference_carried: dict[str, set[int]] = {}
+        for rsid, ref, alt, variation_id in cursor:
+            if ref == alt:
+                reference_carried.setdefault(rsid, set()).add(variation_id)
             # If a rsid has multiple single-base REFs (shouldn't happen at
             # one position but defending against future data shapes), keep
             # the first.
             if rsid not in out:
                 out[rsid] = ref
+        # Only a current cache gives REF == ALT its one meaning; an older
+        # one still holds normal-allele records written REF == ALT, and
+        # keeps the locus REF (the 2.4.1 behaviour) until `db update`.
+        normal: dict[str, str] = {}
+        if reference_carried and self._cache_is_current(build):
+            normal = self._normal_alleles_on_other_build(build, reference_carried)
+            for rsid in reference_carried:
+                if rsid in normal:
+                    out[rsid] = normal[rsid]
+                else:
+                    out.pop(rsid, None)
+        self._normal_alleles[build] = normal
         return out
 
+    def normal_allele_for(self, rsid: str, build: str) -> str | None:
+        """The normal allele at `rsid` where `build`'s reference carries a variant, or None.
+
+        Set only where ``reference_for`` returns the other build's REF of
+        the same ClinVar variant (C at F5 rs6025 on GRCh37). ClinPGx and
+        SNPedia derive their ``alt`` against it there; everywhere else
+        they keep ``Variant.ref``, even where ClinVar's REF differs from it.
+        """
+        self.reference_for(rsid, build)
+        return self._normal_alleles.get(build, {}).get(rsid)
+
+    def _normal_alleles_on_other_build(
+        self, build: str, reference_carried: dict[str, set[int]]
+    ) -> dict[str, str]:
+        """The normal allele at each reference-carried rsID, from the other build.
+
+        For each rsID, the single-base REF of the same VariationIDs on the
+        other build where that row's REF differs from its ALT. An rsID with
+        no such row, or more than one candidate REF, is left out.
+        """
+        other = BUILD_GRCH38 if build == BUILD_GRCH37 else BUILD_GRCH37
+        conn = self._connection(other)
+        if conn is None or not self._cache_is_current(other):
+            return {}
+        rsids = sorted(reference_carried)
+        candidates: dict[str, set[str]] = {}
+        for start in range(0, len(rsids), _BATCH_CHUNK):
+            chunk = rsids[start : start + _BATCH_CHUNK]
+            placeholders = ",".join("?" * len(chunk))
+            for rsid, ref, alt, variation_id in conn.execute(
+                f"SELECT DISTINCT rsid, ref, alt, allele_id FROM clinvar_variants "
+                f"WHERE rsid IN ({placeholders})",
+                chunk,
+            ):
+                if variation_id in reference_carried[rsid] and len(ref) == 1 and ref != alt:
+                    candidates.setdefault(rsid, set()).add(ref)
+        return {rsid: refs.pop() for rsid, refs in candidates.items() if len(refs) == 1}
+
     def fetch_remote_signal(self) -> str | None:
         r"""Freshness signal derived from the per-SCV submission_summary md5.
 
@@ -691,9 +770,13 @@ class ClinVarAnnotator(Annotator):
 
         A row annotates only when all of these hold:
 
-        - REF != ALT. ClinVar's reference-allele records (HGVS ``=``,
-          e.g. ``c.1601=``) carry REF == ALT; they describe the reference
-          allele, never a variant the user carries.
+        - REF == ALT means this build's reference carries the variant
+          allele (F5 c.1601G>A is T>T on GRCh37, whose reference base is
+          the Leiden allele). The loader keeps no other REF == ALT rows:
+          it drops normal-allele records (HGVS ``c.N=``) written REF ==
+          ALT and REF == ALT rows that are not SNVs (cache ``iv:5``). Such
+          a row annotates a user who carries its ALT, counting copies of
+          it, like any other row.
         - The row's REF agrees with ``variant.ref`` when the input supplies
           one (directly, or as the complement for a reverse-stranded
           input). Together with the locus this identifies the variant by
@@ -705,26 +788,26 @@ class ClinVarAnnotator(Annotator):
 
         Two guards decide whether the locus may be matched at all:
 
-        - A call with no reference allele and no rsID (array vendor probes
-          such as 23andMe ``i5000123``) is never locus-matched: nothing
-          confirms that the row at its position describes the same
-          variant. The pipeline never infers a REF for such a call from
-          position (the identity table fills REF only for rsID-carrying
-          calls), so a no-rsID call with a REF is a VCF record whose REF
-          came from the file, and the REF check applies to it.
+        - A call with no reference allele is locus-matched only when
+          ClinVar holds its rsID on this build (``rsid_loci``, every
+          position ClinVar records for that rsID). That excludes array
+          vendor probes without an rsID (23andMe ``i5000123``) and array
+          calls whose rsID neither ClinVar nor the identity table holds (a
+          withdrawn or merged ID): nothing confirms that the row at the
+          position describes the same variant. The pipeline fills REF only
+          from the identity rows of the call's own rsID, so a call with a
+          REF is either one of those or a VCF record whose REF came from
+          the file, and the REF check applies to it.
         - When the input carries an rsID that ClinVar places elsewhere
-          (``rsid_loci``, every position ClinVar records for that rsID on
-          this build) and not at the input's locus, the rows at the locus
-          belong to a different variant and are not reported under the
-          input's rsID. An rsID ClinVar does not hold at all (a retired or
-          merged ID) still matches by locus.
+          and not at the input's locus, the rows at the locus belong to a
+          different variant and are not reported under the input's rsID.
 
         The Annotation's rsID is the input's when it has one, otherwise
         the matching row's. identical per-SCV rows collapse.
         """
         if variant.is_no_call:
             return []
-        if variant.ref is None and not variant.rsid.startswith("rs"):
+        if variant.ref is None and not rsid_loci:
             return []
         if rsid_loci and variant_locus(variant) not in rsid_loci:
             return []
@@ -746,8 +829,6 @@ class ClinVarAnnotator(Annotator):
                 allele_id,
                 row_rsid,
             ) = row
-            if ref == alt:
-                continue
             if variant.ref is not None and variant.ref not in (ref, complement(ref)):
                 continue
             clinvar_is_indel = len(ref) > 1 or len(alt) > 1
@@ -785,6 +866,7 @@ class ClinVarAnnotator(Annotator):
                         variant.allele1, variant.allele2, alt
                     ),
                     locus=variant_locus(variant),
+                    reference_carries_alt=ref == alt,
                 )
             )
         return _collapse_identical_scvs(annotations)

{allelix-2.4.1 → allelix-2.4.2}/allelix/annotators/pharmgkb.py

@@ -10,7 +10,13 @@ import sqlite3
 import urllib.error
 from typing import TYPE_CHECKING, ClassVar
 
-from allelix.annotators.base import Annotator, LicenseDescriptor, is_clinvar_homref, variant_locus
+from allelix.annotators.base import (
+    Annotator,
+    LicenseDescriptor,
+    carried_alt,
+    is_clinvar_homref,
+    variant_locus,
+)
 from allelix.databases._versions import PHARMGKB_INTERPRETER_VERSION
 from allelix.databases.cpic_loader import (
     fetch_cpic_allele_functions,
@@ -30,7 +36,7 @@ from allelix.databases.pharmgkb_loader import (
     schema_is_current,
 )
 from allelix.models import Annotation
-from allelix.utils.allele import derive_alt_from_diploid, strand_aware_genotype_match
+from allelix.utils.allele import strand_aware_genotype_match
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator
@@ -86,6 +92,7 @@ class PharmGKBAnnotator(Annotator):
         data_dir: Path,
         clinvar_ref_provider: Callable[[str, str], str | None] | None = None,
         palindromic_provider: Callable[[set[str]], set[str]] | None = None,
+        normal_allele_provider: Callable[[str, str], str | None] | None = None,
     ) -> None:
         """Resolve the ClinPGx SQLite cache path within `data_dir`.
 
@@ -100,12 +107,19 @@ class PharmGKBAnnotator(Annotator):
         matching is skipped there. In production it's wired to
         `RsidIdentityAnnotator.palindromic_rsids`. None keeps the per-genotype
         palindrome guard only.
+
+        `normal_allele_provider` gives the normal allele where the build's
+        reference carries a ClinVar variant allele, for deriving `alt`
+        (`base.carried_alt`). In production it's wired to
+        `ClinVarAnnotator.normal_allele_for`. None derives `alt` against
+        `Variant.ref` everywhere.
         """
         super().__init__(data_dir)
         self._db_path = data_dir / PHARMGKB_DB_FILENAME
         self._conn: sqlite3.Connection | None = None
         self._clinvar_ref_provider = clinvar_ref_provider
         self._palindromic_provider = palindromic_provider
+        self._normal_allele_provider = normal_allele_provider
 
     def _connection(self) -> sqlite3.Connection:
         if self._conn is None:
@@ -319,6 +333,9 @@ class PharmGKBAnnotator(Annotator):
             references = (
                 [f"pharmgkb:annotation/{pgkb_annotation_id}"] if pgkb_annotation_id else []
             )
+            alt, reference_carries_alt = carried_alt(
+                variant, variant.allele1, variant.allele2, self._normal_allele_provider
+            )
             annotations.append(
                 Annotation(
                     source=self.name,
@@ -332,8 +349,9 @@ class PharmGKBAnnotator(Annotator):
                     references=references,
                     condition=phenotype or "",
                     gene=gene or "",
-                    alt=derive_alt_from_diploid(variant.ref, variant.allele1, variant.allele2),
+                    alt=alt,
                     locus_ref=variant.ref,
+                    reference_carries_alt=reference_carries_alt,
                     carried_alleles=(variant.allele1, variant.allele2),
                     locus=variant_locus(variant),
                 )
@@ -422,6 +440,9 @@ class PharmGKBAnnotator(Annotator):
                 references = (
                     [f"pharmgkb:annotation/{pgkb_annotation_id}"] if pgkb_annotation_id else []
                 )
+                alt, reference_carries_alt = carried_alt(
+                    variant, variant.allele1, variant.allele2, self._normal_allele_provider
+                )
                 yield Annotation(
                     source=self.name,
                     rsid=variant.rsid,
@@ -434,8 +455,9 @@ class PharmGKBAnnotator(Annotator):
                     references=references,
                     condition=phenotype or "",
                     gene=gene or "",
-                    alt=derive_alt_from_diploid(variant.ref, variant.allele1, variant.allele2),
+                    alt=alt,
                     locus_ref=variant.ref,
+                    reference_carries_alt=reference_carries_alt,
                     carried_alleles=(variant.allele1, variant.allele2),
                     locus=variant_locus(variant),
                 )

{allelix-2.4.1 → allelix-2.4.2}/allelix/annotators/rsid_identity.py

@@ -5,7 +5,8 @@
 Not a clinical source: it never produces Annotations. The pipeline uses it
 for three things, all keyed by locus on the input's own build:
 
-1. ``Variant.ref`` for array data on GRCh37 and GRCh38 (``refs_at_loci``).
+1. ``Variant.ref`` for array data on GRCh37 and GRCh38, from the rows of
+   the call's own rsID at its locus (``alleles_at_loci``).
 2. rsID recovery for rsID-less VCF records on both builds
    (``alleles_at_loci`` feeding ``resolve_rsid_at_locus``).
 3. Translating a GRCh37 ``(chrom, pos, ref, alt)`` to its GRCh38 key so the

{allelix-2.4.1 → allelix-2.4.2}/allelix/annotators/snpedia.py

@@ -18,7 +18,13 @@ import logging
 import sqlite3
 from typing import TYPE_CHECKING, ClassVar
 
-from allelix.annotators.base import Annotator, LicenseDescriptor, is_clinvar_homref, variant_locus
+from allelix.annotators.base import (
+    Annotator,
+    LicenseDescriptor,
+    carried_alt,
+    is_clinvar_homref,
+    variant_locus,
+)
 from allelix.databases.manager import (
     download,
     verify_file_hash,
@@ -29,7 +35,7 @@ from allelix.databases.snpedia_loader import (
     install_prebuilt_cache,
 )
 from allelix.models import Annotation
-from allelix.utils.allele import complement, derive_alt_from_diploid
+from allelix.utils.allele import complement
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator
@@ -125,6 +131,7 @@ class SNPediaAnnotator(Annotator):
         self,
         data_dir: Path,
         clinvar_ref_provider: Callable[[str, str], str | None] | None = None,
+        normal_allele_provider: Callable[[str, str], str | None] | None = None,
     ) -> None:
         """Initialize with path to the data directory.
 
@@ -132,11 +139,16 @@ class SNPediaAnnotator(Annotator):
         callable used by the ADR-0023 hom-ref check. In production it is
         wired to ``ClinVarAnnotator.reference_for``. ``None`` disables the
         check (tests, standalone use).
+
+        ``normal_allele_provider`` gives the normal allele where the build's
+        reference carries a ClinVar variant allele, for deriving ``alt``
+        (``base.carried_alt``); wired to ``ClinVarAnnotator.normal_allele_for``.
         """
         super().__init__(data_dir)
         self._db_path = data_dir / SNPEDIA_DB_FILENAME
         self._conn: sqlite3.Connection | None = None
         self._clinvar_ref_provider = clinvar_ref_provider
+        self._normal_allele_provider = normal_allele_provider
 
     def _connection(self) -> sqlite3.Connection:
         if self._conn is None:
@@ -314,6 +326,9 @@ class SNPediaAnnotator(Annotator):
 
             description = f"SNPedia: {summary}"
             forward_allele1, forward_allele2 = forward_genotype
+            alt, reference_carries_alt = carried_alt(
+                variant, forward_allele1, forward_allele2, self._normal_allele_provider
+            )
             genotype_match = f"{forward_allele1}{forward_allele2}"
 
             annotations.append(
@@ -328,12 +343,9 @@ class SNPediaAnnotator(Annotator):
                     genotype_match=genotype_match,
                     references=[f"https://www.snpedia.com/index.php/{snp_url_path}"],
                     gene=gene or "",
-                    alt=derive_alt_from_diploid(
-                        variant.ref,
-                        forward_allele1,
-                        forward_allele2,
-                    ),
+                    alt=alt,
                     locus_ref=variant.ref,
+                    reference_carries_alt=reference_carries_alt,
                     carried_alleles=(forward_allele1, forward_allele2),
                     locus=variant_locus(variant),
                 )
@@ -418,6 +430,9 @@ class SNPediaAnnotator(Annotator):
                 category = _REPUTE_CATEGORY.get(repute_lower, "trait")
                 description = f"SNPedia: {summary}"
                 forward_allele1, forward_allele2 = forward_genotype
+                alt, reference_carries_alt = carried_alt(
+                    variant, forward_allele1, forward_allele2, self._normal_allele_provider
+                )
                 genotype_match = f"{forward_allele1}{forward_allele2}"
                 yield Annotation(
                     source=self.name,
@@ -430,12 +445,9 @@ class SNPediaAnnotator(Annotator):
                     genotype_match=genotype_match,
                     references=[f"https://www.snpedia.com/index.php/{snp_url_path}"],
                     gene=gene or "",
-                    alt=derive_alt_from_diploid(
-                        variant.ref,
-                        forward_allele1,
-                        forward_allele2,
-                    ),
+                    alt=alt,
                     locus_ref=variant.ref,
+                    reference_carries_alt=reference_carries_alt,
                     carried_alleles=(forward_allele1, forward_allele2),
                     locus=variant_locus(variant),
                 )

{allelix-2.4.1 → allelix-2.4.2}/allelix/databases/_versions.py

@@ -15,7 +15,13 @@ reject stale caches without forcing a full re-download.
 # ("-", "not specified", "no classification provided", etc.) in the cache.
 # Without this bump, existing iv:3 caches stay poisoned — is_ready() would
 # treat them as current and the fix would only reach fresh / --force builds.
-CLINVAR_INTERPRETER_VERSION = 4
+# iv:4→iv:5: the loader classifies records by their HGVS name (2.4.2).
+# Normal-allele records (c.N=) lose their REF == ALT rows and their
+# Pathogenic / Likely pathogenic rows, and REF == ALT non-SNV rows are
+# dropped, so a REF == ALT row means this build's reference carries the
+# variant allele. An iv:4 cache still holds the old rows and must not be
+# read with the new rule.
+CLINVAR_INTERPRETER_VERSION = 5
 # Also bump for a change to how CPIC allele-function data is loaded: a bump
 # makes existing ClinPGx caches not ready, and `allelix db update` rebuilds
 # them, fetching the CPIC table again, so the change reaches them.

{allelix-2.4.1 → allelix-2.4.2}/allelix/databases/manager.py

@@ -9,6 +9,7 @@ import gzip
 import hashlib
 import logging
 import os
+import re
 import sqlite3
 import urllib.request
 from pathlib import Path
@@ -167,6 +168,8 @@ def verify_file_hash(path: Path, algorithm: str, expected_hex: str) -> None:
 # Both files use `\t` as field separator and `#` as comment-line prefix.
 
 # variant_summary.txt.gz — 43 columns. We only need a handful.
+_VS_TYPE = 1  # "Type": "single nucleotide variant", "Deletion", ...
+_VS_NAME = 2  # "Name": HGVS, e.g. "NM_000130.5(F5):c.1601G>A (p.Arg534Gln)"
 _VS_RS = 9  # "RS# (dbSNP)"     — number only, no `rs` prefix
 _VS_GENE_SYMBOL = 4  # "GeneSymbol"
 _VS_REVIEW_STATUS = 24  # "ReviewStatus" — aggregate
@@ -227,6 +230,33 @@ _CLINVAR_PLACEHOLDER_CLNSIGS: frozenset[str] = frozenset(
 )
 
 
+# Per-SCV classifications dropped from normal-allele records whose VCF
+# alleles differ on the build (see ``describes_reference_allele``).
+_NORMAL_ALLELE_DROPPED_CLNSIGS: frozenset[str] = frozenset(
+    {
+        "pathogenic",
+        "likely pathogenic",
+        "pathogenic/likely pathogenic",
+        "pathogenic, low penetrance",
+        "likely pathogenic, low penetrance",
+    }
+)
+
+_HGVS_ALLELE = re.compile(r"\b[cgmn]\.([^\s(]+)")
+
+
+def describes_reference_allele(name: str) -> bool:
+    """Return True when a ClinVar record's HGVS name describes the reference sequence.
+
+    ClinVar writes the normal (reference-sequence) allele as ``c.N=``, for
+    example ``NM_000130.5(F5):c.1601=``. Only the nucleotide description
+    counts: a synonymous protein change such as ``c.123A>G (p.Leu41=)``
+    describes a real variant.
+    """
+    match = _HGVS_ALLELE.search(name)
+    return match is not None and match.group(1).endswith("=")
+
+
 def _open_tsv(path: Path) -> Iterator[list[str]]:
     """Stream a (possibly-gzipped) tab-delimited TSV, skipping comment lines."""
     opener: object = gzip.open if path.suffix == ".gz" else open
@@ -345,7 +375,8 @@ def iter_clinvar_tsv_records(
                 "  ref TEXT, "
                 "  alt TEXT, "
                 "  gene TEXT, "
-                "  review_status TEXT"
+                "  review_status TEXT, "
+                "  normal_allele INTEGER"
                 ");"
             )
             batch: list[tuple[object, ...]] = []
@@ -377,6 +408,16 @@ def iter_clinvar_tsv_records(
                     variation_id = int(cols[_VS_VARIATION_ID].strip())
                 except (ValueError, IndexError):
                     continue
+                normal_allele = describes_reference_allele(cols[_VS_NAME])
+                if ref == alt and (
+                    normal_allele or cols[_VS_TYPE].strip() != "single nucleotide variant"
+                ):
+                    # REF == ALT has one meaning left in the cache: this
+                    # build's reference carries the variant allele (F5
+                    # c.1601G>A on GRCh37). A normal-allele record with
+                    # REF == ALT describes the reference itself, and a
+                    # non-SNV with REF == ALT has no alleles on this build.
+                    continue
                 batch.append(
                     (
                         variation_id,
@@ -387,17 +428,18 @@ def iter_clinvar_tsv_records(
                         alt,
                         cols[_VS_GENE_SYMBOL].strip(),
                         cols[_VS_REVIEW_STATUS].strip(),
+                        int(normal_allele),
                     )
                 )
                 if len(batch) >= INSERT_BATCH_SIZE:
                     tmp_conn.executemany(
-                        "INSERT OR IGNORE INTO vs VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                        "INSERT OR IGNORE INTO vs VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
                         batch,
                     )
                     batch.clear()
             if batch:
                 tmp_conn.executemany(
-                    "INSERT OR IGNORE INTO vs VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                    "INSERT OR IGNORE INTO vs VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
                     batch,
                 )
             tmp_conn.commit()
@@ -415,14 +457,20 @@ def iter_clinvar_tsv_records(
                 except (ValueError, IndexError):
                     continue
                 row = cursor.execute(
-                    "SELECT rsid, chromosome, position, ref, alt, gene, review_status "
-                    "FROM vs WHERE variation_id = ?",
+                    "SELECT rsid, chromosome, position, ref, alt, gene, review_status, "
+                    "normal_allele FROM vs WHERE variation_id = ?",
                     (variation_id,),
                 ).fetchone()
                 if row is None:
                     continue
-                rsid, chromosome, position, ref, alt, gene, review_status_agg = row
+                rsid, chromosome, position, ref, alt, gene, review_status_agg, normal = row
                 clinical_significance = cols[_SS_CLIN_SIG].strip()
+                if normal and clinical_significance.lower() in _NORMAL_ALLELE_DROPPED_CLNSIGS:
+                    # A normal-allele record names the reference sequence;
+                    # carrying it is not a pathogenic finding (F5 c.1601=,
+                    # written T>C on GRCh37). Its other classifications
+                    # stay as they are.
+                    continue
                 # ClinVar's submission_summary
                 # carries several placeholder values that mean "no clinical
                 # significance recorded." A placeholder that ISN'T in

{allelix-2.4.1 → allelix-2.4.2}/allelix/models.py

@@ -211,6 +211,12 @@ class Annotation:
     #   analysis build, chromosome in Allelix's bare form. Lets enrichment
     #   key every annotation by position rather than by rsID (ADR-0040).
     locus: tuple[str, int] | None = field(default=None, compare=False, repr=False)
+    # ``reference_carries_alt``: ``alt`` is the reference base because this
+    #   build's reference sequence carries the variant allele (F5 c.1601G>A
+    #   on GRCh37): a ClinVar row written REF == ALT, or a ClinPGx / SNPedia
+    #   genotype whose alt is derived against the normal allele from the
+    #   other build. Exempts the annotation from invariant 2 only.
+    reference_carries_alt: bool = field(default=False, compare=False, repr=False)
 
     def __post_init__(self) -> None:
         """Enforce the allele-identity invariants.
@@ -222,7 +228,9 @@ class Annotation:
            (``ALT_IS_NON_REFERENCE_SOURCES``), ``alt`` is never the
            reference base. GWAS is exempt: its ``alt`` is the study's
            effect (risk) allele, which is often the reference allele.
-           Checked when ``locus_ref`` is known.
+           Checked when ``locus_ref`` is known. An annotation whose alt is
+           the reference base because the build's reference carries the
+           variant allele is exempt (``reference_carries_alt``).
 
         Annotators filter offending source rows before construction; a
         violation here is a programming error, not a data condition.
@@ -237,6 +245,7 @@ class Annotation:
             and self.alt
             and self.locus_ref is not None
             and self.alt == self.locus_ref
+            and not self.reference_carries_alt
         ):
             raise AnnotationInvariantError(
                 f"{self.source} annotation for {self.rsid}: alt {self.alt!r} is the "
@@ -267,7 +276,7 @@ class Annotation:
 # new public-output path, you're re-introducing the bug — add the field
 # here and use ``annotation_to_public_dict`` instead.
 _INTERNAL_ANNOTATION_FIELDS: frozenset[str] = frozenset(
-    {"is_must_include", "locus_ref", "carried_alleles", "locus"}
+    {"is_must_include", "locus_ref", "carried_alleles", "locus", "reference_carries_alt"}
 )
 
 

{allelix-2.4.1 → allelix-2.4.2}/allelix/reports/_pipeline.py

@@ -498,7 +498,10 @@ def _enrichment_allele(a: Annotation) -> str | None:
     The annotation's ``alt``; when it has none (a GWAS row with no reported
     risk allele), the user's single carried non-reference allele. None when
     the locus or its REF is unknown, when there is no such allele or more
-    than one, or when the allele is the reference.
+    than one, or when the allele is the reference, unless the annotation
+    says the build's reference carries the variant allele
+    (``reference_carries_alt``, F5 c.1601G>A on GRCh37): that allele is
+    the variant, and its GRCh38 key is the real variant there.
     """
     if a.locus is None or a.locus_ref is None:
         return None
@@ -508,7 +511,7 @@ def _enrichment_allele(a: Annotation) -> str | None:
         if len(carried) != 1:
             return None
         allele = carried.pop()
-    if allele == a.locus_ref:
+    if allele == a.locus_ref and not a.reference_carries_alt:
         return None
     return allele
 
@@ -544,7 +547,8 @@ def _enrichment_keys(
     GWAS row with no reported risk allele) uses the user's single carried
     non-reference allele, as the rsID-less position fallback always did,
     and gets no key when there is none or more than one. An allele equal
-    to the reference has no variant to look up. GRCh38 keys are used as
+    to the reference has no variant to look up, except where the build's
+    reference carries the variant allele (``reference_carries_alt``). GRCh38 keys are used as
     they are; GRCh37 keys go through the identity table; any other build
     gets no keys.
     """

{allelix-2.4.1 → allelix-2.4.2}/allelix/utils/allele.py

@@ -162,8 +162,9 @@ def resolve_rsid_at_locus(
     """Pick the rsID for an rsID-less call from the ``(ref, alt, rsid)`` rows at its locus.
 
     Shared by every position resolver (ClinVar, gnomAD) so they apply one
-    rule. A row is consistent with the call when it is not a
-    reference-allele record (REF != ALT), its REF equals ``variant_ref``
+    rule. A row is consistent with the call when its REF differs from its
+    ALT (a REF == ALT row names the reference base itself, which no
+    non-reference call explains), its REF equals ``variant_ref``
     when that is known, and the user carries its ALT. The call resolves
     when those rows:
 

{allelix-2.4.1 → allelix-2.4.2/allelix.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 2.4.1
+Version: 2.4.2
 Summary: Open-source genotype analysis toolkit. Format-agnostic ingestion, database-agnostic annotation, offline-first.
 Author: Allelix
 Maintainer-email: dial481 <dial481@users.noreply.github.com>

{allelix-2.4.1 → allelix-2.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "allelix"
-version = "2.4.1"
+version = "2.4.2"
 description = "Open-source genotype analysis toolkit. Format-agnostic ingestion, database-agnostic annotation, offline-first."
 readme = "README.md"
 requires-python = ">=3.11"