dbsnp-database

dbSNP データベース統合

前提条件

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

基本ルール

• ラッパーを使用する：データベースへのクエリには、独自の HTTP リクエストや curl リクエストを組み立てるのではなく、必ず提供されているラッパースクリプト scripts/dbsnp_cli.py を実行してください。このスクリプトはレート制限、再試行、JSON 解析を自動的に処理します。
• コマンドの選択：特定のバリアントの rsID を見つけるために search-region を使用しないでください。代わりに resolve-variant を使用してください。
• 出力サイズ：特に必要な場合を除き、get-variant で --full を使用しないでください。生のペイロードが 1 MB を超えることがあります。
• シェルの安全性：シェルによる展開エラーを防ぐため、HGVS 文字列は必ずシングルクォートで囲んでください。
• 通知：このスキルを使用した場合は、そのことを出力に必ず記載してください。

使用する場面

次のことが必要な場合に、このスキルを使用してください：

• ゲノムバリアントを標準 rsID に対応付ける（VCF 座標または HGVS 表記から）。
• rsID の要約データを取得する：バリアントの種類、遺伝子との関連、臨床的意義、集団ごとのアレル頻度。
• 特定のアセンブリ上で rsID をゲノム座標に変換する。
• 染色体領域内で既知のバリアントをすべて検索する。

次のことが必要な場合は使用しないでください：

• 提出者の根拠を含む臨床的病原性分類を取得する（clinvar-database を使用）。
• 集団由来別に層別化した正確な集団レベルのアレル頻度を取得する（gnomad-database を使用）。
• 新規変異の機能的影響を予測する（alphagenome-single-variant-analysis を使用）。
• バリアントの影響を受けるタンパク質の 3D 構造を表示する（alphafold-database-fetch-and-analyze / pdb-database を使用）。

コマンド選択ガイド

**最初の試行で適切なコマンドを選択してください。**ユーザーの入力に合ったサブコマンドを以下から選びます。通常、コマンド呼び出しは 1 回で十分です。

• ユーザーが次の情報を提示した場合：実行するコマンド
• rsID（例：rs7412、rs268）：get-variant
• ゲノム座標：chrom pos ref alt（例：8 19962213 C T）：resolve-variant
• HGVS 文字列（例：NC_000008.11:g.19962213del）：resolve-hgvs
• rsID を提示し、座標への変換を希望する場合：resolve-rsid
• 染色体領域（chrom start end）：search-region

注意

特定のバリアントの rsID を見つけるために search-region を使用しないでください。ユーザーが染色体、位置、参照アレル、代替アレル（4 つの値）を提示した場合は、resolve-variant を使用してください。これは直接的な 1 回の API 呼び出しで検索できます。search-region は位置範囲内のすべてのバリアントを調査する場合に限って使用し、数百から数千件の結果を返します。

クイックスタート

# Look up variant rs7412: type, gene, clinical significance, MAF
uv run scripts/dbsnp_cli.py get-variant rs7412 --output /tmp/rs7412.json

# Find the rsID for a variant at chr8:19962213 C>T
uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T \
  --output /tmp/resolve.json

すべてのサブコマンドは JSON をディスクに書き込みます。出力は必ず /tmp/ ディレクトリに保存してください。--output フラグは必須です。

コマンド

1. get-variant — バリアントレコードを取得

1 つの rsID の RefSNP レコードを取得します。デフォルトでは、出力は 最も有用なフィールドに絞られます。rs268 と 268 のどちらも指定できます。

uv run scripts/dbsnp_cli.py get-variant rs268 --output /tmp/rs268.json
uv run scripts/dbsnp_cli.py get-variant 268 --assembly GCF_000001405.40 \
  --output /tmp/rs268.json

引数：

• rsid（位置指定、必須）：RefSNP 識別子です。
• --assembly：RefSeq アセンブリアクセッション（デフォルト：GCF_000001405.40 = GRCh38）。
• --full：完全な未加工 JSON ペイロードを返します。下記の警告を参照してください。
• --output：出力ファイルのパス（デフォルト：/tmp/dbsnp_output.json）。

省略出力のフィールド：

• refsnp_id：数値の rsID
• variant_type：例：snv、ins、del、delins
• genes：遺伝子シンボル（遺伝子座名）のソート済みリスト
• clinical_significances：臨床的意義ラベルのリスト
• minor_allele_frequencies：研究名、アレル数、総数
• placements：指定したアセンブリ上のゲノム配置

警告

--full について： 未加工の RefSNP ペイロードは通常 50～500 KB で、臨床的に重要なバリアントのうち、登録が多いものでは 1 MB を超える場合があります。 省略出力に含まれないデータが特に必要な場合にのみ --full を使用してください。たとえば、次のようなデータです。

• すべての転写産物とタンパク質アイソフォームにわたる完全な HGVS 命名法。
• 個別の登録者情報とタイムスタンプを含む、完全な登録履歴。
• 研究内のサブ集団別の集団レベルのアレル頻度の内訳（例：集団別の gnomAD カウント）。
• 複数のアセンブリ（GRCh37 と GRCh38 の両方）にわたるゲノム配置の全データ。
• この rsID に統合された旧 rsID を示す統合履歴。

2. resolve-variant — ゲノム座標 → rsID

ゲノム座標（染色体、位置、参照アレル、代替アレル）からバリアントの rsID を特定します。ユーザーが 8 19962213 C T のように、スペース区切りの座標でバリアントを指定した場合に使用するコマンドです。

uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T \
  --output /tmp/resolve.json

引数：

• chrom（位置指定）：染色体番号（例：8）、または RefSeq 配列アクセッション （例：NC_000008.11）。染色体 X と Y は、それぞれ数値に置き換えて 23（X）、24（Y）として指定する必要があります。
• pos（位置指定）：1 を起点とするゲノム上の位置です。
• ref（位置指定）：参照アレル（例：C）です。
• alts（位置指定）：代替アレル（複数可）をカンマ区切りで指定します（例：T）。
• --assembly：RefSeq アセンブリアクセッション（デフォルト：GCF_000001405.40）。
• --output：出力ファイルのパス（デフォルト：/tmp/dbsnp_output.json）。

出力： {"rsids": ["12345", "67890"]}

3. resolve-rsid — rsID → ゲノム座標

既知の rsID について、特定のアセンブリ上のゲノム配置（配列 ID とアレルの詳細）を取得します。

uv run scripts/dbsnp_cli.py resolve-rsid rs7412 --output /tmp/coords.json

引数：

• rsid（位置指定）：RefSNP 識別子です。
• --assembly：RefSeq アセンブリアクセッション（デフォルト：GCF_000001405.40）。
• --output：出力ファイルのパス（デフォルト：/tmp/dbsnp_output.json）。

出力： {"rsid": "7412", "assembly": "...", "placements": [...]}

4. resolve-hgvs — HGVS → rsID

HGVS 表記に対応する rsID（複数可）を検索します。

uv run scripts/dbsnp_cli.py resolve-hgvs 'NC_000008.11:g.19962213del' \
  --output /tmp/hgvs.json

引数：

• hgvs（位置指定）：HGVS 文字列です。
• --assembly：RefSeq アセンブリアクセッション（デフォルト：GCF_000001405.40）。
• --output：出力ファイルのパス（デフォルト：/tmp/dbsnp_output.json）。

出力： {"rsids": ["12345"]}

ヒント

HGVS 文字列には、シェルが解釈する文字（コロンや大なり記号など）が含まれることがよくあります。シェルによる展開を防ぐため、必ずシングルクォートで囲んでください。

5. search-region — リージョン内のバリアント検索

範囲を指定した染色体領域内のすべての rsID を検索します。

uv run scripts/dbsnp_cli.py search-region 7 117100000 117300000 \
  --output /tmp/region.json

引数：

• chrom（位置引数）：染色体（例：7）。X 染色体には 23、Y 染色体には 24 を使用してください。
• start（位置引数）：開始位置。
• end（位置引数）：終了位置。
• --retmax：返す rsID の最大数（デフォルト：500、上限：5 000）。
• --output：出力ファイルのパス（デフォルト：/tmp/dbsnp_output.json）。

出力：

{
  "rsids": ["12345", "67890", "..."],
  "returned": 500,
  "total_available": 1423,
  "truncated": true,
  "note": "Only 500 of 1423 variants returned.  Increase --retmax ..."
}

total_available が返された件数を上回る場合、出力には truncated フラグと note が含まれます。さらに取得するには --retmax の値を増やしてください（最大 5 000）。

典型的なワークフロー

座標から既知のバリアントを特定する

# Step 1: Map VCF coordinates to rsID
uv run scripts/dbsnp_cli.py resolve-variant 19 44908684 T C \
  --output /tmp/step1.json

# Step 2: Get the full details for the resolved rsID
uv run scripts/dbsnp_cli.py get-variant <rsid_from_step1> \
  --output /tmp/step2.json

遺伝子領域内のバリアントを調査する

# Step 1: Find all variants in a region spanning the CFTR gene
uv run scripts/dbsnp_cli.py search-region 7 117100000 117300000 \
  --retmax 1000 --output /tmp/region.json

# Step 2: Retrieve details on individual rsIDs of interest
uv run scripts/dbsnp_cli.py get-variant <rsid> --output /tmp/detail.json

HGVS 表記をゲノム座標に変換する

# Step 1: Get the rsID for an HGVS expression
uv run scripts/dbsnp_cli.py resolve-hgvs 'NC_000019.10:g.44908684T>C' \
  --output /tmp/hgvs.json

# Step 2: Resolve that rsID to VCF-style coordinates
uv run scripts/dbsnp_cli.py resolve-rsid <rsid> --output /tmp/coords.json

アセンブリのデフォルトと自動フォールバック

Variation Services のエンドポイント（get-variant、resolve-variant、 resolve-rsid、resolve-hgvs で使用）は、RefSeq アセンブリアクセッションを必要とします。 GRCh38 の RefSeq アクセッションは GCF_000001405.40、GRCh37 のものは GCF_000001405.25 です。

search-region サブコマンドは常に GRCh38 の位置を検索します。

重要

アセンブリの自動フォールバック： resolve-variant と resolve-hgvs コマンドは、まず GRCh38 を自動的に試します。rsID が見つからない場合は、 エラーを報告する前に GRCh37 で再試行します。フォールバックが行われると、出力 JSON に成功した アセンブリを説明する "note" フィールドが含まれます。 別のアセンブリを手動で再試行する必要はありません。スクリプトが透過的に処理します。

--assembly を指定する必要があるのは、特定のアセンブリに検索対象を 限定したい場合のみです（例：ユーザーの座標が GRCh37 であると判明している場合）。

NCBI API キーとレート制限

API キーがない場合、スクリプトは毎秒 3 リクエストに制限されます。キーがある場合は、 毎秒 10 リクエストに増加します。

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

HTTP 500 エラーのトラブルシューティング

参照アレルの不一致

指定した参照アレルが参照配列と一致しないという詳細なメッセージとともに HTTP 500 エラーが発生した場合：

意味： 座標位置は有効である可能性がありますが、指定した参照アレル（ref）が、 要求されたアセンブリ上のその位置の塩基と一致していません。

対応： 1. 同じクエリを機械的に再試行しないでください。2. アセンブリを確認してください：座標はアセンブリごとに異なります。3. アセンブリを切り替えてください：GRCh37 を照会していた場合は GRCh38 を試すか（--assembly GCF_000001405.40 を使用）、GRCh38 を照会していた場合は GRCh37 を試してください（--assembly GCF_000001405.25 を使用）。

よくある間違い

• 間違い： HGVS 文字列を引用符で囲み忘れる 修正： 単一引用符で囲みます： 'NC_000008.11:g.19962213del'

• 間違い： 配列アクセッションの代わりに染色体名を resolve-variant に渡す 修正： 数値の染色体 ID（例：8）または NC_000008.11 のような RefSeq アクセッションを使います

• 間違い： 必要ないのに get-variant で --full を使う 修正： ほとんどの用途では省略形式の出力で十分です。--full は 50～500 KB 以上の JSON を返します

• 間違い： search-region がデフォルトですべての結果を返すと思い込む 修正： デフォルトの --retmax は 500 です。出力の total_available を確認し、結果が切り捨てられたかどうかを確認します

• 間違い： search-region で GRCh37 座標を使う 修正： search-region は常に GRCh38 の位置を使用します。GRCh37 の座標を使う場合は、まず座標をリフトオーバーしてください

• 間違い： 最初の呼び出しが失敗したとき、--assembly を変えて resolve-variant または resolve-hgvs を手動で再試行する 修正： スクリプトは GRCh38、次に GRCh37 を自動的に試します。呼び出しは 1 回で十分です

• 間違い： 染色体の値として X または Y を渡す 修正： 数値の対応値を使います。染色体 X は 23、染色体 Y は 24 です。CLI はデフォルトで染色体を数値として扱います。