iTOL — 在线交互式进化树展示与注释平台¶

一句话说明¶

iTOL（Interactive Tree of Life）是 EMBL 提供的免费在线工具，把 Newick/Nexus 格式的进化树上传后，可以交互式地给树叶、分支、节点添加颜色、标签、热图、饼图等注释，最终导出高质量矢量图。白话理解：把系统发育树"P图"的专业网站。

安装与配置¶

iTOL 是纯网页工具，无需安装，直接访问：

https://itol.embl.de

如果需要批量操作，可以用 R 包 itol.toolkit 或 Python 的 itolapi 在本地生成注释文件：

# 安装 R 辅助包（可选，批量生成注释文件）
install.packages("itol.toolkit")  # 在 R 控制台运行

# 安装 Python API 客户端（可选，用于脚本自动上传）
pip install itolapi  # 命令行安装 Python 客户端

注册免费账号可以保存树文件（当前托管超过 150 万棵树）。

核心用法¶

上传树文件¶

1. 打开 https://itol.embl.de/upload.cgi
2. 拖入 .nwk / .nexus / .xml 文件
3. 点击 Upload
4. 进入交互编辑界面

基本控制面板操作¶

Controls 面板 → Basic → 调整树型（圆形/矩形/扇形）
Controls 面板 → Advanced → 修改叶标签字体、颜色
Datasets 面板 → 上传注释文件（见下方格式）

生成注释文件（Python itolapi 示例）¶

from itolapi import Itol, ItolExport  # 导入 API 库

# --- 上传树 ---
itol_uploader = Itol()
itol_uploader.params['treeName'] = 'my_tree'           # 树的名称
itol_uploader.params['treeFile'] = 'tree.nwk'          # 本地 Newick 文件路径
itol_uploader.params['datasetFile'] = 'annotation.txt' # 注释文件路径（可选）
status = itol_uploader.upload()                        # 执行上传
print("上传状态:", status)
print("树 ID:", itol_uploader.comm.upload_id)          # 获取返回的树 ID

# --- 导出图片 ---
itol_exporter = ItolExport()
itol_exporter.set_export_param_value('tree', itol_uploader.comm.upload_id)  # 指定树 ID
itol_exporter.set_export_param_value('format', 'svg')   # 导出格式：svg/pdf/png
itol_exporter.set_export_param_value('display_mode', '2')  # 1=矩形 2=圆形 3=无根
itol_exporter.export('output_tree.svg')                 # 保存到本地

参数详解¶

注释文件类型	用途	关键字段
DATASET_COLORSTRIP	给叶节点加彩色色块	COLOR, LABEL
DATASET_HEATMAP	多列数值热图	FIELD_LABELS, DATA
DATASET_PIECHART	叶节点旁边的饼图	FIELD_COLORS, DATA
DATASET_BINARY	有/无某特征（0/1）	FIELD_SHAPES, DATA
DATASET_TEXT	叶节点旁文字注释	DATA
POPUP_INFO	点击节点弹出信息框	DATA
TREE_COLORS	分支/节点颜色	TYPE=branch/clade

注释文件第一行必须是 DATASET_XXX，用制表符 \t 分隔字段。

实战案例¶

案例：给宏基因组进化树加门水平彩色色块¶

# 1. 准备注释文件 phylum_color.txt
cat > phylum_color.txt << 'EOF'
DATASET_COLORSTRIP          # 数据集类型
SEPARATOR TAB               # 分隔符：制表符
DATASET_LABEL   Phylum      # 图例标签
COLOR   #ff0000             # 默认颜色（必填）
DATA                        # 数据开始
NODE001 #1f77b4 Firmicutes          # 节点ID 颜色 标签
NODE002 #ff7f0e Bacteroidetes
NODE003 #2ca02c Proteobacteria
NODE004 #d62728 Actinobacteria
EOF

# 2. 在 iTOL 网页 → Datasets → Upload annotation file → 选择此文件

案例：用 itol.toolkit（R）批量生成热图注释¶

library(itol.toolkit)  # 加载工具包

# 假设已有 OTU 丰度矩阵 data.frame，行为样本，列为物种
unit <- create_unit(
  data = otu_matrix,            # 丰度数据矩阵
  key = "heatmap_demo",         # 注释文件名前缀
  type = "DATASET_HEATMAP",     # 注释类型
  tree = "my_tree.nwk"          # 对应的树文件
)
write_unit(unit)  # 输出注释文件到当前目录

常见报错与解决¶

报错 / 问题	原因	解决方法
上传后树为空	Newick 格式有误	用 `ete3.Tree()` 预验证格式
注释不显示	节点 ID 与树叶名不匹配	对比注释文件第一列与树叶名
导出图片文字模糊	选了 PNG 低分辨率	改用 SVG 或提高 DPI 参数
叶名乱码	含特殊字符或空格	替换为下划线，避免括号
API 上传超时	树文件过大（>50万叶）	先裁剪树，保留关键分支

速查表¶

# 常用网址
主站：https://itol.embl.de
帮助：https://itol.embl.de/help.cgi
视频教程：https://itol.embl.de/video_tutorials.cgi

# 支持的树格式
Newick (.nwk)  Nexus (.nexus/.nex)  phyloXML (.xml)
QIIME2 输出   EPA/pplacer 放置文件

# 最新版本
iTOL v6（2024年4月）— 全面重写 UI，支持 GTDB 分类

# itolapi Python 安装
pip install itolapi

# 常用导出格式
svg（矢量图，推荐）  pdf  eps  png