phylogenetics

系统发育学

何时使用

当需要对同源位点或蛋白质进行比对、构建基因树、评估分支支持度，并生成可解释的树形图时，使用此工作流。多位点分区、一致性因子、祖先状态和年代推断请参阅 IQ-TREE 参考。

基因树本身并不能确立物种树、传播方向或水平转移。仅凭采样日期不足以证明分子钟。

版本与安装

本文档已于 2026-10-01 对照当前官方文档进行审核。所执行的冒烟工作流在 Python 3.12 上使用了 MAFFT 7.526、IQ-TREE 3.1.4、FastTree 2.2.0 和 ETE3 3.1.3。ETE3 在此辅助工具中仍被有意保留；ETE4 是独立的 API，并非可直接替换的替代品。ETE3 导入了 cgi，该模块已在 Python 3.13 中移除。原生可执行文件并非 Python 包。

以下为示意性安装命令；安装后请验证可执行文件版本：

conda create -n phylo -c conda-forge -c bioconda mafft iqtree fasttree trimal
conda activate phylo
uv venv --python 3.12 .venv-phylo
uv pip install --python .venv-phylo/bin/python ete3==3.1.3 numpy six
# Optional rendering backend; it can require a working Qt platform plugin.
uv pip install --python .venv-phylo/bin/python PyQt5

该辅助工具默认使用 iqtree3 和 FastTree；若已有 IQ-TREE 2 安装，可使用 --iqtree-bin iqtree2；若安装的可执行文件名为 fasttree，则使用 --fasttree-bin fasttree。版本 2 的兼容性经过源码检查，但在本次更新中未进行运行时测试。所有分析均在本地进行；此技能不调用任何 HTTP API 或远程推理端点。

工作流

1. 确立生物学输入

• 选择具有适当分类群覆盖度的同源序列；在假定单一历史能描述所有位点之前，先排查旁系同源、污染和重组。
• 使用唯一且不含空白的 FASTA ID，并单独保存样本元数据表。该辅助工具会拒绝空记录/全部缺失的记录以及 ID 中包含 Newick 标点符号的记录。
• 指定 --type nt 或 --type aa。该辅助工具会向 IQ-TREE 传递 -st DNA 或 -st AA，并显式选择核苷酸/蛋白质 FastTree 标志。
• 若使用密码子模型，编码 DNA 需要密码子感知的比对。普通的 MAFFT 核苷酸比对不会自动保持阅读框。
• 保留原始序列、登录号版本、过滤条件、比对结果和确切命令。检查比对长度、空位、组成和分类群身份。

2. 比对与检查

以下 MAFFT 命令已在小型合成 FASTA 数据上验证过：

mafft --auto --thread 1 --inputorder sequences.fasta > aligned.fasta
# L-INS-i: locally alignable homologs, typically small datasets.
mafft --localpair --maxiterate 1000 --thread 1 --inputorder sequences.fasta > linsi.fasta
# E-INS-i: homologs with large internal gaps.
mafft --genafpair --maxiterate 1000 --thread 1 --inputorder sequences.fasta > einsi.fasta
# FFT-NS-i (two refinement cycles), then FFT-NS-2 (progressive).
mafft --retree 2 --maxiterate 2 --thread 1 --inputorder sequences.fasta > fftnsi.fasta
mafft --retree 2 --maxiterate 0 --thread 1 --inputorder sequences.fasta > fftns.fasta

auto 将选择权交给 MAFFT。仅凭序列数量不足以作为准确性标准。单线程运行可简化可重复性；MAFFT 多线程迭代优化在不同运行之间可能产生不同结果。

修剪是可选的，且必须由比对质量证明其合理性，而不能假定它一定能改善每棵树。以下 trimAl 命令经过文档检查，仅为示意；本次审核未安装 trimAl：

trimal -in aligned.fasta -out trimmed.fasta -automated1 -fasta

记录保留的列/分类群，并比较对修剪的敏感性。修剪失败必须停止修剪步骤；不得悄悄地将未修剪的输入以“trimmed”文件名复制。捆绑的辅助工具不会自动修剪。

3. 推断树

使用维护良好的辅助工具，而不是重新创建子进程包装器。在技能目录下，确保可执行文件位于 PATH 中：

python scripts/phylogenetic_analysis.py sequences.fasta --type nt --threads 1 \
  --bootstrap 1000 --seed 42 --output-dir results --no-visualization
# Use a reviewed alignment (including any explicit trimming) without realigning.
python scripts/phylogenetic_analysis.py aligned.fasta --aligned --type nt \
  --threads 1 --output-dir reviewed --no-visualization
# Protein FastTree alternative; --threads applies to MAFFT/IQ-TREE, not FastTree.
python scripts/phylogenetic_analysis.py proteins.fasta --type aa --fasttree \
  --threads 1 --output-dir fast_protein --no-visualization

标准 IQ-TREE 命令使用 -m MFP（ModelFinder，包含 FreeRate 模型）、-B 1000（UFBoot）和 --alrt 1000。-m TEST 仍受支持，但搜索的模型集较窄。使用 --model 指定有科学依据的固定模型。IQ-TREE 检查点会被保留；--redo 会显式重新启动并替换结果。当数据或模型假设发生变化时，请使用新的输出前缀。

FastTree 对 DNA 使用 -nt -gtr -gamma，对蛋白质使用 -lg -gamma。其搜索在 Gamma20 重缩放之前使用 CAT 近似；这并非完整的 Gamma 模型 ML 搜索。JTT 是 FastTree 的蛋白质默认值（无 -jtt 标志）；核苷酸 JC 通过 -nt 且不加 -gtr 来选择。FastTree 默认提供 SH 样局部支持度，范围为 0–1，而非 UFBoot 百分比。应使用基于工作负载的基准测试，而非通用的分类群阈值，来决定使用哪种推断工具。

4. 解读支持度、定根和输出

阅读 .iqtree 和 .log，而不仅仅是图片。在默认的联合检验中， IQ-TREE 会写入以斜杠分隔的 SH-aLRT/UFBoot 标签；请在 报告中核实它们的顺序。UFBoot >=95 和 SH-aLRT >=80 是常见的筛选阈值，并非正确性的 证明或后验概率。不要将标准自举的 70% 规则套用于 UFBoot。模型设定错误、比对错误和采样都可能 产生支持度很高的错误分支；在评估模型违背和 UFBoot 高估时， 可考虑使用 -bnni。

可逆替换模型不会推断进化根。除非显式选择 --outgroup 或 --midpoint 显示选项，否则该辅助工具会保留所提供的树 朝向。应从生物学角度选择外群；中点 定根假设路径长度足够符合分子钟，且仅是一种启发式方法。 --outgroup 会将一个分类单元传递给 IQ-TREE 并验证其 存在。显示重定根会在其分裂上保留支持度标签。 两种显示选项都不会创建带日期的系统发育树，也不会覆盖原始推断的树。

主要输出为 <prefix>.treefile（IQ-TREE）或 <prefix>.tree（FastTree）、 比对文件，以及 IQ-TREE 的 .iqtree、.log、.ckp.gz，外加可选的辅助 文件。.model.gz 缓存模型选择工作；它不是估计模型 参数的报表。请将这些产物放在一起保存。

5. 汇总和可视化

ETE 必须使用 format=1 将联合 IQ-TREE 标签读取为内部名称； 其默认的数值支持度解析器无法解析 95.2/99。该辅助工具渲染 的是原始文本标签，而非 ETE 的默认支持度值。分支统计 使用所有原始的非根边，包括零长度边，且不进行重定根。

# Run from the skill directory in the ETE3 environment.
import sys
sys.path.insert(0, "scripts")
from phylogenetic_analysis import load_tree, tree_summary

tree = load_tree("results/sequences.treefile")
print(tree.get_leaf_names())
print(tree_summary("results/sequences.treefile"))

要请求渲染，请省略 --no-visualization。ETE3 需要 PyQt5；在无头 主机上，必须提供相应的 Qt 平台插件。缺少渲染 支持不会影响推断出的树，并会被明确报告。本次审查中未 实际运行 Qt 渲染。FigTree 或 iTOL 也可以显示 Newick；请核实 查看器是否保留支持度标签和分支长度标尺。

官方参考

• MAFFT 手册和线程
• IQ-TREE 快速入门、当前版本、模型假设
• FastTree 手册
• ETE3 树解析和绘制
• trimAl 手册