gget

gget

概述

gget 是一款命令行生物信息学工具和 Python 包，可统一访问 20 多个基因组数据库和分析方法。通过一致的接口查询基因信息、序列分析结果、蛋白质结构、病毒序列、表达数据、疾病关联，以及小鼠组织／细胞特异性指标。大多数 gget 模块既可作为命令行工具使用，也可作为 Python 函数调用。

重要提示：gget 查询的数据库会持续更新，有时会改变其结构。本文档适用于 gget 0.30.5（截至 2026-06-07 的 PyPI 最新版本）。如需确保工作可复现，请固定使用 gget==0.30.5；若上游数据库适配器出现故障，请先查看发行说明，再更新 gget。

安装

请在干净的虚拟环境中安装 gget，以避免冲突：

# Reproducible install targeting this skill
uv venv .venv
source .venv/bin/activate
uv pip install "gget==0.30.5"

# In Python/Jupyter
import gget

快速开始

所有模块的基本用法：

# Command-line
gget <module> [arguments] [options]

# Python
gget.module(arguments, options)

大多数模块返回：

• 命令行：JSON（默认）或使用 -csv 标志返回 CSV
• Python：DataFrame 或字典

各模块通用标志：

• -o/--out：将结果保存到文件
• -q/--quiet：隐藏进度信息
• -csv：返回 CSV 格式（仅限命令行）

Python 参数名称通常与不带前导短横线的 CLI 长选项一致。例如，--census_version 对应 census_version=...。使用 gget <module> --help 查看当前准确的参数签名。

模块类别

gget 提供 6 个类别中的 23 个模块。每个模块的参数、CLI 和 Python 示例以及返回值结构，详见 references/module_catalog.md；各参数的详细文档见 references/module_reference.md。

类别	模块
1. 参考数据与基因信息	ref（Ensembl 参考数据下载）、search（基因搜索）、info（基因／转录本详情）、seq（核苷酸和蛋白质序列）
2. 序列分析与比对	blast、blat、muscle（多序列比对）、diamond（本地比对）
3. 结构与蛋白质分析	pdb（结构和元数据）、alphafold（结构预测）、elm（线性基序）
4. 表达与疾病数据	archs4（相关性、组织表达）、cellxgene（单细胞）、enrichr（富集分析）、bgee（直系同源关系和表达）、opentargets（疾病和药物）、cbio（癌症基因组学）、cosmic（突变）
5. 病毒与小鼠特异性	virus（病毒序列）、8cube（小鼠特异性和表达）
6. 其他工具	mutate（突变序列）、gpt（文本生成）、setup（安装模块依赖项）

有几个模块首次使用前需要运行一次 gget setup（alphafold、elm、cellxgene）；下载其数据库时，cosmic 会提示输入 COSMIC 凭据。

常见工作流

多模块流程示例包括基因特征分析、结构比较、表达与富集分析、疾病和药物关联、直系同源比较，以及为 kallisto 或比对准备参考文件。这些示例见 references/common_workflows.md，更完整的版本见 references/workflows.md。

最佳实践

数据检索

• 对于大型查询，使用 --limit 控制结果数量
• 使用 -o/--out 保存结果，以确保可复现
• 检查数据库版本／发行版本，确保各项分析保持一致
• 在生产脚本中使用 --quiet 减少输出

序列分析

• 使用 BLAST／BLAT 时，先采用默认参数，再调整灵敏度
• 使用 gget diamond 时添加 --threads，加快本地比对
• 使用 --diamond_db 保存 DIAMOND 数据库，以便重复查询
• 进行多序列比对时，大型数据集可使用 -s5/--super5

表达与疾病数据

• 在 cellxgene 中，基因符号区分大小写（例如，'PAX7' 与 'Pax7'）
• 首次使用 alphafold、cellxgene、elm、gpt 前，先运行 gget setup
• 进行富集分析时，使用数据库快捷方式以方便操作
• 使用 -dd 缓存 cBioPortal 数据，避免重复下载
• 对于 OpenTargets，在编写筛选条件前检查返回的列名；gget 0.30.5 遵循较新的 OpenTargets API 架构

结构预测

• AlphaFold 多聚体预测：使用 -mr 20 提高准确度
• 使用 -r 标志对最终结构进行 AMBER 松弛
• 在 Python 中使用 plot=True 可视化结果
• 运行 AlphaFold 预测前，先检查 PDB 数据库

病毒数据

• 使用 gget virus 时，先采用严格的筛选条件，再请求范围较广的病毒数据集
• 将 command_summary.txt 与下游结果一并保存，以便复现并在部分下载后恢复
• 使用 --baseline 和 --merge-results 恢复中断的病毒元数据／序列下载

错误处理

• 数据库结构会发生变化；适配器失效时，请检查上游发行说明，并明确固定到较新且已修复的版本
• 固定已知可用版本以确保环境可复现：uv pip install "gget==0.30.5"
• 使用 gget info 时，每次最多处理约 1000 个 Ensembl ID
• 对于大规模分析，为 API 查询实施速率限制
• 使用虚拟环境以避免依赖冲突
• 将 COSMIC 和 OpenAI 凭据保存在命名环境变量中，或通过交互式提示输入；不要将真实凭据写入示例、笔记本或日志

输出格式

命令行

• 默认：JSON
• CSV：添加 -csv 标志
• FASTA：gget seq、gget mutate
• PDB：gget pdb、gget alphafold
• PNG：gget cbio plot
• FASTA/CSV/JSONL 文件夹：gget virus

Python

• 默认：DataFrame 或字典
• JSON：添加 json=True 参数
• 保存到文件：添加 save=True 或指定 out="filename"
• AnnData：gget cellxgene
• DataFrame/JSON：gget 8cube specificity、psi_block、expression

资源

此技能包含参考文档，提供各模块的详细信息：

references/

• module_reference.md - 所有模块的完整参数参考
• database_info.md - 查询的数据库及其更新频率信息
• workflows.md - 扩展工作流示例和用例

如需更多帮助：

• 官方文档：https://pachterlab.github.io/gget/
• GitHub 问题：https://github.com/pachterlab/gget/issues
• 引用：Luebbert, L. & Pachter, L. (2023). 使用 gget 高效查询基因组参考数据库。Bioinformatics. https://doi.org/10.1093/bioinformatics/btac836

Agent 操作流程

1. 检查环境。 确认网络访问权限、API 密钥（如有需要），以及数据库当前的 API 文档和速率限制。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。对于任何会影响结果的值，不要猜测，应先询问。
3. 先运行小规模测试。 获取一条已知记录，并在批量查询前检查响应格式。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 确认标识符可解析、报告记录数量，并记录数据库版本或访问日期。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生这种情况	请执行以下操作
出现 HTTP 429 或 5xx 错误	通过退避、批量请求遵守速率限制，并如实报告部分结果。
这些说明中提到的函数、标志或端点在已安装版本中不存在	查看已安装版本自己的文档（help()、--help、官方文档），进行调整并告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所采用的假设。

诚信规则

• 切勿伪造结果、参数、标识符、引文或统计数据。如果某项内容无法运行或验证，请明确说明。
• 切勿编造登录号、ID 或记录；未找到时应报告“未找到”。
• 将此处与特定版本相关的细节视为可能已过时：请根据已安装版本的官方文档进行确认。
• 对于需要付费、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，请先征求同意。

相关技能

• biopython：提供 Biopython（Bio.Seq、Bio.SeqIO、Bio.Align、Bio.Entrez、Bio.Blast、Bio.PDB、Bio.Phylo、Bio.motifs、Bio.SeqUtils、Bio.Restriction）fo…
• bioservices：统一的 Python 接口，可访问 40 多种生物信息学服务。
• pathway-enrichment：对基因列表或排序后的基因数据运行通路和基因集富集分析，然后解读结果。