alterlab-geo

GEO 数据库

概述

基因表达综合数据库（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. 分析——质量控制、差异表达、聚类、荟萃分析 → 参见 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。
• Profiles——与序列特征关联的基因特异性表达数据， 可按基因名称查询，并交叉引用至 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 key 时为 3 req/s，使用时为 10 req/s。插入延迟：time.sleep(0.34)（不使用 key）或 time.sleep(0.1)（使用 key）。
• FTP： 无速率限制——批量下载的首选方式（使用 wget -r 下载整个目录）。
• GEOparse 缓存： 文件缓存在 destdir 中；后续调用会复用这些文件。
• 方法选择： 使用 GEOparse 访问系列级数据，使用 E-utilities 搜索／批量获取元数据，使用 FTP 直接／批量下载文件。在本地缓存；使用 Biopython 时务必设置 Entrez.email。

重要说明

• 数据质量： GEO 接受的用户提交数据质量不一。请检查平台注释和处理方法，核实元数据和实验设计，留意批次效应，并考虑重新处理原始数据。
• 文件大小： 系列矩阵文件可能超过 1 GB；补充文件（如 CEL）可能非常大。请预留磁盘空间；分批下载。
• 引用： GEO 数据可免费用于研究。请引用原始研究和 GEO 数据库（Barrett 等，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