alterlab-blast

BLAST+ — 命令行序列搜索

端到端运行本地 NCBI BLAST+ 2.17.0 搜索：使用 makeblastdb 构建数据库，使用 blastn / blastp / blastx / tblastn 搜索，生成可供机器解析的表格输出，并按分类群限定搜索范围。对于超大型蛋白质搜索，可交由 DIAMOND blastp --ultra-sensitive 处理（据 DIAMOND 项目称，速度比 BLAST 快 100 倍至 10,000 倍）。这是 CLI / 本地数据库 技能，与 Biopython Web API 和 gget 单行命令有意区分（参见下方的路由表）。

批量构建数据库和大型搜索会大量占用 CPU 和 IO，且完全离线——适合在本地计算资源上运行，避免消耗 API 调用。

何时使用此技能

当请求涉及以下任一内容时，使用此技能：

• “对这些序列运行 BLAST”、“运行 blastn/blastp/blastx/tblastn”、“命令行 BLAST”
• “构建本地 BLAST 数据库”、“makeblastdb”、“为 BLAST 建立此 FASTA 的索引”
• “将我的 reads 与本地 nt/nr 数据库比对”、“获取可供解析的表格形式 BLAST 命中结果”
• “将 BLAST 搜索限定到某个分类群”（-taxids / -negative_taxids）
• “BLAST 搜索数百万个蛋白质太慢” → DIAMOND blastp
• 从 BLAST DB 中提取序列（blastdbcmd，需要 -parse_seqids）

不适用的情况

请将相关请求路由到合适的相邻技能，而非勉强使用 BLAST+：

请求实际涉及……	路由到
Web BLAST API（Bio.Blast.NCBIWWW.qblast），或在 Python 工作流中使用 Bio.Blast 解析 BLAST 结果	alterlab-biopython
快速单行命令 BLAST/数据库查询（gget blast、基因/结构/富集查询）	alterlab-gget
以编程方式统一访问多种生物学 Web 服务（UniProt、KEGG、Ensembl REST、NCBI eUtils）	alterlab-bioservices
根据序列构建/搜索系统发育树，而非进行相似性搜索	alterlab-phylogenetics
将 reads 比对到参考基因组（BWA/minimap2 → BAM）以及处理 SAM/BAM	alterlab-pysam
FASTQ→VCF 变异检测工作流	alterlab-nf-core-sarek
转录本水平的 RNA-seq 定量（salmon/kallisto）	alterlab-rnaseq-quant
16S/ITS 扩增子分类（QIIME 2）	alterlab-qiime2-amplicon
蛋白质结构预测 / 嵌入（ESM、AlphaFold）	alterlab-esm

如果用户明确提到“Web BLAST”、“NCBIWWW”或“不安装任何东西”，他们需要的是 alterlab-biopython，而不是此技能。

快速开始

# 1. Build a protein DB (‑parse_seqids enables blastdbcmd retrieval + DIAMOND reuse)
makeblastdb -in proteins.fasta -dbtype prot -parse_seqids -out mydb -title "my proteins"

# 2. Search, tabular output you can parse, std 12 columns
blastp -query query.faa -db mydb -outfmt 6 -evalue 1e-5 -out hits.tsv

# 3. QC / summarize the tabular output (stdlib only)
uv run python scripts/parse_blast_tab.py hits.tsv --best-hit

-outfmt 6 是规范的机器可读格式；其默认列为 std 集合：qseqid sseqid pident length mismatch gapopen qstart qend sstart send evalue bitscore。使用 -outfmt 7 可获得相同的列，并附带注释行。

选择合适的程序

查询	目标数据库	程序
核苷酸	核苷酸	blastn
蛋白质	蛋白质	blastp
核苷酸（翻译后）	蛋白质	blastx
蛋白质	核苷酸（翻译后）	tblastn

对于 makeblastdb，核苷酸目标序列使用 -dbtype nucl，蛋白质目标序列使用 -dbtype prot。

五个常见误区

1. -max_target_seqs 并不是“得分最高的前 N 个命中”的筛选器。 它是在搜索过程中作为启发式截断条件应用的、要保留的比对序列数量；分数相同的序列按“数据库中的序列顺序”打破平局，而非按分数。设置 -max_target_seqs 1 并不能可靠地返回得分最高的单个命中。要获得最佳命中，请设置一个足够大的值，并在排序后选取首行（参见 scripts/parse_blast_tab.py --best-hit）。默认值为 500。
2. blastn 的 -task 设置错误。 megablast（默认值）适用于高度相似的序列；跨物种或差异较大的命中请使用 blastn，查询序列短于约 30 nt 时（引物、sgRNA）请使用 blastn-short。dc-megablast 是用于物种间比较的不连续选项。
3. 构建数据库时忘记使用 -parse_seqids。 若未使用该选项，就无法通过 blastdbcmd -entry 提取序列，DIAMOND 也无法干净地复用序列 ID。之后无法添加此选项，必须重建数据库。
4. 为 DIAMOND 的 -outfmt 自定义列列表加引号。 BLAST+ 要求将格式说明加引号（-outfmt '6 qseqid sseqid pident evalue'）；DIAMOND 则要求不加引号（--outfmt 6 qseqid sseqid pident evalue）。混淆两者是常见的隐蔽错误。
5. 多线程。 使用 -num_threads N。从 BLAST+ 2.15 起，默认的 -mt_mode 0 表示 BLAST 会根据查询和数据库的大小自行选择拆分方式，这是 NCBI 建议保留的设置。仅在有意为之时覆盖：-mt_mode 1 = ThreadByQuery（许多小型查询），-mt_mode 2 = ThreadByDatabase（少量大型查询、大型数据库）。

完整选项参考、分类范围限制和数据库准备详情： references/blast_cli.md。

分类范围限制

按 NCBI taxid 将搜索范围限制在某些分支内（或排除这些分支）：

blastn -query q.fna -db nt -taxids 9606 -outfmt 6 -out human_only.tsv
blastp -query q.faa -db nr -negative_taxids 2 -outfmt 6 -out no_bacteria.tsv

按 taxid 限定范围需要使用支持分类信息的数据库（构建或下载时带有 *.taxid 映射，例如 NCBI 预格式化的 nt / nr）。参见 references/blast_cli.md。

DIAMOND — 大规模蛋白质搜索的快速方案

如果使用 blastp / blastx 搜索数百万个蛋白质时速度太慢，DIAMOND 可直接用于蛋白质空间搜索：

diamond makedb --in nr.faa -d nr_diamond
diamond blastp -d nr_diamond -q query.faa -o hits.tsv \
  --ultra-sensitive --outfmt 6 qseqid sseqid pident length evalue bitscore

灵敏度级别（从快到最灵敏）：--fast、--mid-sensitive、 --sensitive、--more-sensitive、--very-sensitive、--ultra-sensitive。若未指定灵敏度标志，DIAMOND 将运行其默认模式，灵敏度介于 --fast 和 --mid-sensitive 之间。需要达到与 BLAST 相当的召回率时，请使用 --ultra-sensitive。DIAMOND 的 --outfmt 6 与下方的 BLAST+ 表格解析器兼容。详情和权衡： references/diamond.md。

推荐工作流

1. 从上方的查询/目标表中选择程序。
2. 使用 makeblastdb -parse_seqids 构建数据库（或下载 NCBI 预格式化数据库）。对于超过约 100 万个蛋白质的情况，请改为构建 DIAMOND 数据库。
3. 执行搜索，使用 -outfmt 6、明确的 -evalue 阈值、正确的 -task（blastn）和 -num_threads。如需限定范围，添加 -taxids。
4. 解析并进行质量控制，使用 scripts/parse_blast_tab.py — 它会按 bitscore 排序、提取每个查询的最佳命中、应用一致性/覆盖率/e-value 筛选条件，并在列数似乎被截断时标记 -max_target_seqs 陷阱。
5. 提取任意命中序列，使用 blastdbcmd -db mydb -entry <id>（需要 -parse_seqids）。

报告前请验证

• 确认 blastn -version / diamond version 确实已运行 — 切勿报告未实际产生的命中。
• 说明所用的程序、-task、-evalue 和数据库；没有这些信息，结果毫无意义。
• 如果使用了 -max_target_seqs，请确认最佳命中是通过事后按 bitscore 排序选出的，而不是将保留数量误当作前 N 个命中。
• 对于 DIAMOND 结果，请注明所用的灵敏度级别。

参考资料

• references/blast_cli.md — BLAST+ 2.17.0 选项完整参考：程序、makeblastdb、-outfmt 列、-task、分类范围限定、-mt_mode、blastdbcmd 检索，以及 -max_target_seqs 的注意事项。
• references/diamond.md — DIAMOND 数据库构建、灵敏度模式、输出格式，以及何时应选择它而非 BLAST+。
• NCBI BLAST+ 手册：https://www.ncbi.nlm.nih.gov/books/NBK569856/
• DIAMOND：https://github.com/bbuchfink/diamond

属于 AlterLab 学术技能套件。