第一个Krona图：ktImportText 命令实战

前面聊完 Krona 的核心概念，今天直接上手。我最喜欢的一步——看到命令行跑完，浏览器里蹦出一张可交互的圈图，那种成就感比跑通一个 pipeline 还爽。

ktImportText 是 KronaTools 里最常用的命令之一。你给它一个文本文件，它就能吐出完整的交互式 HTML 图表。嗯，我们从头走一遍。

1. 输入文件长什么样？

其实格式很简单：制表符分隔，每一行描述一个层级路径和一个数值。

Root\tBacteria\tProteobacteria\tEscherichia\tE.coli\t120
Root\tBacteria\tFirmicutes\tBacillus\tB.subtilis\t80
Root\tArchaea\tCrenarchaeota\tSulfolobus\tS.solfataricus\t45
Root\tEukaryota\tFungi\tSaccharomyces\tS.cerevisiae\t200

要制表符，不是空格。我曾经因为复制粘贴变成了空格，结果跑出来全是 "No data"… 排查了半天，哭笑不得。

层级可以任意深，最后一个字段必须是整数或浮点数，表示丰度（计数、覆盖度、丰度值都行）。

字段位置	内容	示例
第1~n-1字段	分类层级，从根到叶	Root → Bacteria → Proteobacteria → …
最后一个字段	数值（丰度、计数等）	120

2. 运行 ktImportText

命令最简洁的用法：

ktImportText -i input.txt -o my_krona.html

如果数据量不大，几秒钟就结束了。但我是建议你加上 -v 参数，能看到处理的细节，心里踏实：

ktImportText -i input.txt -o my_krona.html -v

输出就是 my_krona.html，但你先别急——这个文件可不是独立运行的。你打开看看会发现里面引用了若干 JS 和 CSS 文件。

3. 输出结构：不止一个 HTML

实际上 ktImportText 会生成一个目录，里面包含：

my_krona/                ← 目录（以 -o 指定名称，.html 会被替换掉）
├── my_krona.html        ← 主页面
├── kronaLib.js          ← Krona 核心交互库（可能内嵌）
├── kronaSort.js         ← 排序库
├── kronaXML.js          ← XML 解析
├── krona.css            ← 样式
└── data/                ← 存放数据文件（JSON 或 XML）
    └── krona.html.json  ← 实际数据

所以你不能单拎 HTML 出来发给别人，得把整个目录打包。我以前踩过坑：直接 email 了 HTML 文件，对方打不开，弹出空白页。后来加上一句「把整个文件夹拖到浏览器里」，才算搞定。

如果你想让生成的文件更集中，可以指定 -o 为目录路径 + 文件名前缀，或者生成后手动整理。

4. 用浏览器打开，交互检查

双击 my_krona.html 就能在默认浏览器打开。你会看到一根根彩色的扇形，从圆心辐射出去。点击扇形可以展开下一层级，鼠标悬停能看到具体数值和百分比。

缩放：点击圆心向外扩散，点击外圈向内收缩。
搜索：右上角有个搜索框，输入分类名能高亮定位。
排序：默认按数值从大到小排列，你也可以手动拖动调整显示顺序。

为什么推荐用 Chrome / Firefox？我试过用老版 Edge，有些 JS 动画卡顿。新 Edge 基于 Chromium 没问题。

5. 常见坑 & 我踩过的雷

坑1：路径分隔符用错了
Krona 默认以制表符分隔层级。如果用了逗号或空格，数据会被当成单层节点，所有东西挤在一圈上。

小技巧：检查文件编码
文本最好用 UTF-8 无 BOM。如果数据里包含中文分类名，BOM 可能导致首字符乱码。我自己写过一个小脚本：file -i input.txt 看编码，确保是 charset=utf-8。

坑2：数值太大或太小
Krona 支持的数字范围很广，但如果你的丰度值差异超过 10⁶ 倍，小数值可能会被挤压成几乎不可见的细丝。这种情况建议先做 log 变换，或截断极值。

6. 理解输出格式：数据流图

下面这张图帮你理清整个数据流——从文本到交互图的完整链路。

你从左边输入数据，中间跑命令，右边生成目录。红框是命令，绿框是输出目录。注意那个小黄框的提示——跨域问题偶尔会遇到，尤其当你把 HTML 文件拖到浏览器里时。解决办法很简单：在目录里开一个本地 HTTP 服务。

python3 -m http.server 8000 --directory my_krona/

然后访问 http://localhost:8000/my_krona.html，完美。

7. 实战：从零生成一个迷你 Krona

来，跟我一起敲一遍。新建一个 test.txt，内容就我们刚才的例子：

Root\tBacteria\tProteobacteria\tE.coli\t120
Root\tBacteria\tFirmicutes\tB.subtilis\t80
Root\tArchaea\tCrenarchaeota\tSulfolobus\t45
Root\tEukaryota\tFungi\tS.cerevisiae\t200

（确保是制表符！）然后执行：

ktImportText -i test.txt -o my_first_krona.html -v

你会看到类似：

Parsing "test.txt"...
Processing 4 lines...
Writing output to "my_first_krona/my_first_krona.html"...
Done.

打开 my_first_krona/my_first_krona.html，你会看到四个大扇形，分别代表 Bacteria、Archaea、Eukaryota。点击 Bacteria 能看到 Proteobacteria 和 Firmicutes，再点 Proteobacteria 看到 E.coli。完美体现了层级结构。

8. 几个参数让我觉得好用

参数	说明	我常用的场景
`-n`	指定图的标题（显示在顶部）	多项目对比时标明样本名称
`-s`	设定圆环的最大半径（像素）	在报告里固定大小好排版
`-d`	指定输出目录名（不通过 -o 推断）	批量生成时统一目录结构
`--expand`	初始展开层级，比如 `--expand 2`	让看图者一眼看到第二层级的概貌

我个人的推荐初学者组合：

ktImportText -i data.txt -o result.html -v -n "My First Krona" --expand 2

这样既有界面标题，又能直接看到二级分类，一目了然。

9. 本章重点一句话总结

记住：输入是制表符分隔的层级+数值，输出是一个目录，里面包含 HTML、JS、CSS 和数据文件。要打开它，要么双击主 HTML（多数情况工作），要么用本地服务器。保存好这个操练，后面的章节我们会在实际生物信息学数据上用它——比如从 MetaPhlAn 或 Kraken 的输出直接生成物种丰度圈图，那才是真正干活的时候。