TBtools | 开箱须知

写在前面

最近可能是不少人要赶毕业论文，于是找上了 TBtools，并急急忙忙希望解决自己的问题。于是，他们总是会在群里 @我或者 @管理员。事实上，这是一个违背群约定的事情，而我向来极其厌恶不遵守约定的任何人。于是在以前我会清理掉他们，毕竟他们其实就是只是来“利用”TBtools一下，毕业以后也并不会去想着这个事情，甚至论文发表的时候，也可能并不会给引用（只看Google Scholar 近500个检索结果，而 bioRxiv 文章只有 200+个citations）。但无论如何，大家都是混学位的，想想也就不管了，能帮一个也算一个。
而事实上，很多问题本来可以避免，只要大家愿意看一看 TBtools 使用手册，或者是翻一翻生信札记公众号的推文，同时，细心一点。
Okay，我知道，大家都很忙，事情也很急，于是写一个短文，相信可以尽可能减少一些 TBtools 的使用问题。

1. TBtools 简介

大体介绍 TBtools：

开发目的：降低生信下游数据分析门槛，减少繁杂操作所耗费时间
目标群体：湿实验科研工作者为主，兼顾干实验分析需求
整体功能：blablabla...

2. 开箱预警

安装与使用 TBtools 时，用户应确保同时不违背以下任一预警：

运行 TBtools，仅用于纯粹的学术研究。
未经 CJ 授权，不允许用于任何可能的商业用途（如售卖图文/视频教程中使用了 TBtools，付费网站开发业务中调用 TBtools，付费培训培训中使用了 TBtools 等）。如果确实不清楚是否可行，那么可发送邮件给 CJ （ccj0410@gmail.com），其余操作姿势请参考《中华人民共和国著作权法》。
TBtools 为自由但不开源软件，任何人不应反编译并将代码用于其他项目。请注意，代码实现逻辑同样受著作权法保护。

3. TBtools 的获取

TBtools 的两个主要获取途径:

github
github上存放了 TBtools 的稳定版本。访问链接 https://github.com/CJ-Chen/TBtools/releases，找到自己使用的操作系统对应的版本，下载即可。
QQ群
QQ 群主要用于 TBtools 用户之间交流使用经验和问题。数十位经验丰富的朋友和我均会在群里，不时回复一些值得回复的使用为。TBtools 所有版本更新均优先在 QQ 群中释放，所以具备最新特性的版本只能在 QQ 群中获取。打开 QQ，搜索 QQ 群。

加入其中一个群并在群共享中找到最新版本即可。

4. TBtools 的安装与更新

不同平台的安装方式：
1. Windows
在 Windows 下，直接双击下载好的 .exe 即可。注，不建议直接使用 jar 文件运行，除非不需要使用 TBtoos中部分 Wrapper ，如 BLAST 功能

2. Mac OS
在 Mac 下，直接双击下载好的 .dmg 即可。注，不建议直接使用 jar 文件运行，除非不需要使用 TBtoos中部分 Wrapper ，如 BLAST 功能

3. 其他操作系统，如Linux不同发行版本
在这些操作系统下，用户需要自行安装 Java 运行时环境，版本应在 1.6 或者更高。在具有Java运行时环境的操作系统中，用户可以通过双击 .jar 文件，启动 TBtools；或者通过命令行的方式启动，如

java -jar pathTo/TBtools_JRE1.6.jar

两种更新方式：
1. 安装器（exe/dmg）
若使用安装器进行 TBtools 版本更新，那么其更新方式与安装方式类似，启动新版本的安装器后，可以选择更新模式，运行即可。
2. jar 文件替换更新
无论是使用安装器安装还是直接运行 .jar 文件，除了极少数情况，TBtools 版本更新完全可以手动完成。直接获取最新版本 TBtools 的 .jar 文件，替换原本 TBtools 主目录下同名文件即可。

5. TBtools 使用通识

IOS 逻辑
TBtools 所有功能界面的设计均遵循一个非常简单的逻辑，即：

Input : 按照界面指示的格式准备输入，并设置输入文件
Output：设置输出文件或者文件夹，如果界面上有提示的话
Start：点击 Start 按钮
简单称为 IOS逻辑。用户在使用 TBtools 的每一个功能时，打开对应界面，那么第一件事即设置输入文件，第二件事即设置输出文件，最后一件事即点击开始运行按钮

[ \t ] 符号的含义
在 TBtools 界面上，常常可以看到 [ \t ] 符号，这个符号，对应的是键盘上的 Tab 键，即制表符。注意到，TBtools 输入文件格式要求中，几乎没有以空格符（即 Space 键）分隔的形式。所以，用户准备任何输入文件，一旦涉及到列的分隔，均直接使用 Tab 键即可。一般情况下，在 Excel 等软件中准备的文本，复制黏贴到外部文本文件，列分隔默认为Tab。当然，也可以直接在 Excel 中选择文件另存为 文本文件（制表符分隔）。
设置输入文件的方式：摁钮选择与拖拽放置
TBtools 界面上几乎所有输入均支持拖拽放置。用户准备输入文件后，直接拖拽并放置文件于输入文本框即可。当然，也支持用户通过点击摁钮，在弹出对话框中选择输入文件。
输入文件格式提示信息位置
在 TBtools 中，几乎所有输入文件的格式要求，均直接在输入文本区域附近，如

或
输出文件/文件夹设置注意
与输入文件不同，输出文件/文件夹的设置需要用于参考界面提示进行准备，判断清楚，具体是需要设置输出文件路径还是输出文件夹路径。
对于需要设置输出文件路径的，用户在拖拽设置输出目录后，需要自行手动补全输出文件名（拖拽放置文件或文件夹时，TBtools仅会获取文件所在的文件夹或放置的文件夹路径，需要用户自行设置输出文件名字）。

当然，也存在部分功能，只要设置到输出目录，如

对于这种情况，直接设置到输出目录即可，无需也不应该手动输入文件名字。同时，需要注意，这类情况下，建议确保输出文件夹已经存在。

6. TBtools 运行报错，如何处理？

TBtools 几乎所有功能均经过大量用户的测试，所以可以说，程序非常稳定。但无论程序如何稳健，也需要用户按照正确的要求设置输入文件。一旦输入文件格式有误更或者确实并没有被 TBtools 恰当处理，那么 TBtools 就会报出警告或异常，此时一个黑框往往自动弹出。

区分 Warning 和 Error。
对于前者，一般可以不予理会，程序会自动继续运行，直到得到结果。这类 Warning 是我基于认知直接定义的，在处理一些文件时，总会有部分不符合规范的内容，直接忽略，但还是要提醒用户，确实存在这么回事。警告信息，一般用户可以看到Warning字样。如

【补图】

对于后者，一旦出现，程序一般会终止运行。

【补图】

常见报错信息与可能原因自查
任何软件的报错信息中，往往包括了可能的解决办法。用于遇到报错，可基于报错信息，自行猜测并调整输入文件格式。以下，列出几类常见报错：
a. 数组越界，java.lang.ArrayIndexOutOfBoundsException
【补图】
这类报错往往是用户输入表格文件列数与输入文件格式要求不对应。如，TBtools 要求输入四列的文件，而用户仅仅提供了三列的文件；更或者用户输入的文件使用空格而不是制表符分隔，从而无法被 TBtools 正确识别。具体参考前文 [ \t ] 符号的含义
b. 文件夹不存在，FileNotFoundException
【补图】
这类报错相对简单，往往是用户并没有遵从 IOS 逻辑。或者忘记设置某个输入文件，或者没有设置输出文件。
c....
TBtools 常见问题文集
五年多，组建了数个 TBtools 使用交流群，覆盖了 15000 名用户，几乎每天都会遇到这样那样的用户使用问题。对于一些常见使用问题，我进行了整理。用户遇到使用问题后，无法自行解决，那么首先应该查看这一文集，https://www.jianshu.com/nb/42090583
如何正确提出使用问题
【参考 https://www.jianshu.com/p/be889f7171b4】

写在后面

没有太多想说的。有计划日后录制系列视频。

每一个功能的示例数据我都准备好了，然而这半年一年内估计是没有足够的时间与精力做公益....毕竟存在很多现实的问题需要考量。有机会再算吧。