Gnomad Database
- 1.2k installs
- 2.6k repo stars
- Updated July 7, 2026
- google-deepmind/science-skills
gnomad-database is a Google DeepMind science skill that retrieves gnomAD gene constraint metrics and variant allele frequencies via rate-limited wrapper scripts for developers building biological or medical AI prototypes
About
gnomad-database is a Google DeepMind science-skills module for querying the Genome Aggregation Database without hitting gnomAD APIs directly. Three uv-run helper scripts cover variant frequency by variant ID or rsID, gene constraint metrics including pLI and LOEUF (oe_lof_upper), and region or gene variant search with consequence filters. The skill mandates license notification to .licenses/gnomad_database_LICENSE.txt on first use and always routes queries through the bundled wrappers to enforce API rate limits gracefully. Outputs land as JSON files such as variant_frequency.json or gene_constraint.json for downstream agent reasoning. Reach for gnomad-database when you need population allele frequencies, loss-of-function intolerance scores, or regional variant lists—not somatic cancer tracking (COSMIC) or raw sequencing reads (ENA).
- Fetches gene constraint metrics (pLI, LOEUF, and related scores) via GraphQL
- Enforces a strict 10 queries-per-minute rate limit to respect API policy
- Built as a reusable CLI script with argparse for easy integration into agent workflows
- Depends on scienceskillscommon for standardized HTTP client behavior
- Outputs structured JSON results to a specified file path
Gnomad Database by the numbers
- 1,241 all-time installs (skills.sh)
- +166 installs in the week ending Aug 5, 2026 (Skillselion tracking)
- Ranked #270 of 2,064 Data Science & ML skills by installs in the Skillselion catalog
- Security screen: LOW risk (skills.sh audit)
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/google-deepmind/science-skills --skill gnomad-databaseAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 1.2k |
|---|---|
| repo stars | ★ 2.6k |
| Security audit | 3 / 3 scanners passed |
| Last updated | July 7, 2026 |
| Repository | google-deepmind/science-skills ↗ |
How do you query gnomAD gene constraint metrics?
Quickly retrieve accurate gene constraint metrics like pLI and LOEUF from the gnomAD database for biological or medical AI prototypes.
Who is it for?
Bioinformatics developers and medical AI engineers who need gnomAD constraint and variant frequency data via scripted, rate-limited queries.
Skip if: Skip gnomad-database for somatic cancer mutations, patient genome analysis, or workflows that require raw sequencing read access.
When should I use this skill?
User needs gnomAD variant frequency, pLI/LOEUF constraint metrics, or gene/region variant search for a genomic prototype.
What you get
JSON files with allele frequencies, pLI/LOEUF constraint scores, and variant search results
- variant_frequency.json
- gene constraint JSON
- region variant search JSON
By the numbers
- Bundles 3 helper scripts for gnomAD queries
- Supports variant lookup by chrom-pos-ref-alt ID or rsID
Files
gnomAD Database
Prerequisites
1. `uv`: Read the uv skill and follow its Setup instructions to ensure uv is installed and on PATH. 2. User Notification: If LICENSE_NOTIFICATION.txt does not already exist in this skill directory then (1) prominently notify the user to check the terms at https://gnomad.broadinstitute.org/policies and https://gnomad.broadinstitute.org/data#api, then (2) create the file recording the notification text and timestamp.
Core Rules
- Use the Wrapper: ALWAYS execute the provided helper scripts to query the
database rather than accessing the database directly. The scripts automatically enforce the gnomAD API rate limits gracefully.
- Notification: If this skill is used, ensure this is mentioned in the
output.
Utility Scripts
All scripts are located in the scripts/ subdirectory of this skill's installation directory. When running them, use the full absolute path to the script (e.g. /path/to/gnomad_database/scripts/get_variant_frequency.py).
1. Variant Frequency. Retrieves global and ancestry-specific allele frequencies, homozygote counts, and Grpmax Filtering AF (faf95/faf99) for exome, genome, and total (exome+genome combined) data. The filtering allele frequency (FAF) is the maximum credible genetic ancestry group AF (lower bound of the 95% or 99% CI). Variant ID format must be chrom-pos-ref-alt (e.g., 1-55516888-G-GA). Alternately, you may provide an rsID.
# By variant ID:
uv run scripts/get_variant_frequency.py --variant_id {variant_id} [--dataset {dataset}] --output variant_frequency.json
# By rsID (e.g., rs1800562):
uv run scripts/get_variant_frequency.py --rsid {rsid} [--dataset {dataset}] --output variant_frequency.json2. Gene Constraint. Retrieves constraint metrics for a gene. The response will explicitly contain pli, and the LOEUF score is represented by oe_lof_upper.
uv run scripts/get_gene_constraint.py --gene {gene_symbol} --output {gene_symbol}_constraint.json3. Region/Gene Variant Search. Finds all variants in a region or gene.
# By region:
uv run scripts/search_variants.py --chrom {chrom} --start {start} --end {end} --output region_variants.json
# By gene:
uv run scripts/search_variants.py --gene {gene_symbol} --consequence {pLoF|missense} --output {gene_symbol}_variants.jsonReferences
Further documentation on the data: https://gnomad.broadinstitute.org/data#api More general database documentation: https://gnomad.broadinstitute.org/help
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Fetches gene constraint metrics from gnomAD.
This script retrieves constraint metrics (pLI, LOEUF, etc.) for a given gene
from the gnomAD database using its GraphQL API. It enforces a rate limit
of 10 queries per minute to respect the API's usage policy.
"""
# /// script
# requires-python = ">=3.10"
# dependencies = [
# "scienceskillscommon",
# ]
# [tool.uv.sources]
# scienceskillscommon = { path = "../../scienceskillscommon" }
# ///
import argparse
import json
import os
from science_skills.skills.scienceskillscommon import http_client
# Respect 10 queries per minute requirement.
CLIENT = http_client.HttpClient("https://gnomad.broadinstitute.org", qps=0.1666)
def get_gene_constraint(
gene_symbol: str,
output_path: str,
):
"""Fetch gene constraint from gnomAD."""
url = "https://gnomad.broadinstitute.org/api"
query = """
query($geneSymbol: String!, $referenceGenome: ReferenceGenomeId!) {
gene(gene_symbol: $geneSymbol, reference_genome: $referenceGenome) {
gene_id
symbol
gnomad_constraint {
pli
oe_lof
oe_lof_lower
oe_lof_upper
oe_mis
oe_mis_lower
oe_mis_upper
}
}
}
"""
variables = {"geneSymbol": gene_symbol, "referenceGenome": "GRCh38"}
response_data = CLIENT.fetch_json(
url,
method="POST",
json_body={"query": query, "variables": variables},
)
result = json.dumps(response_data, indent=2)
os.makedirs(os.path.dirname(output_path), exist_ok=True)
with open(output_path, "w") as f:
f.write(result)
f.write("\n")
if __name__ == "__main__":
parser = argparse.ArgumentParser(
description="Fetch gene constraint from gnomAD"
)
parser.add_argument("--gene", required=True, help="Gene symbol (e.g. PCSK9)")
parser.add_argument(
"--output",
"-o",
required=True,
help="Output file path. Prints to stdout if not specified.",
)
args = parser.parse_args()
get_gene_constraint(args.gene, args.output)
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Fetches variant frequency from gnomAD."""
# /// script
# requires-python = ">=3.10"
# dependencies = [
# "scienceskillscommon",
# ]
# [tool.uv.sources]
# scienceskillscommon = { path = "../../scienceskillscommon" }
# ///
import argparse
import json
import os
import sys
from science_skills.skills.scienceskillscommon import http_client
# Respect 10 queries per minute requirement.
CLIENT = http_client.HttpClient("https://gnomad.broadinstitute.org", qps=0.1666)
def resolve_rsid(rsid: str, dataset: str) -> str:
"""Resolves an rsID to a variant ID."""
url = "https://gnomad.broadinstitute.org/api"
query = """
query($query: String!, $dataset: DatasetId!) {
variant_search(query: $query, dataset: $dataset) {
variant_id
}
}
"""
variables = {"query": rsid, "dataset": dataset}
response_data = CLIENT.fetch_json(
url, method="POST", json_body={"query": query, "variables": variables}
)
variants = response_data.get("data", {}).get("variant_search", [])
if not variants:
print(
json.dumps({"error": f"Could not resolve rsID {rsid}"}), file=sys.stderr
)
sys.exit(1)
# For simplicity, return the first match if multiple
return variants[0]["variant_id"]
def get_variant_frequency(
variant_id: str,
rsid: str,
dataset: str,
output_path: str,
):
"""Fetches variant frequency from gnomAD."""
if rsid and not variant_id:
variant_id = resolve_rsid(rsid, dataset)
elif not variant_id:
print(
json.dumps({"error": "Must provide either variant_id or rsid"}),
file=sys.stderr,
)
sys.exit(1)
url = "https://gnomad.broadinstitute.org/api"
# GraphQL query for variant frequency and filtering allele frequency
query = """
query($variantId: String!, $dataset: DatasetId!) {
variant(variantId: $variantId, dataset: $dataset) {
variant_id
rsids
exome {
ac
an
af
homozygote_count
hemizygote_count
faf95 {
popmax
popmax_population
}
faf99 {
popmax
popmax_population
}
populations {
id
ac
an
homozygote_count
hemizygote_count
}
}
genome {
ac
an
af
homozygote_count
hemizygote_count
faf95 {
popmax
popmax_population
}
faf99 {
popmax
popmax_population
}
populations {
id
ac
an
homozygote_count
hemizygote_count
}
}
joint {
ac
an
homozygote_count
hemizygote_count
faf95 {
popmax
popmax_population
}
faf99 {
popmax
popmax_population
}
}
}
}
"""
variables = {"variantId": variant_id, "dataset": dataset}
response_data = CLIENT.fetch_json(
url, method="POST", json_body={"query": query, "variables": variables}
)
result = json.dumps(response_data, indent=2)
os.makedirs(os.path.dirname(output_path), exist_ok=True)
with open(output_path, "w") as f:
f.write(result)
f.write("\n")
if __name__ == "__main__":
parser = argparse.ArgumentParser(
description="Fetch variant frequency from gnomAD"
)
parser.add_argument(
"--variant_id",
help="Variant ID in chrom-pos-ref-alt format",
)
parser.add_argument(
"--rsid",
help="Variant rsID (e.g. rs121918506)",
)
parser.add_argument(
"--dataset", default="gnomad_r4", help="gnomAD dataset to query"
)
parser.add_argument(
"--output",
"-o",
required=True,
help="Output file path.",
)
args = parser.parse_args()
get_variant_frequency(args.variant_id, args.rsid, args.dataset, args.output)
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Searches for variants in a gene or region from gnomAD."""
# /// script
# requires-python = ">=3.10"
# dependencies = [
# "scienceskillscommon",
# ]
# [tool.uv.sources]
# scienceskillscommon = { path = "../../scienceskillscommon" }
# ///
import argparse
import json
import os
import sys
from science_skills.skills.scienceskillscommon import http_client
# Respect 10 queries per minute requirement.
CLIENT = http_client.HttpClient("https://gnomad.broadinstitute.org", qps=0.1666)
def search_variants_gene(
gene_symbol: str,
consequence: str,
dataset: str,
output_path: str,
):
"""Searches for variants in a gene from gnomAD."""
url = "https://gnomad.broadinstitute.org/api"
query = """
query($geneSymbol: String!, $dataset: DatasetId!, $referenceGenome: ReferenceGenomeId!) {
gene(gene_symbol: $geneSymbol, reference_genome: $referenceGenome) {
variants(dataset: $dataset) {
variant_id
rsids
consequence
exome {
ac
an
af
homozygote_count
hemizygote_count
populations {
id
ac
an
homozygote_count
hemizygote_count
}
}
genome {
ac
an
af
homozygote_count
hemizygote_count
populations {
id
ac
an
homozygote_count
hemizygote_count
}
}
}
}
}
"""
variables = {
"geneSymbol": gene_symbol,
"dataset": dataset,
"referenceGenome": "GRCh38",
}
response_data = CLIENT.fetch_json(
url, method="POST", json_body={"query": query, "variables": variables}
)
data = response_data
if "data" in data and data["data"].get("gene"):
variants = data["data"]["gene"].get("variants", [])
if consequence:
variants = [
v
for v in variants
if consequence.lower() in (v.get("consequence") or "").lower()
]
data["data"]["gene"]["variants"] = variants
result = json.dumps(data, indent=2)
os.makedirs(os.path.dirname(output_path), exist_ok=True)
with open(output_path, "w") as f:
f.write(result)
f.write("\n")
def search_variants_region(
chrom: str,
start: int,
stop: int,
dataset: str,
output_path: str,
):
"""Searches for variants in a region from gnomAD."""
url = "https://gnomad.broadinstitute.org/api"
query = """
query($chrom: String!, $start: Int!, $stop: Int!, $dataset: DatasetId!, $referenceGenome: ReferenceGenomeId!) {
region(chrom: $chrom, start: $start, stop: $stop, reference_genome: $referenceGenome) {
variants(dataset: $dataset) {
variant_id
rsids
consequence
exome {
ac
an
af
homozygote_count
hemizygote_count
populations {
id
ac
an
homozygote_count
hemizygote_count
}
}
genome {
ac
an
af
homozygote_count
hemizygote_count
populations {
id
ac
an
homozygote_count
hemizygote_count
}
}
}
}
}
"""
variables = {
"chrom": str(chrom),
"start": int(start),
"stop": int(stop),
"dataset": dataset,
"referenceGenome": "GRCh38",
}
response_data = CLIENT.fetch_json(
url, method="POST", json_body={"query": query, "variables": variables}
)
result = json.dumps(response_data, indent=2)
os.makedirs(os.path.dirname(output_path), exist_ok=True)
with open(output_path, "w") as f:
f.write(result)
f.write("\n")
if __name__ == "__main__":
parser = argparse.ArgumentParser(
description="Search variants in a gene or region from gnomAD"
)
parser.add_argument("--gene", help="Gene symbol (e.g. PCSK9)")
parser.add_argument("--chrom", help="Chromosome")
parser.add_argument("--start", type=int, help="Start position")
parser.add_argument("--end", type=int, help="End position")
parser.add_argument(
"--consequence", help="Filter by consequence (e.g. pLoF, missense)"
)
parser.add_argument(
"--dataset", default="gnomad_r4", help="gnomAD dataset to query"
)
parser.add_argument("--output", "-o", required=True, help="Output file path.")
args = parser.parse_args()
if args.gene:
search_variants_gene(args.gene, args.consequence, args.dataset, args.output)
elif args.chrom and args.start and args.end:
search_variants_region(
args.chrom, args.start, args.end, args.dataset, args.output
)
else:
print(
json.dumps({
"error": "Must provide either --gene OR --chrom, --start, and --end"
}),
file=sys.stderr,
)
sys.exit(1)
Related skills
Microsoft FoundryDeploy, evaluate, and continuously improve Microsoft Foundry agents from a single agent interface.490k1.3k
Ai Research ReproductionOrchestrate trustworthy, auditable reproduction of deep learning repositories directly from their READMEs.176k511Run TrainSafely execute selected deep learning training commands with standardized evidence capture.176k511Explore RunSafely run isolated exploratory experiments with clear recording and conservative selection before committing changes.176k511Paper Context ResolverFetch precise reproduction-critical details like dataset splits, preprocessing steps, or evaluation protocols from the original academic paper when the repo README leav141k511Repo Intake And PlanScan unfamiliar AI research repositories and receive a minimal, trustworthy reproduction target before investing significant time.140k511How it compares
Use gnomad-database over generic API prompts when you need scripted, rate-limited gnomAD constraint and frequency exports for agent pipelines.
FAQ
Which gnomAD metrics does gnomad-database return?
gnomad-database retrieves gene constraint metrics including pLI and LOEUF (reported as oe_lof_upper) plus global and ancestry-specific allele frequencies, homozygote counts, and filtering allele frequency for variants.
Must gnomad-database use the bundled scripts?
gnomad-database requires always executing the provided uv-run wrapper scripts instead of calling gnomAD APIs directly. The wrappers enforce rate limits and write JSON output files for each query type.
Is Gnomad Database safe to install?
skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.