Gnomad Database

gnomAD Database

Overview

gnomAD is the largest publicly available collection of human genetic variation. gnomAD v4 contains exome sequences from 730,947 individuals and genome sequences from 76,215 individuals across diverse ancestries.

Key resources:

• Browser: https://gnomad.broadinstitute.org/
• GraphQL API: https://gnomad.broadinstitute.org/api
• Downloads: https://gnomad.broadinstitute.org/downloads

When to Use This Skill

• Variant frequency lookup: Checking if a variant is rare, common, or absent
• Pathogenicity assessment: Filtering benign common variants (ACMG BA1/BS1/PM2)
• Loss-of-function intolerance: pLI and LOEUF scores for gene constraint
• Population-stratified frequencies: Comparing allele frequencies across ancestries
• Constraint analysis: Identifying genes depleted of missense or LoF variation

Supporting Files

• [graphql_queries.md](references/graphql_queries.md) - Complete GraphQL query templates, population IDs, LoF annotation fields, in silico predictor IDs, Python helper with retry logic
• [variant_interpretation.md](references/variant_interpretation.md) - ACMG/AMP criteria thresholds, LoF assessment (LOFTEE), homozygous observations, in silico predictor score ranges, ancestry-specific considerations

GraphQL API

Endpoint: POST https://gnomad.broadinstitute.org/api

Datasets: gnomad_r4 (v4 exomes, GRCh38), gnomad_r4_genomes, gnomad_r3 (GRCh38), gnomad_r2_1 (GRCh37)

Query Variants by Gene

import requests

def query_gnomad_gene(gene_symbol, dataset="gnomad_r4", reference_genome="GRCh38"):
    """Fetch variants in a gene from gnomAD."""
    url = "https://gnomad.broadinstitute.org/api"
    query = """
    query GeneVariants($gene_symbol: String!, $dataset: DatasetId!, $reference_genome: ReferenceGenomeId!) {
      gene(gene_symbol: $gene_symbol, reference_genome: $reference_genome) {
        gene_id
        gene_symbol
        variants(dataset: $dataset) {
          variant_id
          pos
          ref
          alt
          consequence
          genome { af ac an ac_hom populations { id ac an af } }
          exome { af ac an ac_hom }
          lof
          lof_flags
          lof_filter
        }
      }
    }
    """
    variables = {"gene_symbol": gene_symbol, "dataset": dataset, "reference_genome": reference_genome}
    response = requests.post(url, json={"query": query, "variables": variables})
    return response.json()

# Filter to rare PTVs
result = query_gnomad_gene("BRCA1")
variants = result["data"]["gene"]["variants"]
rare_ptvs = [v for v in variants
    if v.get("lof") == "HC"
    and v.get("genome", {}).get("af", 1) < 0.001]

Query a Specific Variant

def query_gnomad_variant(variant_id, dataset="gnomad_r4"):
    """Fetch details for a variant (e.g., '17-43094692-G-A')."""
    url = "https://gnomad.broadinstitute.org/api"
    query = """
    query VariantDetails($variantId: String!, $dataset: DatasetId!) {
      variant(variantId: $variantId, dataset: $dataset) {
        variant_id
        chrom pos ref alt consequence lof rsids
        genome { af ac an ac_hom populations { id ac an af } }
        exome { af ac an ac_hom populations { id ac an af } }
        in_silico_predictors { id value flags }
        clinvar_variation_id
      }
    }
    """
    response = requests.post(url, json={"query": query, "variables": {"variantId": variant_id, "dataset": dataset}})
    return response.json()

Gene Constraint Scores

def query_gnomad_constraint(gene_symbol, reference_genome="GRCh38"):
    """Fetch constraint scores for a gene."""
    url = "https://gnomad.broadinstitute.org/api"
    query = """
    query GeneConstraint($gene_symbol: String!, $reference_genome: ReferenceGenomeId!) {
      gene(gene_symbol: $gene_symbol, reference_genome: $reference_genome) {
        gene_id gene_symbol
        gnomad_constraint {
          exp_lof exp_mis exp_syn obs_lof obs_mis obs_syn
          oe_lof oe_mis oe_syn oe_lof_lower oe_lof_upper
          lof_z mis_z syn_z pLI
        }
      }
    }
    """
    response = requests.post(url, json={"query": query, "variables": {"gene_symbol": gene_symbol, "reference_genome": reference_genome}})
    return response.json()

Constraint score interpretation:

LOEUF is preferred over pLI (less sensitive to sample size).

Population Frequency Analysis

import pandas as pd

def get_population_frequencies(variant_id, dataset="gnomad_r4"):
    """Extract per-population allele frequencies."""
    url = "https://gnomad.broadinstitute.org/api"
    query = """
    query PopFreqs($variantId: String!, $dataset: DatasetId!) {
      variant(variantId: $variantId, dataset: $dataset) {
        variant_id
        genome { populations { id ac an af ac_hom } }
      }
    }
    """
    response = requests.post(url, json={"query": query, "variables": {"variantId": variant_id, "dataset": dataset}})
    populations = response.json()["data"]["variant"]["genome"]["populations"]
    df = pd.DataFrame(populations)
    return df[df["an"] > 0].sort_values("af", ascending=False)

Population IDs: afr (African), ami (Amish), amr (Admixed American), asj (Ashkenazi Jewish), eas (East Asian), fin (Finnish), mid (Middle Eastern), nfe (Non-Finnish European), sas (South Asian)

Key Workflows

Variant Pathogenicity Assessment

1. Check population frequency (AF < 1% recessive, < 0.1% dominant) 2. Check ancestry-specific frequencies (variant rare overall may be common in one population) 3. Assess LoF confidence: lof field HC = high-confidence, LC = low-confidence 4. Apply ACMG: BA1 (AF > 5%), BS1 (AF > prevalence), PM2 (absent/very rare)

Gene Prioritization in Rare Disease

1. Query constraint scores for candidate genes 2. Filter pLI > 0.9 or LOEUF < 0.35 3. Cross-reference with observed LoF variants 4. Integrate with ClinVar

Best Practices

• Use gnomAD v4 (gnomad_r4) by default; v2 only for GRCh37 compatibility
• Handle null responses: absence in gnomAD is informative but not conclusive
• Distinguish exome vs genome data: genome has more uniform coverage
• Rate limit GraphQL queries: add delays between requests
• Check ac_hom for recessive disease analysis

Attribution

Adapted from K-Dense-AI/claude-scientific-skills (CC0-1.0). Original skill by Kuan-lin Huang.

gnomAD GraphQL Query Reference

API Endpoint

POST https://gnomad.broadinstitute.org/api
Content-Type: application/json

Body: { "query": "<graphql_query>", "variables": { ... } }

Dataset Identifiers

Core Query Templates

1. Variants in a Gene

query GeneVariants($gene_symbol: String!, $dataset: DatasetId!, $reference_genome: ReferenceGenomeId!) {
  gene(gene_symbol: $gene_symbol, reference_genome: $reference_genome) {
    gene_id
    gene_symbol
    chrom
    start
    stop
    variants(dataset: $dataset) {
      variant_id
      pos
      ref
      alt
      consequence
      lof
      lof_flags
      lof_filter
      genome {
        af
        ac
        an
        ac_hom
        populations { id ac an af ac_hom }
      }
      exome {
        af
        ac
        an
        ac_hom
        populations { id ac an af ac_hom }
      }
      rsids
      clinvar_variation_id
      in_silico_predictors { id value flags }
    }
  }
}

2. Single Variant Lookup

query VariantDetails($variantId: String!, $dataset: DatasetId!) {
  variant(variantId: $variantId, dataset: $dataset) {
    variant_id
    chrom
    pos
    ref
    alt
    consequence
    lof
    lof_flags
    rsids
    genome { af ac an ac_hom populations { id ac an af } }
    exome { af ac an ac_hom populations { id ac an af } }
    in_silico_predictors { id value flags }
    clinvar_variation_id
  }
}

Variant ID format: {chrom}-{pos}-{ref}-{alt} (e.g., 17-43094692-G-A)

3. Gene Constraint

query GeneConstraint($gene_symbol: String!, $reference_genome: ReferenceGenomeId!) {
  gene(gene_symbol: $gene_symbol, reference_genome: $reference_genome) {
    gene_id
    gene_symbol
    gnomad_constraint {
      exp_lof exp_mis exp_syn
      obs_lof obs_mis obs_syn
      oe_lof oe_mis oe_syn
      oe_lof_lower oe_lof_upper
      oe_mis_lower oe_mis_upper
      lof_z mis_z syn_z
      pLI
      flags
    }
  }
}

4. Region Query (by genomic position)

query RegionVariants($chrom: String!, $start: Int!, $stop: Int!, $dataset: DatasetId!, $reference_genome: ReferenceGenomeId!) {
  region(chrom: $chrom, start: $start, stop: $stop, reference_genome: $reference_genome) {
    variants(dataset: $dataset) {
      variant_id
      pos
      ref
      alt
      consequence
      genome { af ac an }
      exome { af ac an }
    }
  }
}

5. ClinVar Variants in Gene

query ClinVarVariants($gene_symbol: String!, $reference_genome: ReferenceGenomeId!) {
  gene(gene_symbol: $gene_symbol, reference_genome: $reference_genome) {
    clinvar_variants {
      variant_id
      pos
      ref
      alt
      clinical_significance
      clinvar_variation_id
      gold_stars
      major_consequence
      in_gnomad
      gnomad_exomes { ac an af }
    }
  }
}

Population IDs

LoF Annotation Fields

In Silico Predictor IDs

Common values for in_silico_predictors[].id:

• cadd — CADD PHRED score
• revel — REVEL score
• spliceai_ds_max — SpliceAI max delta score
• pangolin_largest_ds — Pangolin splicing score
• polyphen — PolyPhen-2 prediction
• sift — SIFT prediction

Python Helper

import requests
import time

def gnomad_query(query: str, variables: dict, retries: int = 3) -> dict:
    """Execute a gnomAD GraphQL query with retry logic."""
    url = "https://gnomad.broadinstitute.org/api"
    headers = {"Content-Type": "application/json"}

    for attempt in range(retries):
        try:
            response = requests.post(
                url,
                json={"query": query, "variables": variables},
                headers=headers,
                timeout=60
            )
            response.raise_for_status()
            result = response.json()

            if "errors" in result:
                print(f"GraphQL errors: {result['errors']}")
                return result

            return result
        except requests.exceptions.RequestException as e:
            if attempt < retries - 1:
                time.sleep(2 ** attempt)  # exponential backoff
            else:
                raise

    return {}

gnomAD Variant Interpretation Guide

Allele Frequency Thresholds for Disease Interpretation

ACMG/AMP Criteria

Notes:

• BA1 applies to most conditions; exceptions include autosomal dominant with high penetrance (e.g., LDLR for FH: BA1 threshold is ~0.1%)
• BS1 requires knowing disease prevalence; for rare diseases (1:10,000), BS1 if AF > 0.01%
• Homozygous counts (ac_hom) matter for recessive diseases

Practical Thresholds

Absence in gnomAD

A variant absent in gnomAD (ac = 0) is evidence of rarity, but interpret carefully:

• gnomAD does not capture all rare variants (sequencing depth, coverage, calling thresholds)
• A variant absent in 730K exomes is very strong evidence of rarity for PM2
• Check coverage at the position: if < 10x, absence is less informative

Loss-of-Function Variant Assessment

LOFTEE Classification (lof field)

• HC (High Confidence): Predicted to truncate functional protein
• Stop-gained, splice site (±1,2), frameshift variants
• Passes all LOFTEE quality filters

• LC (Low Confidence): LoF annotation with quality concerns
• Check lof_flags for specific reason
• May still be pathogenic — requires manual review

Common lof_flags

Homozygous Observations

The ac_hom field counts homozygous (or hemizygous in males for chrX) observations.

For recessive diseases:

• If a variant is observed homozygous in healthy individuals in gnomAD, it is strong evidence against pathogenicity (BS2 criterion)
• Even a single homozygous observation can be informative

Coverage at Position

Always check that gnomAD has adequate coverage at the variant position before concluding absence is meaningful. The gnomAD browser shows coverage tracks, and coverage data can be downloaded from:

• https://gnomad.broadinstitute.org/downloads#v4-coverage

In Silico Predictor Scores

Ancestry-Specific Considerations

• A variant rare overall may be a common founder variant in a specific population
• Always check all ancestry-specific AFs, not just the total
• Finnish and Ashkenazi Jewish populations have high rates of founder variants
• Report ancestry-specific frequencies when relevant to patient ancestry