allelix 1.8.1__py3-none-any.whl

allelix/__init__.py

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 dial481
+"""Allelix: open-source genotype analysis toolkit."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("allelix")
+except PackageNotFoundError:
+    __version__ = "0.0.0+local"

allelix/annotators/__init__.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 dial481
+"""Annotator registry. Unlike parsers, ALL annotators run on every variant."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from allelix.annotators.alphamissense import AlphaMissenseAnnotator
+from allelix.annotators.base import Annotator
+from allelix.annotators.cadd import CaddAnnotator
+from allelix.annotators.clinvar import CLINVAR_SUPPORTED_BUILDS, ClinVarAnnotator
+from allelix.annotators.gnomad import GnomadAnnotator
+from allelix.annotators.gwas import GWASCatalogAnnotator
+from allelix.annotators.pharmgkb import PharmGKBAnnotator
+from allelix.annotators.snpedia import SNPediaAnnotator
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def get_annotators(
+    data_dir: Path,
+    clinvar_builds: tuple[str, ...] = CLINVAR_SUPPORTED_BUILDS,
+    *,
+    include_benign: bool = False,
+    gwas_filter_traits: bool = True,
+    cadd_full: bool = False,
+) -> list[Annotator]:
+    """Construct all registered annotators bound to the given data directory.
+
+    `clinvar_builds` selects which ClinVar builds are managed by this
+    process. Default is both GRCh37 and GRCh38 (per ADR-0021). The CLI
+    narrows it via `db update --build grch37|grch38`.
+
+    `include_benign` passes through to ClinVarAnnotator. Default False
+    suppresses Benign/Likely_benign annotations (ADR-0008 amendment).
+
+    `gwas_filter_traits` passes through to GWASCatalogAnnotator. Default
+    True excludes common-trait noise categories (ADR-0024 amendment).
+
+    `cadd_full` enables CADD full mode (tabix queries against the
+    complete 81 GB CADD file). Requires ``pysam`` and a local copy.
+
+    ADR-0023: ClinVar's `reference_for(rsid, build)` is wired into
+    PharmGKB and SNPedia as the primary hom-ref suppression filter — the
+    REF allele lookup universally determines whether the user is
+    homozygous reference (and thus a non-finding for that variant).
+    """
+    clinvar = ClinVarAnnotator(data_dir, builds=clinvar_builds, include_benign=include_benign)
+    pharmgkb = PharmGKBAnnotator(data_dir, clinvar_ref_provider=clinvar.reference_for)
+    gwas = GWASCatalogAnnotator(data_dir, filter_traits=gwas_filter_traits)
+    snpedia = SNPediaAnnotator(data_dir, clinvar_ref_provider=clinvar.reference_for)
+    gnomad = GnomadAnnotator(data_dir)
+    alphamissense = AlphaMissenseAnnotator(data_dir)
+    cadd = CaddAnnotator(data_dir, full_mode=cadd_full)
+    return [clinvar, pharmgkb, gwas, snpedia, gnomad, alphamissense, cadd]
+
+
+_ANNOTATOR_CLASSES: dict[str, type[Annotator]] = {
+    cls.name: cls
+    for cls in [
+        ClinVarAnnotator,
+        PharmGKBAnnotator,
+        GWASCatalogAnnotator,
+        SNPediaAnnotator,
+        GnomadAnnotator,
+        AlphaMissenseAnnotator,
+        CaddAnnotator,
+    ]
+}
+
+
+def get_annotator_class(name: str) -> type[Annotator] | None:
+    """Return the annotator class for a given source name, or None."""
+    return _ANNOTATOR_CLASSES.get(name)
+
+
+__all__ = [
+    "AlphaMissenseAnnotator",
+    "Annotator",
+    "CaddAnnotator",
+    "ClinVarAnnotator",
+    "GWASCatalogAnnotator",
+    "GnomadAnnotator",
+    "PharmGKBAnnotator",
+    "SNPediaAnnotator",
+    "get_annotator_class",
+    "get_annotators",
+]

allelix/annotators/alphamissense.py

@@ -0,0 +1,228 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 dial481
+"""AlphaMissense variant pathogenicity enrichment.
+
+AlphaMissense is not a clinical annotator — it does not produce
+Annotation objects. It enriches existing annotations with missense
+variant pathogenicity predictions. The pipeline calls
+``bulk_lookup()`` after all annotators have run, and stamps each
+annotation's ``am_pathogenicity`` and ``am_class`` fields.
+
+License: CC BY 4.0. Attribution: Cheng et al., Science 2023
+(doi:10.1126/science.adg7492).
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from typing import TYPE_CHECKING, ClassVar
+
+from allelix.annotators.base import Annotator, LicenseDescriptor
+from allelix.databases._versions import ALPHAMISSENSE_SCHEMA_VERSION
+from allelix.databases.alphamissense_loader import (
+    ALPHAMISSENSE_CACHE_URL,
+    ALPHAMISSENSE_DB_FILENAME,
+    ALPHAMISSENSE_EXPECTED_SHA256,
+    install_prebuilt_cache,
+)
+from allelix.databases.gnomad_loader import GNOMAD_DB_FILENAME
+from allelix.databases.manager import (
+    download,
+    get_database_info,
+    verify_file_hash,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from allelix.models import Annotation, Variant
+
+logger = logging.getLogger(__name__)
+
+_BULK_BATCH_SIZE = 900
+
+
+class AlphaMissenseAnnotator(Annotator):
+    """Missense variant pathogenicity enrichment from AlphaMissense.
+
+    Subclasses Annotator for ``db update`` / ``db status`` / ``is_ready()``
+    integration. ``annotate()`` always returns ``[]`` — AlphaMissense does
+    not participate in the per-variant annotation loop.
+    """
+
+    name: ClassVar[str] = "alphamissense"
+    display_name: ClassVar[str] = "AlphaMissense"
+    attribution: ClassVar[str] = "AlphaMissense"
+    requires_download: ClassVar[bool] = True
+    server_driven_freshness: ClassVar[bool] = False
+    license: ClassVar[LicenseDescriptor] = LicenseDescriptor(
+        spdx="CC-BY-4.0",
+        license_url="https://creativecommons.org/licenses/by/4.0/",
+        attribution_text=(
+            "AlphaMissense predictions from Cheng et al., Science 2023"
+            " (doi:10.1126/science.adg7492). Licensed under CC BY 4.0."
+        ),
+        source_url="https://zenodo.org/records/10813168",
+        citation="Cheng et al., Science 2023 (doi:10.1126/science.adg7492)",
+        commercial_ok=True,
+    )
+
+    def __init__(self, data_dir: Path) -> None:
+        """Bind to the data directory."""
+        super().__init__(data_dir)
+        self._db_path = data_dir / ALPHAMISSENSE_DB_FILENAME
+        self._conn: sqlite3.Connection | None = None
+
+    def _connection(self) -> sqlite3.Connection:
+        if self._conn is None:
+            if not self._db_path.exists():
+                raise FileNotFoundError(
+                    f"AlphaMissense cache not found at {self._db_path}. "
+                    "Run `allelix db update` first."
+                )
+            self._conn = sqlite3.connect(self._db_path)
+            self._check_gnomad_version()
+        return self._conn
+
+    def _check_gnomad_version(self) -> None:
+        """Warn if the gnomAD version used to build the AM cache differs from installed."""
+        assert self._conn is not None
+        row = self._conn.execute(
+            "SELECT version FROM database_versions WHERE name = 'alphamissense_gnomad_source'"
+        ).fetchone()
+        if row is None:
+            return
+        stamped = row[0]
+        if stamped == "no_gnomad":
+            logger.warning(
+                "AlphaMissense cache was built without gnomAD (--no-gnomad). "
+                "rsID lookups will return no results."
+            )
+            return
+        gnomad_info = get_database_info(self.data_dir / GNOMAD_DB_FILENAME, "gnomad")
+        if gnomad_info is None:
+            return
+        installed = gnomad_info["version"]
+        if installed and stamped != installed:
+            logger.warning(
+                "AlphaMissense cache was built against gnomAD %s but installed "
+                "gnomAD is %s. rsID mappings may be stale. Rebuild with: "
+                "python scripts/build_alphamissense_cache.py",
+                stamped,
+                installed,
+            )
+
+    def setup(self) -> None:
+        """Download the pre-built AlphaMissense cache from HuggingFace."""
+        gz_path = self.data_dir / "alphamissense.sqlite.gz"
+        download(ALPHAMISSENSE_CACHE_URL, gz_path)
+        verify_file_hash(gz_path, "sha256", ALPHAMISSENSE_EXPECTED_SHA256)
+        install_prebuilt_cache(
+            gz_path,
+            self._db_path,
+            source_url=ALPHAMISSENSE_CACHE_URL,
+        )
+        try:
+            gz_path.unlink()
+        except OSError:
+            logger.warning("Could not remove staged file at %s", gz_path)
+
+    def is_ready(self) -> bool:
+        """True when the AlphaMissense SQLite cache exists with current schema version."""
+        info = get_database_info(self._db_path, "alphamissense")
+        if info is None:
+            return False
+        tag = info.get("local_version_tag") or ""
+        return tag == f"sv:{ALPHAMISSENSE_SCHEMA_VERSION}" or not tag
+
+    def version(self) -> str | None:
+        """Return the cached database version, or None."""
+        info = get_database_info(self._db_path, "alphamissense")
+        return info["version"] if info else None
+
+    def record_count(self) -> int | None:
+        """Return the number of variants in the cache, or None."""
+        info = get_database_info(self._db_path, "alphamissense")
+        return info["record_count"] if info else None
+
+    def close(self) -> None:
+        """Close the SQLite connection if open."""
+        if self._conn is not None:
+            self._conn.close()
+            self._conn = None
+
+    def fetch_remote_signal(self) -> str | None:
+        """Code-driven source — no runtime freshness probe (ADR-0030)."""
+        return None
+
+    def cached_remote_signal(self) -> str | None:
+        """Code-driven source — no cached signal to compare (ADR-0030)."""
+        return None
+
+    def annotate(self, variant: Variant) -> list[Annotation]:
+        """Not used — AlphaMissense enriches, does not annotate. Always returns []."""
+        return []
+
+    def lookup(self, rsid: str) -> tuple[float, str] | None:
+        """Return (am_pathogenicity, am_class) for a single rsID, or None."""
+        conn = self._connection()
+        row = conn.execute(
+            "SELECT MAX(am_pathogenicity), am_class FROM alphamissense_scores WHERE rsid = ?",
+            (rsid,),
+        ).fetchone()
+        if row is None or row[0] is None:
+            return None
+        return (row[0], row[1])
+
+    def bulk_lookup(self, rsids: set[str]) -> dict[str, tuple[float, str]]:
+        """Return ``{rsid: (am_pathogenicity, am_class)}`` for found rsIDs.
+
+        Fallback for annotations without a known alt allele. Uses MAX to
+        resolve multi-allelic sites. Prefer ``bulk_lookup_by_alt`` when alt
+        is available.
+
+        Batches into chunks of 900 to stay within SQLite's variable limit.
+        """
+        if not rsids:
+            return {}
+        conn = self._connection()
+        result: dict[str, tuple[float, str]] = {}
+        rsid_list = list(rsids)
+        for i in range(0, len(rsid_list), _BULK_BATCH_SIZE):
+            batch = rsid_list[i : i + _BULK_BATCH_SIZE]
+            placeholders = ",".join("?" * len(batch))
+            rows = conn.execute(
+                f"SELECT rsid, MAX(am_pathogenicity), am_class"
+                f" FROM alphamissense_scores"
+                f" WHERE rsid IN ({placeholders}) GROUP BY rsid",
+                batch,
+            ).fetchall()
+            for rsid, score, cls in rows:
+                if score is not None:
+                    result[rsid] = (score, cls)
+        return result
+
+    def bulk_lookup_by_alt(
+        self, keys: set[tuple[str, str]]
+    ) -> dict[tuple[str, str], tuple[float, str]]:
+        """Return ``{(rsid, alt): (am_pathogenicity, am_class)}`` for exact matches."""
+        if not keys:
+            return {}
+        conn = self._connection()
+        result: dict[tuple[str, str], tuple[float, str]] = {}
+        key_list = list(keys)
+        batch_size = _BULK_BATCH_SIZE // 2
+        for i in range(0, len(key_list), batch_size):
+            batch = key_list[i : i + batch_size]
+            clauses = " OR ".join(["(rsid = ? AND alt = ?)"] * len(batch))
+            params = [v for rsid, alt in batch for v in (rsid, alt)]
+            rows = conn.execute(
+                f"SELECT rsid, alt, am_pathogenicity, am_class"
+                f" FROM alphamissense_scores WHERE {clauses}",
+                params,
+            ).fetchall()
+            for rsid, alt, score, cls in rows:
+                if score is not None:
+                    result[(rsid, alt)] = (score, cls)
+        return result

allelix/annotators/base.py

@@ -0,0 +1,214 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 dial481
+"""Abstract base class for reference-database annotators."""
+
+from __future__ import annotations
+
+import contextlib
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import TYPE_CHECKING, ClassVar
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+    from types import TracebackType
+
+    from allelix.models import Annotation, Variant
+
+
+@dataclass(frozen=True)
+class LicenseDescriptor:
+    """Single source of truth for a data source's license terms."""
+
+    spdx: str
+    license_url: str
+    attribution_text: str
+    source_url: str | None = None
+    citation: str | None = None
+    commercial_ok: bool | None = None
+    licensable: bool = False
+    purchase_url: str | None = None
+
+
+_NON_COMMERCIAL_SPDX: frozenset[str] = frozenset(
+    {
+        "CC-BY-NC-SA-3.0-US",
+        "CC-BY-NC-SA-4.0",
+        "CC-BY-NC-4.0",
+    }
+)
+
+
+def is_non_commercial(descriptor: LicenseDescriptor) -> bool:
+    """Return True if the license prohibits commercial use."""
+    if descriptor.commercial_ok is not None:
+        return not descriptor.commercial_ok
+    return descriptor.spdx in _NON_COMMERCIAL_SPDX
+
+
+class Permission(Enum):
+    """Three-state permission result for a source in the current license context."""
+
+    ALLOW = auto()
+    BLOCK_FINAL = auto()
+    BLOCK_PURCHASABLE = auto()
+
+
+def permission(
+    descriptor: LicenseDescriptor,
+    *,
+    commercial: bool,
+    license_held: bool,
+) -> Permission:
+    """Determine whether a source is permitted under the current license context."""
+    if not commercial:
+        return Permission.ALLOW
+    if not is_non_commercial(descriptor):
+        return Permission.ALLOW
+    if not descriptor.licensable:
+        return Permission.BLOCK_FINAL
+    if license_held:
+        return Permission.ALLOW
+    return Permission.BLOCK_PURCHASABLE
+
+
+def is_clinvar_homref(
+    variant: Variant,
+    clinvar_ref_provider: Callable[[str, str], str | None] | None,
+) -> bool:
+    """Return True if the variant is homozygous reference per ClinVar (ADR-0023)."""
+    if clinvar_ref_provider is None:
+        return False
+    ref = clinvar_ref_provider(variant.rsid, variant.build)
+    return ref is not None and len(ref) == 1 and variant.allele1 == ref and variant.allele2 == ref
+
+
+class Annotator(ABC):
+    """Base class for all reference database annotators.
+
+    Annotators bind to a `data_dir` at construction. `setup()` performs the
+    one-time download/parse into the cache. `is_ready()` reports whether the
+    cache exists and is queryable. `annotate(variant)` returns zero or more
+    `Annotation` objects for the variant — checking both rsid AND genotype, per
+    the regulatory posture (ADR-0003) and the genotype-matching rule (ADR-0007).
+
+    Annotators hold resources (SQLite connections, file handles). Always close
+    them via `close()` or the context manager protocol; the CLI uses
+    `contextlib.ExitStack` to guarantee deterministic cleanup.
+
+    Attributes:
+        name: Lowercase identifier (e.g., "clinvar").
+        display_name: Human-readable name ("ClinVar").
+        attribution: Display label used in user-facing reports ("ClinVar").
+            Equal to `display_name` for first-party single-source annotators.
+        requires_download: Whether `setup()` needs network/disk space.
+    """
+
+    name: ClassVar[str]
+    display_name: ClassVar[str]
+    attribution: ClassVar[str]
+    requires_download: ClassVar[bool] = True
+    server_driven_freshness: ClassVar[bool] = True
+    license: ClassVar[LicenseDescriptor]
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        """Enforce required ClassVars at subclass definition time."""
+        super().__init_subclass__(**kwargs)
+        is_abstract = any(getattr(v, "__isabstractmethod__", False) for v in cls.__dict__.values())
+        if not is_abstract and not hasattr(cls, "license"):
+            msg = f"{cls.__name__} must declare a 'license' ClassVar of type LicenseDescriptor"
+            raise TypeError(msg)
+        if hasattr(cls, "license"):
+            desc = cls.license
+            if (
+                desc.spdx.startswith("LicenseRef-") or desc.spdx.startswith("custom-")
+            ) and desc.commercial_ok is None:
+                msg = (
+                    f"{cls.__name__} uses custom SPDX '{desc.spdx}' but "
+                    f"does not declare commercial_ok (True or False)"
+                )
+                raise TypeError(msg)
+            if desc.licensable and desc.purchase_url is None:
+                msg = (
+                    f"{cls.__name__} declares licensable=True but "
+                    f"purchase_url is None — set it explicitly"
+                )
+                raise TypeError(msg)
+
+    def __init__(self, data_dir: Path) -> None:
+        """Bind the annotator to a data directory (created elsewhere)."""
+        self.data_dir = data_dir
+
+    def __del__(self) -> None:
+        """Release resources on GC to prevent ResourceWarning."""
+        with contextlib.suppress(Exception):
+            self.close()
+
+    def __enter__(self) -> Annotator:
+        """Return self for `with` usage."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Release any open resources via `close()`."""
+        self.close()
+
+    @abstractmethod
+    def setup(self) -> None:
+        """Download and prepare the reference database. Idempotent."""
+        ...
+
+    @abstractmethod
+    def annotate(self, variant: Variant) -> list[Annotation]:
+        """Return all annotations for this variant.
+
+        Implementations MUST verify both rsid AND genotype — presence in the
+        database is not enough. The user must carry the flagged allele.
+        """
+        ...
+
+    @abstractmethod
+    def is_ready(self) -> bool:
+        """Whether the local cache exists and is queryable."""
+        ...
+
+    @abstractmethod
+    def version(self) -> str | None:
+        """Return the cached database version, or None if not set up."""
+        ...
+
+    @abstractmethod
+    def close(self) -> None:
+        """Release any open resources (database connections, file handles)."""
+        ...
+
+    @abstractmethod
+    def fetch_remote_signal(self) -> str | None:
+        """Fetch a small remote freshness signal (md5 hash, ETag, Last-Modified).
+
+        Implementations MUST return a prefixed, opaque string (e.g.
+        `"md5:abcdef…"`, `"lm:Wed, 21 Oct 2025 …"`, `"etag:…"`) so that a
+        future server-side switch in signal type triggers a refresh
+        rather than a silent miss.
+
+        Returns None on any failure (network error, timeout, missing
+        header, source doesn't expose a signal). Never raises — `db update`
+        treats None as "can't verify freshness" and falls through to skip
+        with a notice. See ADR-0012.
+        """
+        ...
+
+    @abstractmethod
+    def cached_remote_signal(self) -> str | None:
+        """Return the remote signal stored at last successful download, or None.
+
+        Returns None if the cache is missing entirely OR if the cache was
+        written by a pre-v0.4.2 release that didn't capture signals.
+        """
+        ...