clinvar-database

ClinVar データベース

前提条件

1. uv：uv スキルを読み、セットアップの手順に従って、uv がインストールされ、PATH に設定されていることを確認してください。
2. ユーザーへの通知：ワークスペースのルートディレクトリに .licenses/clinvar_database_LICENSE.txt がまだ存在しない場合は、（1）https://www.ncbi.nlm.nih.gov/clinvar/ の利用条件を確認するよう、ユーザーに目立つ形で通知し、（2）通知内容とタイムスタンプを記録したファイルを作成してください。
3. .env ファイル：ホームディレクトリに .env ファイルがあることを確認してください。存在しない場合は作成してください。
4. NCBI_API_KEY（任意）：NCBI のレート制限が毎秒 3 リクエストから 10 リクエストに引き上げられます。このスキルはキーがなくても動作しますが、多くのクエリを実行する予定がある場合や、429 エラーが発生した場合は、キーの利用をおすすめします。キーは https://www.ncbi.nlm.nih.gov/account/settings/ で無料登録できます。このスキルがユーザーのリクエストに関連する場合、キーの有無を確認し、ユーザーにキーを依頼するには、credentials スキルの安全な認証情報プロトコルを必ず使用してください。

概要

ClinVar は、ヒトのゲノム変異に関する臨床的分類の主要なコンセンサス記録です。世界各地の検査機関による評価に基づき、病原性ラベル（Pathogenic、Likely Pathogenic、Benign、VUS）の「臨床的な正解」を提供します。

使用する場面

次のような場合に使用してください：

• 特定の変異について、現在の臨床的意義とスター評価（レビュー状況）を確認する。
• 過去の臨床検査機関による分類について、臨床医の注記、評価基準、根拠を取得する。
• 特定の変異について、優先される疾患名と関連する HPO 用語を取得する。
• 変異の一覧を取得する（例：「シグナルから 50bp 以内にある HBB 遺伝子の Pathogenic 変異をすべて探す」）。
• 特定の変異について解釈の相違を確認し、各分類を提出した組織を特定する。

次のような場合には使用しないでください：

• 世界の集団における特定のアレル頻度を調べる（gnomAD を使用してください）。
• タンパク質の通常の生物学的役割や一般的な遺伝形式を説明する（OMIM を使用してください）。
• フレームシフトやエクソンスキッピングなど、新規変異の機序的影響を予測する（AlphaGenome を使用してください）。
• 病原性変異を持つ患者に推奨されるサーベイランスのスケジュールを調べる（GeneReviews を使用してください）。
• 影響を受けるタンパク質の 3D 構造モデルを生成または表示する（PDB / AlphaFold を使用してください）。

クイックスタート

ClinVar のクエリは、厳格なレート制限と XML/JSON の解析に対応する、堅牢な Python ラッパースクリプトを通じて実行します。

例：BRCA1 の変異を検索する

uv run scripts/clinvar_api.py search --query "BRCA1[gene]" --output results.json

基本ルール

• Retmax の制約：検索コマンドのデフォルトは --retmax 200 です。「すべて一覧表示」や遺伝子全体を対象とするリクエストでは、データを漏れなく取得するために、--retmax を明示的により大きい値（例：1000）に設定する必要があります。
• ラッパーを使用する：標準的なクエリにはラッパースクリプトを優先して使用してください。レート制限、再試行、複雑な XML 解析を処理します。スクリプトで解析された出力に必要なフィールドが含まれていない場合は、スクリプトを変更するか、NCBI E-utilities API に直接クエリを送信できます。ただし、生の XML スキーマは複雑で、レコードの種類によって異なる点に注意してください。
• レート制限に達すると、スクリプトは明確なエラーを表示します。ユーザーが .env ファイルに NCBI_API_KEY を追加できるよう、キーの有無を確認して依頼する際は、credentials スキルの安全な認証情報プロトコルを必ず使用してください。
• 通知：このスキルを使用した場合は、その旨を出力に記載してください。

ユーティリティスクリプト

1. count — 一致するバリアントの件数を数える

目的： ID を取得せずに、クエリに一致するバリアントの件数を確認します。完全な search を実行するかどうかを判断する際に使用します。

引数：

• --query：（必須）NCBI Entrez 検索クエリ文字列。
• --output：（必須）出力 JSON ファイルのパス。

例： uv run scripts/clinvar_api.py count \ --query "TP53[gene] AND \"uncertain significance\"[clinsig]" \ --output count.json 出力： {"total_count": <int>}

2. search — バリアントを検索する

目的： NCBI Entrez の検索構文を使用し、ゲノム上の位置、遺伝子記号、または臨床属性に基づいてバリアントを特定します。検索コマンドは、一致するすべての結果を確実かつ再現性のある形で取得できるよう、自動的にページネーションを実行します。

# Fetch ALL matching variants (default behavior)
uv run scripts/clinvar_api.py search \
  --query "BRCA1[gene]" --output results.json

# Search by Chromosome and Position Range
uv run scripts/clinvar_api.py search \
  --query "11[chr] AND 5225000:5226000[chrpos]" --output results.json

# Combine terms using Entrez syntax
uv run scripts/clinvar_api.py search \
  --query "HBB[gene] AND pathogenic[clinsig]" --output results.json

# Cap results at 50
uv run scripts/clinvar_api.py search \
  --query "TP53[gene]" --retmax 50 --output results.json

引数：

• --query：（必須）NCBI Entrez 検索クエリ文字列。
• --retmax：返すバリアント ID の最大合計数。デフォルトは 0 で、「一致する結果をすべて取得する」ことを意味します。 結果数に上限を設けるには、正の整数を設定します。
• --page_size：API リクエストごとに取得する ID の数（デフォルト：500、NCBI の制限により最大：10000）。
• --output：（必須）出力 JSON ファイルのパス。

出力： 以下を含む JSON オブジェクト：

• total_count — ClinVar で一致するバリアントの合計数。
• fetched_count — 実際に取得した ID の数。
• variant_ids — ClinVar Variation ID 文字列のリスト。

3. summary — 解釈の概要を取得する

目的： バリアントを迅速にスクリーニングするために、主要な臨床的意義のラベル、スター評価（レビュー状況）、基本的な表現型データを取得します。

# Get summary for one or more Variation IDs
uv run scripts/clinvar_api.py summary \
  --variant_ids 12345 67890 --output summary.json

引数：

• --variant_ids：（必須）1 つ以上の ClinVar Variation ID。
• --output：（必須）出力 JSON ファイルのパス。

出力： 概要オブジェクトの JSON リスト。各オブジェクトには以下が含まれます：

• variant_id、title、clinical_significance、review_status、
  last_evaluated、phenotypes
• genes — {gene_id, symbol, strand} のリスト
• variation_type — 例：一塩基バリアント、欠失、挿入
• molecular_consequences — 文字列のリスト（例：["ミスセンスバリアント",
  "ナンセンス"]）

4. evidence — 臨床的エビデンスを取得する

目的： 自由記述の臨床医による根拠、アサーションの方法、提出者による具体的な注記など、単一バリアントの完全な臨床記録を取得します。

# Get full evidence for a single Variation ID
uv run scripts/clinvar_api.py evidence \
  --variant_id 12345 --output evidence.json

引数：

• --variant_id：（必須）単一の ClinVar Variation ID。
• --output：（必須）出力 JSON ファイルのパス。

出力： 以下を含む JSON オブジェクト：

• variant_id
• allele_info — {chromosome, position_start, position_stop, reference_allele, alternate_allele, cytogenetic_band, dbsnp_rsid}（GRCh38 を優先）
• conditions — {name, medgen_cui, omim_id, orphanet_id, hpo_terms} のリスト
• functional_consequences — {value, sequence_ontology_id} のリスト
• structural_variant_details — {outer_start, inner_start, inner_stop, outer_stop, copy_number}（CNV の場合のみ存在し、それ以外では null）
• citation_references — グローバルな「Citations」セクションで引用されている PubMed ID のリスト
• submissions — 提出者ごとの記録のリスト。各記録には以下が含まれます：
  • submitter_name、classification、curator_notes、 assertion_criteria
  • date_last_evaluated — 提出者が分類を最後にレビューした日付

一般的なワークフロー

件数確認を先に行うワークフロー（推奨）

結果数が多い、または不明な場合は、まず count を使用して続行するかどうかを判断し、次に search（自動でページネーションを実行し、total_count / fetched_count を返します）を実行してから、summary でスクリーニングします。

# Step 1: Gauge size (optional — search also returns total_count)
uv run scripts/clinvar_api.py count \
  --query "HBB[gene] AND pathogenic[clinsig]" --output count.json

# Step 2: Fetch all variant IDs (auto-paginates)
uv run scripts/clinvar_api.py search \
  --query "HBB[gene] AND pathogenic[clinsig]" --output ids.json

# Step 3: Get summaries (extract variant_ids from search output)
uv run scripts/clinvar_api.py summary \
  --variant_ids 12345 67890 --output summary.json

詳細調査：search → evidence

特定のバリアントについて、提出者による根拠、PubMed の引用、オントロジーに関連付けられた疾患、アレルの座標など、臨床像の全体を把握する必要がある場合は、evidence を使用します。

uv run scripts/clinvar_api.py evidence \
  --variant_id 12345 --output evidence.json

ワークフロー：バリアントを確実に発見するための三角測量

ClinVar のメタデータには一貫性がありません。「すべてを列挙する」というリクエストに対応する際は、単一のフィルターに頼らず、1 回のターンで以下を実行し、結果を統合してください。

1. 正確なラベルで検索（例："3 prime UTR variant"[molecular_consequence]）。
2. HGVS 表記パターンで検索（例：c.*）。
3. ゲノム座標範囲で検索（[chrpos] を使用）。

この「三角測量」により、ラベルが欠落している構造バリアントも見落とさずに済みます。

HGVS によるコーディング領域か非コーディング領域かの確認

molecular_consequences だけでは曖昧な場合があります（例：splice donor variant はコーディング領域と非コーディング領域の両方に現れます）。HGVS パターンについては、必ず title フィールドも照合してください。

• c.-… — 5' UTR（非コーディング）
• c.*… — 3' UTR（非コーディング）
• c.123+N / c.123-N — イントロン（非コーディング）
• p.Trp146Arg など — タンパク質への影響（コーディング）

UTR／イントロンの HGVS 表記があり、p. アノテーションがないバリアントは、スプライシングのラベルが付いていても非コーディングです。反対に、p. アノテーションがあれば、コーディング領域への影響を示します。

ClinVar メタデータのリファレンス

• 3' UTR
  • 検索文字列："3 prime UTR variant"[mol_consequence]
  • HGVS：c.*
• 5' UTR
  • 検索文字列："5 prime UTR variant"[mol_consequence]
  • HGVS：c.-
• 「信頼度の高い」バリアントや専門家によるレビュー済みのコンセンサスを見つけるには、review_status フィルターを使用してください。これにより、単一ラボによる主張と、パネルレビュー済みの確定情報を最も効率よく区別できます。

使用するフィールド

• 病原性を手早く確認 — summary → clinical_significance を使用
• 遺伝子記号と鎖 — summary → genes を使用
• バリアントの種類（SNV、欠失など） — summary → variation_type を使用
• タンパク質レベルの影響 — summary → molecular_consequences を使用
• ゲノム座標（GRCh38） — evidence → allele_info を使用
• 関連する疾患（オントロジー） — evidence → conditions を使用
• SO 機能的影響 — evidence → functional_consequences を使用
• CNV のブレークポイント／コピー数 — evidence → structural_variant_details を使用
• PubMed の参考文献 — evidence → citation_references を使用
• ラボによる最終レビュー日 — last_evaluated の両方を使用
• 臨床医による根拠 — evidence → submissions[].curator_notes を使用

ゲノム座標の取得（デフォルトは HG38/GRCh38）

正確なゲノム座標を <chrom>:<pos>:<ref>><alt> の形式（例：chr5:70951945:G>A）で取得するには、evidence コマンドを使用する必要があります。これらの詳細は summary の出力には含まれません。

バリアントを列挙または提示する際は、ユーザーから明示的に求められていない場合でも、必ずゲノム座標を <chrom>:<pos>:<ref>><alt> の形式で含めてください。座標が summary にない場合は、evidence コマンドまたは dbSNP のフォールバックを使用して取得してください。

1. Evidence を取得：uv run scripts/clinvar_api.py evidence --variant_id <ID> --output evidence.json を使用します。
2. VCF 属性を抽出：evidence コマンドは XML を解析します。以下を抽出してください。
   • 染色体：Chr
   • 位置：positionVCF（または start）
   • Ref：referenceAlleleVCF（または referenceAllele）
   • Alt：Assembly="GRCh38" の SequenceLocation 要素から取得する alternateAlleleVCF（または alternateAllele）。

精度の低い座標（遺伝子範囲）のフォールバック： ClinVar は、非コーディングバリアントに対して遺伝子全体の範囲を返すことがよくあります。抽出した座標が特定の位置ではなく遺伝子範囲を示している場合は、dbsnp-database スキルを使用し、dbsnp_rsid または HGVS タイトルから正確な座標を特定してください。1. evidence の出力に dbsnp_rsid があるか確認します。2. uv run scripts/dbsnp_cli.py resolve-rsid {rsid} を実行して、正確な GRCh38 座標を取得します。3. dbSNP の SPDI または HGVS データを使用して、<chrom>:<pos>:<ref>><alt> の形式にします。

構造バリアントに関する注意

structural_variant_details フィールドが設定されるのは、コピー数バリアント （CNV）のみです。標準的な SNV や小さなインデルでは、このフィールドは null になります。 代わりに、allele_info フィールド（position_start、position_stop、 reference_allele、alternate_allele）を使用してください。

CNV／大規模欠失に関する注意

大規模なコピー数バリアント（CNV）では、molecular_consequences が空の場合が よくあります。バリアントのタイトルに「del」が含まれ、座標が対象領域と重複している場合は、 ラベルがなくても関連性があります。

API キーの取得と使用

https://www.ncbi.nlm.nih.gov/account/settings/ で無料のキーを登録できます。このスキルが ユーザーのリクエストに関連していると思われる場合は、必ず credentials スキルの安全な 認証情報プロトコルを使用して、このキーがあるかを確認し、必要に応じて取得を依頼してください。

ベストプラクティス

• python の実行には、必ず uv run を使用してください。
• jq が使用できない場合は、すぐに Python のワンライナーで JSON を処理してください （例：uv run python3 -c "import json; ..."）。
• 結果セットのサイズを把握するため、search の前に count を使用してください。
• search コマンドはデフォルトですべての結果を取得し、出力に total_count と fetched_count を含めます。取得が完全であることを確認するため、必ずこれらが一致するか 確認してください。
• Entrez の結果はソートされていません。日付順に並べるには、すべての結果を取得し、 last_evaluated でローカルにソートしてください。

よくある間違い

• E-utilities の XML を自分で解析しようとする — 予測できない XML スキーマを 堅牢に処理する、付属の clinvar_api.py クライアントを必ず使用してください。
• HTTP 429 Too Many Requests が発生する — クライアントは一時停止を指示する例外を スローします。必ず credentials スキルの安全な認証情報プロトコルを使用して NCBI_API_KEY があるかを確認し、ユーザーが .env ファイルに追加できるよう取得を依頼してから、 再試行してください。
• 生の DNA 配列を API に送信する — API が受け付けるのは HGVS 命名法、RS ID、 または適切な Entrez 座標構文（11[chr] AND 1234[chrpos]）です。生の ATCG 文字列は 受け付けません。
• 同義変異や非コード変異の場合 — 多くの ClinVar レコードでは正確なゲノム上の位置情報が 欠けているため、HGVS 命名法（例：CAPN3 AND "c.551C>T"）のほうが座標検索（[chrpos]）よりも 信頼性が高くなります。
• 分子影響の大文字と小文字の違い — ClinVar は大文字と小文字が混在する文字列を返します。 フィルタリング時には、必ず大文字と小文字を区別しない照合（.lower()）を使用してください。
• search の出力を単なるリストとして解析する — search が返すのは total_count、fetched_count、variant_ids を含む JSON オブジェクトであり、単なるリストではありません。