gget

用途

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

资料提示：gget 查询的数据库持续更新，有时会改变其结构。本说明针对 gget 0.30.5（PyPI 截至 2026-06-07 的当前版本）。为可复现工作，建议固定 gget==0.30.5；若上游数据库适配器失效，在查看发布说明后更新 gget。

安装

建议在干净的虚拟环境中安装以避免冲突：

uv venv .venv
source .venv/bin/activate
uv pip install "gget==0.30.5"

在 Python/Jupyter 中：

import gget

主要能力（模块分类）

gget 提供 23 个模块，分为六类：

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

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

使用方式

所有模块的基本用法模式：

# 命令行
gget <module> [arguments] [options]

# Python
gget.module(arguments, options)

多数模块返回：

命令行：默认 JSON，加 -csv 标志返回 CSV
Python：DataFrame 或字典

跨模块通用标志：

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

Python 参数名通常与命令行长选项一致，去掉前导短横线。例如 --census_version 对应 census_version=...。使用 gget <module> --help 查看当前确切签名。

输出格式：

命令行：默认 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

适用场景

资料列出了若干常见工作流：基因表征、结构比较、表达与富集分析、疾病与药物关联、同源比较，以及为 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 schema

结构预测：

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 凭据放在命名环境变量或交互提示中；不要将真实凭据写入示例、notebook 或日志

代理操作流程（资料提供）

检查环境：确认网络访问、API 密钥（如需要）以及数据库当前 API 文档和速率限制。
确定输入：从数据或用户确认格式、标识符和参数。对任何会改变结果的值应询问而非猜测。
先运行小版本：获取单条已知记录并检查响应格式，再进行批量查询。
执行完整任务。
验证结果：标识符可解析、报告记录数、记录数据库版本或访问日期。
报告：说明运行了什么（版本、命令、参数）、检查了什么、还有什么不确定。

异常处理：HTTP 429 或 5xx 错误时遵守速率限制并退避、批量请求、如实报告部分结果；若指令中的函数、标志或端点在实际安装版本中缺失，查看已安装版本自身文档（help()、--help、官方文档）并告知用户，绝不虚构 API；若必需输入、标识符或参数不明确，询问用户或在运行前明确说明假设。

完整性规则：绝不捏造结果、参数、标识符、引用或统计；无法运行或验证时如实说明；绝不虚构登录号、ID 或记录，应报告“未找到”；将版本相关细节视为可能过时，对照已安装版本的官方文档确认；在涉及花钱、消耗共享 GPU 或云配额、触碰个人或患者数据、或不可撤销的操作前先询问。

资源

官方文档：https://pachterlab.github.io/gget/
GitHub issues：https://github.com/pachterlab/gget/issues
引用：Luebbert, L. & Pachter, L. (2023). Efficient querying of genomic reference databases with gget. Bioinformatics. https://doi.org/10.1093/bioinformatics/btac836

本技能包含参考文档：references/module_reference.md（所有模块的完整参数参考）、database_info.md（所查询数据库及其更新频率信息）、workflows.md（扩展工作流示例与用例）。

技能介绍

用途

安装