geneharmony 0.3.0__py3-none-any.whl

geneharmony/__init__.py

@@ -0,0 +1,17 @@
+"""
+geneharmony — async toolkit to normalize gene identifiers and annotate gene sets.
+Resolves symbols/IDs against the Alliance of Genome Resources (AGR) and annotates with data from AGR or user-ingested datasets.
+"""
+__version__ = "0.3.0"
+
+from .annotator import Annotator
+from .datasets import AGRDataset
+from .taxa import TaxonField, taxon_mapper, resolve_taxon
+
+__all__ = [
+    "Annotator",
+    "AGRDataset",
+    "TaxonField",
+    "taxon_mapper",
+    "resolve_taxon",
+]

geneharmony/annotator.py

@@ -0,0 +1,356 @@
+"""User-facing entry point: bulk download, per-gene API, and annotate.
+
+`Annotator` ties the lower-level pieces (`AGRClient`, `Downloader`, the gene
+index, the dataset registry) into one object over a resolved cache directory. The
+intended use is an iterative *filter-then-requery* traversal — one primary AGR
+dataset per `annotate` call — so cardinality stays under the caller's control:
+
+    ann = Annotator()
+    orth = await ann.annotate(["TP53", "BRCA1"], AGRDataset.ORTHOLOGY, taxon="human")
+    mouse = orth.loc[orth.Gene2SpeciesTaxonID == "NCBITaxon:10090", "Gene2ID"].unique()
+    pheno = await ann.annotate(list(mouse), AGRDataset.PHENOTYPES, taxon="mouse")
+
+`annotate` wide-left-joins each source onto the normalized base frame in order:
+an AGR dataset contributes its native columns; an ingested external annotation
+(referenced by name) contributes columns prefixed with `name.`.
+"""
+
+import asyncio
+import math
+import os
+from contextlib import AsyncExitStack
+from pathlib import Path
+from typing import Final
+import pandas as pd
+
+from .client import AGRClient
+from .datasets import DATASETS, AGRDataset, ApiSpec, BulkSpec
+from .downloader import Downloader
+from .ingest import load_tsv_gz
+from .models import DownloadFile
+from .normalizer import GeneIndex, build_gene_index
+from .taxa import resolve_taxon
+from .store import read_parquet, write_parquet
+
+type Genes = str | list[str] | pd.DataFrame
+
+_APP_DIR: Final = "geneharmony"
+_GENE_ID: Final = "GeneId"
+_PAGE_SIZE: Final = 500
+
+
+def default_cache_dir() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME")
+    root = Path(base) if base else Path.home() / ".cache"
+    return root / _APP_DIR
+
+
+def resolve_cache_dir(cache_dir: Path | None) -> Path:
+    cache = cache_dir or default_cache_dir()
+    cache.mkdir(parents=True, exist_ok=True)
+    return cache
+
+class Annotator:
+    def __init__(
+        self,
+        cache_dir: Path | None = None,
+        *,
+        client: AGRClient | None = None,
+        downloader: Downloader | None = None,
+    ) -> None:
+        self._cache = resolve_cache_dir(cache_dir)
+        self._client = client
+        self._downloader = downloader
+        self._index: GeneIndex | None = None
+
+    async def normalize(
+        self,
+        genes: str | list[str],
+        *,
+        taxon: str | None = None,
+        limit: int | None = 1,
+        case_insensitive: bool = False,
+    ) -> pd.DataFrame:
+        index = await self._gene_index()
+        return index.lookup(
+            genes,
+            taxon=taxon,
+            limit=limit,
+            case_insensitive=case_insensitive,
+        )
+
+    async def download(self, dataset: AGRDataset, *, refresh: bool = False) -> Path:
+        """Download a dataset's bulk file, convert TSV -> Parquet, drop the .tsv.gz."""
+        bulk = DATASETS[dataset].bulk
+        if bulk is None:
+            raise ValueError(f"{dataset!r} has no bulk file; query it via annotate()")
+        dest = self._cache / "bulk" / f"{dataset}.parquet"
+        if dest.exists() and not refresh:
+            return dest
+        async with AsyncExitStack() as stack:
+            client = self._client or await stack.enter_async_context(AGRClient())
+            downloader = self._downloader or await stack.enter_async_context(Downloader())
+            file = _select_download(await client.list_downloads(), bulk)
+            tmp = dest.with_name(f"{dest.stem}.tsv.gz")
+            await downloader.download(file.s3Url, tmp)
+            write_parquet(load_tsv_gz(tmp, dtype=str), dest)
+            tmp.unlink(missing_ok=True)
+        return dest
+
+    async def ingest_annotation(
+        self,
+        source: str | Path | pd.DataFrame,
+        name: str,
+        *,
+        gene_id_column: str | list[str],
+        normalize: bool = True,
+        taxon: str | None = None,
+        case_insensitive: bool = False,
+        override: bool = False,
+    ) -> tuple[dict, pd.DataFrame | None]:
+        """Store an external annotation table, keyed by canonical `GeneId`.
+
+        `gene_id_column` may name several columns; they are tried left-to-right
+        per row, the first identifier that resolves wins (a fallback for tables
+        whose primary ID column has gaps). The id columns are kept as-is and a
+        separate `GeneId` column is added for the resolved canonical id, so the
+        input must not already contain a `GeneId` column. The returned unmapped
+        frame holds the rows (with their original columns) where no candidate
+        resolved.
+        """
+        dest = self._cache / "external" / f"{name}.parquet"
+        if dest.exists() and not override:
+            return _ingest_summary(name, None, None, None, None), None
+
+        df = source.copy() if isinstance(source, pd.DataFrame) else _read_table(source)
+        columns = [gene_id_column] if isinstance(gene_id_column, str) else list(gene_id_column)
+        if not columns:
+            raise ValueError("gene_id_column must name at least one column")
+        missing = [c for c in columns if c not in df.columns]
+        if missing:
+            raise KeyError(
+                f"gene_id_column(s) {missing!r} not found; columns are {list(df.columns)}"
+            )
+        if _GENE_ID in df.columns:
+            raise ValueError(
+                f"input already has a {_GENE_ID!r} column; rename it — a separate "
+                f"{_GENE_ID!r} column is added for the resolved canonical id."
+            )
+
+        if normalize:
+            str_cols = df[columns].astype(str)
+            values = [v for v in pd.unique(str_cols.values.ravel()) if v != "nan"]
+            mapping = await self._id_map(values, taxon, case_insensitive)
+            resolved = str_cols.apply(lambda col: col.map(mapping)).bfill(axis=1).iloc[:, 0]
+        else:
+            resolved = df[columns].bfill(axis=1).iloc[:, 0]
+
+        df[_GENE_ID] = resolved
+
+        rows_in = len(df)
+        rows_dropped = 0
+        unmapped_df: pd.DataFrame | None = None
+        if normalize:
+            unmapped_mask = df[_GENE_ID].isna()
+            unmapped_df = df[unmapped_mask].copy()
+            rows_dropped = int(unmapped_mask.sum())
+            df = df[~unmapped_mask].reset_index(drop=True)
+
+        write_parquet(df, dest)
+        return _ingest_summary(name, rows_in, len(df), rows_dropped, normalize), unmapped_df
+
+    async def annotate(
+        self,
+        genes: Genes,
+        *sources: AGRDataset | str,
+        taxon: str | None = None,
+        limit: int | None = 1,
+        case_insensitive: bool = False,
+    ) -> pd.DataFrame:
+        if isinstance(genes, pd.DataFrame):
+            base = genes.copy()
+        else:
+            base = await self.normalize(
+                genes, taxon=taxon, limit=limit, case_insensitive=case_insensitive
+            )
+        if _GENE_ID not in base.columns:
+            raise KeyError(f"base frame has no {_GENE_ID!r} column to join on")
+
+        gene_ids = base[_GENE_ID].dropna().unique().tolist()
+        out = base
+        for source in sources:
+            if isinstance(source, AGRDataset):
+                frame, key = await self._load_agr_source(source, gene_ids)
+            else:
+                frame, key = self._load_external(source)
+            frame[f'has.{source}'] = True
+            out = out.merge(frame, how="left", left_on=_GENE_ID, right_on=key)
+            out[f'has.{source}'] = out[f'has.{source}'].fillna(False)
+        return out.reset_index(drop=True)
+    
+    async def get_orthologs(
+        self, 
+        genes: Genes,
+        taxon: str | None = None,
+        target_taxon: str | None = None,
+        limit: int | None = 1,
+        case_insensitive: bool = False
+    ) -> pd.DataFrame:
+        """Convenience method to get orthologs for a set of genes."""
+        df = await self.annotate(
+            genes,
+            AGRDataset.ORTHOLOGY,
+            taxon=taxon,
+            limit=limit,
+            case_insensitive=case_insensitive,
+        )
+        if target_taxon:
+            df = df[df["Gene2SpeciesTaxonID"] == resolve_taxon(target_taxon).id]
+            
+        return df[["query", "match_kind", "Gene2ID", "Gene2Symbol", "Gene2SpeciesTaxonID"]]
+        
+
+    async def _gene_index(self) -> GeneIndex:
+        """Lazily build the gene index, caching it for the Annotator's lifetime.
+
+        The `GENE` bulk file is downloaded and converted to `bulk/gene.parquet`
+        like any other dataset; the index is then built from it in memory.
+        """
+        if self._index is None:
+            path = await self.download(AGRDataset.GENE)
+            self._index = build_gene_index(read_parquet(path))
+        return self._index
+
+    async def _id_map(
+        self, queries: list[str], taxon: str | None, case_insensitive: bool = False
+    ) -> dict[str, str]:
+        index = await self._gene_index()
+        unique = list(dict.fromkeys(queries))
+        df = index.lookup(unique, taxon=taxon, limit=1, case_insensitive=case_insensitive)
+        df = df[df["match_kind"].notna()]
+        return dict(zip(df["query"], df[_GENE_ID]))
+
+    async def _load_agr_source(
+        self, dataset: AGRDataset, gene_ids: list[str]
+    ) -> tuple[pd.DataFrame, str]:
+        spec = DATASETS[dataset]
+        if spec.bulk is not None:
+            path = self._cache / "bulk" / f"{dataset}.parquet"
+            if not path.exists():
+                await self.download(dataset)
+            frame = read_parquet(path)
+            key = spec.bulk.join_key
+            return frame[frame[key].isin(set(gene_ids))].reset_index(drop=True), key
+        assert spec.api is not None
+        return await self._fetch_api(dataset, spec.api, gene_ids), spec.api.join_key
+
+    async def _fetch_api(
+        self, dataset: AGRDataset, api: ApiSpec, gene_ids: list[str]
+    ) -> pd.DataFrame:
+        api_dir = self._cache / "api" / dataset
+        cached = [g for g in gene_ids if (api_dir / f"{_safe(g)}.parquet").exists()]
+        missing = [g for g in gene_ids if g not in set(cached)]
+
+        frames = [read_parquet(api_dir / f"{_safe(g)}.parquet") for g in cached]
+        if missing:
+            async with AsyncExitStack() as stack:
+                client = self._client or await stack.enter_async_context(AGRClient())
+                frames.extend(
+                    await asyncio.gather(
+                        *[self._fetch_one(client, api, g, api_dir) for g in missing]
+                    )
+                )
+        if not frames:
+            return pd.DataFrame(columns=[api.join_key])
+        return pd.concat(frames, ignore_index=True)
+
+    async def _fetch_one(
+        self, client: AGRClient, api: ApiSpec, gene_id: str, api_dir: Path
+    ) -> pd.DataFrame:
+        results = await _fetch_all_pages(client, api.endpoint.format(gene_id=gene_id))
+        rows = [api.project(gene_id, r) for r in results]
+        frame = pd.DataFrame(rows) if rows else pd.DataFrame(columns=[api.join_key])
+        write_parquet(frame, api_dir / f"{_safe(gene_id)}.parquet")
+        return frame
+
+    def _load_external(self, name: str) -> tuple[pd.DataFrame, str]:
+        path = self._cache / "external" / f"{name}.parquet"
+        if not path.exists():
+            raise KeyError(
+                f"unknown source {name!r}: not an AGRDataset or an ingested annotation"
+            )
+        frame = read_parquet(path)
+        frame = frame.rename(
+            columns={c: f"{name}.{c}" for c in frame.columns if c != _GENE_ID}
+        )
+        return frame, _GENE_ID
+
+
+def _select_download(files: list[DownloadFile], spec: BulkSpec) -> DownloadFile:
+    match = next(
+        (
+            f
+            for f in files
+            if f.dataType == spec.data_type
+            and f.fileType == spec.file_type
+            and f.dataSubType == spec.data_sub_type
+        ),
+        None,
+    )
+    if match is None:
+        raise LookupError(
+            f"no download matching {spec.data_type}/{spec.file_type}/{spec.data_sub_type}"
+        )
+    return match
+
+
+async def _fetch_all_pages(
+    client: AGRClient, endpoint: str, page_size: int = _PAGE_SIZE
+) -> list[dict]:
+    first = await client.get_json(endpoint, params={"limit": page_size, "page": 1})
+    results = list(first.get("results", []))
+    pages = math.ceil(first.get("total", len(results)) / page_size)
+    if pages > 1:
+        rest = await asyncio.gather(
+            *[
+                client.get_json(endpoint, params={"limit": page_size, "page": p})
+                for p in range(2, pages + 1)
+            ]
+        )
+        for page in rest:
+            results.extend(page.get("results", []))
+    return results
+
+
+def _safe(gene_id: str) -> str:
+    return gene_id.replace(":", "_").replace("/", "_")
+
+
+def _read_table(path: str | Path) -> pd.DataFrame:
+    suffix = Path(path).suffix.lower()
+    if suffix == ".parquet":
+        return pd.read_parquet(path)
+    if suffix in (".tsv", ".tab", ".txt"):
+        return pd.read_csv(path, sep="\t")
+    if suffix == ".csv":
+        return pd.read_csv(path)
+    raise ValueError(
+        f"unsupported annotation file type {suffix!r} for {path!r} "
+        "(expected .csv, .tsv/.tab/.txt, or .parquet)"
+    )
+
+
+def _ingest_summary(
+    name: str,
+    rows_in: int | None,
+    rows_stored: int | None,
+    rows_dropped: int | None,
+    normalized: bool | None,
+) -> dict:
+    return {
+        "annotation_name": name,
+        "rows_in": rows_in,
+        "rows_stored": rows_stored,
+        "rows_dropped_unmapped": rows_dropped,
+        "normalized": normalized,
+    }

geneharmony/client.py

@@ -0,0 +1,100 @@
+"""Async HTTP client for the Alliance of Genome Resources REST API.
+
+A single `AGRClient` owns one pooled `httpx.AsyncClient` and bounds in-flight
+requests with a semaphore. GETs retry transient failures (429/5xx, timeouts,
+transport errors) with exponential backoff and jitter, honoring `Retry-After`.
+"""
+
+import asyncio
+import random
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any, Final, Self
+
+import httpx
+from pydantic import TypeAdapter
+
+from .models import DownloadFile
+
+AGR_BASE_URL: Final = "https://www.alliancegenome.org/api"
+
+type Params = Mapping[str, str | int | bool]
+
+_RETRYABLE_STATUS: Final[frozenset[int]] = frozenset({429, 502, 503, 504})
+_DOWNLOADS_ADAPTER: Final = TypeAdapter(list[DownloadFile])
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    if value is None:
+        return None
+    if value.isdigit():
+        return float(value)
+    try:
+        retry_at = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    return max(0.0, (retry_at - datetime.now(timezone.utc)).total_seconds())
+
+
+class AGRClient:
+    def __init__(
+        self,
+        base_url: str = AGR_BASE_URL,
+        *,
+        max_concurrent: int = 5,
+        timeout: httpx.Timeout = httpx.Timeout(10.0, read=120.0),
+        max_retries: int = 4,
+        backoff_base: float = 0.5,
+        backoff_cap: float = 30.0,
+    ) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            timeout=timeout,
+            limits=httpx.Limits(max_connections=max_concurrent),
+        )
+        self._sem = asyncio.Semaphore(max_concurrent)
+        self._max_retries = max_retries
+        self._backoff_base = backoff_base
+        self._backoff_cap = backoff_cap
+
+    async def get_json(self, path: str, params: Params | None = None) -> Any:
+        return (await self._get(path, params)).json()
+
+    async def get_text(self, path: str, params: Params | None = None) -> str:
+        return (await self._get(path, params)).text
+
+    async def list_downloads(self) -> list[DownloadFile]:
+        return _DOWNLOADS_ADAPTER.validate_python(await self.get_json("/downloads"))
+
+    async def _get(self, path: str, params: Params | None) -> httpx.Response:
+        for attempt in range(self._max_retries + 1):
+            last = attempt == self._max_retries
+            try:
+                async with self._sem:
+                    response = await self._client.get(path, params=params)
+            except (httpx.TransportError, httpx.TimeoutException):
+                if last:
+                    raise
+                delay = self._backoff(attempt)
+            else:
+                if response.status_code not in _RETRYABLE_STATUS or last:
+                    response.raise_for_status()
+                    return response
+                delay = _parse_retry_after(response.headers.get("Retry-After"))
+                if delay is None:
+                    delay = self._backoff(attempt)
+            await asyncio.sleep(delay)
+        raise AssertionError("retry loop exited without returning")
+
+    def _backoff(self, attempt: int) -> float:
+        return random.uniform(0.0, min(self._backoff_cap, self._backoff_base * 2**attempt))
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        await self.aclose()

geneharmony/datasets.py

@@ -0,0 +1,107 @@
+"""Registry of AGR datasets the annotator can pull, with their backends.
+
+Each `AGRDataset` maps to a `DatasetSpec` describing how to obtain it:
+- `bulk` — a selector into the `/downloads` listing (matched at runtime, never a
+  hardcoded `s3Url`) plus the column its rows join on.
+- `api` — a per-gene endpoint template, the column its projected rows join on,
+  and a `project` callable flattening one API result into a single flat row.
+
+Orthology is served from its bulk TSV (complete, richly columned); phenotypes and
+alleles from the per-gene API (their bulk files are nested per-MOD JSON, deferred).
+The API orthology projection mirrors the bulk column names so either backend
+yields the same `Gene1ID`/`Gene2ID`/`Gene2SpeciesTaxonID` shape. `GENE` is the
+bulk file backing the in-memory gene index — downloaded through the same path,
+but built into a `GeneIndex` rather than joined onto a base frame.
+"""
+
+import enum
+from collections.abc import Callable
+from typing import Any, Final, NamedTuple
+
+type Json = dict[str, Any]
+type Projector = Callable[[str, Json], dict[str, Any]]
+
+
+class AGRDataset(enum.StrEnum):
+    GENE = "gene"
+    ORTHOLOGY = "orthology"
+    PHENOTYPES = "phenotypes"
+    ALLELES = "alleles"
+
+
+class BulkSpec(NamedTuple):
+    data_type: str
+    file_type: str
+    data_sub_type: str
+    join_key: str
+
+
+class ApiSpec(NamedTuple):
+    endpoint: str
+    join_key: str
+    project: Projector
+
+
+class DatasetSpec(NamedTuple):
+    bulk: BulkSpec | None
+    api: ApiSpec | None
+
+
+def _project_orthologs(gene_id: str, result: Json) -> dict[str, Any]:
+    g = result.get("geneToGeneOrthologyGenerated", {})
+    subject = g.get("subjectGene", {})
+    obj = g.get("objectGene", {})
+    return {
+        "Gene1ID": subject.get("primaryExternalId", gene_id),
+        "Gene1Symbol": subject.get("geneSymbol", {}).get("displayText"),
+        "Gene1SpeciesTaxonID": subject.get("taxon", {}).get("curie"),
+        "Gene2ID": obj.get("primaryExternalId"),
+        "Gene2Symbol": obj.get("geneSymbol", {}).get("displayText"),
+        "Gene2SpeciesTaxonID": obj.get("taxon", {}).get("curie"),
+        "Gene2SpeciesName": obj.get("taxon", {}).get("name"),
+        "Confidence": g.get("confidence", {}).get("name"),
+        "IsBestScore": g.get("isBestScore", {}).get("name"),
+        "IsBestRevScore": g.get("isBestScoreReverse", {}).get("name"),
+    }
+
+
+def _project_phenotypes(gene_id: str, result: Json) -> dict[str, Any]:
+    return {
+        "gene_id": gene_id,
+        "phenotypeStatement": result.get("phenotypeStatement"),
+        "references": "|".join(result.get("pubmedPubModIDs") or []),
+    }
+
+
+def _project_alleles(gene_id: str, result: Json) -> dict[str, Any]:
+    variants = result.get("variantList") or []
+    variant = variants[0] if variants else {}
+    return {
+        "gene_id": gene_id,
+        "allele_id": (result.get("allele") or {}).get("curie"),
+        "symbol": result.get("symbol"),
+        "alterationType": result.get("alterationType"),
+        "hasPhenotype": result.get("hasPhenotype", False),
+        "hasDisease": result.get("hasDisease", False),
+        "variantType": (variant.get("variantType") or {}).get("name"),
+    }
+
+
+DATASETS: Final[dict[AGRDataset, DatasetSpec]] = {
+    AGRDataset.GENE: DatasetSpec(
+        bulk=BulkSpec("GENE", "TSV", "COMBINED", "GeneId"),
+        api=None,
+    ),
+    AGRDataset.ORTHOLOGY: DatasetSpec(
+        bulk=BulkSpec("ORTHOLOGY-ALLIANCE", "TSV", "COMBINED", "Gene1ID"),
+        api=ApiSpec("/gene/{gene_id}/orthologs", "Gene1ID", _project_orthologs),
+    ),
+    AGRDataset.PHENOTYPES: DatasetSpec(
+        bulk=None,
+        api=ApiSpec("/gene/{gene_id}/phenotypes", "gene_id", _project_phenotypes),
+    ),
+    AGRDataset.ALLELES: DatasetSpec(
+        bulk=None,
+        api=ApiSpec("/gene/{gene_id}/alleles", "gene_id", _project_alleles),
+    ),
+}

geneharmony/downloader.py

@@ -0,0 +1,96 @@
+"""Streaming file downloader for arbitrary HTTP(S) URLs.
+
+`Downloader` fetches a file from any absolute URL, streaming it to disk via an
+atomic temp-then-rename write; an existing file whose byte size already matches
+the expected size is left untouched. Bytes are written verbatim — compressed
+files stay compressed on disk and are inflated downstream at ingest. It is not
+tied to any particular host or data provider.
+"""
+
+import asyncio
+import os
+import random
+from pathlib import Path
+from typing import Final, Self
+import httpx
+
+_CHUNK_SIZE: Final = 1 << 20
+_RETRYABLE_STATUS: Final[frozenset[int]] = frozenset({429, 500, 502, 503, 504})
+
+
+class SizeMismatchError(RuntimeError):
+    def __init__(self, url: str, expected: int, actual: int) -> None:
+        super().__init__(f"{url}: expected {expected} bytes, got {actual}")
+        self.url = url
+        self.expected = expected
+        self.actual = actual
+
+
+class Downloader:
+    def __init__(
+        self,
+        *,
+        max_concurrent: int = 3,
+        timeout: httpx.Timeout = httpx.Timeout(10.0, read=None),
+        max_retries: int = 3,
+        backoff_base: float = 0.5,
+        backoff_cap: float = 30.0,
+    ) -> None:
+        self._client = httpx.AsyncClient(
+            follow_redirects=True,
+            timeout=timeout,
+            limits=httpx.Limits(max_connections=max_concurrent),
+        )
+        self._sem = asyncio.Semaphore(max_concurrent)
+        self._max_retries = max_retries
+        self._backoff_base = backoff_base
+        self._backoff_cap = backoff_cap
+
+    async def download(
+        self, url: str, dest: Path, *, expected_size: int | None = None
+    ) -> Path:
+        if dest.exists() and (expected_size is None or dest.stat().st_size == expected_size):
+            return dest
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        tmp = dest.with_name(dest.name + ".part")
+        for attempt in range(self._max_retries + 1):
+            last = attempt == self._max_retries
+            try:
+                size = await self._stream_to(url, tmp)
+            except (httpx.TransportError, httpx.TimeoutException):
+                if last:
+                    raise
+            except httpx.HTTPStatusError as exc:
+                if last or exc.response.status_code not in _RETRYABLE_STATUS:
+                    raise
+            else:
+                if expected_size is not None and size != expected_size:
+                    tmp.unlink(missing_ok=True)
+                    raise SizeMismatchError(url, expected_size, size)
+                os.replace(tmp, dest)
+                return dest
+            await asyncio.sleep(self._backoff(attempt))
+        raise AssertionError("retry loop exited without returning")
+
+    async def _stream_to(self, url: str, tmp: Path) -> int:
+        async with self._sem, self._client.stream("GET", url) as response:
+            if response.is_error:
+                await response.aread()
+            response.raise_for_status()
+            written = 0
+            with tmp.open("wb") as f:
+                async for chunk in response.aiter_bytes(_CHUNK_SIZE):
+                    written += f.write(chunk)
+        return written
+
+    def _backoff(self, attempt: int) -> float:
+        return random.uniform(0.0, min(self._backoff_cap, self._backoff_base * 2**attempt))
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        await self.aclose()

geneharmony/ingest.py

@@ -0,0 +1,22 @@
+"""Decompress and parse cached AGR bulk download files.
+
+Bulk files are stored gzipped (`.json.gz` / `.tsv.gz`). These helpers read
+straight from the compressed file into memory — JSON into the parsed object,
+TSV into a DataFrame — so no decompressed copy is written to disk. AGR TSV files
+carry a leading block of `#` comment lines before the header, which is skipped.
+"""
+
+import gzip
+import json
+from pathlib import Path
+from typing import Any
+import pandas as pd
+
+
+def load_json_gz(path: Path) -> Any:
+    with gzip.open(path, "rt", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def load_tsv_gz(path: Path, dtype: type[str] | None = None) -> pd.DataFrame:
+    return pd.read_csv(path, sep="\t", comment="#", compression="gzip", dtype=dtype)

geneharmony/models.py

@@ -0,0 +1,15 @@
+from datetime import datetime
+from pydantic import BaseModel, PositiveInt
+
+class DownloadFile(BaseModel):
+    filename: str
+    s3Path: str
+    s3Url: str
+    stableURL: str
+    releaseVersion: str
+    size: PositiveInt
+    lastModified: datetime
+    dataType: str
+    fileType: str
+    dataSubType: str
+    fileExtension: str

geneharmony/normalizer.py

@@ -0,0 +1,190 @@
+"""In-memory gene normalizer built from the GENE-TSV-COMBINED bulk file.
+
+`load_gene_index` reads the file and precomputes O(1) lookups from every
+identifier form — primary ID, deprecated (secondary) ID, official symbol,
+synonym, systematic name and external cross-reference (e.g. `NCBI_Gene:`,
+`ENSEMBL:`, `UniProtKB:`) — to row positions in the loaded table.
+
+`GeneIndex.lookup` takes one query or a list and returns a DataFrame with one
+row per match: the original `query`, the `match_kind`, and every column of the
+matched gene record. Matches are ranked by precedence (primary ID > secondary ID
+> official symbol > synonym > cross-reference); `limit` caps matches per query and `taxon` narrows
+symbols that recur across species. Unmatched queries are still returned, with a
+null `match_kind`. Matching is case-sensitive unless `case_insensitive=True`,
+since case can be meaningful across species (human TP53 vs mouse Trp53).
+"""
+
+import enum
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final, NamedTuple
+import pandas as pd
+
+from .ingest import load_tsv_gz
+from .taxa import resolve_taxon
+
+type _Tables = dict["MatchKind", dict[str, list[int]]]
+
+# Cross-reference databases whose IDs denote protein families / enzyme classes
+# rather than genes; one such token fans out to hundreds of genes, so they are
+# excluded from the index. Keys are the token prefix before the first ':'.
+_XREF_EXCLUDED_PREFIXES: Final[frozenset[str]] = frozenset(
+    {"PANTHER", "TreeFam", "ExPASy", "TCDB"}
+)
+
+
+class MatchKind(enum.IntEnum):
+    PRIMARY_ID = 0
+    SECONDARY_ID = 1
+    OFFICIAL_SYMBOL = 2
+    SYNONYM = 3
+    CROSS_REFERENCE = 4
+
+
+class GeneMatch(NamedTuple):
+    row: int
+    kind: MatchKind
+
+
+@dataclass(slots=True)
+class GeneIndex:
+    records: pd.DataFrame
+    _taxon_ids: tuple[str, ...]
+    _exact: _Tables
+    _folded: _Tables | None = None
+
+    def lookup(
+        self,
+        queries: str | list[str],
+        *,
+        taxon: str | None = None,
+        limit: int | None = 1,
+        case_insensitive: bool = False,
+    ) -> pd.DataFrame:
+        if isinstance(queries, str):
+            queries = [queries]
+        taxon_id = resolve_taxon(taxon).id if taxon is not None else None
+
+        order: list[int] = []
+        query_col: list[str] = []
+        kind_col: list[str] = []
+        rows: list[int] = []
+        miss_order: list[int] = []
+        miss_query: list[str] = []
+
+        for i, query in enumerate(queries):
+            matches = self._resolve(query, taxon_id, case_insensitive)
+            if limit is not None:
+                matches = matches[:limit]
+            if matches:
+                for match in matches:
+                    order.append(i)
+                    query_col.append(query)
+                    kind_col.append(match.kind.name)
+                    rows.append(match.row)
+            else:
+                miss_order.append(i)
+                miss_query.append(query)
+
+        matched = self.records.iloc[rows].reset_index(drop=True)
+        matched.insert(0, "match_kind", kind_col)
+        matched.insert(0, "query", query_col)
+        matched.insert(0, "_order", order)
+
+        if miss_query:
+            missed = pd.DataFrame({"_order": miss_order, "query": miss_query, "match_kind": None})
+            matched = pd.concat([matched, missed], ignore_index=True)
+
+        return (
+            matched.sort_values("_order", kind="stable")
+            .drop(columns="_order")
+            .reset_index(drop=True)
+        )
+
+    def _resolve(self, query: str, taxon_id: str | None, case_insensitive: bool) -> list[GeneMatch]:
+        tables = self._exact
+        key = query
+        if case_insensitive:
+            tables = self._folded_tables()
+            key = query.casefold()
+
+        matches = [
+            GeneMatch(row, kind)
+            for kind in MatchKind
+            for row in tables[kind].get(key, ())
+        ]
+        if taxon_id is not None:
+            matches = [m for m in matches if self._taxon_ids[m.row] == taxon_id]
+
+        seen: set[int] = set()
+        unique: list[GeneMatch] = []
+        for match in matches:
+            if match.row not in seen:
+                seen.add(match.row)
+                unique.append(match)
+        return unique
+
+    def _folded_tables(self) -> _Tables:
+        if self._folded is None:
+            self._folded = _fold(self._exact)
+        return self._folded
+
+
+def _fold(tables: _Tables) -> _Tables:
+    folded: _Tables = {}
+    for kind, table in tables.items():
+        merged: dict[str, list[int]] = {}
+        for key, table_rows in table.items():
+            merged.setdefault(key.casefold(), []).extend(table_rows)
+        folded[kind] = merged
+    return folded
+
+
+def build_gene_index(records: pd.DataFrame) -> GeneIndex:
+    primary: dict[str, list[int]] = {}
+    secondary: dict[str, list[int]] = {}
+    official: dict[str, list[int]] = {}
+    synonym: dict[str, list[int]] = {}
+    cross_reference: dict[str, list[int]] = {}
+
+    for i, gene_id in enumerate(records["GeneId"].tolist()):
+        primary.setdefault(gene_id, []).append(i)
+
+    for i, symbol in enumerate(records["GeneSymbol"].tolist()):
+        if isinstance(symbol, str):
+            official.setdefault(symbol, []).append(i)
+
+    for column in ("GeneSynonyms", "GeneSystematicName"):
+        for i, value in enumerate(records[column].tolist()):
+            if isinstance(value, str):
+                for token in value.split("|"):
+                    if not token:
+                        continue
+                    synonym.setdefault(token, []).append(i)
+
+    for i, value in enumerate(records["GeneSecondaryIds"].tolist()):
+        if isinstance(value, str):
+            for token in value.split("|"):
+                if not token:
+                    continue
+                secondary.setdefault(token, []).append(i)
+
+    for i, value in enumerate(records["GeneCrossReferences"].tolist()):
+        if isinstance(value, str):
+            for token in value.split("|"):
+                if not token or token.split(":", 1)[0] in _XREF_EXCLUDED_PREFIXES:
+                    continue
+                cross_reference.setdefault(token, []).append(i)
+
+    exact: _Tables = {
+        MatchKind.PRIMARY_ID: primary,
+        MatchKind.SECONDARY_ID: secondary,
+        MatchKind.OFFICIAL_SYMBOL: official,
+        MatchKind.SYNONYM: synonym,
+        MatchKind.CROSS_REFERENCE: cross_reference,
+    }
+    return GeneIndex(records, tuple(records["Taxon"].tolist()), exact)
+
+
+def load_gene_index(path: Path) -> GeneIndex:
+    return build_gene_index(load_tsv_gz(path, dtype=str))

geneharmony/store.py

@@ -0,0 +1,61 @@
+"""Atomic Parquet persistence for cached frames.
+
+Backs the bulk, per-gene API, and external-annotation caches. Writes go through a
+same-directory temp file then `os.replace`, so a reader never sees a half-written
+file. Object columns holding dicts/lists are JSON-encoded to strings before
+writing (Parquet can't represent them natively); `read_parquet(decode_json=...)`
+reverses that for the columns a caller knows were nested.
+"""
+
+import json
+import os
+import tempfile
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+
+def _is_missing(value: Any) -> bool:
+    return value is None or (isinstance(value, float) and pd.isna(value))
+
+
+def _encode_nested(df: pd.DataFrame) -> pd.DataFrame:
+    nested = [
+        col
+        for col in df.columns
+        if isinstance(next((v for v in df[col] if not _is_missing(v)), None), (dict, list))
+    ]
+    if not nested:
+        return df
+    out = df.copy()
+    for col in nested:
+        out[col] = [None if _is_missing(v) else json.dumps(v) for v in out[col]]
+    return out
+
+
+def _atomic_write(path: Path, write_fn: Callable[[Path], None]) -> None:
+    fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    os.close(fd)
+    tmp = Path(tmp_name)
+    try:
+        write_fn(tmp)
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def write_parquet(df: pd.DataFrame, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    encoded = _encode_nested(df)
+    _atomic_write(path, lambda p: encoded.to_parquet(p, compression="zstd", index=False))
+
+
+def read_parquet(path: Path, *, decode_json: Iterable[str] = ()) -> pd.DataFrame:
+    df = pd.read_parquet(path)
+    for col in decode_json:
+        if col in df.columns:
+            df[col] = [None if _is_missing(v) else json.loads(v) for v in df[col]]
+    return df

geneharmony/taxa.json

@@ -0,0 +1,11 @@
+[
+  {"id": "NCBITaxon:9606", "species": "Homo sapiens", "common": ["human"]},
+  {"id": "NCBITaxon:10090", "species": "Mus musculus", "common": ["mouse"]},
+  {"id": "NCBITaxon:10116", "species": "Rattus norvegicus", "common": ["rat"]},
+  {"id": "NCBITaxon:7955", "species": "Danio rerio", "common": ["zebrafish"]},
+  {"id": "NCBITaxon:7227", "species": "Drosophila melanogaster", "common": ["fly", "fruit fly"]},
+  {"id": "NCBITaxon:6239", "species": "Caenorhabditis elegans", "common": ["worm", "roundworm"]},
+  {"id": "NCBITaxon:559292", "species": "Saccharomyces cerevisiae S288C", "common": ["yeast", "budding yeast", "saccharomyces cerevisiae"]},
+  {"id": "NCBITaxon:8355", "species": "Xenopus laevis", "common": ["african clawed frog"]},
+  {"id": "NCBITaxon:8364", "species": "Xenopus tropicalis", "common": ["western clawed frog", "tropical clawed frog"]}
+]

geneharmony/taxa.py

@@ -0,0 +1,86 @@
+"""Species taxon resolution, built from `taxa.json`.
+
+One entry per AGR species. `resolve_taxon` maps any alias — canonical
+`NCBITaxon:` ID, bare number, species name or common name — to its `Taxon`
+record; `taxon_mapper` builds a `value -> field` callable for annotating a taxon
+column of a DataFrame.
+"""
+
+import enum
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Final, NamedTuple
+from importlib.resources import files
+
+_TAXA_PATH = files("geneharmony").joinpath("taxa.json")
+
+
+class Taxon(NamedTuple):
+    """A resolved species: its canonical NCBITaxon ID, species name and common names."""
+
+    id: str
+    species: str
+    common: tuple[str, ...]
+
+    @property
+    def number(self) -> str:
+        """The bare NCBI taxon number, without the `NCBITaxon:` prefix."""
+        return self.id.split(":", 1)[1]
+
+    @property
+    def common_name(self) -> str | None:
+        """The primary common name, or None if the species has none."""
+        return self.common[0] if self.common else None
+
+
+class TaxonField(enum.StrEnum):
+    ID = "id"
+    NUMBER = "number"
+    SPECIES = "species"
+    COMMON_NAME = "common_name"
+
+
+def _load_taxa() -> tuple[Taxon, ...]:
+    return tuple(
+        Taxon(entry["id"], entry["species"], tuple(entry["common"]))
+        for entry in json.loads(_TAXA_PATH.read_text())
+    )
+
+
+_TAXA: Final[tuple[Taxon, ...]] = _load_taxa()
+
+
+_TAXON_BY_ALIAS: Final[dict[str, Taxon]] = {
+    alias.casefold(): taxon
+    for taxon in _TAXA
+    for alias in (taxon.id, taxon.number, taxon.species, *taxon.common)
+}
+
+
+def resolve_taxon(value: str) -> Taxon:
+    """Resolve a taxon ID, number, species name or common name to its `Taxon` record.
+
+    Pull out the part you need with `.id`, `.species`, `.common_name` or `.number`.
+    """
+    taxon = _TAXON_BY_ALIAS.get(value.strip().casefold())
+    if taxon is None:
+        raise ValueError(f"unknown taxon: {value!r}")
+    return taxon
+
+
+def taxon_mapper(field: TaxonField) -> Callable[[object], str | None]:
+    """Build a `value -> field` function for mapping a taxon column.
+
+    The returned callable takes any taxon alias (ID, number, species, common name)
+    and returns the requested `field`; unknown or non-string values yield `None`.
+    Intended for `df[col].map(taxon_mapper(TaxonField.COMMON_NAME))`.
+    """
+
+    def mapper(value: object) -> str | None:
+        if not isinstance(value, str):
+            return None
+        taxon = _TAXON_BY_ALIAS.get(value.strip().casefold())
+        return getattr(taxon, field) if taxon is not None else None
+
+    return mapper

geneharmony-0.3.0.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: geneharmony
+Version: 0.3.0
+Summary: Async toolkit to normalize gene identifiers and annotate gene sets with data from the Alliance of Genome Resources (AGR) or user-ingested datasets.
+Project-URL: Homepage, https://github.com/limenode/geneharmony
+Project-URL: Repository, https://github.com/limenode/geneharmony
+Project-URL: Issues, https://github.com/limenode/geneharmony/issues
+Author-email: Lionel Sequeira <lionelsequeira@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agr,alliance of genome resources,annotation,bioinformatics,gene,genomics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28
+Requires-Dist: pandas>=3
+Requires-Dist: pyarrow>=14
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# geneharmony
+
+An async Python toolkit that normalizes gene identifiers and annotates gene sets using the [Alliance of Genome Resources](https://www.alliancegenome.org) (AGR) REST API and bulk-download files, with functionality to append local annotations.
+
+It resolves gene symbols and identifiers to canonical genes using an in-memory index built from AGR's bulk gene file, fetches per-gene API data concurrently, and downloads and parses AGR bulk datasets.
+
+## Highlights
+
+- **Gene normalization**: Resolve symbols, primary/secondary IDs, synonyms, systematic names, and external cross-references (NCBI, Ensembl, UniProtKB, RefSeq, …) to the appropriate records in the AGR's `GENE-TSV-COMBINED` file.
+- **Nine model organisms**: Human, mouse, rat, zebrafish, fly, worm, yeast, african clawed frog, and western clawed frog.
+- **Concurrent and resilient**: Pooled, rate-limited HTTP with automatic retry/backoff for transient failures.
+- **Transparent caching**: Bulk files, per-gene API results, and ingested annotations are cached as Parquet to expedite repeat runs.
+- **Bring your own data**: Ingest external annotation tables keyed on whatever gene identifier you have; they normalize to canonical AGR genes and join cleanly.
+
+## Install
+
+Requires **Python 3.12+**. Install from PyPI with pip or uv — all dependencies (`httpx`, `pydantic` v2, `pandas` 3.x, `pyarrow`) are resolved automatically:
+
+```bash
+pip install geneharmony
+# or
+uv add geneharmony
+```
+
+## Development
+
+Contributors use **pixi** (conda-forge) for a reproducible environment from the lockfile. End users do not need pixi.
+
+```bash
+# 1. Install the environment from the lockfile
+pixi install
+
+# 2. Run Python inside the environment
+pixi run python <script>
+
+# 3. Or open the interactive driver notebook
+pixi run jupyter lab src/notebook.ipynb
+```
+
+Notebook outputs are stripped from version control via a git clean filter. The filter config is repo-local, so enable it once per clone:
+
+```bash
+git config filter.nbstrip.clean "pixi run jupyter nbconvert --clear-output --to notebook --stdin --stdout --log-level=ERROR"
+git config filter.nbstrip.smudge cat
+```
+
+## Usage
+
+The `Annotator` is the single entry point. It is async, so call its methods with `await` (inside a notebook cell, an `async def`, or `asyncio.run(...)`).
+
+### Quick start
+
+```python
+from geneharmony import Annotator, AGRDataset
+
+ann = Annotator()
+
+# Resolve gene symbols to canonical AGR records
+genes = await ann.normalize(["TP53", "BRCA1"], taxon="human")
+
+# Annotate genes with phenotypic information
+annotated_genes = await ann.annotate(["Atp7b", "Ttn"], AGRDataset.PHENOTYPES, taxon="mouse")
+```
+
+### Resolving genes (`normalize`)
+
+`normalize` accepts an identifier or a list of identifiers and returns one row per match. Unmatched queries are **retained** with a null `match_kind` so misses stay visible.
+
+```python
+df = await ann.normalize(
+    ["TP53", "ENSG00000141510", "not_a_gene"],
+    taxon="human",          # any alias: "human", "9606", "Homo sapiens", "NCBITaxon:9606"
+    limit=1,                # max matches per query; use None for all
+    case_insensitive=False, # case can be meaningful (human TP53 vs mouse Trp53)
+)
+
+resolved = df[df.match_kind.notna()]   # drop the misses
+```
+
+Matches are ranked by identifier precedence:
+
+```
+PRIMARY_ID > SECONDARY_ID > OFFICIAL_SYMBOL > SYNONYM > CROSS_REFERENCE
+```
+
+### Annotating genes (`annotate`)
+
+`annotate` builds a normalized base frame, then **left joins** one or more sources onto the canonical `GeneId`:
+
+```python
+from geneharmony import AGRDataset
+
+orth = await ann.annotate(
+    ["TP53", "BRCA1"],
+    AGRDataset.ORTHOLOGY,
+    taxon="human",
+)
+```
+
+For chaining annotate calls, the recommended pattern is an **iterative filter-then-requery traversal** — one AGR dataset per call — so result cardinality stays under your control:
+
+```python
+# 1. Find orthologs of human genes
+orth = await ann.annotate(["TP53", "BRCA1"], AGRDataset.ORTHOLOGY, taxon="human")
+
+# 2. Keep the mouse orthologs
+mouse = orth.loc[orth.Gene2SpeciesTaxonID == "NCBITaxon:10090", "Gene2ID"].unique()
+
+# 3. Fetch their phenotypes
+pheno = await ann.annotate(list(mouse), AGRDataset.PHENOTYPES, taxon="mouse")
+```
+
+#### Available AGR datasets
+
+| Dataset                 | Backend      | Key columns contributed                                     |
+| ----------------------- | ------------ | ----------------------------------------------------------- |
+| `AGRDataset.ORTHOLOGY`  | Bulk TSV     | `Gene2ID`, `Gene2Symbol`, `Gene2SpeciesTaxonID`, …          |
+| `AGRDataset.PHENOTYPES` | Per-gene API | `phenotypeStatement`, `references`                          |
+| `AGRDataset.ALLELES`    | Per-gene API | `allele_id`, `symbol`, `alterationType`, `variantType`, …   |
+
+### Orthologs convenience helper
+
+For the common ortholog case there is a shortcut that returns a tidy subset:
+
+```python
+orthologs = await ann.get_orthologs(
+    ["TP53", "BRCA1"],
+    taxon="human",
+    target_taxon="mouse",   # optional: filter to one target species
+)
+# -> columns: query, match_kind, Gene2ID, Gene2Symbol, Gene2SpeciesTaxonID
+```
+
+### Downloading bulk datasets (`download`)
+
+Bulk datasets are downloaded and converted to Parquet on first use (and cached thereafter). You can pre-fetch one explicitly:
+
+```python
+path = await ann.download(AGRDataset.ORTHOLOGY)
+# Force a refresh across AGR releases:
+path = await ann.download(AGRDataset.ORTHOLOGY, refresh=True)
+```
+
+### Ingesting your own annotations (`ingest_annotation`)
+
+Bring an external table (CSV, TSV, or Parquet file, or a `DataFrame`), normalize its gene identifiers to canonical AGR genes, and store it for joining by name:
+
+```python
+summary, unmapped = await ann.ingest_annotation(
+    "my_expression_table.csv",
+    name="expression",
+    gene_id_column="symbol",   # or a list of columns, tried left-to-right per row
+    taxon="human",
+)
+
+# Join it alongside an AGR dataset; its columns are prefixed `expression.`
+df = await ann.annotate(["TP53", "BRCA1"], AGRDataset.ORTHOLOGY, "expression", taxon="human")
+```
+
+`summary` reports rows in / stored / dropped; `unmapped` holds the rows whose identifiers could not be resolved (with their original columns) so nothing is silently lost.
+
+### Supported species
+
+| Common name           | Species                          | Taxon ID           |
+| --------------------- | -------------------------------- | ------------------ |
+| human                 | *Homo sapiens*                   | `NCBITaxon:9606`   |
+| mouse                 | *Mus musculus*                   | `NCBITaxon:10090`  |
+| rat                   | *Rattus norvegicus*              | `NCBITaxon:10116`  |
+| zebrafish             | *Danio rerio*                    | `NCBITaxon:7955`   |
+| fly / fruit fly       | *Drosophila melanogaster*        | `NCBITaxon:7227`   |
+| worm / roundworm      | *Caenorhabditis elegans*         | `NCBITaxon:6239`   |
+| yeast / budding yeast | *Saccharomyces cerevisiae S288C* | `NCBITaxon:559292` |
+| african clawed frog   | *Xenopus laevis*                 | `NCBITaxon:8355`   |
+| western clawed frog   | *Xenopus tropicalis*             | `NCBITaxon:8364`   |
+
+Any of the aliases above — common name, full species name, bare number, or `NCBITaxon:` ID — can be passed as `taxon`.
+
+## Caching
+
+Results are cached so repeat work is fast and largely offline. The cache defaults to `$XDG_CACHE_HOME/geneharmony` (falling back to `~/.cache/geneharmony`); pass a `cache_dir` to `Annotator(...)` to share or relocate it.
+
+```
+bulk/<dataset>.parquet            # downloaded + converted bulk datasets (incl. the gene index source)
+api/<dataset>/<gene_id>.parquet   # per-gene API results
+external/<name>.parquet           # ingested annotations
+```
+
+The gene index is built from `bulk/gene.parquet`, which becomes stale across AGR releases. Refresh it with `await ann.download(AGRDataset.GENE, refresh=True)` (or by deleting the file).
+
+## Acknowledgements & Citation
+
+This project is a client for data and services provided by the **Alliance of Genome Resources (AGR)**. It is not affiliated with or endorsed by the Alliance. All gene, ortholog, phenotype, and allele data are sourced from AGR and its member model-organism databases, and remain subject to the Alliance's terms of use.
+
+If you use data obtained through this wrapper, please cite the Alliance of Genome Resources:
+
+> [Updates to the Alliance of Genome Resources central infrastructure.](https://pubmed.ncbi.nlm.nih.gov/38552170/) 2024. Alliance of Genome Resources Consortium. Genetics. 2024 May 7;227(1):iyae049. doi: 10.1093/genetics/iyae049. PMID: 38552170.
+
+Please also consult the [Alliance citation and data-usage guidelines](https://www.alliancegenome.org/cite-us) and acknowledge the underlying model-organism databases (e.g. SGD, WormBase, FlyBase, ZFIN, MGI, RGD, Xenbase) as appropriate.

geneharmony-0.3.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+geneharmony/__init__.py,sha256=0-sHvuoBiKxIeivfD7iKyrgfeQmBclTQHnnKjQSlXtk,475
+geneharmony/annotator.py,sha256=hXTYESOfC1ADKBsMo5kh-7NLhqPUjrdSfgN5jEpmojw,13459
+geneharmony/client.py,sha256=dG-lm9t5Krv540DEbmpOwJYR6zZbGGyk3aArb_9EDAQ,3523
+geneharmony/datasets.py,sha256=GHWXgNxN3cngUfzOaYxgu4vDzraCtx10gNheDTa3_U4,3839
+geneharmony/downloader.py,sha256=X0OSczbigq6dtEj0LtiLNn3xqHVx5QUh4qvAbOjVg7U,3538
+geneharmony/ingest.py,sha256=-BViPSxGMKCymlLwkCegIVnHckLLxpvbfZ6GrD2oZ7o,757
+geneharmony/models.py,sha256=rGiMCo07EvxV_0GXjwnNE0XUdglsH3yRzPscNaz_b54,326
+geneharmony/normalizer.py,sha256=8fm1gs6GAimBtTum0tFIfCClw0mLpJYeGlfhX6demVo,6600
+geneharmony/store.py,sha256=Ukx0OwPwY0kKkcpUHKBNBdhmhav1gINqTQDYK50Vwy0,1938
+geneharmony/taxa.json,sha256=TiseisPSZw3oj1I2v3y98x2rCtnKhMefBt1PRMuIFkY,864
+geneharmony/taxa.py,sha256=zqUw8Ma62W5yrg6fqAxZNVjxMH9Ca0l_YXXDCmZR89I,2599
+geneharmony-0.3.0.dist-info/METADATA,sha256=5YkxIUwkPmr_tss9XdFR9_OZGXcDWrwuP_eTq8TykgM,10066
+geneharmony-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+geneharmony-0.3.0.dist-info/licenses/LICENSE,sha256=r0h8rf3XM4VXvFcvxGHMrqJos3l3v654b1Z2Tb5Tk6w,1072
+geneharmony-0.3.0.dist-info/RECORD,,

geneharmony-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

geneharmony-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lionel Sequeira
+
+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.