第四章 第一个Krona图表：用 ktImportText 快速上手

好，咱们开始动手做第一个 Krona 图表。手里有数据，就差把它变成交互式可探索的圆环图了。
我刚开始用 Krona 工具链的时候，最烦的就是「哎呀格式不对报错」。今天咱们用 ktImportText 这个命令行工具，走通最小闭环——从文本文件到 HTML 图表，一气呵成。

4.1 ktImportText 是干嘛的

说白了，它是一个「文本 → 层次结构 → 交互图」的转换器。你给它一个制表符分隔的计数文件，它就能自动识别分类路径，构建出咱们上章讲的那套圆环层级。

核心输入格式只有一句话：每一行是 计数\t分类路径。注意是两个制表符？不，一个制表符。路径内部用空格分割？不，用制表符分割层级。很多新手第一坑就在这里。

4.2 准备一份示例数据

我习惯在真实项目里先拿小数据测试，确认格式无误再上全量文件。下面是一份我常用的「迷你微生物群落」数据，存为 microbial_sample.txt：

120	Bacteria	Proteobacteria	Escherichia
80	Bacteria	Firmicutes	Lactobacillus
60	Bacteria	Actinobacteria	Mycobacterium
30	Archaea	Euryarchaeota	Methanococcus
25	Viruses	Caudovirales	Lambdavirus
15	Eukaryota	Fungi	Saccharomyces
10	Eukaryota	Metazoa	Nematoda
5	Unclassified

每一行：第一列是整数计数，后边依次是域、门、属（也可以任意层级，无所谓）。关键点：同一分类路径在不同行里不能出现「部分重叠但层级拼写不一致」的情况，否则 Krona 会认为它们是不同的分支。我以前因为拼写大小写不统一（Bacteria vs bacteria），多出好几个孤立小扇区，找 bug 找了半天……

4.3 运行 ktImportText 生成图表

确保你已经装好了 KronaTools（参考第三章）。打开终端，进入数据所在的目录，执行：

ktImportText -o my_first_krona.html microbial_sample.txt

如果一切顺利，你会看到类似下面的输出（没有错误信息就是最好）：

Loading: microbial_sample.txt
Processing: 7 unique nodes, 7 leaves, 0 duplicates
Creating HTML: my_first_krona.html
Done.

嗯，注意那个「0 duplicates」——它表示没有重复的分类路径，每个叶节点都是唯一的。如果出现「X duplicates merged」，说明你某些行写重复了，Krona 会自动累计计数，倒也不影响结果，但最好提前整理干净。

4.4 看看我们得到了什么

用浏览器打开 my_first_krona.html，你会看到一个可缩放、可点击的圆形层级图。最内圈是 Bacteria / Archaea / Viruses / Eukaryota / Unclassified，外圈依次展开门、属。鼠标悬停会显示计数和百分比，点击可以「钻取」到下一层。

这就是你的第一个交互式 Krona 报告！不过别急，这还只是默认外观。咱们接下来看看几个常用参数，能让图表更清楚。

4.5 参数速查表

参数	说明	示例
-o	输出 HTML 文件路径（必选）	-o report.html
-n	设置图表标题，显示在左上角	-n "My Microbiome"
-q	安静模式，不打印处理信息	-q
-r	根节点名称，默认为 "root"	-r "All Reads"
-c	指定颜色文件（覆盖默认配色）	-c my_colors.txt
-m	合并相同路径下的小类别（小于 N 的合并）	-m 5

4.6 处理多个输入文件

实际工作中我们经常有多个样本，比如对照组和实验组。你可以把多个文本文件按顺序传给 ktImportText，它会生成一份多组对比的图表（采用星形多边形对比方式）。命令类似：

ktImportText -o combined.html sample1.txt sample2.txt sample3.txt

Krona 会在外圈为每个样本划分一个扇形区域，方便直观比较同一分类在不同样本中的丰度变化。不过要注意：多个文件的分类路径层级结构必须保持一致，否则对比会错位。我踩过的坑：有个样本里多写了一层「Unassigned」，导致那个样本的圈多出一环，对其他样本的对应关系全乱了。解决方案是提前用脚本统一层级。

4.7 常见格式踩坑与排查步骤

1. 分割符错误：检查 input 文件里每列之间是否真的是制表符 \t，而不是多个空格。在终端用 cat -A input.txt 查看，制表符显示为 ^I。
2. 空行或注释行：Krona 默认不跳过以 # 开头的行，会直接报错。建议用 grep -v "^#" input.txt > clean.txt 清理。
3. 计数不是正整数：计数值必须是整数，不能是浮点数或空字段。遇到 0.5 或 100.0 会解析失败。
4. 分类路径中含有特殊字符：像括号 () 或冒号 :，一般没问题，但引号 " 和逗号 , 可能被误解析。稳妥做法是在数据清洗阶段去掉或替换为下划线。
5. 重复路径合并计数是否符合预期：如果希望相同路径自动累加，Krona 默认会合并。但如果你刻意想要两个同路径不同计数的「分支」，那就要改成不同根路径，比如 SampleA 和 SampleB 作为顶层。

4.8 本章知识结构

把上述流程凝缩成一张图，方便你对照着操作：

4.9 小结与下一步动作

现在你已经跑通了第一条 Krona 图生成流水线。这个过程看起来简单，但它是后续批量处理、多组对比、甚至定制颜色系统的基础。我每次接手新项目都会先拿小样本跑一遍 ktImportText，确认格式无误后才上全量数据——这个习惯帮我省去了不知道多少 debug 时间。