Clarity Clinical Skill

Access clinical variant annotations from ClinVar and population frequency data from gnomAD through Clarity Protocol's integrated database.

Quick Start

List all clinical variants:

python scripts/query_clinical.py

Filter by gene symbol:

python scripts/query_clinical.py --gene-symbol MAPT

Get details for a specific variant:

python scripts/query_clinical.py --gene MAPT --variant NM_005910.6:c.926C>T

Get variant details in readable format:

python scripts/query_clinical.py --gene MAPT --variant NM_005910.6:c.926C>T --format summary

Clinical Variant Fields

Each clinical variant includes:

• gene_symbol: HGNC gene symbol
• variant_notation: Full HGVS notation (transcript-based)
• clinvar_significance: Clinical significance classification (e.g., "Pathogenic", "Benign")
• clinvar_review_status: Review status stars (e.g., "criteria provided, multiple submitters")
• clinvar_last_evaluated: Date of last ClinVar evaluation
• gnomad_af: Allele frequency in gnomAD (population prevalence)
• gnomad_ac: Allele count in gnomAD
• gnomad_an: Total allele number in gnomAD
• fetched_at: When this data was retrieved from ClinVar/gnomAD

ClinVar Significance Values

• Pathogenic: Strong evidence for disease causation
• Likely pathogenic: Moderate evidence for disease causation
• Benign: Strong evidence of no disease causation
• Likely benign: Moderate evidence of no disease causation
• Uncertain significance: Insufficient evidence
• Conflicting interpretations: Disagreement among submitters

gnomAD Frequency Interpretation

• af < 0.0001: Very rare (< 0.01%)
• af < 0.001: Rare (< 0.1%)
• af < 0.01: Uncommon (< 1%)
• af >= 0.01: Common (>= 1%)

Rate Limits

• Anonymous (no API key): 10 requests/minute
• With API key: 100 requests/minute

To use an API key, set the CLARITY_API_KEY environment variable:

export CLARITY_API_KEY=your_key_here
python scripts/query_clinical.py --gene-symbol MAPT

Get your API key at https://clarityprotocol.io

Error Handling

404 Not Found: The specified gene/variant combination does not exist in the clinical database.

429 Rate Limit: You've exceeded the rate limit. The script will display how long to wait.

500 Server Error: The API server encountered an error. Try again later.

Timeout: The request took longer than 30 seconds.

Pagination

Clinical variant lists are paginated. The API returns a next_cursor field if more results are available.

Use Cases

• Check if a variant is pathogenic in ClinVar
• Get population frequency data for a mutation
• Compare clinical significance across variants in a gene
• Assess variant review status quality
• Filter common vs. rare variants using gnomAD