altar-opentargets-e2g 0.1.0__tar.gz

altar_opentargets_e2g-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+*.pyc
+*~
+**/__pycache__/*
+*.swp
+.vscode/
+.idea/
+.DS_Store
+.env*
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+pytest.xml
+.hypothesis/
+.python-version
+.venv/
+.venv-*/
+*.egg-info/
+build/
+dist/
+site/
+*.sqlite3
+*.log
+
+# Generated variant indexes and datasets. The small canonical gene table is tracked.
+altar/altar/variants/data/ccres.dnatree
+altar/altar/variants/data/region_annotations.parquet
+altar/altar/variants/data/variants.pkl.gz
+altar/altar/variants/data/raw/
+

altar_opentargets_e2g-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Riya Sinha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

altar_opentargets_e2g-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: altar-opentargets-e2g
+Version: 0.1.0
+Summary: Open Targets ENCODE-rE2G binding for Altar's variant-gene link contract
+Project-URL: Documentation, https://kundajelab.github.io/altar/
+Project-URL: Issues, https://github.com/kundajelab/altar/issues
+Project-URL: Repository, https://github.com/kundajelab/altar
+Author: Riya Sinha
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: altar<0.2,>=0.1
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# altar-opentargets-e2g
+
+This binding normalizes the Open Targets Platform `enhancer_to_gene` dataset (ENCODE-rE2G evidence) into
+Altar's public `VariantGeneLinkSource` relation.
+
+The package owns Open Targets schema and provenance semantics, but not storage. Convert source rows to
+`OpenTargetsE2GRow`, stream them through `OpenTargetsE2GImporter`, and query the published generation with
+`OpenTargetsE2GSource`. Both operate on Altar's generic `VariantGeneLinkStore`; no Open Targets × PostgreSQL,
+Parquet, DuckDB, or service-specific class is required.
+
+```python
+from altar.sources import InMemoryVariantGeneLinkStore
+from altar_opentargets_e2g import (
+    OpenTargetsE2GImportConfig,
+    OpenTargetsE2GImporter,
+    OpenTargetsE2GSource,
+)
+
+store = InMemoryVariantGeneLinkStore()
+await OpenTargetsE2GImporter(store).ingest(
+    rows,
+    OpenTargetsE2GImportConfig(
+        data_release="25.12",
+        score_threshold=0.6,
+        threshold_applied=True,
+    ),
+    generation_id="sha256-of-the-source-asset",
+)
+source = OpenTargetsE2GSource(store)
+```
+
+The importer accepts an iterable so operators can read large upstream Parquet datasets in bounded batches.
+`OpenTargetsE2GRow.from_source_mapping()` accepts the official camelCase `enhancer_to_gene` Parquet fields;
+the binding intentionally does not require a particular Parquet engine. See the
+[Open Targets dataset documentation](https://platform-docs.opentargets.org/data-access/datasets) and
+[rE2G documentation](https://platform-docs.opentargets.org/gentropy/enhancer-to-gene) for acquisition and
+upstream transformations.
+
+The Open Targets pipeline currently filters released rE2G output at `score >= 0.6`. Pass the threshold and
+whether it was applied in `OpenTargetsE2GImportConfig`; Altar retains those semantics in every `LinkScore`
+rather than treating the released table as unthresholded raw predictions.
+
+The caller supplies a generation identifier for the exact extraction; partial generations stay hidden,
+exact replay is idempotent, and publication happens only after the iterable completes. Use
+`VariantGeneLinkQuery.data_releases` when a store contains more than one Open Targets release.
+
+The contract is imported from `altar`; the binding is independently versioned and tested against the public
+Altar conformance suite.

altar_opentargets_e2g-0.1.0/README.md

@@ -0,0 +1,48 @@
+# altar-opentargets-e2g
+
+This binding normalizes the Open Targets Platform `enhancer_to_gene` dataset (ENCODE-rE2G evidence) into
+Altar's public `VariantGeneLinkSource` relation.
+
+The package owns Open Targets schema and provenance semantics, but not storage. Convert source rows to
+`OpenTargetsE2GRow`, stream them through `OpenTargetsE2GImporter`, and query the published generation with
+`OpenTargetsE2GSource`. Both operate on Altar's generic `VariantGeneLinkStore`; no Open Targets × PostgreSQL,
+Parquet, DuckDB, or service-specific class is required.
+
+```python
+from altar.sources import InMemoryVariantGeneLinkStore
+from altar_opentargets_e2g import (
+    OpenTargetsE2GImportConfig,
+    OpenTargetsE2GImporter,
+    OpenTargetsE2GSource,
+)
+
+store = InMemoryVariantGeneLinkStore()
+await OpenTargetsE2GImporter(store).ingest(
+    rows,
+    OpenTargetsE2GImportConfig(
+        data_release="25.12",
+        score_threshold=0.6,
+        threshold_applied=True,
+    ),
+    generation_id="sha256-of-the-source-asset",
+)
+source = OpenTargetsE2GSource(store)
+```
+
+The importer accepts an iterable so operators can read large upstream Parquet datasets in bounded batches.
+`OpenTargetsE2GRow.from_source_mapping()` accepts the official camelCase `enhancer_to_gene` Parquet fields;
+the binding intentionally does not require a particular Parquet engine. See the
+[Open Targets dataset documentation](https://platform-docs.opentargets.org/data-access/datasets) and
+[rE2G documentation](https://platform-docs.opentargets.org/gentropy/enhancer-to-gene) for acquisition and
+upstream transformations.
+
+The Open Targets pipeline currently filters released rE2G output at `score >= 0.6`. Pass the threshold and
+whether it was applied in `OpenTargetsE2GImportConfig`; Altar retains those semantics in every `LinkScore`
+rather than treating the released table as unthresholded raw predictions.
+
+The caller supplies a generation identifier for the exact extraction; partial generations stay hidden,
+exact replay is idempotent, and publication happens only after the iterable completes. Use
+`VariantGeneLinkQuery.data_releases` when a store contains more than one Open Targets release.
+
+The contract is imported from `altar`; the binding is independently versioned and tested against the public
+Altar conformance suite.

altar_opentargets_e2g-0.1.0/altar_opentargets_e2g/__init__.py

@@ -0,0 +1,22 @@
+# Copyright 2026 Riya Sinha
+"""Open Targets ENCODE-rE2G binding for Altar's variant-gene link contract."""
+
+from altar_opentargets_e2g.ingest import OpenTargetsE2GImporter, OpenTargetsE2GImportReport
+from altar_opentargets_e2g.schema import (
+    OPEN_TARGETS_E2G_DATASET,
+    OpenTargetsE2GImportConfig,
+    OpenTargetsE2GRow,
+    OpenTargetsResourceScore,
+)
+from altar_opentargets_e2g.source import OpenTargetsE2GSource
+
+
+__all__ = [
+    "OPEN_TARGETS_E2G_DATASET",
+    "OpenTargetsE2GImportConfig",
+    "OpenTargetsE2GImportReport",
+    "OpenTargetsE2GImporter",
+    "OpenTargetsE2GRow",
+    "OpenTargetsE2GSource",
+    "OpenTargetsResourceScore",
+]

altar_opentargets_e2g-0.1.0/altar_opentargets_e2g/ingest.py

@@ -0,0 +1,99 @@
+# Copyright 2026 Riya Sinha
+"""Streaming Open Targets normalization into a generic variant-gene link store."""
+
+from __future__ import annotations
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING
+
+from altar.sources import VariantGeneLinkDatasetRef, VariantGeneLinkStore
+
+from altar_opentargets_e2g.schema import (
+    OPEN_TARGETS_E2G_DATASET,
+    OpenTargetsE2GImportConfig,
+)
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from altar.sources import VariantGeneEvidenceRecord
+
+    from altar_opentargets_e2g.schema import OpenTargetsE2GRow
+
+
+@dataclass(frozen=True)
+class OpenTargetsE2GImportReport:
+    """Counts for one atomically published streaming import."""
+
+    generation_id: str
+    processed_rows: int
+    added_records: int
+    skipped_records: int
+
+
+class OpenTargetsE2GImporter:
+    """Normalize an iterable of Open Targets rows without owning its transport or database."""
+
+    def __init__(
+        self,
+        store: VariantGeneLinkStore,
+        *,
+        dataset: VariantGeneLinkDatasetRef = OPEN_TARGETS_E2G_DATASET,
+        batch_size: int = 10_000,
+    ) -> None:
+        if batch_size < 1:
+            msg = "batch_size must be positive"
+            raise ValueError(msg)
+        self._store = store
+        self._dataset = dataset
+        self._batch_size = batch_size
+
+    async def ingest(
+        self,
+        rows: Iterable[OpenTargetsE2GRow],
+        config: OpenTargetsE2GImportConfig,
+        *,
+        generation_id: str,
+    ) -> OpenTargetsE2GImportReport:
+        """Stage bounded batches and publish only after the complete iterable succeeds.
+
+        ``generation_id`` should identify the exact upstream asset or extraction. Replaying the same rows with
+        the same identifier is idempotent; changed records are rejected by the store rather than overwritten.
+        """
+        if not generation_id.strip():
+            msg = "generation_id must not be empty"
+            raise ValueError(msg)
+        processed = 0
+        added = 0
+        skipped = 0
+        batch: list[VariantGeneEvidenceRecord] = []
+        # Establish an empty staged generation so a valid empty release can still be published.
+        await self._store.write_records(self._dataset, generation_id, ())
+        for row in rows:
+            record = row.to_evidence_record(config)
+            provenance_metadata = dict(record.provenance.metadata)
+            provenance_metadata["import_generation_id"] = generation_id
+            batch.append(
+                replace(
+                    record,
+                    provenance=replace(record.provenance, metadata=provenance_metadata),
+                    metadata={**record.metadata, "import_generation_id": generation_id},
+                )
+            )
+            processed += 1
+            if len(batch) >= self._batch_size:
+                result = await self._store.write_records(self._dataset, generation_id, batch)
+                added += result.added
+                skipped += result.skipped
+                batch.clear()
+        if batch:
+            result = await self._store.write_records(self._dataset, generation_id, batch)
+            added += result.added
+            skipped += result.skipped
+        await self._store.publish_generation(self._dataset, generation_id)
+        return OpenTargetsE2GImportReport(
+            generation_id=generation_id,
+            processed_rows=processed,
+            added_records=added,
+            skipped_records=skipped,
+        )

altar_opentargets_e2g-0.1.0/altar_opentargets_e2g/py.typed

@@ -0,0 +1 @@
+# PEP 561 marker

altar_opentargets_e2g-0.1.0/altar_opentargets_e2g/schema.py

@@ -0,0 +1,314 @@
+# Copyright 2026 Riya Sinha
+"""Open Targets ``enhancer_to_gene`` rows and canonical normalization."""
+
+from __future__ import annotations
+import math
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+
+from altar.sources import (
+    BiosampleContext,
+    GenomeBuild,
+    GenomicInterval,
+    LinkDistances,
+    LinkProvenance,
+    LinkScore,
+    RegulatoryElement,
+    ScoreDirection,
+    TargetGene,
+    VariantGeneEvidenceRecord,
+    VariantGeneLinkDatasetRef,
+    normalize_chromosome,
+)
+
+
+OPEN_TARGETS_E2G_DATASET = VariantGeneLinkDatasetRef(
+    namespace="org.opentargets.platform",
+    name="enhancer-to-gene",
+    version="1",
+)
+
+_SCORE_INTERPRETATION = (
+    "Open Targets ENCODE-rE2G confidence in the regulatory-element-to-gene assignment; "
+    "higher values indicate stronger evidence"
+)
+_DISTANCE_INTERPRETATION = (
+    "element_to_gene_bp is Open Targets distanceToTss: the unsigned minimum distance from the "
+    "regulatory interval boundary to the target gene TSS (zero for promoters or a TSS inside the interval); "
+    "variant_to_element_bp is zero because this source answers overlap queries"
+)
+
+
+@dataclass(frozen=True)
+class OpenTargetsE2GImportConfig:
+    """Release metadata required to interpret Open Targets rows."""
+
+    data_release: str
+    genome_build: GenomeBuild = GenomeBuild.GRCH38
+    gene_namespace_version: str | None = None
+    dataset_url: str | None = None
+    score_threshold: float | None = None
+    threshold_applied: bool | None = None
+
+    def __post_init__(self) -> None:
+        release = self.data_release.strip()
+        if not release:
+            msg = "Open Targets data_release must not be empty"
+            raise ValueError(msg)
+        object.__setattr__(self, "data_release", release)
+        if self.score_threshold is None:
+            if self.threshold_applied is not None:
+                msg = "threshold_applied requires score_threshold"
+                raise ValueError(msg)
+        elif not math.isfinite(self.score_threshold) or not 0 <= self.score_threshold <= 1:
+            msg = "score_threshold must be finite and between zero and one"
+            raise ValueError(msg)
+        elif self.threshold_applied is None:
+            msg = "threshold_applied is required with score_threshold"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True)
+class OpenTargetsResourceScore:
+    """One named component score retained from the Open Targets interval schema."""
+
+    name: str
+    value: float | None
+
+
+@dataclass(frozen=True)
+class OpenTargetsE2GRow:
+    """The public subset of one Open Targets ``enhancer_to_gene`` Parquet/table row."""
+
+    interval_id: str
+    chromosome: str
+    start: int
+    end: int
+    gene_id: str
+    score: float | None
+    biosample_name: str | None
+    biosample_id: str | None
+    interval_type: str
+    distance_to_tss: int | None
+    datasource_id: str
+    pmid: str | None = None
+    study_id: str | None = None
+    gene_symbol: str | None = None
+    biosample_from_source_id: str | None = None
+    resource_scores: tuple[OpenTargetsResourceScore, ...] = ()
+    quality_controls: tuple[str, ...] = ()
+    evidence_metadata: Mapping[str, object] = field(default_factory=dict)
+
+    @classmethod
+    def from_source_mapping(cls, row: Mapping[str, object]) -> OpenTargetsE2GRow:
+        """Parse one row using the official Open Targets camelCase Parquet schema."""
+        known_fields = {
+            "chromosome",
+            "start",
+            "end",
+            "geneId",
+            "score",
+            "distanceToTss",
+            "resourceScore",
+            "datasourceId",
+            "intervalType",
+            "pmid",
+            "biosampleName",
+            "biosampleFromSourceId",
+            "biosampleId",
+            "studyId",
+            "intervalId",
+            "qualityControls",
+        }
+        return cls(
+            interval_id=_required_string(row, "intervalId"),
+            chromosome=_required_string(row, "chromosome"),
+            start=_required_integer(row, "start"),
+            end=_required_integer(row, "end"),
+            gene_id=_required_string(row, "geneId"),
+            score=_optional_number(row, "score"),
+            biosample_name=_optional_string(row, "biosampleName"),
+            biosample_id=_optional_string(row, "biosampleId"),
+            interval_type=_required_string(row, "intervalType"),
+            distance_to_tss=_optional_integer(row, "distanceToTss"),
+            datasource_id=_required_string(row, "datasourceId"),
+            pmid=_optional_string(row, "pmid"),
+            study_id=_optional_string(row, "studyId"),
+            biosample_from_source_id=_optional_string(row, "biosampleFromSourceId"),
+            resource_scores=_resource_scores(row.get("resourceScore")),
+            quality_controls=_string_sequence(row.get("qualityControls"), field_name="qualityControls"),
+            evidence_metadata={key: value for key, value in row.items() if key not in known_fields},
+        )
+
+    def to_evidence_record(self, config: OpenTargetsE2GImportConfig) -> VariantGeneEvidenceRecord:
+        """Normalize this source row into Altar's query-independent storage record."""
+        if not self.interval_id.strip():
+            msg = "Open Targets interval_id must not be empty"
+            raise ValueError(msg)
+        chromosome = normalize_chromosome(self.chromosome)
+        interval = GenomicInterval(
+            chromosome=chromosome,
+            start=self.start,
+            end=self.end,
+            genome_build=config.genome_build,
+        )
+        normalized_biosample_id = _normalize_ontology_id(self.biosample_id)
+        context = None
+        if self.biosample_name is not None or normalized_biosample_id is not None:
+            context = BiosampleContext(
+                id=normalized_biosample_id,
+                name=self.biosample_name or normalized_biosample_id or "unknown",
+                namespace=_biosample_namespace(normalized_biosample_id),
+            )
+        publications = (f"PMID:{self.pmid}",) if self.pmid else ()
+        return VariantGeneEvidenceRecord(
+            record_id=f"opentargets:{config.data_release}:{self.interval_id}",
+            evidence_interval=interval,
+            regulatory_element=RegulatoryElement(
+                id=f"{config.genome_build.value}:{chromosome}:{self.start}-{self.end}",
+                interval=interval,
+                element_type=self.interval_type,
+            ),
+            target_gene=TargetGene(
+                id=self.gene_id,
+                namespace="ensembl_gene",
+                namespace_version=config.gene_namespace_version,
+                symbol=self.gene_symbol,
+            ),
+            context=context,
+            source_id=self.datasource_id,
+            source_name="Open Targets Platform",
+            method="ENCODE-rE2G",
+            data_release=config.data_release,
+            score=LinkScore(
+                value=self.score,
+                direction=ScoreDirection.HIGHER_IS_STRONGER,
+                interpretation=_SCORE_INTERPRETATION,
+                threshold=config.score_threshold,
+                threshold_rule="greater-than-or-equal" if config.score_threshold is not None else None,
+                threshold_applied=config.threshold_applied,
+                threshold_interpretation=(
+                    "The Open Targets released dataset applies its configured minimum valid score during "
+                    "pipeline quality control."
+                    if config.score_threshold is not None
+                    else None
+                ),
+            ),
+            distances=LinkDistances(
+                element_to_gene_bp=self.distance_to_tss,
+                variant_to_gene_bp=None,
+                variant_to_element_bp=0,
+                interpretation=_DISTANCE_INTERPRETATION,
+            ),
+            provenance=LinkProvenance(
+                source_record_id=self.interval_id,
+                source_dataset="enhancer_to_gene",
+                source_url=config.dataset_url,
+                study_id=self.study_id,
+                publication_ids=publications,
+                metadata={
+                    "interval_type": self.interval_type,
+                    "biosample_from_source_id": self.biosample_from_source_id,
+                    "resource_scores": [
+                        {"name": resource_score.name, "value": resource_score.value}
+                        for resource_score in self.resource_scores
+                    ],
+                    "quality_controls": list(self.quality_controls),
+                    "additional": dict(self.evidence_metadata),
+                },
+            ),
+            metadata={"source_schema": "opentargets.enhancer_to_gene.v1"},
+        )
+
+
+def _normalize_ontology_id(value: str | None) -> str | None:
+    if value is None:
+        return None
+    for prefix in ("CL_", "UBERON_", "EFO_"):
+        if value.startswith(prefix):
+            return value.replace("_", ":", 1)
+    return value
+
+
+def _biosample_namespace(value: str | None) -> str | None:
+    if value is None or ":" not in value:
+        return None
+    return value.split(":", 1)[0]
+
+
+def _required_string(row: Mapping[str, object], field_name: str) -> str:
+    value = row.get(field_name)
+    if not isinstance(value, str) or not value.strip():
+        msg = f"Open Targets {field_name} must be a non-empty string"
+        raise ValueError(msg)
+    return value
+
+
+def _optional_string(row: Mapping[str, object], field_name: str) -> str | None:
+    value = row.get(field_name)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        msg = f"Open Targets {field_name} must be a string or null"
+        raise TypeError(msg)
+    return value
+
+
+def _required_integer(row: Mapping[str, object], field_name: str) -> int:
+    value = row.get(field_name)
+    if isinstance(value, bool) or not isinstance(value, int):
+        msg = f"Open Targets {field_name} must be an integer"
+        raise TypeError(msg)
+    return value
+
+
+def _optional_integer(row: Mapping[str, object], field_name: str) -> int | None:
+    value = row.get(field_name)
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int):
+        msg = f"Open Targets {field_name} must be an integer or null"
+        raise TypeError(msg)
+    return value
+
+
+def _optional_number(row: Mapping[str, object], field_name: str) -> float | None:
+    value = row.get(field_name)
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        msg = f"Open Targets {field_name} must be numeric or null"
+        raise TypeError(msg)
+    return float(value)
+
+
+def _resource_scores(value: object) -> tuple[OpenTargetsResourceScore, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, (str, bytes)) or not isinstance(value, Sequence):
+        msg = "Open Targets resourceScore must be a sequence or null"
+        raise TypeError(msg)
+    scores = []
+    for item in value:
+        if not isinstance(item, Mapping):
+            msg = "Open Targets resourceScore entries must be mappings"
+            raise TypeError(msg)
+        scores.append(
+            OpenTargetsResourceScore(
+                name=_required_string(item, "name"),
+                value=_optional_number(item, "value"),
+            )
+        )
+    return tuple(scores)
+
+
+def _string_sequence(value: object, *, field_name: str) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, (str, bytes)) or not isinstance(value, Sequence):
+        msg = f"Open Targets {field_name} must be a sequence or null"
+        raise TypeError(msg)
+    if not all(isinstance(item, str) for item in value):
+        msg = f"Open Targets {field_name} entries must be strings"
+        raise TypeError(msg)
+    return tuple(value)

altar_opentargets_e2g-0.1.0/altar_opentargets_e2g/source.py

@@ -0,0 +1,61 @@
+# Copyright 2026 Riya Sinha
+"""Open Targets E2G source over Altar's generic canonical evidence store."""
+
+from __future__ import annotations
+from dataclasses import replace
+from importlib.metadata import PackageNotFoundError, version
+
+from altar.sources import (
+    StoredVariantGeneLinkSource,
+    VariantGeneEvidenceRecord,
+    VariantGeneLink,
+    VariantGeneLinkDatasetRef,
+    VariantGeneLinkStore,
+    VariantLocus,
+)
+
+from altar_opentargets_e2g.schema import OPEN_TARGETS_E2G_DATASET
+
+
+try:
+    _BINDING_VERSION = version("altar-opentargets-e2g")
+except PackageNotFoundError:  # pragma: no cover - editable installs provide package metadata
+    _BINDING_VERSION = "0.1.0"
+
+
+class OpenTargetsE2GSource(StoredVariantGeneLinkSource):
+    """Query normalized Open Targets evidence from any compliant link store."""
+
+    name = "opentargets_e2g"
+    binding_id = "org.kundajelab.bindings.opentargets-e2g"
+    binding_version = _BINDING_VERSION
+
+    def __init__(
+        self,
+        store: VariantGeneLinkStore,
+        dataset: VariantGeneLinkDatasetRef = OPEN_TARGETS_E2G_DATASET,
+    ) -> None:
+        super().__init__(
+            store,
+            dataset,
+            name=self.name,
+            binding_id=self.binding_id,
+            binding_version=self.binding_version,
+            failure_label="Open Targets E2G store",
+        )
+
+    def decode_record(self, record: VariantGeneEvidenceRecord, locus: VariantLocus) -> VariantGeneLink:
+        """Restore stable tuple shapes used by the binding's public provenance metadata."""
+        link = record.to_link(locus)
+        metadata = dict(link.provenance.metadata)
+        resource_scores = metadata.get("resource_scores")
+        quality_controls = metadata.get("quality_controls")
+        if not isinstance(resource_scores, list) or not all(isinstance(value, dict) for value in resource_scores):
+            msg = f"record {record.record_id!r} has invalid resource_scores metadata"
+            raise TypeError(msg)
+        if not isinstance(quality_controls, list) or not all(isinstance(value, str) for value in quality_controls):
+            msg = f"record {record.record_id!r} has invalid quality_controls metadata"
+            raise TypeError(msg)
+        metadata["resource_scores"] = tuple(resource_scores)
+        metadata["quality_controls"] = tuple(quality_controls)
+        return replace(link, provenance=replace(link.provenance, metadata=metadata))

altar_opentargets_e2g-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "altar-opentargets-e2g"
+version = "0.1.0"
+description = "Open Targets ENCODE-rE2G binding for Altar's variant-gene link contract"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "Riya Sinha" }]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Typing :: Typed",
+]
+dependencies = ["altar>=0.1,<0.2"]
+
+[project.urls]
+Documentation = "https://kundajelab.github.io/altar/"
+Issues = "https://github.com/kundajelab/altar/issues"
+Repository = "https://github.com/kundajelab/altar"
+
+[project.entry-points."altar.variant_gene_link_sources"]
+opentargets_e2g = "altar_opentargets_e2g:OpenTargetsE2GSource"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["altar_opentargets_e2g"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+ignore_missing_imports = true

altar_opentargets_e2g-0.1.0/tests/fixtures/opentargets_e2g_links.json

@@ -0,0 +1,98 @@
+[
+  {
+    "interval_id": "ot-001",
+    "chromosome": "chr7",
+    "start": 140753330,
+    "end": 140753350,
+    "gene_id": "ENSG00000157764",
+    "gene_symbol": "BRAF",
+    "score": 0.81,
+    "biosample_name": "T cell",
+    "biosample_id": "CL_0000084",
+    "interval_type": "enhancer",
+    "distance_to_tss": 3200,
+    "datasource_id": "E2G",
+    "pmid": "38014075",
+    "study_id": "ENCODE-rE2G-T-cell"
+  },
+  {
+    "interval_id": "ot-002",
+    "chromosome": "7",
+    "start": 140753330,
+    "end": 140753350,
+    "gene_id": "ENSG00000146648",
+    "gene_symbol": "EGFR",
+    "score": 0.72,
+    "biosample_name": "T cell",
+    "biosample_id": "CL_0000084",
+    "interval_type": "enhancer",
+    "distance_to_tss": 4100,
+    "datasource_id": "E2G",
+    "pmid": "38014075",
+    "study_id": "ENCODE-rE2G-T-cell"
+  },
+  {
+    "interval_id": "ot-003",
+    "chromosome": "7",
+    "start": 140753330,
+    "end": 140753350,
+    "gene_id": "ENSG00000157764",
+    "gene_symbol": "BRAF",
+    "score": 0.64,
+    "biosample_name": "liver",
+    "biosample_id": "UBERON_0002107",
+    "interval_type": "enhancer",
+    "distance_to_tss": 3200,
+    "datasource_id": "E2G",
+    "pmid": "38014075",
+    "study_id": "ENCODE-rE2G-liver"
+  },
+  {
+    "interval_id": "ot-004",
+    "chromosome": "7",
+    "start": 140753335,
+    "end": 140753345,
+    "gene_id": "ENSG00000157764",
+    "gene_symbol": "BRAF",
+    "score": 0.0,
+    "biosample_name": "T cell",
+    "biosample_id": "CL_0000084",
+    "interval_type": "enhancer",
+    "distance_to_tss": 3195,
+    "datasource_id": "E2G",
+    "pmid": null,
+    "study_id": "fixture-zero-score"
+  },
+  {
+    "interval_id": "ot-005",
+    "chromosome": "7",
+    "start": 140753335,
+    "end": 140753345,
+    "gene_id": "ENSG00000157764",
+    "gene_symbol": "BRAF",
+    "score": null,
+    "biosample_name": "T cell",
+    "biosample_id": "CL_0000084",
+    "interval_type": "enhancer",
+    "distance_to_tss": null,
+    "datasource_id": "E2G",
+    "pmid": null,
+    "study_id": "fixture-missing-score"
+  },
+  {
+    "interval_id": "ot-006",
+    "chromosome": "7",
+    "start": 140800000,
+    "end": 140800100,
+    "gene_id": "ENSG00000157764",
+    "gene_symbol": "BRAF",
+    "score": 0.9,
+    "biosample_name": "T cell",
+    "biosample_id": "CL_0000084",
+    "interval_type": "enhancer",
+    "distance_to_tss": 100,
+    "datasource_id": "E2G",
+    "pmid": "38014075",
+    "study_id": "non-overlapping"
+  }
+]

altar_opentargets_e2g-0.1.0/tests/test_source.py

@@ -0,0 +1,335 @@
+# Copyright 2026 Riya Sinha
+# Assertions are the pytest API; fixed-size fixture expectations are intentional.
+# ruff: noqa: PLR2004
+from __future__ import annotations
+import json
+from dataclasses import replace
+from importlib.metadata import version
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+from altar.sources import (
+    GenomeBuild,
+    GenomeBuildMismatchError,
+    GenomicInterval,
+    InMemoryVariantGeneLinkStore,
+    InvalidCursorError,
+    SqliteVariantGeneLinkStore,
+    VariantGeneLinkQuery,
+    VariantGeneLinkStore,
+    VariantLocus,
+    get_variant_gene_link_source_registry,
+)
+from altar.testing import VariantGeneLinkSourceContract
+from altar_opentargets_e2g import (
+    OPEN_TARGETS_E2G_DATASET,
+    OpenTargetsE2GImportConfig,
+    OpenTargetsE2GImporter,
+    OpenTargetsE2GRow,
+    OpenTargetsE2GSource,
+    OpenTargetsResourceScore,
+)
+
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Iterator
+
+
+FIXTURE_PATH = Path(__file__).parent / "fixtures" / "opentargets_e2g_links.json"
+KNOWN_IDS = tuple(f"opentargets:25.12:ot-00{number}" for number in range(1, 6))
+
+
+@pytest.fixture
+def fixture_rows() -> list[OpenTargetsE2GRow]:
+    values = json.loads(FIXTURE_PATH.read_text())
+    return [OpenTargetsE2GRow(**value) for value in values]
+
+
+def _config(**changes: object) -> OpenTargetsE2GImportConfig:
+    config = OpenTargetsE2GImportConfig(
+        data_release="25.12",
+        dataset_url="https://ftp.ebi.ac.uk/pub/databases/opentargets/platform/25.12/output/enhancer_to_gene",
+    )
+    return replace(config, **changes)
+
+
+@pytest.fixture(params=("memory", "sqlite"))
+async def store(
+    request: pytest.FixtureRequest,
+    tmp_path: Path,
+    fixture_rows: list[OpenTargetsE2GRow],
+) -> AsyncIterator[VariantGeneLinkStore]:
+    if request.param == "memory":
+        backend = InMemoryVariantGeneLinkStore()
+        await OpenTargetsE2GImporter(backend, batch_size=2).ingest(
+            fixture_rows,
+            _config(),
+            generation_id="25.12-fixture",
+        )
+        yield backend
+        return
+    backend = SqliteVariantGeneLinkStore(tmp_path / "opentargets.sqlite")
+    await OpenTargetsE2GImporter(backend, batch_size=2).ingest(
+        fixture_rows,
+        _config(),
+        generation_id="25.12-fixture",
+    )
+    try:
+        yield backend
+    finally:
+        backend.close()
+
+
+@pytest.fixture
+def known_query() -> VariantGeneLinkQuery:
+    return VariantGeneLinkQuery(
+        locus=VariantLocus.from_vcf(
+            chromosome="chr7",
+            position=140753336,
+            reference_allele="A",
+            alternate_allele="T",
+            genome_build=GenomeBuild.GRCH38,
+        ),
+        page_size=2,
+    )
+
+
+@pytest.fixture
+def empty_query() -> VariantGeneLinkQuery:
+    return VariantGeneLinkQuery(
+        locus=VariantLocus(
+            interval=GenomicInterval(
+                chromosome="7",
+                start=1,
+                end=2,
+                genome_build=GenomeBuild.GRCH38,
+            )
+        )
+    )
+
+
+@pytest.fixture
+def source(store: VariantGeneLinkStore) -> OpenTargetsE2GSource:
+    return OpenTargetsE2GSource(store)
+
+
+class TestOpenTargetsE2GSourceConformance(VariantGeneLinkSourceContract):
+    @pytest.fixture
+    def source(self, source: OpenTargetsE2GSource) -> OpenTargetsE2GSource:
+        return source
+
+    @pytest.fixture
+    def known_query(self, known_query: VariantGeneLinkQuery) -> VariantGeneLinkQuery:
+        return known_query
+
+    @pytest.fixture
+    def expected_record_ids(self) -> tuple[str, ...]:
+        return KNOWN_IDS
+
+    @pytest.fixture
+    def empty_query(self, empty_query: VariantGeneLinkQuery) -> VariantGeneLinkQuery:
+        return empty_query
+
+
+def test_registry_and_distribution_identity() -> None:
+    registry = get_variant_gene_link_source_registry()
+    assert registry.get("opentargets_e2g") is OpenTargetsE2GSource
+    assert OpenTargetsE2GSource.binding_version == version("altar-opentargets-e2g")
+
+
+async def test_one_element_can_link_multiple_genes_and_contexts(
+    source: OpenTargetsE2GSource, known_query: VariantGeneLinkQuery
+) -> None:
+    links = [link async for link in source.stream_links(known_query)]
+    shared = [
+        link
+        for link in links
+        if link.regulatory_element is not None and link.regulatory_element.id.endswith("140753330-140753350")
+    ]
+    assert {link.target_gene.symbol for link in shared} == {"BRAF", "EGFR"}
+    assert {link.context.name for link in shared if link.context is not None} == {"T cell", "liver"}
+    assert len(shared) == 3
+
+
+async def test_normalized_filters_and_pagination(
+    source: OpenTargetsE2GSource, known_query: VariantGeneLinkQuery
+) -> None:
+    filtered = replace(known_query, context_ids=("CL:0000084",), source_ids=("E2G",), page_size=1)
+    links = [link async for link in source.stream_links(filtered)]
+    assert [link.record_id for link in links] == [KNOWN_IDS[0], KNOWN_IDS[1], KNOWN_IDS[3], KNOWN_IDS[4]]
+    assert all(link.context is not None and link.context.id == "CL:0000084" for link in links)
+
+    union_filtered = replace(
+        known_query,
+        context_ids=("not-present",),
+        context_names=("liver",),
+        data_releases=("25.12",),
+    )
+    union_links = [link async for link in source.stream_links(union_filtered)]
+    assert [link.record_id for link in union_links] == [KNOWN_IDS[2]]
+
+
+async def test_missing_score_is_not_zero(source: OpenTargetsE2GSource, known_query: VariantGeneLinkQuery) -> None:
+    links = {link.record_id: link async for link in source.stream_links(known_query)}
+    assert links[KNOWN_IDS[3]].score.value == 0.0
+    assert links[KNOWN_IDS[4]].score.value is None
+
+
+def test_missing_biosample_context_is_preserved_as_missing(fixture_rows: list[OpenTargetsE2GRow]) -> None:
+    row = replace(fixture_rows[0], biosample_name=None, biosample_id=None)
+    assert row.to_evidence_record(_config()).context is None
+
+
+@pytest.mark.parametrize("store_kind", ["memory", "sqlite"])
+async def test_upstream_evidence_fields_survive_both_stores(
+    store_kind: str,
+    tmp_path: Path,
+    fixture_rows: list[OpenTargetsE2GRow],
+    known_query: VariantGeneLinkQuery,
+) -> None:
+    row = replace(
+        fixture_rows[0],
+        biosample_from_source_id="source-cell-1",
+        resource_scores=(OpenTargetsResourceScore(name="DNase", value=0.4),),
+        quality_controls=("fixture-qc",),
+        evidence_metadata={"partition": "part-0001"},
+    )
+    backend: VariantGeneLinkStore
+    if store_kind == "memory":
+        backend = InMemoryVariantGeneLinkStore()
+    else:
+        backend = SqliteVariantGeneLinkStore(tmp_path / "metadata.sqlite")
+    try:
+        await OpenTargetsE2GImporter(backend).ingest([row], _config(), generation_id="metadata")
+        link = (await OpenTargetsE2GSource(backend).query_links(known_query)).links[0]
+        assert link.provenance.metadata == {
+            "interval_type": "enhancer",
+            "biosample_from_source_id": "source-cell-1",
+            "resource_scores": ({"name": "DNase", "value": 0.4},),
+            "quality_controls": ("fixture-qc",),
+            "additional": {"partition": "part-0001"},
+            "import_generation_id": "metadata",
+        }
+    finally:
+        if isinstance(backend, SqliteVariantGeneLinkStore):
+            backend.close()
+
+
+async def test_import_is_bounded_idempotent_and_published_atomically(
+    fixture_rows: list[OpenTargetsE2GRow], known_query: VariantGeneLinkQuery
+) -> None:
+    backend = InMemoryVariantGeneLinkStore()
+    importer = OpenTargetsE2GImporter(backend, batch_size=1)
+
+    def failing_rows() -> Iterator[OpenTargetsE2GRow]:
+        yield fixture_rows[0]
+        yield replace(fixture_rows[1], interval_id="")
+
+    with pytest.raises(ValueError, match="interval_id"):
+        await importer.ingest(failing_rows(), _config(), generation_id="failed")
+    assert (await OpenTargetsE2GSource(backend).query_links(known_query)).links == ()
+
+    first = await importer.ingest(fixture_rows, _config(), generation_id="failed")
+    repeated = await importer.ingest(fixture_rows, _config(), generation_id="failed")
+    assert first.processed_rows == len(fixture_rows)
+    assert first.added_records == len(fixture_rows) - 1
+    assert first.skipped_records == 1
+    assert repeated.added_records == 0
+    assert repeated.skipped_records == len(fixture_rows)
+    assert await backend.generation_size(OPEN_TARGETS_E2G_DATASET, "failed") == len(fixture_rows)
+
+
+def test_official_parquet_mapping_is_parsed_without_a_storage_dependency() -> None:
+    row = OpenTargetsE2GRow.from_source_mapping(
+        {
+            "chromosome": "7",
+            "start": 140753330,
+            "end": 140753350,
+            "geneId": "ENSG00000157764",
+            "score": 0.81,
+            "distanceToTss": 3200,
+            "resourceScore": [{"name": "DNase", "value": 0.4}],
+            "datasourceId": "E2G",
+            "intervalType": "enhancer",
+            "pmid": "38014075",
+            "biosampleName": "T cell",
+            "biosampleFromSourceId": None,
+            "biosampleId": "CL_0000084",
+            "studyId": "ENCODE-rE2G-T-cell",
+            "intervalId": "ot-001",
+            "qualityControls": [],
+            "futureField": {"retained": True},
+        }
+    )
+    assert row.resource_scores == (OpenTargetsResourceScore(name="DNase", value=0.4),)
+    assert row.evidence_metadata == {"futureField": {"retained": True}}
+
+
+def test_official_mapping_rejects_malformed_required_fields() -> None:
+    with pytest.raises(ValueError, match="geneId"):
+        OpenTargetsE2GRow.from_source_mapping(
+            {
+                "chromosome": "7",
+                "start": 1,
+                "end": 2,
+                "geneId": None,
+                "datasourceId": "E2G",
+                "intervalType": "enhancer",
+                "intervalId": "bad",
+            }
+        )
+
+
+def test_release_threshold_semantics_are_explicit(fixture_rows: list[OpenTargetsE2GRow]) -> None:
+    record = fixture_rows[0].to_evidence_record(_config(score_threshold=0.6, threshold_applied=True))
+    assert record.score.threshold == 0.6
+    assert record.score.threshold_rule == "greater-than-or-equal"
+    assert record.score.threshold_applied is True
+
+    with pytest.raises(ValueError, match="threshold_applied"):
+        _config(score_threshold=0.6)
+
+
+async def test_empty_release_is_publishable_and_release_rows_are_retained(
+    fixture_rows: list[OpenTargetsE2GRow], known_query: VariantGeneLinkQuery
+) -> None:
+    backend = InMemoryVariantGeneLinkStore()
+    empty = await OpenTargetsE2GImporter(backend).ingest([], _config(), generation_id="empty")
+    await OpenTargetsE2GImporter(backend).ingest(
+        fixture_rows[:1],
+        _config(data_release="26.01"),
+        generation_id="26.01-fixture",
+    )
+    await OpenTargetsE2GImporter(backend).ingest(
+        fixture_rows[:1],
+        _config(),
+        generation_id="25.12-fixture",
+    )
+    assert empty.processed_rows == empty.added_records == empty.skipped_records == 0
+    links = [link async for link in OpenTargetsE2GSource(backend).stream_links(known_query)]
+    assert {link.data_release for link in links} == {"25.12", "26.01"}
+    selected = replace(known_query, data_releases=("26.01",))
+    assert [link.data_release async for link in OpenTargetsE2GSource(backend).stream_links(selected)] == ["26.01"]
+
+
+async def test_build_mismatch_is_a_query_error(source: OpenTargetsE2GSource, known_query: VariantGeneLinkQuery) -> None:
+    mismatched = replace(
+        known_query,
+        locus=replace(
+            known_query.locus,
+            interval=replace(known_query.locus.interval, genome_build=GenomeBuild.GRCH37),
+        ),
+    )
+    with pytest.raises(GenomeBuildMismatchError, match="liftover must be explicit"):
+        await source.query_links(mismatched)
+
+
+async def test_cursor_is_bound_to_locus_and_filters(
+    source: OpenTargetsE2GSource, known_query: VariantGeneLinkQuery
+) -> None:
+    page = await source.query_links(replace(known_query, page_size=1))
+    assert page.next_cursor is not None
+    changed = replace(known_query, page_size=1, context_names=("liver",), cursor=page.next_cursor)
+    with pytest.raises(InvalidCursorError, match="does not belong"):
+        await source.query_links(changed)