gnomad-api-cache 0.1.0__tar.gz

gnomad_api_cache-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true -diff

gnomad_api_cache-0.1.0/.github/workflows/workflow.yml

@@ -0,0 +1,109 @@
+name: Publish to PyPI
+
+# Build once, verify that single artifact across the whole supported Python
+# range, then publish it: TestPyPI on a manual run (a dry run you can repeat),
+# PyPI when a GitHub Release is published. Authentication is PyPI Trusted
+# Publishing (OIDC) — no API tokens and no stored secrets.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+# Least privilege by default; the two publish jobs opt into id-token below.
+permissions:
+  contents: read
+
+# Never let two publish runs race for the same version.
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Install build backend
+        run: python -m pip install --upgrade build
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Check metadata renders on PyPI
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  verify:
+    name: Verify wheel on Python ${{ matrix.python-version }}
+    needs: build
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install the built wheel
+        run: |
+          WHEEL=$(ls dist/*.whl)
+          python -m pip install "${WHEEL}"
+      - name: Smoke-test both entry points
+        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"
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: [build, verify]
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/gnomad-api-cache
+    permissions:
+      id-token: write          # required for OIDC trusted publishing
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [build, verify]
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gnomad-api-cache
+    permissions:
+      id-token: write          # required for OIDC trusted publishing
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

gnomad_api_cache-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+# pixi environments
+.pixi/*
+!.pixi/config.toml
+
+# pycache
+__pycache__/
+
+# scratch
+scratch/
+
+# data
+data/

gnomad_api_cache-0.1.0/LICENSE

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

gnomad_api_cache-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: gnomad-api-cache
+Version: 0.1.0
+Summary: Fetch and cache gnomAD annotations for VCF variants.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cyvcf2<0.35,>=0.34.0
+Requires-Dist: pyarrow<26,>=25.0.0
+Requires-Dist: requests<3,>=2.32
+Requires-Dist: tqdm<5,>=4.66
+Description-Content-Type: text/markdown
+
+# gnomad-api-cache
+
+Fetch gnomAD annotations for the variants in a VCF, cache them in SQLite, and
+export to various output formats (parquet, csv, tsv, json).
+
+The public gnomAD API allows roughly 10 requests (of 25 variants each) per minute. 
+Annotating a cohort twice — or exporting a second format — fetches from the locally 
+built cache rather than requerying. 
+
+Re-running into an existing cache fetches only what is missing.
+
+## Install
+
+```bash
+pip install gnomad-api-cache
+
+# or with uv
+uv pip install gnomad-api-cache    # into the active environment
+uv add gnomad-api-cache            # into a project
+uv tool install gnomad-api-cache   # just the CLI
+```
+
+Requires Python 3.11 or newer.
+
+## Usage
+
+### Command line
+
+Inputs are any VCF-like file (VCF, BCF, or bgzipped VCF) and a SQLite database to store the cache. The output retrieves all variants from the cache and writes them to a file in the specified format.
+```bash
+gnomad-api-cache -i cohort.vcf.gz -c gnomad.sqlite -o annotations.parquet
+```
+
+The output format is inferred from the file extension (`.csv`, `.tsv`,
+`.parquet`, `.json`, `.jsonl`) and can be forced with `-f`:
+
+```bash
+gnomad-api-cache -i cohort.vcf.gz -c gnomad.sqlite -o annotations.txt -f tsv
+```
+
+Omit `-o` to populate the cache without writing a table:
+
+```bash
+gnomad-api-cache -i cohort.vcf.gz -c gnomad.sqlite
+```
+
+`python -m gnomad_api_cache` accepts the same arguments. Run
+`gnomad-api-cache --help` for the full list, including `--dataset`,
+`--include-populations`, and `--require-build`.
+
+### Python
+
+```python
+from gnomad_api_cache import VariantCache
+
+with VariantCache("gnomad.sqlite") as cache:
+    summary = cache.fetch_vcf("cohort.vcf.gz")
+    print(summary)  # 1234 requested, 0 already cached, 1200 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:
+
+```python
+from cyvcf2 import Variant
+from gnomad_api_cache import VariantCache
+
+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)
+```
+
+An open cache is a read-only `Mapping` keyed by `chrom-pos-ref-alt`, so cached
+records are available without another request:
+
+```python
+record = cache["1-55051215-G-A"]  # None if gnomAD has no such variant
+print(len(cache), cache.status_counts())
+```
+
+## Acknowledgement & Citation
+
+This is an unofficial client. It queries the public gnomAD GraphQL API at
+<https://gnomad.broadinstitute.org/api> and is not affiliated with or endorsed
+by the Broad Institute or the gnomAD project. Please use the shared API
+considerately — the default delay between requests is set to stay within the
+documented rate limit.
+
+If you use gnomAD data obtained through this tool, cite the current flagship
+gnomAD paper. As of the latest release, it is as follows (v4 Preprint, Vancouver):
+
+> Guez J, Goodrich JK, Moldovan MA, Chao KR, Kar P, Panchal R, Wilson MW, Laricchia KM, Rohlicek G, Biba D, Marten D. Integrating 730,947 exome sequences with clinical literature improves gene discovery. Medrxiv. 2026 Mar 25. <https://doi.org/10.64898/2026.03.23.26349081>
+
+gnomAD data use terms: <https://gnomad.broadinstitute.org/terms>
+
+## License
+
+MIT — see [LICENSE](LICENSE).

gnomad_api_cache-0.1.0/README.md

@@ -0,0 +1,103 @@
+# gnomad-api-cache
+
+Fetch gnomAD annotations for the variants in a VCF, cache them in SQLite, and
+export to various output formats (parquet, csv, tsv, json).
+
+The public gnomAD API allows roughly 10 requests (of 25 variants each) per minute. 
+Annotating a cohort twice — or exporting a second format — fetches from the locally 
+built cache rather than requerying. 
+
+Re-running into an existing cache fetches only what is missing.
+
+## Install
+
+```bash
+pip install gnomad-api-cache
+
+# or with uv
+uv pip install gnomad-api-cache    # into the active environment
+uv add gnomad-api-cache            # into a project
+uv tool install gnomad-api-cache   # just the CLI
+```
+
+Requires Python 3.11 or newer.
+
+## Usage
+
+### Command line
+
+Inputs are any VCF-like file (VCF, BCF, or bgzipped VCF) and a SQLite database to store the cache. The output retrieves all variants from the cache and writes them to a file in the specified format.
+```bash
+gnomad-api-cache -i cohort.vcf.gz -c gnomad.sqlite -o annotations.parquet
+```
+
+The output format is inferred from the file extension (`.csv`, `.tsv`,
+`.parquet`, `.json`, `.jsonl`) and can be forced with `-f`:
+
+```bash
+gnomad-api-cache -i cohort.vcf.gz -c gnomad.sqlite -o annotations.txt -f tsv
+```
+
+Omit `-o` to populate the cache without writing a table:
+
+```bash
+gnomad-api-cache -i cohort.vcf.gz -c gnomad.sqlite
+```
+
+`python -m gnomad_api_cache` accepts the same arguments. Run
+`gnomad-api-cache --help` for the full list, including `--dataset`,
+`--include-populations`, and `--require-build`.
+
+### Python
+
+```python
+from gnomad_api_cache import VariantCache
+
+with VariantCache("gnomad.sqlite") as cache:
+    summary = cache.fetch_vcf("cohort.vcf.gz")
+    print(summary)  # 1234 requested, 0 already cached, 1200 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:
+
+```python
+from cyvcf2 import Variant
+from gnomad_api_cache import VariantCache
+
+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)
+```
+
+An open cache is a read-only `Mapping` keyed by `chrom-pos-ref-alt`, so cached
+records are available without another request:
+
+```python
+record = cache["1-55051215-G-A"]  # None if gnomAD has no such variant
+print(len(cache), cache.status_counts())
+```
+
+## Acknowledgement & Citation
+
+This is an unofficial client. It queries the public gnomAD GraphQL API at
+<https://gnomad.broadinstitute.org/api> and is not affiliated with or endorsed
+by the Broad Institute or the gnomAD project. Please use the shared API
+considerately — the default delay between requests is set to stay within the
+documented rate limit.
+
+If you use gnomAD data obtained through this tool, cite the current flagship
+gnomAD paper. As of the latest release, it is as follows (v4 Preprint, Vancouver):
+
+> Guez J, Goodrich JK, Moldovan MA, Chao KR, Kar P, Panchal R, Wilson MW, Laricchia KM, Rohlicek G, Biba D, Marten D. Integrating 730,947 exome sequences with clinical literature improves gene discovery. Medrxiv. 2026 Mar 25. <https://doi.org/10.64898/2026.03.23.26349081>
+
+gnomAD data use terms: <https://gnomad.broadinstitute.org/terms>
+
+## License
+
+MIT — see [LICENSE](LICENSE).