allelix 2.0.2__tar.gz → 2.1.0__tar.gz

{allelix-2.0.2 → allelix-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 2.0.2
+Version: 2.1.0
 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.0.2 → allelix-2.1.0}/allelix/annotators/clinvar.py

@@ -30,6 +30,7 @@ from allelix.databases.manager import (
     verify_file_hash,
 )
 from allelix.models import Annotation
+from allelix.utils.allele import strand_aware_carrier_match
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Iterator
@@ -384,7 +385,6 @@ class ClinVarAnnotator(Annotator):
             (variant.rsid,),
         ).fetchall()
         annotations: list[Annotation] = []
-        carrier_alleles = {variant.allele1, variant.allele2}
         user_is_multibase = len(variant.allele1) > 1 or len(variant.allele2) > 1
         # ADR-0023: report the user's actual diploid call consistently
         # across annotators, not the matched ALT base alone.
@@ -404,7 +404,14 @@ class ClinVarAnnotator(Annotator):
             clinvar_is_indel = len(ref) > 1 or len(alt) > 1
             if clinvar_is_indel and not user_is_multibase:
                 continue
-            if alt not in carrier_alleles:
+            # ADR-0035 PR 4: strand-aware carrier match. Direct {ref, alt}
+            # membership still covers forward-stranded inputs; the
+            # complement-fallback path fires only when Variant.ref confirms
+            # reverse orientation AND the site isn't palindromic — preserving
+            # the v2.0.1 #18 multi-allelic safety invariant.
+            if not strand_aware_carrier_match(
+                variant.ref, variant.allele1, variant.allele2, ref, alt
+            ):
                 continue
             sig_label = _normalize_clnsig(clnsig) if clnsig else "unknown"
             if not self._include_benign and sig_label in _BENIGN_CLNSIGS:
@@ -562,7 +569,6 @@ class ClinVarAnnotator(Annotator):
             rows = rows_by_build_rsid.get((variant.build, variant.rsid))
             if not rows:
                 continue
-            carrier_alleles = {variant.allele1, variant.allele2}
             user_is_multibase = len(variant.allele1) > 1 or len(variant.allele2) > 1
             user_diploid = _user_diploid(variant)
             for row in rows:
@@ -580,7 +586,11 @@ class ClinVarAnnotator(Annotator):
                 clinvar_is_indel = len(ref) > 1 or len(alt) > 1
                 if clinvar_is_indel and not user_is_multibase:
                     continue
-                if alt not in carrier_alleles:
+                # ADR-0035 PR 4: strand-aware carrier match. See annotate() for
+                # the safety rationale (#18 multi-allelic invariant preserved).
+                if not strand_aware_carrier_match(
+                    variant.ref, variant.allele1, variant.allele2, ref, alt
+                ):
                     continue
                 sig_label = _normalize_clnsig(clnsig) if clnsig else "unknown"
                 if not self._include_benign and sig_label in _BENIGN_CLNSIGS:

{allelix-2.0.2 → allelix-2.1.0}/allelix/annotators/gwas.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 
 import contextlib
 import logging
+import re
 import sqlite3
 import zipfile
 from typing import TYPE_CHECKING, ClassVar
@@ -56,6 +57,27 @@ logger = logging.getLogger(__name__)
 
 _BATCH_CHUNK = 500  # SQLite default SQLITE_MAX_VARIABLE_NUMBER is 999
 
+# ADR-0035 PR 3: PheCode often arrives embedded in the upstream DISEASE/TRAIT
+# field (e.g. ``"Type 2 diabetes (PheCode 250.2)"``). The annotator extracts it
+# at the boundary so downstream code reads ``Annotation.phecode`` as a
+# structured field instead of regex-parsing prose. The trimmed trait flows into
+# ``Annotation.trait``; ``description`` is rebuilt below from the structured
+# parts so display surfaces still show the PheCode label.
+_PHECODE_SUFFIX_RE = re.compile(r"\s*\(PheCode\s+([\d.]+)\)\s*$")
+
+
+def _split_trait_and_phecode(raw_trait: str) -> tuple[str, str]:
+    """Split an upstream trait into (clean_trait, phecode).
+
+    PheCode (when present) is returned as a bare numeric string like
+    ``"250.2"``. Returns ``""`` for phecode when no PheCode suffix is found.
+    The clean trait is stripped of trailing whitespace.
+    """
+    m = _PHECODE_SUFFIX_RE.search(raw_trait)
+    if m is None:
+        return raw_trait.strip(), ""
+    return raw_trait[: m.start()].rstrip(), m.group(1)
+
 
 def _magnitude(p_value: float | None, or_beta: float | None) -> float:
     """Derive magnitude from p-value and optional effect size.
@@ -288,9 +310,14 @@ class GWASCatalogAnnotator(Annotator):
                 mag = min(_magnitude(p_value, or_beta), _UNKNOWN_RISK_ALLELE_MAG_CAP)
                 risk_note = " (risk allele not specified in study)"
 
+            clean_trait, phecode = _split_trait_and_phecode(trait)
+            phecode_suffix = f" (PheCode {phecode})" if phecode else ""
             p_str = f"p={p_value:.1e}" if p_value is not None else "p=N/A"
             gene_str = gene or "—"
-            description = f"GWAS Catalog: {trait} ({p_str}, gene: {gene_str}){risk_note}"
+            description = (
+                f"GWAS Catalog: {clean_trait}{phecode_suffix} "
+                f"({p_str}, gene: {gene_str}){risk_note}"
+            )
 
             references: list[str] = []
             if pubmed_id:
@@ -309,10 +336,13 @@ class GWASCatalogAnnotator(Annotator):
                     attribution=self.attribution,
                     genotype_match=user_diploid,
                     references=references,
-                    condition=trait,
+                    condition=clean_trait,
                     gene=gene or "",
-                    alt="",
+                    alt=risk_allele or "",
                     is_must_include=variant.rsid in _MUST_INCLUDE_RSIDS,
+                    trait=clean_trait,
+                    p_value=p_value,
+                    phecode=phecode,
                 )
             )
         return annotations
@@ -377,9 +407,14 @@ class GWASCatalogAnnotator(Annotator):
                     mag = min(_magnitude(p_value, or_beta), _UNKNOWN_RISK_ALLELE_MAG_CAP)
                     risk_note = " (risk allele not specified in study)"
 
+                clean_trait, phecode = _split_trait_and_phecode(trait)
+                phecode_suffix = f" (PheCode {phecode})" if phecode else ""
                 p_str = f"p={p_value:.1e}" if p_value is not None else "p=N/A"
                 gene_str = gene or "—"
-                description = f"GWAS Catalog: {trait} ({p_str}, gene: {gene_str}){risk_note}"
+                description = (
+                    f"GWAS Catalog: {clean_trait}{phecode_suffix} "
+                    f"({p_str}, gene: {gene_str}){risk_note}"
+                )
 
                 references: list[str] = []
                 if pubmed_id:
@@ -397,10 +432,13 @@ class GWASCatalogAnnotator(Annotator):
                     attribution=self.attribution,
                     genotype_match=user_diploid,
                     references=references,
-                    condition=trait,
+                    condition=clean_trait,
                     gene=gene or "",
-                    alt="",
+                    alt=risk_allele or "",
                     is_must_include=variant.rsid in _MUST_INCLUDE_RSIDS,
+                    trait=clean_trait,
+                    p_value=p_value,
+                    phecode=phecode,
                 )
 
 

{allelix-2.0.2 → allelix-2.1.0}/allelix/annotators/pharmgkb.py

@@ -30,6 +30,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
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator
@@ -260,20 +261,25 @@ class PharmGKBAnnotator(Annotator):
         if is_clinvar_homref(variant, self._clinvar_ref_provider):
             return []
 
+        # ADR-0035 PR 4: fetch all rows for the rsid (typically <5) and apply
+        # strand-aware genotype match in Python. Forward-stranded users hit
+        # the same set of rows as the v0.7-era ``WHERE genotype = ?`` SQL;
+        # reverse-stranded users now also match when Variant.ref confirms
+        # orientation AND the source genotype is non-palindromic.
         sql = (
             "SELECT genotype, gene, drugs, phenotype, phenotype_category, "
             "annotation_text, level_of_evidence, score, pgkb_annotation_id "
             "FROM pharmgkb_annotations "
-            "WHERE rsid = ? AND genotype = ? AND is_nonfinding = 0"
+            "WHERE rsid = ? AND is_nonfinding = 0"
         )
-        params = (variant.rsid, user_geno)
+        params = (variant.rsid,)
 
         rows = self._connection().execute(sql, params).fetchall()
         annotations: list[Annotation] = []
         user_diploid = _user_diploid(variant)
         for row in rows:
             (
-                _geno,
+                geno,
                 gene,
                 drugs,
                 phenotype,
@@ -283,6 +289,10 @@ class PharmGKBAnnotator(Annotator):
                 _score,
                 pgkb_annotation_id,
             ) = row
+            if not strand_aware_genotype_match(
+                variant.allele1, variant.allele2, geno, variant.ref
+            ):
+                continue
             sig_label = level_of_evidence.strip().lower() or "unknown"
             description_parts = [f"ClinPGx: {drugs}"] if drugs else ["ClinPGx"]
             if phenotype:
@@ -306,6 +316,7 @@ class PharmGKBAnnotator(Annotator):
                     references=references,
                     condition=phenotype or "",
                     gene=gene or "",
+                    alt=derive_alt_from_diploid(variant.ref, variant.allele1, variant.allele2),
                 )
             )
         return annotations
@@ -352,7 +363,7 @@ class PharmGKBAnnotator(Annotator):
             for row in cursor:
                 rows_by_rsid.setdefault(row[0], []).append(row[1:])
 
-        for variant, user_geno in candidates:
+        for variant, _user_geno in candidates:
             rows = rows_by_rsid.get(variant.rsid)
             if not rows:
                 continue
@@ -369,7 +380,11 @@ class PharmGKBAnnotator(Annotator):
                     _score,
                     pgkb_annotation_id,
                 ) = row
-                if geno != user_geno:
+                # ADR-0035 PR 4: strand-aware genotype match. See annotate() for
+                # the safety rationale (palindrome guard + variant.ref orientation).
+                if not strand_aware_genotype_match(
+                    variant.allele1, variant.allele2, geno, variant.ref
+                ):
                     continue
                 sig_label = level_of_evidence.strip().lower() or "unknown"
                 description_parts = [f"ClinPGx: {drugs}"] if drugs else ["ClinPGx"]
@@ -393,6 +408,7 @@ class PharmGKBAnnotator(Annotator):
                     references=references,
                     condition=phenotype or "",
                     gene=gene or "",
+                    alt=derive_alt_from_diploid(variant.ref, variant.allele1, variant.allele2),
                 )
 
 

{allelix-2.0.2 → allelix-2.1.0}/allelix/annotators/snpedia.py

@@ -29,6 +29,7 @@ from allelix.databases.snpedia_loader import (
     install_prebuilt_cache,
 )
 from allelix.models import Annotation
+from allelix.utils.allele import derive_alt_from_diploid
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator
@@ -272,6 +273,7 @@ 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, allele1, allele2),
                 )
             )
 
@@ -356,4 +358,5 @@ 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, allele1, allele2),
                 )

{allelix-2.0.2 → allelix-2.1.0}/allelix/models.py

@@ -31,6 +31,13 @@ class Variant:
         allele1: First observed allele. A/T/G/C, multi-base for indels, or "-" for no-call.
         allele2: Second observed allele. Same encoding as allele1.
         build: Reference genome build. "GRCh37" (hg19) or "GRCh38" (hg38).
+        ref: Reference allele on the forward strand at this position, when
+            known. VCF parsers populate from the REF column; array parsers
+            currently leave it None. Required by strand-aware carrier matching
+            (ADR-0035) and downstream consumers that need to identify the risk
+            allele within the user's pair. None means "cannot resolve" —
+            consumers degrade gracefully (return ambiguous, skip strand check,
+            etc.) rather than guess.
     """
 
     rsid: str
@@ -39,9 +46,10 @@ class Variant:
     allele1: str
     allele2: str
     build: str = DEFAULT_BUILD
+    ref: str | None = None
 
     def __post_init__(self) -> None:
-        """Normalize allele case at construction (GH #14).
+        """Normalize allele case at construction (GH #14, ADR-0035).
 
         Reference databases (ClinVar, gnomAD, ClinPGx, etc.) all ship
         uppercase alleles, and carrier matching is raw set membership
@@ -53,11 +61,20 @@ class Variant:
         at the model boundary so the invariant is impossible to
         violate downstream. The no-call marker is left as-is;
         multi-base alleles (indels) are uppercased in place.
+
+        ``ref`` (ADR-0035) is a sibling allele field feeding the same
+        downstream matching path (PR 4 strand-aware carrier matching
+        compares ``ref`` against ``{allele1, allele2}`` and against
+        gnomAD's uppercased REF). VCFs derived from soft-masked
+        references emit lowercase bases in the REF column, so the
+        same normalization applies here for the same reason.
         """
         if self.allele1 and self.allele1 != NO_CALL_MARKER:
             self.allele1 = self.allele1.upper()
         if self.allele2 and self.allele2 != NO_CALL_MARKER:
             self.allele2 = self.allele2.upper()
+        if self.ref is not None and self.ref != NO_CALL_MARKER:
+            self.ref = self.ref.upper()
 
     @property
     def is_heterozygous(self) -> bool:
@@ -126,6 +143,15 @@ class Annotation:
     am_pathogenicity: float | None = None
     am_class: str = ""
     cadd_phred: float | None = None
+    # ADR-0035 cluster manifest (PR 3): structured GWAS fields promoted out of
+    # the rendered ``description`` prose. `description` still carries the same
+    # rendered text for HTML / terminal display, but downstream code (rollup,
+    # diff, future consumers) reads the structured fields directly instead of
+    # regex-parsing prose. Populated by the GWAS annotator; empty / None on
+    # non-GWAS rows.
+    trait: str = ""
+    p_value: float | None = None
+    phecode: str = ""
 
     @property
     def zygosity(self) -> str:

{allelix-2.0.2 → allelix-2.1.0}/allelix/parsers/vcf.py

@@ -413,6 +413,7 @@ def _parse_data_line(line: str, sample_idx: int) -> Variant | None:
         allele1=a1,
         allele2=a2,
         # build is overridden by the pipeline (ADR-0021); leave default.
+        ref=ref,
     )
 
 

{allelix-2.0.2 → allelix-2.1.0}/allelix/reports/_pipeline.py

@@ -167,58 +167,26 @@ class AnalysisResult:
         return out
 
 
-# GH #24: both _gwas_base_trait and _gwas_phecode_parent reach into the
-# formatted description string to recover structured fields. The two
-# previously used inconsistent delimiters (" (PheCode " vs "(PheCode "),
-# the spirit of "no regex on prose" violated with .split()/.find().
-# Until trait/p-value/PheCode are carried as structured fields on
-# Annotation (deferred to v2.1+, see ADR-0024 followup), at least keep
-# the delimiter consistent across both readers.
-_PHECODE_DELIM = " (PheCode "
-
-
-def _gwas_base_trait(description: str) -> str | None:
-    """Extract trait text from a GWAS description, stripping MTAG suffix and PheCode label."""
-    marker = "GWAS Catalog: "
-    if marker not in description:
-        return None
-    s = description.split(marker, 1)[1]
-    s = s.split(" (p=", 1)[0]
-    if s.endswith(" (MTAG)"):
-        s = s[: -len(" (MTAG)")]
-    s = s.split(_PHECODE_DELIM, 1)[0]
-    return s.strip().lower()
-
-
-def _gwas_phecode_parent(description: str) -> str | None:
-    """Extract PheCode parent (numeric prefix before the dot), or None."""
-    idx = description.find(_PHECODE_DELIM)
-    if idx == -1:
-        return None
-    rest = description[idx + len(_PHECODE_DELIM) :]
-    end = rest.find(")")
-    if end == -1:
-        return None
-    code = rest[:end].strip()
-    parent = code.split(".", 1)[0]
-    return parent if parent.isdigit() else None
+# ADR-0035 PR 3 closed the GH #24 structural-half: GWAS rollup now reads
+# trait / phecode / p_value from structured Annotation fields instead of
+# regex-parsing the rendered ``description`` prose. The previous
+# ``_gwas_base_trait`` / ``_gwas_phecode_parent`` / ``_gwas_p_value`` helpers
+# and the ``_PHECODE_DELIM`` shared-delimiter constant (the v2.0.1 suppress-
+# half) are gone — rollup keys directly off ``a.trait``, ``a.phecode``,
+# ``a.p_value``. MTAG suffix still lives in ``description`` for display and
+# is detected with ``"(MTAG)" in a.description``; promoting that to a
+# structured flag is outside the ADR-0035 cluster manifest.
 
 
-def _gwas_p_value(description: str) -> float:
-    """Extract p-value from a GWAS description. Returns inf if unparseable."""
-    idx = description.find("(p=")
-    if idx == -1:
-        return float("inf")
-    rest = description[idx + len("(p=") :]
-    end = rest.find(",")
-    if end == -1:
-        end = rest.find(")")
-    if end == -1:
-        return float("inf")
-    try:
-        return float(rest[:end].strip())
-    except ValueError:
-        return float("inf")
+def _gwas_phecode_parent(phecode: str) -> str | None:
+    """Return the integer parent of a structured PheCode (e.g., ``"411.4"`` → ``"411"``).
+
+    Returns None when no PheCode is set or the prefix isn't an integer.
+    """
+    if not phecode:
+        return None
+    parent = phecode.split(".", 1)[0]
+    return parent if parent.isdigit() else None
 
 
 def rollup_gwas_duplicates(annotations: list[Annotation]) -> list[Annotation]:
@@ -238,29 +206,25 @@ def rollup_gwas_duplicates(annotations: list[Annotation]) -> list[Annotation]:
     if not gwas_rows:
         return annotations
 
-    plain_keys = {
-        (a.rsid, _gwas_base_trait(a.description))
-        for a in gwas_rows
-        if "(MTAG)" not in a.description
-    }
+    plain_keys = {(a.rsid, a.trait.lower()) for a in gwas_rows if "(MTAG)" not in a.description}
     after_mtag = [
         a
         for a in gwas_rows
         if a.is_must_include
         or "(MTAG)" not in a.description
-        or (a.rsid, _gwas_base_trait(a.description)) not in plain_keys
+        or (a.rsid, a.trait.lower()) not in plain_keys
     ]
 
     by_parent: dict[tuple[str, str], list[Annotation]] = {}
     no_phecode: list[Annotation] = []
     for a in after_mtag:
-        parent = _gwas_phecode_parent(a.description)
+        parent = _gwas_phecode_parent(a.phecode)
         if parent is None or a.is_must_include:
             no_phecode.append(a)
         else:
             by_parent.setdefault((a.rsid, parent), []).append(a)
     for group in by_parent.values():
-        winner = min(group, key=lambda x: _gwas_p_value(x.description))
+        winner = min(group, key=lambda x: x.p_value if x.p_value is not None else float("inf"))
         no_phecode.append(winner)
 
     survivors.extend(no_phecode)
@@ -438,6 +402,23 @@ def run_analysis(
                     resolution = clinvar_resolver.bulk_resolve_rsids(rsidless)
                     for (chrom, pos, ref, alt), rsid in resolution.items():
                         resolved_coords[rsid] = (chrom, pos, 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
+            # match; SNPedia / ClinPGx per-row alt threading from PR 2)
+            # consume this. Variants without rsIDs (post-resolution) or
+            # whose rsID isn't in gnomAD keep ref=None and degrade
+            # gracefully — direct-match-only with no strand-flip.
+            if gnomad is not None and gnomad.is_ready():
+                need_ref = {v.rsid for v in batch_buf if v.ref is None and v.rsid.startswith("rs")}
+                if need_ref:
+                    coord_map = gnomad.bulk_resolve_coordinates(need_ref)
+                    for v in batch_buf:
+                        if v.ref is None and v.rsid in coord_map:
+                            entries = coord_map[v.rsid]
+                            # All multi-allelic rows at a position share the
+                            # same REF; first entry's REF is canonical.
+                            v.ref = entries[0][2] if entries else None
             # High-value rsID match runs AFTER resolution so a variant
             # entering as ID=. that resolves to a high-value rsID is still
             # caught. GH #11.

{allelix-2.0.2 → allelix-2.1.0}/allelix/reports/diff.py

@@ -26,7 +26,7 @@ if TYPE_CHECKING:
 
     from allelix.models import Annotation
 
-_SUPPORTED_SCHEMA_VERSIONS = {"1", "2", "3", "4"}
+_SUPPORTED_SCHEMA_VERSIONS = {"1", "2", "3", "4", "5"}
 
 # GH #25: magnitude comparison tolerance. Magnitudes are scored on a
 # 0-10 scale; representation noise from JSON round-tripping (e.g. 7.5

{allelix-2.0.2 → allelix-2.1.0}/allelix/reports/json_report.py

@@ -5,7 +5,7 @@
 Output schema (versioned via `schema_version`):
 
     {
-      "schema_version": "4",
+      "schema_version": "5",
       "allelix_version": "1.1.0",
       "generated_at": "2026-05-11T12:34:56+00:00",
       "regulatory_notice": "...",
@@ -52,7 +52,11 @@ if TYPE_CHECKING:
     from allelix.reports.diff import DiffResult
 
 
-SCHEMA_VERSION = "4"
+SCHEMA_VERSION = "5"
+# v4 → v5 bump: enters the ADR-0035 cluster contract. Incoming cluster fields
+# (variant.ref via Variant model, annotation.trait / .p_value / .phecode via
+# Annotation model) land across PRs 1-4 of the v2.1 Cluster B work. v4
+# consumers reading v5 output still succeed — every v4 field is unchanged.
 
 
 def _annotation_dict(a: Annotation) -> dict:

allelix-2.1.0/allelix/utils/allele.py

@@ -0,0 +1,211 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 Allelix
+"""Strand flipping, complement logic, and ambiguous-SNP detection.
+
+A SNP read on the reverse strand has its alleles complemented (A↔T, C↔G).
+Two databases reporting the "same" variant on opposite strands will list
+opposite allele letters. For most SNPs this is unambiguous and reversible.
+For A/T and C/G SNPs (palindromic), the complement equals the alternative —
+so a strand-flip is undetectable from sequence alone and is best handled by
+extra information (allele frequency, surrounding context).
+
+ADR-0010 documents the design.
+"""
+
+from __future__ import annotations
+
+from allelix.models import NO_CALL_MARKER
+
+_COMPLEMENT: dict[str, str] = {"A": "T", "T": "A", "C": "G", "G": "C"}
+
+# A/T and C/G SNPs are palindromic; their complement equals the alternative,
+# so strand orientation cannot be inferred from the alleles alone.
+_AMBIGUOUS_PAIRS: frozenset[frozenset[str]] = frozenset(
+    {frozenset({"A", "T"}), frozenset({"C", "G"})}
+)
+
+
+def complement(allele: str) -> str:
+    """Return the reverse-complement of a single allele string.
+
+    A → T, T → A, C → G, G → C. The no-call marker `-` and any unrecognized
+    character are returned unchanged. Handles indels (multi-base alleles) by
+    complementing each base in reverse order.
+    """
+    if allele == NO_CALL_MARKER or not allele:
+        return allele
+    if len(allele) == 1:
+        return _COMPLEMENT.get(allele, allele)
+    return "".join(_COMPLEMENT.get(b, b) for b in reversed(allele))
+
+
+def flip_genotype(allele1: str, allele2: str) -> tuple[str, str]:
+    """Return both alleles complemented (the reverse-strand reading)."""
+    return complement(allele1), complement(allele2)
+
+
+def resolve_strand(user_allele: str, gnomad_ref: str, gnomad_alt: str) -> str | None:
+    """Return reference-forward allele, or None if not directly present.
+
+    Maps an array-reported allele to its reference-forward equivalent
+    using gnomAD's ref/alt as the ground truth. If the user allele
+    matches ref or alt directly, it's already forward and is returned.
+
+    GH #18: previously, when the user allele did NOT directly match
+    ref or alt, this function fell back to a complement check
+    (``complement(user_allele) ∈ {ref, alt}`` → return the complement)
+    on the assumption that the array was read on the minus strand. At
+    multi-allelic sites that fallback is unsound — the complement of
+    the user's true forward allele can coincidentally equal a different
+    alt at the same position, returning an allele the user does not
+    carry. The downstream CADD enrichment path then stamps a wrong-
+    allele score onto the annotation. The complement fallback is
+    removed: if the user allele is not in ``{ref, alt}``, return None
+    and let the caller skip enrichment rather than risk a coincidental
+    match. (ADR-0010 already defers proper strand handling; this makes
+    the deferral explicit at the resolution layer.)
+
+    Only operates on single-base alleles. Multi-base alleles (indels)
+    pass through as-is — array indels are rare and not minus-strand
+    reported.
+    """
+    if len(user_allele) != 1:
+        return user_allele
+    if user_allele in (gnomad_ref, gnomad_alt):
+        return user_allele
+    return None
+
+
+def strand_aware_carrier_match(
+    variant_ref: str | None,
+    allele1: str,
+    allele2: str,
+    source_ref: str,
+    source_alt: str,
+) -> bool:
+    """Return True if the user carries ``source_alt`` directly or via strand-flip.
+
+    Multi-allelic safety (the v2.0.1 #18 audit): only fires strand-flip when the
+    ``variant_ref`` context confirms the user is reverse-stranded relative to the
+    source's ref. Without that context — ``variant_ref`` is None, or it agrees
+    with ``source_ref`` (forward) — strand-flip never fires and the carrier
+    match falls back to direct membership only. Skips palindromic ``(ref, alt)``
+    pairs (A/T, C/G) where strand cannot be inferred from sequence alone
+    (ADR-0010 documents the limitation).
+
+    Args:
+        variant_ref: User's claimed REF at the variant locus. ``None`` means
+            the parser couldn't supply one (array data prior to gnomAD-backed
+            population, or the source didn't carry a REF column).
+        allele1: First user allele (upper-cased at ``Variant`` construction).
+        allele2: Second user allele.
+        source_ref: REF from the annotator's source row (forward strand).
+        source_alt: ALT from the annotator's source row (forward strand).
+
+    Returns:
+        True when the user carries ``source_alt`` on either strand. False
+        otherwise — including the abstain cases (palindromic site, no
+        ``variant_ref`` context with no direct match, ref disagreement that
+        isn't a clean complement).
+    """
+    user = {allele1, allele2}
+    if source_alt in user:
+        return True
+    if variant_ref is None:
+        return False
+    if is_strand_ambiguous(source_ref, source_alt):
+        return False
+    if variant_ref == source_ref:
+        return False
+    if variant_ref == complement(source_ref):
+        return complement(source_alt) in user
+    return False
+
+
+def strand_aware_genotype_match(
+    allele1: str,
+    allele2: str,
+    source_geno: str,
+    variant_ref: str | None,
+) -> bool:
+    """Per-genotype carrier match with strand-flip support for ClinPGx / SNPedia.
+
+    PharmGKB / ClinPGx and SNPedia store the user's full diploid (sorted SNV
+    pair like ``"AG"``) rather than per-allele rows. Direct equality remains
+    the primary match. Strand-flip fires only when ``variant_ref`` confirms
+    reverse orientation against the source diploid AND the source diploid is
+    not palindromic (A/T or C/G).
+
+    Args:
+        allele1: First user allele (upper-cased single base for SNVs).
+        allele2: Second user allele.
+        source_geno: Source row's sorted diploid string (e.g. ``"AG"``).
+        variant_ref: User's claimed REF at this locus. ``None`` means no
+            reference context; strand-flip is skipped (direct match only).
+
+    Returns:
+        True when the user matches ``source_geno`` directly or via a
+        complement reading. False otherwise.
+    """
+    if len(allele1) != 1 or len(allele2) != 1 or len(source_geno) != 2:
+        return False
+    user_normalized = "".join(sorted((allele1, allele2)))
+    if user_normalized == source_geno:
+        return True
+    if variant_ref is None:
+        return False
+    user_complement_pair = sorted((complement(allele1), complement(allele2)))
+    if "".join(user_complement_pair) != source_geno:
+        return False
+    if variant_ref in source_geno:
+        return False
+    if complement(variant_ref) not in source_geno:
+        return False
+    distinct = set(source_geno)
+    return distinct != {"A", "T"} and distinct != {"C", "G"}
+
+
+def derive_alt_from_diploid(ref: str | None, allele1: str, allele2: str) -> str:
+    """Derive the user's carried alt from a matched diploid given a known REF.
+
+    For per-genotype annotators (SNPedia, ClinPGx) the matched row describes
+    the user's full diploid pair; the alt the user carries is whichever side
+    of the pair does not equal REF. Returns the empty string when alt cannot
+    be cleanly identified:
+
+    - ``ref`` is None — no reference context yet (e.g., array data prior to
+      strand-aware ref population, ADR-0035 PR 4).
+    - Both alleles equal ref — hom-ref; should be filtered earlier
+      (ADR-0023 for ClinPGx; SNPedia rarely matches hom-ref) but defensive.
+    - Neither allele equals ref — multi-allelic het where the matched row's
+      alleles disagree with the reference (rare for SNPs); conservatively
+      skip rather than guess.
+
+    Conservative-on-uncertainty mirrors the v2.0.1 #23 suppress-half: when
+    the alt can't be cleanly identified, return "" rather than a guess that
+    could stamp the wrong allele's gnomAD / AlphaMissense / CADD value.
+    """
+    if ref is None:
+        return ""
+    if allele1 == ref and allele2 == ref:
+        return ""
+    if allele1 == ref:
+        return allele2
+    if allele2 == ref:
+        return allele1
+    if allele1 == allele2:
+        return allele1
+    return ""
+
+
+def is_strand_ambiguous(ref: str, alt: str) -> bool:
+    """True if (ref, alt) is an A/T or C/G pair — strand cannot be inferred.
+
+    Multi-base indels and any allele containing a no-call or unknown letter
+    are reported as not ambiguous (they have other ways to disambiguate).
+    """
+    if len(ref) != 1 or len(alt) != 1:
+        return False
+    if ref not in _COMPLEMENT or alt not in _COMPLEMENT:
+        return False
+    return frozenset({ref, alt}) in _AMBIGUOUS_PAIRS

{allelix-2.0.2 → allelix-2.1.0}/allelix.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 2.0.2
+Version: 2.1.0
 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.0.2 → allelix-2.1.0}/pyproject.toml

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

{allelix-2.0.2 → allelix-2.1.0}/tests/test_models.py

@@ -38,6 +38,33 @@ class TestVariant:
         v = Variant("rs1", "1", 100, "A", "A", build="GRCh38")
         assert v.build == "GRCh38"
 
+    def test_ref_defaults_to_none(self):
+        """ADR-0035: Variant.ref is optional; array parsers leave it unset."""
+        v = Variant("rs1", "1", 100, "A", "A")
+        assert v.ref is None
+
+    def test_ref_explicit(self):
+        """ADR-0035: VCF parsers populate ref from the REF column."""
+        v = Variant("rs1", "1", 100, "A", "G", ref="A")
+        assert v.ref == "A"
+
+    def test_ref_lowercase_normalized_to_uppercase(self):
+        """ADR-0035 + GH #14: soft-masked references emit lowercase REF.
+
+        Without normalization the strand-aware carrier match (PR 4) would
+        compare a lowercase user ref against uppercase gnomAD / annotator
+        alleles and silently mismatch — exactly the #14 failure mode for
+        the new field. Normalize at the model boundary so the invariant
+        is impossible to violate downstream.
+        """
+        v = Variant("rs1", "1", 100, "A", "G", ref="a")
+        assert v.ref == "A"
+
+    def test_ref_lowercase_indel_normalized(self):
+        """Multi-base ref (indel locus) normalized in place."""
+        v = Variant("rs1", "7", 117199644, "CTT", "C", ref="cttg")
+        assert v.ref == "CTTG"
+
     def test_indel_genotype(self):
         v = Variant("rs1", "7", 117199644, "CTT", "C")
         assert v.is_heterozygous

allelix-2.0.2/allelix/utils/allele.py

@@ -1,89 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-or-later
-# Copyright (C) 2026 Allelix
-"""Strand flipping, complement logic, and ambiguous-SNP detection.
-
-A SNP read on the reverse strand has its alleles complemented (A↔T, C↔G).
-Two databases reporting the "same" variant on opposite strands will list
-opposite allele letters. For most SNPs this is unambiguous and reversible.
-For A/T and C/G SNPs (palindromic), the complement equals the alternative —
-so a strand-flip is undetectable from sequence alone and is best handled by
-extra information (allele frequency, surrounding context).
-
-ADR-0010 documents the design.
-"""
-
-from __future__ import annotations
-
-from allelix.models import NO_CALL_MARKER
-
-_COMPLEMENT: dict[str, str] = {"A": "T", "T": "A", "C": "G", "G": "C"}
-
-# A/T and C/G SNPs are palindromic; their complement equals the alternative,
-# so strand orientation cannot be inferred from the alleles alone.
-_AMBIGUOUS_PAIRS: frozenset[frozenset[str]] = frozenset(
-    {frozenset({"A", "T"}), frozenset({"C", "G"})}
-)
-
-
-def complement(allele: str) -> str:
-    """Return the reverse-complement of a single allele string.
-
-    A → T, T → A, C → G, G → C. The no-call marker `-` and any unrecognized
-    character are returned unchanged. Handles indels (multi-base alleles) by
-    complementing each base in reverse order.
-    """
-    if allele == NO_CALL_MARKER or not allele:
-        return allele
-    if len(allele) == 1:
-        return _COMPLEMENT.get(allele, allele)
-    return "".join(_COMPLEMENT.get(b, b) for b in reversed(allele))
-
-
-def flip_genotype(allele1: str, allele2: str) -> tuple[str, str]:
-    """Return both alleles complemented (the reverse-strand reading)."""
-    return complement(allele1), complement(allele2)
-
-
-def resolve_strand(user_allele: str, gnomad_ref: str, gnomad_alt: str) -> str | None:
-    """Return reference-forward allele, or None if not directly present.
-
-    Maps an array-reported allele to its reference-forward equivalent
-    using gnomAD's ref/alt as the ground truth. If the user allele
-    matches ref or alt directly, it's already forward and is returned.
-
-    GH #18: previously, when the user allele did NOT directly match
-    ref or alt, this function fell back to a complement check
-    (``complement(user_allele) ∈ {ref, alt}`` → return the complement)
-    on the assumption that the array was read on the minus strand. At
-    multi-allelic sites that fallback is unsound — the complement of
-    the user's true forward allele can coincidentally equal a different
-    alt at the same position, returning an allele the user does not
-    carry. The downstream CADD enrichment path then stamps a wrong-
-    allele score onto the annotation. The complement fallback is
-    removed: if the user allele is not in ``{ref, alt}``, return None
-    and let the caller skip enrichment rather than risk a coincidental
-    match. (ADR-0010 already defers proper strand handling; this makes
-    the deferral explicit at the resolution layer.)
-
-    Only operates on single-base alleles. Multi-base alleles (indels)
-    pass through as-is — array indels are rare and not minus-strand
-    reported.
-    """
-    if len(user_allele) != 1:
-        return user_allele
-    if user_allele in (gnomad_ref, gnomad_alt):
-        return user_allele
-    return None
-
-
-def is_strand_ambiguous(ref: str, alt: str) -> bool:
-    """True if (ref, alt) is an A/T or C/G pair — strand cannot be inferred.
-
-    Multi-base indels and any allele containing a no-call or unknown letter
-    are reported as not ambiguous (they have other ways to disambiguate).
-    """
-    if len(ref) != 1 or len(alt) != 1:
-        return False
-    if ref not in _COMPLEMENT or alt not in _COMPLEMENT:
-        return False
-    return frozenset({ref, alt}) in _AMBIGUOUS_PAIRS