bioinformatics-visualization

生物信息学可视化

---

iTOL 数据集格式与故障排查

选择合适的数据集类型

DATASET_BINARY（推荐用于标记/符号）：

• 比 DATASET_SYMBOL 更可靠
• 必须为所有物种列出二进制值（0 或 1）
• 格式更简单，与 iTOL 的兼容性更好
• 用途：存在/缺失标记、技术指标、类别高亮

格式示例：

DATASET_BINARY
SEPARATOR TAB

DATASET_LABEL	CLR Technology
COLOR	#ff0000

LEGEND_TITLE	Sequencing Technology
LEGEND_SHAPES	2
LEGEND_COLORS	#ff0000
LEGEND_LABELS	CLR (PacBio)

FIELD_SHAPES	2
FIELD_COLORS	#ff0000
FIELD_LABELS	CLR

DATA
Species_name_1	1
Species_name_2	0
Species_name_3	1

DATASET_SYMBOL（可靠性较低）：

• 格式可能比较棘手
• 每个物种的形状/大小/颜色规格较复杂
• 即使格式有效，也可能无法正确显示
• 除非 BINARY 无法满足需求，否则请避免使用

DATASET_COLORSTRIP（适用于渐变）：

• 用于颜色渐变时可靠（例如时间数据、连续值）
• 只需列出有数据的物种
• 适用于非二元类别数据或连续数据

常见 iTOL 错误及修复方法

错误：“Unknown variable 'SYMBOL_SHAPE'”

• 原因：将全局符号设置与每个物种的数据混用
• 修复方法：切换到 DATASET_BINARY 格式

错误：“Invalid color '1' for node X”

• 原因：DATASET_SYMBOL 数据格式不匹配
• 修复方法：改用 DATASET_BINARY，格式为：species<tab>0_or_1

树上未显示符号：

• 可能原因：DATASET_SYMBOL 格式问题
• 修复方法：转换为 DATASET_BINARY
• 验证：检查配置中的所有物种是否都存在于树文件中

物种名称兼容性

重要：树文件与注释文件中的物种名称必须完全一致

常见问题：

1. 区分大小写：“Alca Torda” 与 “Alca_torda”
2. 空格与下划线：树格式中始终使用下划线
3. 亚种名称：谨慎处理由三部分组成的名称

区分大小写问题的修复方法：

# Convert scientific names to tree format with case normalization
df['species_tree'] = df['scientific_name'].str.replace(' ', '_')
# Fix uppercase after underscore (Alca_Torda -> Alca_torda)
df['species_tree'] = df['species_tree'].str.replace(
    r'_([A-Z])',
    lambda m: '_' + m.group(1).lower(),
    regex=True
)

验证模式：

# Always validate species compatibility
import re

# Extract species from tree
with open('tree.nwk') as f:
    tree_content = f.read()
tree_species = set(re.findall(r'([A-Z][a-z]+_[a-z]+)', tree_content))

# Check config species
config_species = set(df['species_tree'])
missing = config_species - tree_species

if missing:
    print(f"Species in config but not in tree: {missing}")

时间数据的颜色渐变

有效的配色方案：

时间进程（旧 → 新）：

• 浅黄 → 深红（ColorBrewer YlOrRd）
• 清晰展示从过去到现在的进程
• 示例：#ffffcc（2019）→ #b10026（2025）

避免使用：

• 蓝色 → 黄色 → 红色（中间值容易造成混淆）
• 将发散色板用于顺序数据

适用于顺序数据的 ColorBrewer 色板：

• YlOrRd：黄-橙-红（时间、强度）
• YlGn：黄-绿（生长、植被）
• PuBuGn：紫-蓝-绿（水体、深度）

调试工作流

1. 生成配置文件
2. 上传到 iTOL（https://itol.embl.de）
3. 如果出现错误：将错误消息保存到文件
4. 检查格式：BINARY、SYMBOL 还是 COLORSTRIP
5. 验证物种名称：与树文件进行匹配
6. 使用最小数据集测试：先测试 5-10 个物种
7. 根据需要切换格式：从 SYMBOL 切换到 BINARY 通常有效

---

相关技能

• data-visualization：通用可视化最佳实践
• bioinformatics/fundamentals：生物信息学核心概念
• bioinformatics/phylogenetics：系统发育分析工作流