clarity-clinical

通过 Clarity Protocol 从 ClinVar 和 gnomAD 查询临床变异数据。 当用户询问 ClinVar 分类、临床意义、 致病性、gnomAD 频率、群体遗传学或基因的临床数据。 功能：按基因搜索临床变异，获得详细的变异注释。

## 概述（中文）

通过 Clarity Protocol 从 ClinVar 和 gnomAD 查询临床变异数据。
当用户询问 ClinVar 分类、临床意义、
致病性、gnomAD 频率、群体遗传学或基因的临床数据。
功能：按基因搜索临床变异，获得详细的变异注释。

## 原文

# 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:

```bash
python scripts/query_clinical.py
```

Filter by gene symbol:

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

Get details for a specific variant:

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

Get variant details in readable format:

```bash
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:

```bash
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