一、NCBI数据下载攻略

NCBI有多种下载数据的方式，每种方式都有其特定的应用场景和优势。下面我给你详细介绍一下。

1.NCBI Datasets CLI (官方推荐·下一代神器)

这是 NCBI 近年来大力推广的现代化命令行工具，旨在取代旧的 FTP 和部分 EDirect 功能。它的核心理念是 **"Package" (数据包)**，即一次下载打包好序列、注释和元数据。

2.Entrez Direct (EDirect) (瑞士军刀·灵活无敌)

这是 NCBI 的传统命令行工具集 (esearch, efetch, xtract)，直接与 NCBI 的底层数据库 API 对话。

3.Entrez Utilities (图形界面·傻瓜式操作)

这是 NCBI 提供的基于 Web 的图形界面工具，操作简单，无需命令行。

4.FTP / Aspera (传统·海量镜像)

直接访问 NCBI 的 FTP 服务器 (ftp.ncbi.nlm.nih.gov)，或者使用 IBM Aspera Connect 高速传输协议。

5.SRA Toolkit (NGS 原始数据专用)

专门用于下载 Sequence Read Archive (SRA) 数据库中的原始测序读长 (Fastq 数据)。

二、NCBI Datasets CLI介绍、安装及使用方法

1.NCBI Datasets CLI介绍

这是 NCBI 近年来大力推广的现代化命令行工具，旨在取代旧的 FTP 和部分 EDirect 功能。它的核心理念是 **"Package" (数据包)**，即一次下载打包好序列、注释和元数据。特点：以基因组（Genome）为中心，一键打包。优势：

• 打包下载：自动将序列(.fna)、蛋白(.faa)、注释(.gff)和元数据(.json)打包成一个 ZIP，治好了“文件零散”的毛病。
• 元数据丰富：附带的 data_report.jsonl 包含极高价值的结构化信息。
• 断点续传：原生支持断点续传，网络不稳定也不怕。
• 速度快：后端优化了分发网络。劣势：
• 短序列支持差：默认会过滤掉短片段（如 PCR 产物），只关注“有基因组价值”的数据。
• 学习成本：需要学习新的命令行语法。最佳应用场景：
• 下载病毒、细菌、真核生物的参考基因组。
• 需要进行大规模比较基因组学分析。
• 需要结合元数据（采集地、宿主、时间）进行分析。需求及理由我要下病毒/细菌的基因组，做进化树分析。速度快，元数据全，自动打包。

2.NCBI Datasets CLI安装

NCBI Datasets CLI 是 NCBI 的下一代数据下载工具。要在 Linux 上顺畅使用它，您需要安装两个核心程序：

1. datasets: 主程序，负责下载。
2. dataformat: 辅助程序，负责将下载的 JSON 元数据转换为 Excel/表格。

以下提供 3 种安装方式，请根据您的环境选择最适合的一种。方式一：Conda 安装 (最推荐 🌟)如果您是生信分析人员，或者服务器上已经安装了 Anaconda / Miniconda，这是最干净、最方便的方法。

1. 创建环境 (可选，但推荐) 为了不污染基础环境，建议新建一个环境：

conda create -n ncbi_tools python=3.9conda activate ncbi_tools

1. 安装

# 使用 conda-forge 频道 (推荐，更新最快)conda install -c conda-forge ncbi-datasets-cli

1. 验证

datasets --versiondataformat --version

如果输出了版本号 (例如 16.x.x)，恭喜您，安装成功！

方式二：直接下载二进制文件 (通用性最强 🚀)如果您没有 Conda，或者没有管理员权限 (root)，这种方法绝对可行。它不需要任何依赖，下载即用。

1. 下载主程序 (datasets)

# 下载适用于 Linux x64 的最新版curl -o datasets 'https://ftp.ncbi.nlm.nih.gov/pub/datasets/command-line/v2/linux-amd64/datasets'

1. 下载辅助程序 (dataformat)

curl -o dataformat 'https://ftp.ncbi.nlm.nih.gov/pub/datasets/command-line/v2/linux-amd64/dataformat'

1. 赋予执行权限 下载下来的文件默认没有运行权限，需要加 +x。

chmod +x datasets dataformat

1. 配置环境变量 (关键步骤！) 此时您只能通过 ./datasets 运行。为了在任何目录下都能输入 datasets 运行，您需要把它放到系统路径里。

情况 A: 您有 root 权限 (sudo)直接移动到 /usr/local/bin：

sudo mv datasets dataformat /usr/local/bin/

情况 B: 您是普通用户 (无 sudo)建议创建一个个人的 bin 目录：

# 1. 创建目录mkdir -p ~/bin# 2. 移动文件mv datasets dataformat ~/bin/# 3. 将 ~/bin 加入环境变量 (永久生效)# 如果您用 bash:echo'export PATH="$HOME/bin:$PATH"' >> ~/.bashrcsource ~/.bashrc# 如果您用 zsh:echo'export PATH="$HOME/bin:$PATH"' >> ~/.zshrcsource ~/.zshrc

3.NCBI Datasets CLI使用方法

1. 命令结构解剖

最基础的语法结构如下：

datasets download [数据类型] [检索方式] [检索值] [过滤参数] [输出参数]

• 数据类型 (domain): virus (病毒), genome (真核/原核基因组), gene (基因) 等。
• 检索方式: taxon (物种名/ID), accession (编号)。
• 检索值: 具体的名字或编号。

1. 核心场景一：下载病毒数据 (datasets download virus) 2.1 基础用法：按物种名下载 下载该物种的所有基因组序列。

datasets download virus genome taxon "SARS-CoV-2" --filename covid.zip

2.2 进阶用法：精准控制内容 (--include) 默认情况下，它只下载基因组序列 (genome) 和数据报告 (data_report)。如果您需要蛋白序列或注释文件，必须显式指定。

datasets download virus genome taxon "Rhinovirus B" \    --include genome,cds,protein,annotation,biosample \    --filename rhinovirus_b_full.zip

• genome: 基因组核酸序列 (.fna)
• cds: 编码区核酸序列 (.fna) —— 做密码子优化必备
• protein: 氨基酸序列 (.faa) —— 做蛋白结构分析必备
• annotation: 基因位置注释文件 (annotation_report.jsonl) —— 查看基因在基因组上的坐标
• biosample: 详细样本信息 (JSON) —— 流行病学分析必备

2.3 筛选用法：只下载完整的 (--complete-only) 过滤掉那些测序不完整的草图。

datasets download virus genome taxon "Dengue virus" \    --complete-only \    --filename dengue_complete.zip

2.4 筛选用法：按宿主筛选 (--host) 只下载感染人类的序列。

datasets download virus genome taxon "Orthopoxvirus" \    --host "Homo sapiens" \    --filename human_pox.zip

2.5 筛选用法：按发布时间更新 (--released-since) 适用于定期更新数据库，只下载今年新发布的数据。

datasets download virus genome taxon "Influenza A virus" \     --released-after "01/01/2024" \     --filename flu_2024.zip

1. 核心场景二：下载细菌/真核基因组 (datasets download genome)注意：病毒用 virus genome，而细菌、真菌、人类用 genome。命令略有不同。

3.1 按物种下载参考基因组 (Reference Genome) 对于细菌或人，通常我们不需要下载几千个样本，只需要一个标准的参考基因组。

# 下载人类参考基因组 (GRCh38)datasets download genome taxon "human" \    --reference \    --include genome,gff3 \    --filename human_ref.zip

3.2 下载特定菌株 (Strain)

datasets download genome taxon "Escherichia coli" \    --assembly-level complete \    --filename ecoli_complete.zip

• --assembly-level: 控制组装质量。可选 complete (完成图), chromosome (染色体级), scaffold, contig。

1. 核心场景三：按编号精准下载 (accession) 如果您已经有了一个 Accession 列表（比如从文献里看到的，或者用其他工具筛选出来的），这是最精准的方法。

4.1 下载单个编号

datasets download genome accession GCF_000001405.40 --filename human_GRCh38.zip

4.2 下载多个编号 (通过文件) 这是一个极其实用的功能。创建一个包含编号的文本文件 list.txt，每行一个编号。

# list.txt 内容示例:# GCF_000005845.2# GCF_000006945.2datasets download genome accession --inputfile list.txt --filename my_batch.zip

• --inputfile: 读取列表文件。这比在命令行里写一长串编号要好用得多。

1. 结果文件解剖：下载下来到底是什么？ 解压 ZIP 包后，目录结构是标准化的：

ncbi_dataset/├── data/│   ├── assembly_data_report.jsonl  # 元数据 (核心！)│   ├── GCF_000001405.40/          # 每个基因组一个文件夹 (有时会合并)│   │   ├── GCF_000001405.40_GRCh38.p14_genomic.fna  # 序列│   │   └── genomic.gff                              # 注释│   └── dataset_catalog.json        # 目录清单└── README.md

关键提示：

• 对于 **病毒 (virus genome)**：所有序列通常会合并在一个大文件 genomic.fna 中。
• 对于 **细菌/真核 (genome)**：默认每个 Accession 一个单独文件夹。

1. 实用技巧与避坑指南 6.1 "断点续传"策略：Dehydrated 模式 如果你要下载 50GB 数据，强烈建议不要直接下 ZIP，而是使用 Dehydration（脱水） 策略。这是官方推荐的处理大批量数据的方法。第一步：下载“脱水”包 (秒下)加上 --dehydrated 参数。这会只下载数据的“索引”和“元数据”，不含实际序列，所以非常快，体积很小。

# 下载新冠病毒参考基因组的索引datasets download genome taxon 2697049 \    --dehydrated \    --include genome,gff3 \    --filename test_virus.zip

预期结果： 你会得到一个 test_virus.zip。

第二步：解压

unzip test_virus.zip -d test_virus_data

观察： 进入 test_virus_data 目录，你会发现：

• 有 README.md
• 有 ncbi_dataset/data/fetch.txt —— 这个文件是关键，里面记录了真正的数据下载链接。
• 但是！ 此时还没有 .fna (序列) 和 .gff (注释) 文件。这就是“脱水”状态。

第三步：复水 (Rehydrate) —— 真正的下载现在我们把水（数据）加进去。

cd test_virus_datadatasets rehydrate --directory .

预期结果：

• 屏幕上会显示下载进度（因为文件很小，可能一闪而过）。
• 完成后，你再看 ncbi_dataset/data/ 目录下：
• 多出了 GCF_009858895.2 (或其他版本号) 的文件夹。
• 文件夹里有了 genomic.fna 和 genomic.gff。
• 验证成功！

第四步：模拟“断点续传” (进阶验证)为了验证它是否真的能跳过已下载的文件：

1. 不要删除刚才下载好的文件。
2. 再次运行同一条命令：

   datasets rehydrate --directory .

3. 观察输出： 它应该会提示 Nothing to do 或者极快结束，因为它检测到文件已经存在且完整，没有重复下载。

6.2 预览数据量 (summary) 在下载前，强烈建议先用 summary 看看有多少数据，防止硬盘被撑爆。

# 别急着 download，先 summary 一下datasets summary virus genome taxon "Rhinovirus B" --as-json-lines | wc -l

6.3 解决 "No records found" 如果您搜 "HIV"，可能会报错。尝试使用更准确的分类学名称。

• ❌ datasets download virus genome taxon "HIV"
• ✅ datasets download virus genome taxon "Human immunodeficiency virus 1"
• ✅ 或者直接用 TaxID: datasets download virus genome taxon 11676

6.4 关于 API Key 如果您需要频繁、大量下载，建议配置 NCBI API Key 以获得更高并发权限。

export NCBI_API_KEY="您的密钥"datasets download ...

(注：普通用户不配 Key 也能用，只是并发限制稍严)

三、dataformat 查看字段

dataformat 工具非常强大，它既可以告诉您“有哪些字段可用”，也可以帮您“一次性导出所有标准字段”。

1. 第一步：先看看“到底有哪些字段”可用？

在盲目导出之前，我们先列出所有支持的字段名称。

命令

dataformat tsv virus-genome --help

输出解读 (示例) 屏幕上会打印出一个长长的列表，每一行都是一个可用的字段名。例如：

• accession
• source-database
• virus-name
• host-name
• geo-location
• collection-date
• release-date
• completeness
• length
• ... (通常有 30+ 个)

建议：您可以把这个列表保存下来，方便以后查阅：

dataformat tsv virus-genome --help > all_possible_columns.txt

1. 第二步：如何一次性导出所有字段？dataformat 并没有一个 --all 参数（因为它太宽了，打印出来会乱码），但我们可以通过一个小技巧来实现：把刚才查到的所有字段名都传给它。

方法 A：使用 --fields 参数 (手动指定最全的) 这是最稳妥的方法。我为您整理了一个包含所有常用字段的超级命令：

dataformat tsv virus-genome \      --package Rhinovirus_A.zip \      --fields accession,virus-tax-id,virus-name,completeness,length,host-tax-id,host-name,geo-location,release-date,update-date,submitter-names,submitter-affiliation \      > Rhinovirus_A_corrected.tsv

方法 B：使用 Excel 格式 (推荐) 如果字段太多，TSV 文本文件在终端看会换行，非常难受。直接导出为 Excel 格式查看体验最好。

dataformat excel virus-genome \    --package Rhinovirus_A.zip \    --outputfile Rhinovirus_A_metadata.xlsx

注意：dataformat excel 命令默认就会包含比 TSV 更多、更全的字段。这是一个“偷懒”获取全字段的好办法。

四、常见问题

1. Datasets CLI vs 网页版 NCBI Virus

核心问题：为什么我搜同一个病毒，网页上显示 1000 条，命令行只下载了 800 条？

一句话总结： CLI 是“去粗取精”版，帮您过滤了碎片；网页版是“全量展示”版，良莠不齐全都有。

1. Datasets CLI vs 网页版 NCBI Assembly

核心问题：下载细菌/人类基因组时，这两者是一回事吗？

一句话总结： 两者本质是一样的。CLI 是网页版的高级自动化接口，适合批量下载；网页版适合查看单个基因组的详细介绍。

1. 元数据 (Metadata) vs 网页版表格

核心问题：CLI 下载的 jsonl 文件和网页上导出的 csv 表格，内容一样吗？

一句话总结：JSONL 是数据金矿，Excel 是精炼后的首饰。 日常科研用 Excel 足够；如果 Excel 里缺了某个关键字段（比如详细的测序仪型号），去 JSONL 里一定能找到。