工具操作

本文旨在介绍GeneDock平台中工具（Tool）的具体操作方法，尤其是如何自己创建工具。

• 若您想了解“什么是工具，什么是工作流”，请参考文档主要概念。
• 若您想了解“如何制作镜像”，请参考文档如何制作镜像。
• 另外，由于名词使用的问题，除了“Tool”，我们系统中有时还会使用“app”作为“工具”的英文对应，希望不要对您造成太大的困扰。

工具的分类：

• “公共工具”，系统已经配置好的工具，提供给大家，可以直接在工作流配置和运行中使用。（公共工具列表请见下方附录1）
• “系统工具”，系统运行过程中的工具，主要用于工作流配置过程中数据的导入和导出。（系统工具列表请见下方附录2）
• “私有工具”，用户可以自己创建工具，然后放到工作流中，在GeneDock平台上运行。

如何创建工具？

在成功制作并上传完Docker镜像之后，点击GeneDock平台上“工具” –> “创建工具”。

创建一个工具主要需要编写5部分信息：

1. 常规：常规的信息（包括对应的Docker镜像、需要的计算资源等）；
2. 输入项：工具所需要的输入文件；
3. 输出项：工具所需要的输出文件；
4. 命令行参数：工具使用到的参数；
5. 命令行模板：将linux命令与输入项、输出项和命令行参数中的变量信息串起来。

下面我们将更详细的介绍每一部分信息的填写方法。

如何填写常规？

常规部分需要填写的内容：

名称	类型	解释	是否必填	例子
类型	字符	镜像的类型，目前只支持Docker镜像	可选，默认为“docker”	docker
镜像	勾选	对应镜像的路径，若镜像上传GeneDock成功，下拉菜单可选	必选	name/bwa:latest
CPU-内存-磁盘空间	下拉列表可选	用于向云端申请CPU资源、内存和磁盘空间	下拉列表可选	4核-8G-400G
工具分类	下拉列表可选	工具所属类型，可选也可自定义，方便以后查阅	可选，默认为“其他”	索引工具
工具主页	字符	工具主页的URL，方便查阅。若有多个URL，可用一个或多个空格分隔。	可填，默认为“空”	bwa的github
使用帮助	字符	工具的使用方法，方便查阅	可填，默认为“空”	bwa的使用方法

注：若有更大资源的需求，请联系GeneDock工作人员。

例如：

如何填写输入项与输出项？

输入/输出项部分需要填写的内容如下：

名称	类型	解释	是否必填	例子
输入/输出项名称	英文字符	自定义的输入/输出项名称，不能为python 中dict 成员函数名称(详见下方注2)	必填	refgenome
输入/输出项类型	勾选	目前只支持文件类型	可选，默认为“文件”	文件
最小个数	整数	该种输入/输出文件的最小个数	可填，默认为“0”	1
最大个数	整数	该种输入/输出文件的最大个数。目前输出文件最大个数为1	可填，默认为“1”	1
文件格式	数组	文件格式，也是文件的后缀，可以勾选也可以自己输入，支持同时允许多种格式	必填	[“fa”, “fasta”]
提示信息	字符	提示信息	可填，默认为“空”	“需要建立索引的参考基因组序列”
前缀	字符	输入文件是否需要前缀，如picard的input用“INPUT=”的格式	可填，默认为“空”	无
分隔符	勾选	输入文件若有前缀，前缀与文件路径之间的分隔符	可选，默认为“空”	无
必选项	勾选	是否是必选项	可选，默认为“是”	是
元素分隔符	勾选	当最大个数大于1时，多个文件之间的分隔符	可选，默认为“空”	空格

注：多个输入/输出“项”和多个输入/输出“文件”的区别。

• 输入/输出项：指软件运行时不同类型的文件。如bwa index的输入文件为参考基因组序列fasta文件，是1种类型的文件，1种输入项。
• 输入/输出文件：指软件可以同时处理一种类型的多个文件。如Fastqc可以同时处理1个或多个fastq文件，但每次运行Fastqc只针对一个文件。此时通过增加“最大个数”来实现，而多个文件之间的分隔符通过“元素分隔符”设置。
• 目前系统每种输出项只支持一个输出文件，但是每种输入项可以有多个输入文件。

注2：不允许使用的输入/输出项名称。

__class__, __cmp__, __contains__, __delattr__, __delitem__,
__doc__, __eq__, __format__, __ge__, __getattribute__,
__getitem__, __gt__, __hash__, __init__, __iter__, __le__,
__len__, __lt__, __ne__, __new__, __reduce__, __reduce_ex__,
__repr__, __setattr__, __setitem__, __sizeof__, __str__, __subclasshook__,
clear, copy, fromkeys, get, has_key, items, iteritems,
iterkeys, itervalues, keys, pop, popitem,
setdefault, update, values, viewitems, viewkeys, viewvalues

如图：

如何填写命令行参数？

命令行参数部分的填写大部分与输入/输出项类似，主要是用来接收非文件的参数。这部分特有的几个选项说明如下，

命令行参数选项说明：

名称	类型	解释	是否必填	例子
默认值	字符	参数的默认值	可填，默认为“空”	bwa index的-a参数，默认利用bwtsw算法
是否使用引号	勾选	参数是否加引号	可选，默认为“否”	bwa index的-a参数不需要引号
参数项类型	勾选	参数项的类型	可选，默认为”字符串“	如2为整型，0.5为浮点型，“bwtsw”为字符串等

命令行参数的类型如下：

类型名称	类型说明	例子
字符串	字符串型参数	“hg19”
浮点型	浮点型参数	1.3
布尔型	布尔型参数	True or False
整型	整数型参数	8
标签	通过前缀值+False和True使用，命令行是否使用标签值	“–normalize”
数组	方便用户输入数组及后续使用，使用交互与枚举不同。	[2,3,16]
枚举	通过添加属性值（创建枚举列表）和设定默认值来使用	[‘hg19’,’b37’]

如何编写命令行模板？

命令行模板，大部分就是常见的linux命令行，如cd /var/data/。但是由于输入项、输出项和命令行参数这些变量，我们系统此处使用了jinja2模板来替代输入、输出和命令行参数。例如

bwa index [各种命令行参数] [输入项中的参考基因组]
tar zcvf [输出tgz文件] [生成的多个index文件]

当然jinja2模板的功能有很多，这里只讲一下我们系统中会用到的几个的功能：

• 变量输出：

jinja2模板用{{ ... }}来进行变量的输出。由于jinja2模板要用英文字符串，需用“inputs”，“outputs”，“parameters”来表示“输入项”，“输出项”，“命令行参数”。下级的具体设置接在后边，用.分隔。

如bwa index工具的“命令行参数”增加了个参数，参数项名称为“algorithm”，在jinja2模板中为：

bwa index {{ parameters.algorithm }}

• 循环：

当你需要遍历一个数组中的每一个变量，分别进行jinja2模板替换时，你需要用{% for ... in .. %} ... {% endfor %}做循环。事实上，我们的每种输入项均用数组保存的，哪怕只是一个输入文件。

如bwa index工具的有1个输入项“refgenome”，故在jinja2模板中为：

bwa index {% for oneread1 in inputs.refgenome %}{{ oneread1.path }} {% endfor %}

请注意，”%”与”{“、”}”之间不要有空格等其他字符。

• 文件在GeneDock系统中的保存

你可能对上个部分inputs.refgenome中的path属性不解，主要是我们在系统中，文件是以.（一串字符串+后缀）来存储文件。故有四个属性来提取文件信息：.path会返回该文件的绝对路径；.enid会返回该文件的enid；.format会返回该文件的格式；.name会返回该文件的名字。

• 测试模板：

如果你对jinja2模板并不特别熟悉，需要测试是否你的jinja2模板在替换了变量之后，得到的命令行是你想要的结果。你可以在“测试栏”中填写一些测试用的字符作为输入、输出和参数，点击“检测模板”，在“命令行”中检查。

创建成功：

如果一切都顺利，就可以点击“保存”，填写工具名字（APP Name），工具别名（APP alias，方便进一步解释），描述（Description）。之后，你可以在工具中看到你自己创建的工具了。

一个完整的例子：

一些小贴士：

1. 工具的名字命名要规范，包括所用的软件名（如bwa）、具体的subcommand（如index）、版本号；
2. 工具的基本信息、帮助信息、描述尽量填写完整，方便以后使用；
3. 我们的数据系统自动加载在”/var/data/“目录下，故可以在此目录运行程序。

附录1

系统工具列表（共4个）

序号	工具名称
1	loaddata
2	storedata
3	mapinput
4	mapoutput