tooluniverse-immune-repertoire-analysis

ToolUniverse 免疫レパトア解析

T細胞受容体（TCR）およびB細胞受容体（BCR）のレパトアシーケンスデータを解析し、適応免疫応答、クローン増殖、抗原特異性を特徴づけるための包括的なスキルです。

ドメインに基づく推論

レパトアの多様性は免疫の履歴を反映します。クローナリティが高い、つまり少数のクローンが優勢な場合は、活動性感染症、腫瘍浸潤リンパ球、慢性的な刺激などに見られる、抗原によって駆動される増殖を示しています。多様性が低い場合は、免疫不全や治療によるリンパ球減少症が考えられます。結論を出す前に、必ず観察された指標を健常ドナーの参照分布と比較してください。シャノンエントロピーが7の場合、健康な成人では特筆すべき値ではありませんが、化学療法後であれば懸念すべき値です。

推測せずに調べる

• クロノタイプの頻度閾値、CDR3の長さの範囲、収束比率については、IEDB または VDJdb に問い合わせてください。記憶に基づいて値を決めつけないでください。
• 増殖したクローンのエピトープ特異性については、iedb_search_tcell_assays と BVBRC_search_epitopes を検索してください。CDR3 だけから抗原を推測してはいけません。
• 健常ドナーにおける V 遺伝子ファミリーの使用頻度の偏りについては、公開された参照データを取得するか、ImmPort に問い合わせてください。ベースラインの分布が一様だと決めつけないでください。
• シーケンス深度が十分かどうかは、実際のデータからレアファクション曲線を計算してください。深度が十分かどうかを推測してはいけません。

---

概要

適応免疫受容体レパトアシーケンス（AIRR-seq）では、TCR および BCR の可変領域をハイスループットシーケンスすることで、T細胞集団とB細胞集団を包括的にプロファイリングできます。このスキルでは、次の8フェーズのワークフローを提供します。

• クロノタイプの特定と追跡
• 多様性とクローナリティの評価
• V(D)J 遺伝子の使用状況解析
• CDR3 配列の特徴づけ
• クローン増殖と収束の検出
• エピトープ特異性の予測
• シングルセル表現型解析との統合
• 経時的なレパトアの追跡

---

コアワークフロー

フェーズ1：データのインポートとクロノタイプの定義

MiXCR、ImmunoSEQ、AIRR standard、10x Genomics VDJ など、一般的な形式の AIRR-seq データを読み込みます。列名を次のように標準化します：cloneId、count、frequency、cdr3aa、cdr3nt、v_gene、j_gene、chain。次の3つの方法のいずれかでクロノタイプを定義します。

• cdr3aa：CDR3 のアミノ酸配列のみ
• cdr3nt：CDR3 のヌクレオチド配列
• vj_cdr3：V 遺伝子 + J 遺伝子 + CDR3aa（最も一般的で、推奨）

クロノタイプごとに集計し、カウント順に並べ替えてランクを割り当てます。

フェーズ2：多様性とクローナリティの解析

レパトアの多様性指標を計算します。

• シャノンエントロピー：全体的な多様性（高いほど多様性が高い）
• シンプソン指数：無作為に選んだ2つのクローンが同一である確率
• 逆シンプソン指数：クロノタイプの実効数
• ジニ係数：クロノタイプ分布の不均等さ
• クローナリティ：1 - ピールーの均等度（高いほどクローン性が高い）
• リッチネス：ユニークなクロノタイプの数

シーケンス深度が十分かどうかを評価するため、レアファクション曲線を作成します。

フェーズ3：V(D)J 遺伝子使用状況の解析

クロノタイプ数で重み付けして、V 遺伝子と J 遺伝子の使用パターンを解析します。

• V 遺伝子ファミリーの使用頻度
• J 遺伝子ファミリーの使用頻度
• V-J ペアリング頻度
• 使用頻度の偏りに関する統計的検定（一様分布を期待値とするカイ二乗検定）

フェーズ4：CDR3 配列解析

CDR3 配列を特徴づけます。

• 長さの分布：一般的なTCR CDR3は12～18 aa、BCR CDR3は10～20 aaです
• アミノ酸組成：クロノタイプの頻度で重み付けします
• 特異な長さの分布にフラグを付けます（PCR バイアスを示す可能性があります）

フェーズ5：クローン増殖の検出

頻度の閾値（デフォルト：95パーセンタイル）を超える増殖クロノタイプを特定します。複数の時点にわたってクロノタイプを追跡し、持続性、平均／最大頻度、変化倍率を測定します。

フェーズ6：収束とパブリッククロノタイプ

• 収束的組換え：異なるヌクレオチド配列から同じ CDR3 アミノ酸配列が生じること（抗原による選択の証拠）
• パブリッククロノタイプ：複数のサンプル／個体に共有されるクロノタイプ（共通の抗原応答を示す可能性があります）

フェーズ 7：エピトープ予測と特異性

既知の TCR とエピトープの関連をエピトープデータベースで検索します：

• IEDB（iedb_search_tcell_assays）：配列または MHC クラスで T 細胞アッセイの記録を検索します。モチーフ検索には sequence_contains を指定して iedb_search_epitopes を使用します
• BVBRC（BVBRC_search_epitopes）：生物種に基づくエピトープ探索に最適です（例：SARS-CoV-2 の場合は taxon_id="2697049"）。T 細胞／B 細胞アッセイ数とともにエピトープ配列を返します
• VDJdb（VDJDB_* ツール。執筆時点でキュレーション済みレコード 228,214 件）：
  • VDJDB_search_cdr3 -- CDR3 アミノ酸配列（完全一致または部分一致）で検索し、記録されている抗原特異性があれば特定します
  • VDJDB_get_antigen_specificity -- 逆引き検索です。epitope（抗原ペプチド配列。例："GLCTLVAML"）を指定して、それを認識すると確認されたすべての TCR を検索します。mhc.a／mhc.class による拘束、由来となる antigen.gene／antigen.species、および reference.id（PMID）も取得できます
  • VDJDB_get_database_summary -- レコード数と利用可能な列を確認できます。フィルター付きクエリを作成する前に便利です
  • ライブ環境で検証済み：VDJDB_get_antigen_specificity({"epitope": "GLCTLVAML"}) は、よく知られた EBV BMLF1 エピトープ（HLA-A*02:01 に拘束）に特異的な実際の TCR を返します。それぞれの CDR3、V/J セグメント、出典 PMID も取得できます。これは CDR3 のみから特異性を推測するより、直接的で信頼性の高いエピトープ特異性の判定方法です
• PubMed 文献（PubMed_search_articles）：CDR3 とエピトープ／抗原／特異性の組み合わせで検索します
• IEDB 詳細ツール：iedb_get_epitope_antigens（エピトープ→抗原を関連付け）、iedb_get_epitope_mhc（MHC 拘束を取得）

フェーズ 8：シングルセルデータとの統合

TCR／BCR クロノタイプを、対応するシングルセル RNA-seq の細胞表現型と関連付けます：

• クロノタイプを細胞バーコードに対応付けます
• UMAP 上で増殖したクロノタイプの表現型を特定します
• クロノタイプとクラスターの関連を解析します（クロス集計）
• クラスター特異的なクロノタイプを特定します（1 つのクラスター内に細胞の 80％超が存在）
• 差次的遺伝子発現：増殖細胞と非増殖細胞の比較

---

ToolUniverse ツールの統合

主な使用ツール：

• iedb_search_tcell_assays - T 細胞アッセイの記録（配列、MHC クラスのフィルター）
• iedb_search_bcell - B 細胞アッセイの記録
• iedb_search_epitopes - sequence_contains によるエピトープモチーフ検索
• BVBRC_search_epitopes - 生物種に基づくエピトープ探索（病原体特異的なクエリに最適）
• VDJDB_search_cdr3 / VDJDB_get_antigen_specificity - キュレーション済みの CDR3 とエピトープの特異性検索（レコード数 228K 件以上）
• NCBI_SRA_search_runs - 公開 TCR／BCR-seq データセットを検索します（strategy="AMPLICON" を使用）
• ImmPort_search_studies - NIAID の免疫学研究（ワクチン試験、フローサイトメトリー）
• PubMed_search_articles - TCR／BCR の特異性に関する文献
• UniProt_get_entry_by_accession - 抗原タンパク質情報

他のスキルとの統合：

• tooluniverse-single-cell - シングルセル・トランスクリプトミクス
• tooluniverse-rnaseq-deseq2 - バルク RNA-seq 解析
• tooluniverse-variant-analysis - 体細胞超変異解析（BCR）

---

クイックスタート

from tooluniverse import ToolUniverse

# 1. Load data
tcr_data = load_airr_data("clonotypes.txt", format='mixcr')

# 2. Define clonotypes
clonotypes = define_clonotypes(tcr_data, method='vj_cdr3')

# 3. Calculate diversity
diversity = calculate_diversity(clonotypes['count'])
print(f"Shannon entropy: {diversity['shannon_entropy']:.2f}")

# 4. Detect expanded clones
expansion = detect_expanded_clones(clonotypes)
print(f"Expanded clonotypes: {expansion['n_expanded']}")

# 5. Analyze V(D)J usage
vdj_usage = analyze_vdj_usage(tcr_data)

# 6. Query epitope databases
top_clones = expansion['expanded_clonotypes']['clonotype'].head(10)
epitopes = query_epitope_database(top_clones)

---

結果解釈のための推論フレームワーク

エビデンスの評価

評価	基準	例
強い	クローン増殖の頻度が 1％超、収束的組換えを確認、IEDB／VDJdb でエピトープが一致	頻度 5％の CDR3 が、同じアミノ酸をコードする 3 つのヌクレオチド変異を持ち、IEDB でヒット
中程度	クローンが増殖（0.1～1％）、V(D)J バイアスが有意（カイ二乗検定 p < 0.01）、部分的なエピトープ一致	頻度 0.5％のクローンに TRBV20-1 のバイアスがあり、VDJdb に類似した CDR3 モチーフが存在
弱い	低頻度の増殖（0.01～0.1％）、単一時点のみ、エピトープデータベースで一致なし	収束性や既知の特異性がない、中程度に増殖したクローン
不十分	検出限界未満、シーケンシング深度が 10,000 クロノタイプ未満、再現性なし	PCR／シーケンシングのアーティファクトの可能性がある単独のクロノタイプ

解釈のガイダンス

• クローン性指標：Shannon 多様度はレパートリー全体の複雑さを示します（値が高いほど多様で、健常な血液では一般的に 5～12 の範囲です）。Gini 係数は 0（完全に均等）から 1（単一クローンが優勢）までの範囲です。0.3 を超える値はクローンの拡大を示唆します。クローン性（1 - Pielou の均等度）が 0.2 を超える場合は中程度のクローン優位を示し、0.5 を超える場合は強いオリゴクローナルな拡大を示唆します（活動性感染や腫瘍浸潤リンパ球でよく見られます）。
• V(D)J 使用頻度の意義：V 遺伝子または J 遺伝子の使用頻度に偏りがある場合（予想される一様分布とのカイ二乗検定で p < 0.01）、抗原による選択を示している可能性があります。ただし、健常なレパートリーでも、ゲノム上の近接性や組換え効率により、ベースラインの V 遺伝子使用頻度は一様ではありません。可能であれば、一様分布の予想値ではなく、健常ドナーの参照分布と比較してください。
• CDR3 の収束が意味すること：収束組換え（異なる塩基配列から同じ CDR3 アミノ酸配列が生じること）は、独立した組換えイベントが同じ受容体に収束したため、抗原による選択を示す強い証拠です。個人間で共有されるパブリッククローンタイプがあれば、この推論はさらに強まります。拡大したクローンで、収束比（アミノ酸配列 1 つあたりの塩基配列バリアント数）が 2 を超える場合は注目に値します。
• シーケンシング深度：レアファクション曲線がプラトーに達していれば、深度は十分です。曲線がまだ上昇している場合、豊富さと多様度の推定値は過小評価されています。推奨される最低深度は、バルク TCR-seq で合計 50,000～100,000 リードです。
• 経時的な追跡：複数の時点で持続し、頻度が安定または上昇しているクローンは、抗原による維持を示しています。一過性の拡大後に消失するクローンは、急性応答を反映している可能性があります。

統合に関する質問

1. 観察されたクローン拡大のパターン（Gini 係数、最上位クローンの頻度）は、想定される免疫状況（例：ワクチン接種後の拡大、腫瘍浸潤リンパ球のオリゴクローナル性）と一致していますか？
2. コホート内の複数の個人で収束した CDR3 配列が見つかっていますか？見つかっている場合、共通抗原に対するパブリックな応答を示唆していますか？
3. 拡大したクローンタイプは、既知の抗原特異的レパートリーの特徴（例：CMV 特異的応答における TRBV20-1 の濃縮）と一致する V 遺伝子使用頻度の偏りを示していますか？
4. シーケンシング深度は、多様度指標を確実に推定し、低頻度で拡大したクローンを検出するのに十分ですか（レアファクション曲線はプラトーに達していますか）？
5. 経時データでは、クローンの動態（拡大、縮小、持続）は臨床転帰や治療応答と相関していますか？

---

参考文献

• Dash P, et al. (2017) 定量可能な予測特徴により、エピトープ特異的 T 細胞受容体レパートリーが定義される。Nature
• Glanville J, et al. (2017) T 細胞受容体レパートリーにおける特異性グループの特定。Nature
• Stubbington MJT, et al. (2016) 単一細胞トランスクリプトームからの T 細胞の運命とクローン性の推定。Nature Methods
• Vander Heiden JA, et al. (2014) pRESTO：リンパ球受容体レパートリーのハイスループットシーケンシング生リードを処理するためのツールキット。Bioinformatics

---

関連項目

• ANALYSIS_DETAILS.md - 8 つのフェーズすべての詳細なコードスニペット
• USE_CASES.md - ユースケース全般（免疫療法、ワクチン、自己免疫、単一細胞データの統合）とベストプラクティス