tcga-bulk-data-preprocessing-with-omicverse

OmicVerse を使用した TCGA バルクデータの前処理

概要

GDC からダウンロードした TCGA データの読み込み、正規化済み発現行列の作成、臨床メタデータの付与、ov.bulk.pyTCGA を使用した生存解析を行う場合に、このスキルを使用します。

手順

1. 必要なダウンロードデータを集める

ユーザーが GDC Data Portal から次の 3 項目を取得していることを確認します。

• gdc_sample_sheet.<date>.tsv — サンプルシートのエクスポート
• 展開済みの gdc_download_xxxxx/ ディレクトリ（発現アーカイブを含む）
• clinical.cart.<date>/ ディレクトリ（臨床 XML/JSON ファイルを含む）

2. TCGA ヘルパーを初期化する

import omicverse as ov
import scanpy as sc
ov.plot_set()

aml_tcga = ov.bulk.pyTCGA(sample_sheet_path, download_dir, clinical_dir)
aml_tcga.adata_init()  # Builds AnnData with raw counts, FPKM, and TPM layers

3. 保存して再読み込みする

aml_tcga.adata.write_h5ad('data/ov_tcga_raw.h5ad', compression='gzip')

# To reload later:
new_tcga = ov.bulk.pyTCGA(sample_sheet_path, download_dir, clinical_dir)
new_tcga.adata_read('data/ov_tcga_raw.h5ad')

4. メタデータと生存情報を初期化する

aml_tcga.adata_meta_init()   # Gene ID → symbol mapping, patient info
aml_tcga.survial_init()      # NOTE: "survial" spelling — see Critical API Reference below

5. 生存解析を実行する

# Single gene
aml_tcga.survival_analysis('MYC', layer='deseq_normalize', plot=True)

# All genes (can take minutes for large gene sets)
aml_tcga.survial_analysis_all()  # NOTE: "survial" spelling

6. 結果をエクスポートする

aml_tcga.adata.write_h5ad('data/ov_tcga_survival.h5ad', compression='gzip')

重要な API リファレンス

重要：メソッド名のスペルに一貫性がありません

pyTCGA API には、意図的なスペルの不一致があります。2 つのメソッドでは「survial」（「v」が抜けています）が使われ、1 つのメソッドでは正しい「survival」が使われます。

メソッド	スペル	目的
survial_init()	survial（「v」なし）	生存メタデータ列を初期化します
survival_analysis(gene, layer, plot)	survival（正しいスペル）	単一遺伝子の Kaplan-Meier 曲線
survial_analysis_all()	survial（「v」なし）	すべての遺伝子について生存率の有意性を調べます

# CORRECT — use the exact method names as documented
aml_tcga.survial_init()                    # "survial" — no 'v'
aml_tcga.survival_analysis('MYC', layer='deseq_normalize', plot=True)  # "survival" — correct
aml_tcga.survial_analysis_all()            # "survial" — no 'v'

# WRONG — these will raise AttributeError
# aml_tcga.survival_init()                 # AttributeError! Use survial_init()
# aml_tcga.survival_analysis_all()         # AttributeError! Use survial_analysis_all()

生存解析の方法

survival_analysis() は Kaplan-Meier 解析を実行します。

1. 中央値をカットオフとして、患者を発現量の高群と低群に分けます
2. 有意性を評価するため、ログランク検定の p 値を計算します
3. plot=True の場合、信頼区間付きの生存曲線を描画します

レイヤーの選択が重要です：layer='deseq_normalize' の使用を推奨します。DESeq2 による正規化では、ライブラリーサイズと組成バイアスが考慮されるため、サンプル間で発現量を比較できます。別の選択肢として、TPM 正規化値の layer='tpm' も使用できます。

堅牢な検証パターン

import os

# Before pyTCGA init: verify all paths exist
for name, path in [('sample_sheet', sample_sheet_path),
                    ('downloads', download_dir),
                    ('clinical', clinical_dir)]:
    if not os.path.exists(path):
        raise FileNotFoundError(f"TCGA {name} path not found: {path}")

# After adata_init(): verify expected layers were created
expected_layers = ['counts', 'fpkm', 'tpm']
for layer in expected_layers:
    if layer not in aml_tcga.adata.layers:
        print(f"WARNING: Missing layer '{layer}' — check if TCGA archives are fully extracted")

# Before survival analysis: verify metadata is initialized
if 'survial_init' not in dir(aml_tcga) or aml_tcga.adata.obs.shape[1] < 5:
    print("WARNING: Run adata_meta_init() and survial_init() before survival analysis")

トラブルシューティング

• AttributeError: 'pyTCGA' object has no attribute 'survival_init'：スペルミスのある名前 survial_init()（「v」が抜けています）を使用してください。survial_analysis_all() も同様です。上記の重要な API リファレンスを参照してください。
• adata_meta_init() 中の KeyError：発現行列内の遺伝子 ID が想定される形式と一致していません。TCGA では ENSG ID が使用され、メソッド内でシンボルにマッピングされます。アーカイブが同じ GDC ダウンロードから取得されたものであることを確認してください。
• 生存プロットが空、または p 値が NaN になる：臨床 XML ファイルに日付フィールド（days_to_death、days_to_last_follow_up）がありません。clinical.cart.* ディレクトリにメタデータ JSON だけでなく、完全な XML ファイルが含まれていることを確認してください。
• survial_analysis_all() の実行が非常に遅い：この処理では、すべての遺伝子を個別に検定します。約 20,000 個の遺伝子を持つゲノムでは、5～15 分かかると見込んでください。先に対象遺伝子を絞り込むことを検討してください。
• サンプルシートの列が一致しない：TSV がタブ区切りで、ヘッダー行が GDC の想定する形式と一致していることを確認してください。列名が異なる場合は、GDC から再ダウンロードしてください。
• deseq_normalize レイヤーがない：このレイヤーは adata_meta_init() の実行時に作成されます。存在しない場合は、メタデータの初期化手順を再実行してください。

例

• 「私の TCGA OV ダウンロードデータを読み込み、メタデータを初期化して、DESeq 正規化カウントを使用した MYC の生存曲線を描画してください。」
• 「保存済みの AnnData ファイルを再読み込みして生存アノテーションを付与し、更新した .h5ad をエクスポートしてください。」
• 「すべての遺伝子について生存解析を実行し、拡張したデータセットを保存してください。」

参考資料

• チュートリアルノートブック：t_tcga.ipynb
• コピー＆ペースト用のクイックコマンド：reference.md