alterlab-geo

GEO データベース

概要

Gene Expression Omnibus（GEO）は、ハイスループットの遺伝子発現データおよび機能ゲノミクスデータを公開するNCBIのリポジトリです。アレイベースとシーケンスベースの両方の実験から、数十万件の研究（Series）と数百万件のサンプルを収録しています。最新の集計については、GEOブラウザー（https://www.ncbi.nlm.nih.gov/geo/）をご覧ください。

このスキルを使用する場面

遺伝子発現データセットの検索、実験データの取得、生データおよび処理済みファイルのダウンロード、発現プロファイルの照会、GEOデータの計算解析ワークフローへの統合を行う場合に、このスキルを使用してください。

対象外

状況	代わりに使用
SRA/ENAのランアクセッションに対応する生のFASTQリード	alterlab-ena
正常組織の参照発現データ（中央値TPM、eQTL）	alterlab-gtex
研究間で統合された単一細胞発現データ（CELLxGENE Census）	alterlab-cellxgene
すでに用意したカウント行列に対する差次的発現解析の実行	alterlab-pydeseq2
がんコホートの腫瘍変異／コピー数	alterlab-cbioportal

基本的なワークフロー

1. 関連する研究を検索します（E-utilities / Bio.Entrez）→ references/searching.md を参照してください。
2. GEOparseでシリーズを取得します：GEOparse.get_GEO(geo="GSE...", destdir="./data") → references/geoparse_usage.md を参照してください。
3. gse.pivot_samples('VALUE') を使って発現行列（遺伝子 × サンプル）を抽出します。
4. QC、差次的発現解析、クラスタリング、メタ解析などの解析を行います → references/expression_analysis.md を参照してください。

一括ダウンロードの場合はGEOparseを使わず、FTP経由でファイルを直接取得してください → references/data_access.md を参照してください。

GEOデータの構成

GEOでは、さまざまなアクセッションタイプを使ってデータを階層的に整理しています。

• シリーズ（GSE） — 関連するサンプルを含む一連の実験です（例：GSE123456）。 最も大きな組織単位です。実験デザイン、サンプル、研究情報が含まれます。
• サンプル（GSM） — 個別の実験サンプル／生物学的反復です （例：GSM987654）。プラットフォームおよびシリーズに紐付けられています。
• プラットフォーム（GPL） — マイクロアレイまたはシーケンシングのプラットフォームです（例：GPL570、 Affymetrix Human Genome U133 Plus 2.0 Array）。複数の実験で共有されます。
• データセット（GDS） — 差次的解析向けに処理された、キュレーション済みの一貫した形式のコレクションです（例：GDS5678）。 手早く比較解析を行うのに適していますが、キュレーション済みのGDSセットはレガシーとなり、現在は拡充されていません。最近の研究のほとんどはGSEシリーズとしてのみ公開されているため、新しい解析ではGSEを優先してください。
• プロファイル — 配列特徴に紐付けられた遺伝子ごとの発現データです。 遺伝子名で検索でき、Entrez Geneと相互参照されています。

アクセス方法（振り分け）

• GEOparse（推奨） — シリーズ単位で最も簡単にアクセスできます。ダウンロード、メタデータの解析、発現行列の抽出、補足ファイルの取得、サンプルのフィルタリングが可能です。 → references/geoparse_usage.md
• E-utilities（Bio.Entrez） — gds、geoprofilesを対象に、メタデータ検索や一括クエリを行います。必ずEntrez.emailを設定してください。→ references/searching.md
• 直接FTP / wget / curl — シリーズマトリックス、SOFT、MINiML、補足ファイルを一括ダウンロードできます。レート制限はありません。→ references/data_access.md
• GEO2Rウェブツール — https://www.ncbi.nlm.nih.gov/geo/geo2r/?acc=GSExxxxx で利用できる、ブラウザー上でのノーコード差次的発現解析ツールです。再現可能なRスクリプトを生成します。ダウンロード前の探索的解析に便利です。

インストールとセットアップ

uv pip install GEOparse        # primary GEO access (recommended)
uv pip install biopython       # E-utilities / programmatic NCBI access
uv pip install pandas numpy scipy statsmodels scikit-learn  # analysis
uv pip install matplotlib seaborn                           # visualization

NCBI E-utilitiesへのアクセスを設定します（NCBIではメールアドレスが必須です。APIキーを使うと、レート制限が毎秒3リクエストから10リクエストに引き上げられます）。

from Bio import Entrez

Entrez.email = "[email protected]"   # required
# Optional API key — https://www.ncbi.nlm.nih.gov/account/
Entrez.api_key = "your_api_key_here"

主要な概念

• SOFT（Simple Omnibus Format in Text）： GEO の主要なテキスト形式で、メタデータとデータテーブルを含みます。GEOparse で簡単に解析できます。
• MINiML（MIAME Notation in Markup Language）： プログラムからのアクセスやデータ交換に使用する XML 形式です。
• Series Matrix： タブ区切りの発現マトリックスです（サンプルが列、遺伝子／プローブが行）。発現データを取得する最速の形式です。
• MIAME 準拠： GEO が投稿データに求める、最低限の標準化された注釈です。
• 発現値の種類： 生シグナル、正規化済み、または対数変換済みです。プラットフォームと処理方法を必ず確認してください。
• プラットフォーム注釈： プローブ／特徴 ID を遺伝子に対応付けます。生物学的な解釈に不可欠です。

よくあるユースケース

• トランスクリプトーム研究 — 発現データのダウンロード、研究間のプロファイル比較、DEG の特定、メタ解析の実施。
• 薬物応答研究 — 治療後の発現変化の解析、応答バイオマーカーの特定、感受性モデルの構築。
• 疾患生物学 — 疾患群と正常群の発現比較、疾患シグネチャーの特定、患者のサブグループ／病期の比較、発現と転帰の相関分析。
• バイオマーカーの発見 — 診断／予後マーカーのスクリーニング、コホート間での検証、臨床データとの統合。

レート制限とベストプラクティス

• E-utilities の制限： API キーなしでは 3 req/s、API キーありでは 10 req/s です。待機時間を挿入します：time.sleep(0.34)（API キーなし）または time.sleep(0.1)（API キーあり）。
• FTP： レート制限がないため、一括ダウンロードに適しています（ディレクトリ全体には wget -r を使用）。
• GEOparse のキャッシュ： ファイルは destdir にキャッシュされ、以降の呼び出しではキャッシュが再利用されます。
• 方法の選択： シリーズレベルのアクセスには GEOparse、検索／メタデータの一括取得には E-utilities、ファイルの直接取得／一括取得には FTP を使用します。ローカルにキャッシュし、Biopython では必ず Entrez.email を設定してください。

重要な注意事項

• データ品質： GEO は品質にばらつきのあるユーザー投稿データを受け付けています。プラットフォーム注釈と処理方法を確認し、メタデータと実験デザインを検証し、バッチ効果に注意して、生データの再処理を検討してください。
• ファイルサイズ： シリーズマトリックスファイルは 1 GB を超えることがあり、補足ファイル（CEL など）は非常に大きい場合があります。必要なディスク容量を確保し、段階的にダウンロードしてください。
• 引用： GEO データは研究目的で無料で利用できます。元の研究に加えて、GEO データベース（Barrett et al. 2013、Nucleic Acids Research）を引用してください。データセットごとの利用制限を確認し、NCBI のガイドラインに従ってください。
• よくある落とし穴： プラットフォームごとにプローブ ID が異なります（注釈による対応付けが必要です）。値は生データ／正規化済み／対数変換済みの場合があります（メタデータを確認してください）。サンプルメタデータの形式には一貫性がありません。古い投稿にはシリーズマトリックスファイルがない場合があります。プラットフォーム注釈が古くなっている場合があります。

リファレンス一覧

• references/searching.md — E-utilities による検索（データセット、プロファイル、高度なクエリ、検索→要約→取得のワークフロー、メタデータの一括取得）。
• references/geoparse_usage.md — GEOparse のインストール／使用方法、発現マトリックス、補足ファイル、サンプルのフィルタリング、キャッシュ。
• references/data_access.md — FTP への直接アクセス（ftplib、wget、curl）とアクセッション番号からパスを特定する規則。
• references/expression_analysis.md — QC／前処理、差次的発現、相関／クラスタリング、バッチ処理、研究間メタ解析。
• references/geo_reference.md — 詳細な技術リファレンス：E-utilities API エンドポイント、SOFT／MINiML 形式のドキュメント、FTP ディレクトリ構造、正規化パイプライン、プラットフォーム固有の注意点、エラー処理のトラブルシューティング。

その他のリソース

• GEO のウェブサイト： https://www.ncbi.nlm.nih.gov/geo/
• GEO の投稿ガイドライン： https://www.ncbi.nlm.nih.gov/geo/info/submission.html
• GEOparse のドキュメント： https://geoparse.readthedocs.io/
• E-utilities のドキュメント： https://www.ncbi.nlm.nih.gov/books/NBK25501/
• GEO FTP サイト： https://ftp.ncbi.nlm.nih.gov/geo/ (ftp://ftp.ncbi.nlm.nih.gov/geo/ と同じツリー)
• GEO2R ツール： https://www.ncbi.nlm.nih.gov/geo/geo2r/
• NCBI API キー： https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/
• Biopython チュートリアル： https://biopython.org/DIST/docs/tutorial/Tutorial.html

スクリプト

scripts/query_geo.py — NCBI E-utilities 経由で GEO DataSets を利用する実行可能なヘルパーです（キーは不要です。NCBI_API_KEY を設定するとレート制限が緩和されます）。PEP 723 のインライン依存関係ヘッダーがあるため、uv run が requests を自動的にインストールします。

uv run scripts/query_geo.py search "breast cancer AND Homo sapiens[ORGN]" --retmax 5
uv run scripts/query_geo.py summary 200000001,200000002