gnomad-api-cache 0.1.0__tar.gz → 0.2.0__tar.gz

{gnomad_api_cache-0.1.0 → gnomad_api_cache-0.2.0}/.github/workflows/workflow.yml

@@ -66,7 +66,7 @@ jobs:
         run: |
           gnomad-api-cache --version
           python -m gnomad_api_cache --help > /dev/null
-          python -c "from gnomad_api_cache import VariantCache, read_vcf, fetch_gnomad"
+          python -c "from gnomad_api_cache import VariantCache, read_vcf, fetch_into, to_variant_keys"
 
   publish-testpypi:
     name: Publish to TestPyPI
@@ -88,6 +88,7 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
 
   publish-pypi:
     name: Publish to PyPI

{gnomad_api_cache-0.1.0 → gnomad_api_cache-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gnomad-api-cache
-Version: 0.1.0
+Version: 0.2.0
 Summary: Fetch and cache gnomAD annotations for VCF variants.
 License-File: LICENSE
 Requires-Python: >=3.11
@@ -65,34 +65,58 @@ gnomad-api-cache -i cohort.vcf.gz -c gnomad.sqlite
 ```python
 from gnomad_api_cache import VariantCache
 
+variant_ids = ["1-55051215-G-A", "M-8993-T-C", ...]
+
 with VariantCache("gnomad.sqlite") as cache:
-    summary = cache.fetch_vcf("cohort.vcf.gz")
-    print(summary)  # 1234 requested, 0 already cached, 1200 fetched, ...
+    summary = cache.fetch(variant_ids)
+    print(summary)  # 1234 requested, 234 already cached, 1000 fetched, ...
 
     cache.to_parquet("annotations.parquet")
     cache.to_csv("annotations.csv")
 ```
 
-Pass a `filter_function(cyvcf2.Variant) -> bool` to decide which variants are worth querying:
+`cache.fetch` takes in gnomAD id strings (hyphen- or colon-separated), 
+`(chrom, pos, ref, alt)` tuples, row dicts, a dataframe, or a VCF path.
+
+```python
+with VariantCache("gnomad.sqlite") as cache:
+    cache.fetch(df)  # any pandas/polars/duckdb frame with chrom/pos/ref/alt columns
+    cache.fetch("cohort.vcf.gz")
+```
+
+Unusable rows are skipped and tallied; pass `on_error="raise"` to fail on the first one instead.
+
+Reading the VCF yourself lets you filter before querying.
+Define a function of the form `filter_function(cyvcf2.Variant) -> bool` 
+and pass it to `read_vcf` to only fetch variants that pass the filter:
 
 ```python
 from cyvcf2 import Variant
-from gnomad_api_cache import VariantCache
+from gnomad_api_cache import VariantCache, read_vcf
 
 def rare_only(variant: Variant) -> bool:
     af = variant.INFO.get("gnomad41_exome_AF", 0)
     return float(0 if af == "." else af) <= 0.05
 
 with VariantCache("gnomad.sqlite") as cache:
-    cache.fetch_vcf("cohort.vcf.gz", filter_function=rare_only)
+    cache.fetch(read_vcf("cohort.vcf.gz", filter_function=rare_only))
 ```
 
 An open cache is a read-only `Mapping` keyed by `chrom-pos-ref-alt`, so cached
-records are available without another request:
+records can be retrieved using dictionary-like syntax:
+
+```python
+record = cache["1-55051215-G-A"]  # dict, or None if gnomAD has no such variant
+```
+
+`to_variant_keys` builds those keys from any input `fetch` takes, so lookup keys
+do not need to be manually constructed:
 
 ```python
-record = cache["1-55051215-G-A"]  # None if gnomAD has no such variant
-print(len(cache), cache.status_counts())
+from gnomad_api_cache import to_variant_keys
+
+for key in to_variant_keys([("chr1", 55051215, "G", "A")]):
+    record = cache[key.id]  # key.id == "1-55051215-G-A"
 ```
 
 ## Acknowledgement & Citation

{gnomad_api_cache-0.1.0 → gnomad_api_cache-0.2.0}/README.md

@@ -53,34 +53,58 @@ gnomad-api-cache -i cohort.vcf.gz -c gnomad.sqlite
 ```python
 from gnomad_api_cache import VariantCache
 
+variant_ids = ["1-55051215-G-A", "M-8993-T-C", ...]
+
 with VariantCache("gnomad.sqlite") as cache:
-    summary = cache.fetch_vcf("cohort.vcf.gz")
-    print(summary)  # 1234 requested, 0 already cached, 1200 fetched, ...
+    summary = cache.fetch(variant_ids)
+    print(summary)  # 1234 requested, 234 already cached, 1000 fetched, ...
 
     cache.to_parquet("annotations.parquet")
     cache.to_csv("annotations.csv")
 ```
 
-Pass a `filter_function(cyvcf2.Variant) -> bool` to decide which variants are worth querying:
+`cache.fetch` takes in gnomAD id strings (hyphen- or colon-separated), 
+`(chrom, pos, ref, alt)` tuples, row dicts, a dataframe, or a VCF path.
+
+```python
+with VariantCache("gnomad.sqlite") as cache:
+    cache.fetch(df)  # any pandas/polars/duckdb frame with chrom/pos/ref/alt columns
+    cache.fetch("cohort.vcf.gz")
+```
+
+Unusable rows are skipped and tallied; pass `on_error="raise"` to fail on the first one instead.
+
+Reading the VCF yourself lets you filter before querying.
+Define a function of the form `filter_function(cyvcf2.Variant) -> bool` 
+and pass it to `read_vcf` to only fetch variants that pass the filter:
 
 ```python
 from cyvcf2 import Variant
-from gnomad_api_cache import VariantCache
+from gnomad_api_cache import VariantCache, read_vcf
 
 def rare_only(variant: Variant) -> bool:
     af = variant.INFO.get("gnomad41_exome_AF", 0)
     return float(0 if af == "." else af) <= 0.05
 
 with VariantCache("gnomad.sqlite") as cache:
-    cache.fetch_vcf("cohort.vcf.gz", filter_function=rare_only)
+    cache.fetch(read_vcf("cohort.vcf.gz", filter_function=rare_only))
 ```
 
 An open cache is a read-only `Mapping` keyed by `chrom-pos-ref-alt`, so cached
-records are available without another request:
+records can be retrieved using dictionary-like syntax:
+
+```python
+record = cache["1-55051215-G-A"]  # dict, or None if gnomAD has no such variant
+```
+
+`to_variant_keys` builds those keys from any input `fetch` takes, so lookup keys
+do not need to be manually constructed:
 
 ```python
-record = cache["1-55051215-G-A"]  # None if gnomAD has no such variant
-print(len(cache), cache.status_counts())
+from gnomad_api_cache import to_variant_keys
+
+for key in to_variant_keys([("chr1", 55051215, "G", "A")]):
+    record = cache[key.id]  # key.id == "1-55051215-G-A"
 ```
 
 ## Acknowledgement & Citation

{gnomad_api_cache-0.1.0 → gnomad_api_cache-0.2.0}/pixi.toml

@@ -2,7 +2,6 @@
 channels = ["conda-forge", "bioconda"]
 name = "gnomad_api_cache"
 platforms = ["linux-64"]
-version = "0.1.0"
 
 [tasks]
 

{gnomad_api_cache-0.1.0 → gnomad_api_cache-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gnomad-api-cache"
-version = "0.1.0"
+dynamic = ["version"]
 description = "Fetch and cache gnomAD annotations for VCF variants."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -25,5 +25,10 @@ dev = [
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+# Single source of truth for the version. Read at build time, so __version__
+# stays a plain literal and `--version` costs no imports.
+[tool.hatch.version]
+path = "src/gnomad_api_cache/__init__.py"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/gnomad_api_cache"]

gnomad_api_cache-0.2.0/src/gnomad_api_cache/__init__.py

@@ -0,0 +1,89 @@
+"""Fetch and cache gnomAD annotations for VCF variants.
+
+    from gnomad_api_cache import VariantCache, read_vcf
+
+    with VariantCache("gnomad.sqlite") as cache:
+        print(cache.fetch("cohort.vcf.gz"))
+        cache.to_parquet("annotations.parquet")
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+__version__ = "0.2.0"
+
+# Public name -> the module that defines it.
+_LAZY_IMPORTS: dict[str, str] = {
+    "BuildMismatchError": "gnomad_api_cache.adapters.vcf_adapter",
+    "iter_variant_keys": "gnomad_api_cache.adapters.vcf_adapter",
+    "read_variants": "gnomad_api_cache.adapters.vcf_adapter",
+    "read_vcf": "gnomad_api_cache.adapters.vcf_adapter",
+    "read_arrow": "gnomad_api_cache.adapters.record_adapter",
+    "read_dicts": "gnomad_api_cache.adapters.record_adapter",
+    "read_ids": "gnomad_api_cache.adapters.record_adapter",
+    "read_tuples": "gnomad_api_cache.adapters.record_adapter",
+    "to_variant_keys": "gnomad_api_cache.adapters.record_adapter",
+    "VariantCache": "gnomad_api_cache.cache",
+    "FetchSummary": "gnomad_api_cache.fetch",
+    "fetch_into": "gnomad_api_cache.fetch",
+    "InvalidVariantError": "gnomad_api_cache.keys",
+    "VariantKey": "gnomad_api_cache.keys",
+    "DEFAULT_DATASET": "gnomad_api_cache.query",
+    "QUERY_VERSION": "gnomad_api_cache.query",
+}
+
+if TYPE_CHECKING:
+    # Type checkers do not follow __getattr__ well enough to give these real
+    # types, so state them here. Never executed at runtime.
+    from gnomad_api_cache.adapters.record_adapter import (
+        read_arrow,
+        read_dicts,
+        read_ids,
+        read_tuples,
+        to_variant_keys,
+    )
+    from gnomad_api_cache.adapters.vcf_adapter import (
+        BuildMismatchError,
+        iter_variant_keys,
+        read_variants,
+        read_vcf,
+    )
+    from gnomad_api_cache.cache import VariantCache
+    from gnomad_api_cache.fetch import FetchSummary, fetch_into
+    from gnomad_api_cache.keys import InvalidVariantError, VariantKey
+    from gnomad_api_cache.query import DEFAULT_DATASET, QUERY_VERSION
+
+
+def __getattr__(name: str) -> Any:
+    module_name = _LAZY_IMPORTS.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(import_module(module_name), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted([*__all__, "__version__"])
+
+
+__all__ = [
+    "DEFAULT_DATASET",
+    "QUERY_VERSION",
+    "BuildMismatchError",
+    "FetchSummary",
+    "InvalidVariantError",
+    "VariantCache",
+    "VariantKey",
+    "fetch_into",
+    "iter_variant_keys",
+    "read_arrow",
+    "read_dicts",
+    "read_ids",
+    "read_tuples",
+    "read_variants",
+    "read_vcf",
+    "to_variant_keys",
+]

gnomad_api_cache-0.2.0/src/gnomad_api_cache/adapters/_collect.py

@@ -0,0 +1,57 @@
+"""The row -> VariantKey loop."""
+
+from __future__ import annotations
+
+import logging
+from collections import Counter
+from collections.abc import Callable, Iterable, Iterator
+from typing import Any
+
+from gnomad_api_cache.keys import InvalidVariantError, VariantKey
+
+log = logging.getLogger(__name__)
+
+ON_ERROR_SKIP = "skip"
+ON_ERROR_RAISE = "raise"
+ON_ERROR_CHOICES = (ON_ERROR_SKIP, ON_ERROR_RAISE)
+
+
+def collect(
+    rows: Iterable[Any],
+    to_keys: Callable[[Any], VariantKey],
+    *,
+    on_error: str = ON_ERROR_SKIP,
+    label: str | None = None,
+) -> Iterator[VariantKey]:
+    """Build keys from rows, tally and logging what could not be built successfully."""
+    if on_error not in ON_ERROR_CHOICES:
+        raise ValueError(
+            f"on_error must be one of {ON_ERROR_CHOICES}, got {on_error!r}"
+        )
+
+    skipped: Counter[str] = Counter()
+    yielded = 0
+
+    for row in rows:
+        try:
+            key = to_keys(row)
+        except InvalidVariantError as exc:
+            if on_error == ON_ERROR_RAISE:
+                raise
+            skipped[exc.reason] += 1
+            log.debug("skipping %r -- %s", row, exc)
+            continue
+        yielded += 1
+        yield key
+
+    prefix = f"{label}: " if label else ""
+    if skipped:
+        log.info(
+            "%s%d keys, %d rows skipped (%s)",
+            prefix,
+            yielded,
+            sum(skipped.values()),
+            ", ".join(f"{k}={v}" for k, v in sorted(skipped.items())),
+        )
+    else:
+        log.info("%s%d keys", prefix, yielded)

gnomad_api_cache-0.2.0/src/gnomad_api_cache/adapters/record_adapter.py

@@ -0,0 +1,267 @@
+"""Build VariantKey objects from in-memory Python data.
+
+Covers gnomAD id strings, 4-tuples, row mappings, and any dataframe exposing
+the Arrow PyCapsule interface (pandas >= 2.2, polars >= 1.3, duckdb relations,
+pyarrow tables). `to_variant_keys` handles all cases.
+
+Each reader supplies callables to the collect() function in _collect.py.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Mapping, Sequence
+from itertools import chain
+from pathlib import Path
+from typing import Any
+
+from gnomad_api_cache.adapters._collect import ON_ERROR_SKIP, collect
+from gnomad_api_cache.keys import InvalidVariantError, VariantKey
+
+FIELDS = ("chrom", "pos", "ref", "alt")
+
+# Common headers for chrom, pos, ref, alt.
+_FIELD_BY_ALIAS: Mapping[str, str] = {
+    "chr": "chrom",
+    "chrom": "chrom",
+    "chromosome": "chrom",
+    "contig": "chrom",
+    "pos": "pos",
+    "position": "pos",
+    "start_1based": "pos",
+    "ref": "ref",
+    "reference": "ref",
+    "ref_allele": "ref",
+    "reference_allele": "ref",
+    "alt": "alt",
+    "alternate": "alt",
+    "alt_allele": "alt",
+    "alternate_allele": "alt",
+}
+
+# Interval-frame columns are 0-based half-open (BED, bioframe, pyranges) while
+# gnomAD positions are 1-based. Treat them as an error to avoid off-by-one mistakes.
+_INTERVAL_ALIASES = frozenset({"start", "chromstart", "end", "chromend", "stop"})
+
+_VCF_SUFFIXES = (".vcf", ".vcf.gz", ".vcf.bgz", ".bcf", ".bcf.gz")
+
+
+def _looks_like_vcf_path(text: str) -> bool:
+    return text.lower().endswith(_VCF_SUFFIXES)
+
+
+# --- row -> key functions ------------------------------------------------
+
+
+def _key_from_key(row: Any) -> VariantKey:
+    if not isinstance(row, VariantKey):
+        raise InvalidVariantError(f"not a VariantKey: {row!r}", "malformed_row")
+    return row
+
+
+def _key_from_id(row: Any) -> VariantKey:
+    return VariantKey.from_id(str(row))
+
+
+def _key_from_tuple(row: Any) -> VariantKey:
+    if isinstance(row, (str, bytes)) or not isinstance(row, Sequence):
+        raise InvalidVariantError(
+            f"not a (chrom, pos, ref, alt) row: {row!r}", "malformed_row"
+        )
+    if len(row) != 4:
+        raise InvalidVariantError(
+            f"expected 4 fields (chrom, pos, ref, alt), got {len(row)}: {row!r}",
+            "malformed_row",
+        )
+    chrom, pos, ref, alt = row
+    return VariantKey.from_parts(str(chrom), pos, str(ref), str(alt))
+
+
+def _key_from_mapping(
+    row: Any,
+    columns: Mapping[str, str] | None = None,
+) -> VariantKey:
+    if not isinstance(row, Mapping):
+        raise InvalidVariantError(f"not a mapping: {row!r}", "malformed_row")
+
+    if columns is not None:
+        try:
+            values = {field: row[columns[field]] for field in FIELDS}
+        except KeyError as exc:
+            raise InvalidVariantError(
+                f"column {exc.args[0]!r} missing from row: {sorted(row)}",
+                "missing_fields",
+            ) from None
+    else:
+        # Lowercase the row's keys
+        lowered = {str(key).lower(): value for key, value in row.items()}
+        values = {}
+        for alias, field in _FIELD_BY_ALIAS.items():
+            if field not in values and alias in lowered:
+                values[field] = lowered[alias]
+
+        missing = [field for field in FIELDS if field not in values]
+        if missing:
+            if "pos" in missing and _INTERVAL_ALIASES & lowered.keys():
+                raise InvalidVariantError(
+                    "interval columns (start/end) are 0-based half-open while "
+                    "gnomAD positions are 1-based; supply a 1-based 'pos' "
+                    f"column instead: {sorted(row)}",
+                    "interval_columns",
+                )
+            raise InvalidVariantError(
+                f"no column for {missing} in row: {sorted(row)}", "missing_fields"
+            )
+
+    return VariantKey.from_parts(
+        str(values["chrom"]), values["pos"], str(values["ref"]), str(values["alt"])
+    )
+
+
+# --- readers -------------------------------------------------------------
+
+
+def iter_ids(
+    variant_ids: Iterable[Any],
+    *,
+    on_error: str = ON_ERROR_SKIP,
+    label: str | None = None,
+) -> Iterator[VariantKey]:
+    """Yield keys from "chrom-pos-ref-alt" (or colon-separated) id strings."""
+    return collect(variant_ids, _key_from_id, on_error=on_error, label=label)
+
+
+def iter_tuples(
+    variants: Iterable[Any],
+    *,
+    on_error: str = ON_ERROR_SKIP,
+    label: str | None = None,
+) -> Iterator[VariantKey]:
+    """Yield keys from (chrom, pos, ref, alt) rows, e.g. df.itertuples()."""
+    return collect(variants, _key_from_tuple, on_error=on_error, label=label)
+
+
+def iter_dicts(
+    variants: Iterable[Any],
+    *,
+    columns: Mapping[str, str] | None = None,
+    on_error: str = ON_ERROR_SKIP,
+    label: str | None = None,
+) -> Iterator[VariantKey]:
+    """Yield keys from row mappings, e.g. df.to_dict("records").
+
+    Column names are matched case-insensitively against a table of common
+    spellings; `columns` overrides that with an explicit
+    {"chrom": ..., "pos": ..., "ref": ..., "alt": ...} mapping.
+    """
+    return collect(
+        variants,
+        lambda row: _key_from_mapping(row, columns),
+        on_error=on_error,
+        label=label,
+    )
+
+
+def iter_arrow(
+    source: Any,
+    *,
+    columns: Mapping[str, str] | None = None,
+    on_error: str = ON_ERROR_SKIP,
+    label: str | None = None,
+) -> Iterator[VariantKey]:
+    """Yield keys from any object implementing the Arrow PyCapsule interface."""
+    import pyarrow
+
+    def _rows() -> Iterator[dict[str, Any]]:
+        # Stream batch by batch so a large frame is never fully materialized
+        # as Python objects.
+        reader = pyarrow.RecordBatchReader.from_stream(source)
+        for batch in reader:
+            yield from batch.to_pylist()
+
+    return iter_dicts(_rows(), columns=columns, on_error=on_error, label=label)
+
+
+def read_ids(variant_ids: Iterable[Any], **kwargs: Any) -> list[VariantKey]:
+    """Eager convenience wrapper around iter_ids."""
+    return list(iter_ids(variant_ids, **kwargs))
+
+
+def read_tuples(variants: Iterable[Any], **kwargs: Any) -> list[VariantKey]:
+    """Eager convenience wrapper around iter_tuples."""
+    return list(iter_tuples(variants, **kwargs))
+
+
+def read_dicts(variants: Iterable[Any], **kwargs: Any) -> list[VariantKey]:
+    """Eager convenience wrapper around iter_dicts."""
+    return list(iter_dicts(variants, **kwargs))
+
+
+def read_arrow(source: Any, **kwargs: Any) -> list[VariantKey]:
+    """Eager convenience wrapper around iter_arrow."""
+    return list(iter_arrow(source, **kwargs))
+
+
+# --- dispatch ------------------------------------------------------------
+
+
+def to_variant_keys(
+    source: Any,
+    *,
+    columns: Mapping[str, str] | None = None,
+    on_error: str = ON_ERROR_SKIP,
+) -> list[VariantKey]:
+    """Coerce any supported input into a list of VariantKey.
+
+    Accepts a VariantKey, a VCF path (str/Path ending in a VCF suffix), a
+    single id string, a dataframe exposing the Arrow PyCapsule interface, a
+    single row mapping, or an iterable of ids / 4-tuples / row mappings /
+    cyvcf2 Variant records.
+    """
+    if isinstance(source, VariantKey):
+        return [source]
+
+    if isinstance(source, Path) or (
+        isinstance(source, str) and _looks_like_vcf_path(source)
+    ):
+        from gnomad_api_cache.adapters.vcf_adapter import read_vcf
+
+        return read_vcf(source, on_error=on_error)
+
+    if isinstance(source, str):
+        return [VariantKey.from_id(source)]
+
+    if hasattr(source, "__arrow_c_stream__"):
+        return read_arrow(source, columns=columns, on_error=on_error)
+
+    # A dataframe predating the PyCapsule interface. Intercept it before the
+    # generic iterable path, where iterating would yield column names.
+    if hasattr(source, "to_dict") and hasattr(source, "columns"):
+        return read_dicts(
+            source.to_dict("records"), columns=columns, on_error=on_error
+        )
+
+    if isinstance(source, Mapping):
+        return read_dicts([source], columns=columns, on_error=on_error)
+
+    if not isinstance(source, Iterable):
+        raise TypeError(f"cannot build variant keys from {type(source).__name__}")
+
+    # Peek at the first row to pick a reader, then put it back.
+    iterator = iter(source)
+    try:
+        first = next(iterator)
+    except StopIteration:
+        return []
+    rows = chain([first], iterator)
+
+    if isinstance(first, VariantKey):
+        return list(collect(rows, _key_from_key, on_error=on_error))
+    if isinstance(first, (str, bytes)):
+        return read_ids(rows, on_error=on_error)
+    if isinstance(first, Mapping):
+        return read_dicts(rows, columns=columns, on_error=on_error)
+    if hasattr(first, "ALT") and hasattr(first, "CHROM"):
+        from gnomad_api_cache.adapters.vcf_adapter import read_variants
+
+        return read_variants(rows, on_error=on_error)
+    return read_tuples(rows, on_error=on_error)

gnomad_api_cache-0.2.0/src/gnomad_api_cache/adapters/vcf_adapter.py

@@ -0,0 +1,165 @@
+"""Read a VCF, or already-loaded cyvcf2 records, into VariantKey objects."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Iterable, Iterator
+from pathlib import Path
+
+from cyvcf2 import VCF, Variant
+
+from gnomad_api_cache.adapters._collect import ON_ERROR_SKIP, collect
+from gnomad_api_cache.keys import InvalidVariantError, VariantKey
+
+log = logging.getLogger(__name__)
+
+# Use chr1 to detect build
+CHR1_LENGTH_BY_BUILD = {248956422: "GRCh38", 249250621: "GRCh37"}
+
+AltRow = tuple[Variant, str]
+
+
+class BuildMismatchError(RuntimeError):
+    """Raised when a VCF is not on the build the target gnomAD dataset uses."""
+
+
+def detect_build(vcf: VCF) -> str | None:
+    """Return "GRCh38", "GRCh37", or None if the header doesn't say."""
+    lengths: dict[str, int] = dict(zip(vcf.seqnames, vcf.seqlens))
+    chr1 = lengths.get("chr1") or lengths.get("1")
+    if chr1 is None:
+        return None
+    return CHR1_LENGTH_BY_BUILD.get(chr1)
+
+
+def is_normalized(vcf: VCF) -> bool:
+    """True if the header shows bcftools norm was run."""
+    return any(
+        line.startswith("##bcftools_norm") for line in vcf.raw_header.split("\n")
+    )
+
+
+def _alt_syntax_reason(alt: str) -> str | None:
+    """Name the VCF ALT spelling that cannot become a gnomAD ID, or None."""
+    if alt.startswith("<"):
+        return "symbolic"  # <DEL>, <NON_REF>, <*>
+    if "[" in alt or "]" in alt:
+        return "breakend"
+    if alt == "*":
+        return "spanning_deletion"
+    return None
+
+
+def _iter_alt_rows(
+    records: Iterable[Variant],
+    filter_function: Callable[[Variant], bool] | None,
+) -> Iterator[AltRow]:
+    """Fan records out to one (record, alt) row per ALT allele."""
+    for record in records:
+        if filter_function is not None and not filter_function(record):
+            continue
+        for alt in record.ALT:  # empty list when ALT is "."
+            yield record, alt
+
+
+def _key_from_alt_row(row: AltRow) -> VariantKey:
+    record, alt = row
+    reason = _alt_syntax_reason(alt)
+    if reason is not None:
+        raise InvalidVariantError(f"unusable ALT allele: {alt!r}", reason)
+    return VariantKey.from_parts(record.CHROM, record.POS, record.REF, alt)
+
+
+def iter_variant_keys_from_records(
+    records: Iterable[Variant],
+    *,
+    filter_function: Callable[[Variant], bool] | None = None,
+    on_error: str = ON_ERROR_SKIP,
+    label: str | None = None,
+) -> Iterator[VariantKey]:
+    """Yield one VariantKey per ALT allele of already-loaded cyvcf2 records."""
+    return collect(
+        _iter_alt_rows(records, filter_function),
+        _key_from_alt_row,
+        on_error=on_error,
+        label=label,
+    )
+
+
+def iter_variant_keys(
+    path: str | Path,
+    *,
+    require_build: str | None = "GRCh38",
+    warn_unnormalized: bool = True,
+    filter_function: Callable[[Variant], bool] | None = None,
+    on_error: str = ON_ERROR_SKIP,
+) -> Iterator[VariantKey]:
+    """Yield one VariantKey per ALT allele of every record in `path`."""
+    vcf = VCF(str(path))
+    try:
+        build = detect_build(vcf)
+        if require_build is not None:
+            if build is None:
+                log.warning(
+                    "%s: could not determine build from header; assuming %s",
+                    path,
+                    require_build,
+                )
+            elif build != require_build:
+                raise BuildMismatchError(
+                    f"{path}: VCF is {build}, expected {require_build}. "
+                    + "Lift over first, or target a matching gnomAD dataset."
+                )
+
+        if warn_unnormalized and not is_normalized(vcf):
+            log.warning(
+                "%s: no ##bcftools_norm header. Unnormalized indels will silently "
+                + "miss in gnomAD. Run: bcftools norm -f <ref.fa> -m -any",
+                path,
+            )
+
+        yield from iter_variant_keys_from_records(
+            vcf,
+            filter_function=filter_function,
+            on_error=on_error,
+            label=str(path),
+        )
+    finally:
+        # try/finally because a caller may abandon this generator part-way.
+        vcf.close()
+
+
+def read_vcf(
+    path: str | Path,
+    *,
+    require_build: str | None = "GRCh38",
+    warn_unnormalized: bool = True,
+    filter_function: Callable[[Variant], bool] | None = None,
+    on_error: str = ON_ERROR_SKIP,
+) -> list[VariantKey]:
+    """Eager convenience wrapper around iter_variant_keys."""
+    return list(
+        iter_variant_keys(
+            path,
+            require_build=require_build,
+            warn_unnormalized=warn_unnormalized,
+            filter_function=filter_function,
+            on_error=on_error,
+        )
+    )
+
+
+def read_variants(
+    variants: Iterable[Variant],
+    *,
+    filter_function: Callable[[Variant], bool] | None = None,
+    on_error: str = ON_ERROR_SKIP,
+) -> list[VariantKey]:
+    """Eager convenience wrapper around iter_variant_keys_from_records."""
+    return list(
+        iter_variant_keys_from_records(
+            variants,
+            filter_function=filter_function,
+            on_error=on_error,
+        )
+    )

{gnomad_api_cache-0.1.0 → gnomad_api_cache-0.2.0}/src/gnomad_api_cache/cache.py

@@ -26,10 +26,9 @@ from __future__ import annotations
 import json
 import sqlite3
 import zlib
-from collections.abc import Callable, Iterator, Mapping, Sequence
+from collections.abc import Iterator, Mapping, Sequence
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Self
-from cyvcf2 import Variant
 
 if TYPE_CHECKING:
     from gnomad_api_cache.fetch import FetchSummary
@@ -300,29 +299,12 @@ class VariantCache(Mapping[str, "dict[str, Any] | None"]):
             )
         }
 
-    def fetch(self, variants: list[VariantKey], **kwargs) -> FetchSummary:
-        """Fetch missing records into this cache. See fetch.fetch_into."""
+    def fetch(self, variants: Any, **kwargs) -> FetchSummary:
+        """Fetch missing records into this cache.
+
+        Accepts VariantKey objects, gnomAD id strings, (chrom, pos, ref, alt)
+        tuples, row mappings, a dataframe, or a VCF path. See fetch.fetch_into.
+        """
         from gnomad_api_cache import fetch as _fetch
 
         return _fetch.fetch_into(self, variants, **kwargs)
-
-    def fetch_vcf(
-        self,
-        vcf_path: str | Path,
-        retry_errors: bool = True,
-        retry_not_found: bool = False,
-        filter_function: Callable[[Variant], bool] | None = None,
-    ) -> FetchSummary:
-        """Read a VCF and fetch missing records into this cache."""
-        from gnomad_api_cache import fetch as _fetch
-        from gnomad_api_cache.adapters import vcf_adapter
-
-        return _fetch.fetch_into(
-            self,
-            vcf_adapter.read_vcf(
-                vcf_path,
-                filter_function=filter_function
-            ),
-            retry_errors=retry_errors,
-            retry_not_found=retry_not_found,
-        )

{gnomad_api_cache-0.1.0 → gnomad_api_cache-0.2.0}/src/gnomad_api_cache/cli.py

@@ -218,8 +218,6 @@ def main(argv: Sequence[str] | None = None) -> int:
         None if args.require_build.lower() == ANY_BUILD else args.require_build
     )
 
-    # Imported here rather than at module scope so --help and --version stay
-    # fast and do not require cyvcf2 to be importable.
     from gnomad_api_cache.adapters.vcf_adapter import BuildMismatchError, read_vcf
     from gnomad_api_cache.cache import VariantCache
 

{gnomad_api_cache-0.1.0 → gnomad_api_cache-0.2.0}/src/gnomad_api_cache/fetch.py

@@ -3,13 +3,13 @@ from __future__ import annotations
 import time
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass, replace
-from pathlib import Path
 from typing import Any
 
 import requests
 from tqdm import tqdm
 
 from gnomad_api_cache._utils import _chunked
+from gnomad_api_cache.adapters.record_adapter import to_variant_keys
 from gnomad_api_cache.cache import VariantCache
 from gnomad_api_cache.client import post_gnomad
 from gnomad_api_cache.keys import VariantKey
@@ -85,16 +85,22 @@ def _fetch_batches(
 
 def fetch_into(
     cache: VariantCache,
-    variants: list[VariantKey],
+    variants: Any,
     retry_errors: bool = True,
     retry_not_found: bool = False,
     delay: float = REQUEST_DELAY_SECONDS,
 ) -> FetchSummary:
     """Populate an open cache with gnomAD records for `variants`.
 
+    `variants` is anything record_adapter.to_variant_keys accepts: VariantKey
+    objects, id strings, 4-tuples, row mappings, a dataframe, or a VCF path.
+    Coercing here rather than in each caller means every entry point takes the
+    same inputs.
+
     The cache is left open: it belongs to the caller, who may well want to
     export from it next.
     """
+    variants = to_variant_keys(variants)
     variants_to_fetch = cache.needs_query(
         variants,
         retry_errors=retry_errors,
@@ -136,14 +142,3 @@ def fetch_into(
             f"errors; re-run to retry them."
         )
     return summary
-
-
-def fetch_gnomad(
-    variants: list[VariantKey],
-    cache_file: str | Path,
-    **kwargs: Any,
-) -> FetchSummary:
-    """Populate a cache file with gnomAD records for `variants`,
-    creating the cache if it does not exist."""
-    with VariantCache(cache_file) as cache:
-        return fetch_into(cache, variants, **kwargs)

{gnomad_api_cache-0.1.0 → gnomad_api_cache-0.2.0}/src/gnomad_api_cache/keys.py

@@ -11,6 +11,10 @@ _ALLELE_RE = re.compile(r"^[ACGTN]+$")
 class InvalidVariantError(ValueError):
     """Raised when a record cannot be expressed as a gnomAD variant ID."""
 
+    def __init__(self, message: str, reason: str = "invalid") -> None:
+        super().__init__(message)
+        self.reason = reason
+
 
 def normalize_chrom(chrom: str) -> str:
     """Canonicalize a contig name to the form gnomAD expects."""
@@ -55,24 +59,35 @@ class VariantKey:
         a = str(alt).strip().upper()
 
         if c not in CANONICAL_CHROMS:
-            raise InvalidVariantError(f"non-canonical contig: {chrom!r}")
+            raise InvalidVariantError(
+                f"non-canonical contig: {chrom!r}", "non_canonical_contig"
+            )
         try:
             p = int(pos)
         except (TypeError, ValueError):
-            raise InvalidVariantError(f"non-integer position: {pos!r}") from None
+            raise InvalidVariantError(
+                f"non-integer position: {pos!r}", "non_integer_position"
+            ) from None
         if p < 1:
-            raise InvalidVariantError(f"position must be 1-based: {pos!r}")
+            raise InvalidVariantError(
+                f"position must be 1-based: {pos!r}", "non_positive_position"
+            )
         if not _ALLELE_RE.match(r):
-            raise InvalidVariantError(f"non-ACGTN ref allele: {ref!r}")
+            raise InvalidVariantError(f"non-ACGTN ref allele: {ref!r}", "non_acgtn_ref")
         if not _ALLELE_RE.match(a):
-            raise InvalidVariantError(f"non-ACGTN alt allele: {alt!r}")
+            raise InvalidVariantError(f"non-ACGTN alt allele: {alt!r}", "non_acgtn_alt")
 
         return cls(chrom=c, pos=p, ref=r, alt=a)
 
     @classmethod
     def from_id(cls, variant_id: str) -> VariantKey:
-        """Parse a "chrom-pos-ref-alt" string, e.g. from a text file or the cache."""
-        parts = str(variant_id).strip().split("-")
+        """Parse a "chrom-pos-ref-alt" or "chrom:pos:ref:alt" ID string into a VariantKey."""
+        text = str(variant_id).strip()
+        parts = text.split("-")
+        if len(parts) != 4 and ":" in text:
+            parts = text.split(":")
         if len(parts) != 4:
-            raise InvalidVariantError(f"expected chrom-pos-ref-alt, got {variant_id!r}")
+            raise InvalidVariantError(
+                f"expected chrom-pos-ref-alt, got {variant_id!r}", "malformed_id"
+            )
         return cls.from_parts(*parts)

gnomad_api_cache-0.1.0/src/gnomad_api_cache/__init__.py

@@ -1,35 +0,0 @@
-"""Fetch and cache gnomAD annotations for VCF variants.
-
-    from gnomad_api_cache import VariantCache, read_vcf
-
-    with VariantCache("gnomad.sqlite") as cache:
-        print(cache.fetch_vcf("cohort.vcf.gz"))
-        cache.to_parquet("annotations.parquet")
-"""
-
-from __future__ import annotations
-
-from gnomad_api_cache.adapters.vcf_adapter import (
-    BuildMismatchError,
-    iter_variant_keys,
-    read_vcf,
-)
-from gnomad_api_cache.cache import VariantCache
-from gnomad_api_cache.fetch import FetchSummary, fetch_gnomad
-from gnomad_api_cache.keys import InvalidVariantError, VariantKey
-from gnomad_api_cache.query import DEFAULT_DATASET, QUERY_VERSION
-
-__version__ = "0.1.0"
-
-__all__ = [
-    "DEFAULT_DATASET",
-    "QUERY_VERSION",
-    "BuildMismatchError",
-    "FetchSummary",
-    "InvalidVariantError",
-    "VariantCache",
-    "VariantKey",
-    "fetch_gnomad",
-    "iter_variant_keys",
-    "read_vcf",
-]

gnomad_api_cache-0.1.0/src/gnomad_api_cache/adapters/vcf_adapter.py

@@ -1,147 +0,0 @@
-"""Read a VCF into VariantKey objects."""
-
-from __future__ import annotations
-
-import logging
-from collections import Counter
-from collections.abc import Callable, Iterator
-from pathlib import Path
-
-from cyvcf2 import VCF, Variant
-
-from gnomad_api_cache.keys import (
-    CANONICAL_CHROMS,
-    InvalidVariantError,
-    VariantKey,
-    normalize_chrom,
-)
-
-log = logging.getLogger(__name__)
-
-# Use chr1 to detect build
-CHR1_LENGTH_BY_BUILD = {248956422: "GRCh38", 249250621: "GRCh37"}
-
-
-class BuildMismatchError(RuntimeError):
-    """Raised when a VCF is not on the build the target gnomAD dataset uses."""
-
-
-def detect_build(vcf: VCF) -> str | None:
-    """Return "GRCh38", "GRCh37", or None if the header doesn't say."""
-    lengths: dict[str, int] = dict(zip(vcf.seqnames, vcf.seqlens))
-    chr1 = lengths.get("chr1") or lengths.get("1")
-    if chr1 is None:
-        return None
-    return CHR1_LENGTH_BY_BUILD.get(chr1)
-
-
-def is_normalized(vcf: VCF) -> bool:
-    """True if the header shows bcftools norm was run."""
-    return any(
-        line.startswith("##bcftools_norm") for line in vcf.raw_header.split("\n")
-    )
-
-
-def _skip_reason(alt: str, chrom: str) -> str | None:
-    """Return why this allele can't become a gnomAD ID, or None if it can."""
-    if alt.startswith("<"):
-        return "symbolic"  # <DEL>, <NON_REF>, <*>
-    if "[" in alt or "]" in alt:
-        return "breakend"
-    if alt == "*":
-        return "spanning_deletion"
-    if normalize_chrom(chrom) not in CANONICAL_CHROMS:
-        return "non_canonical_contig"  # *_random, chrUn_*, HLA-*
-    return None
-
-
-def iter_variant_keys(
-    path: str | Path,
-    *,
-    require_build: str | None = "GRCh38",
-    warn_unnormalized: bool = True,
-    filter_function: Callable[[Variant], bool] | None = None,
-) -> Iterator[VariantKey]:
-    """Yield one VariantKey per ALT allele of every record in `path`."""
-    vcf = VCF(str(path))
-
-    build = detect_build(vcf)
-    if require_build is not None:
-        if build is None:
-            log.warning(
-                "%s: could not determine build from header; assuming %s",
-                path,
-                require_build,
-            )
-        elif build != require_build:
-            raise BuildMismatchError(
-                f"{path}: VCF is {build}, expected {require_build}. "
-                + "Lift over first, or target a matching gnomAD dataset."
-            )
-
-    if warn_unnormalized and not is_normalized(vcf):
-        log.warning(
-            "%s: no ##bcftools_norm header. Unnormalized indels will silently "
-            + "miss in gnomAD. Run: bcftools norm -f <ref.fa> -m -any",
-            path,
-        )
-
-    skipped: Counter[str] = Counter()
-    yielded = 0
-
-    # main loop
-    for record in vcf:
-        if filter_function is not None and not filter_function(record):
-            continue
-
-        for alt in record.ALT:  # empty list when ALT is "."
-            reason = _skip_reason(alt, record.CHROM)
-            if reason is not None:
-                skipped[reason] += 1
-                continue
-            try:
-                key = VariantKey.from_parts(record.CHROM, record.POS, record.REF, alt)
-            except InvalidVariantError as e:
-                skipped["invalid"] += 1
-                log.debug(
-                    "skipping %s:%s %s>%s -- %s",
-                    record.CHROM,
-                    record.POS,
-                    record.REF,
-                    alt,
-                    e,
-                )
-                continue
-            yielded += 1
-            yield key
-
-    vcf.close()
-
-    if skipped:
-        log.info(
-            "%s: %d keys, %d alleles skipped (%s)",
-            path,
-            yielded,
-            sum(skipped.values()),
-            ", ".join(f"{k}={v}" for k, v in sorted(skipped.items())),
-        )
-    else:
-        log.info("%s: %d keys", path, yielded)
-
-
-def read_vcf(
-    path: str | Path,
-    *,
-    require_build: str | None = "GRCh38",
-    warn_unnormalized: bool = True,
-    filter_function: Callable[[Variant], bool] | None = None,
-) -> list[VariantKey]:
-    """Eager convenience wrapper around iter_variant_keys."""
-    return list(
-        iter_variant_keys(
-            path,
-            require_build=require_build,
-            warn_unnormalized=warn_unnormalized,
-            filter_function=filter_function
-        )
-    )