最佳实践之生物信息

本文提供使用GeneDock生物信息系统（镜像、工具、工作流）的最佳实践，帮助您更高效、更规范地配置、管理生物信息流程。

注意：这些建议仅是众多实现方式的一种，客户在使用的时候可以根据实际情况进行修改。

开发流程

借鉴计算机软件工程领域持续集成的概念，GeneDock目前生物信息资源的开发主要分为：设计（design） - 开发（develop） - 代码评审（code review） - 发布（release）几个阶段。

设计阶段：开发人员会首先提出开发计划（我们目前使用的是github的issue功能），撰写设计文档。如果开发项目重要，还会制作ppt，开会讨论。
开发阶段：开发人员会在GeneDock的测试账号中，配置镜像、工具、工作流的开发和测试。
代码评审阶段：会将开发测试成功的生信配置调用上传到版本仓库中，供其他工程师进行评审（我们目前使用的是github的pull request功能）。
发布阶段：在代码通过其他工程师的评审后，该生信流程的开发才可以正式用于生产。

除了开发，GeneDock生信团队对于生信流程的修改、更新、版本迭代，均会进行“设计-开发-代码评审-发布”的流程，以保证最终产品的质量。

版本控制和目录结构

尽管GeneDock的生物信息系统会保证您存储流程的安全、同时也支持创建不同版本的工具和工作流。但是，我们依然建议您使用版本控制软件（如git和github）对您的生信流程进行管理，方便协同合作、文件追溯等。

我们建议采用以下的目录结构来保存相关配置：

dockers/                                         # 镜像相关配置
    <docker_name>/                               # 镜像名称
        <docker_tag>/                            # 镜像标签
            Dockerfile                           # 该镜像的Dockerfile
            ...                                  # 该镜像相关的其他文件（可选）

tools/                                           # 工具相关配置目录
    <tool_name>/                                 # 工具名称
        <tool_version>/                          # 该工具版本
            <tool_name>.yml                      # 该工具的配置信息
            ...                                  # 该工具相关的其他文件（可选）

workflow/                                        # 工作流相关配置目录
    <worklfow_name>/                             # 工作流名称
        <workflow_version>/                      # 该工作流版本
            <workflow_name>.yml                  # 该工作流的配置信息
            <workflow_name>_parameter.yml        # 该工作流的参数模板（可选）
            <workflow_name>_report.md            # 该工作流的报告模板（可选）
            ...                                  # 该工作流相关的其他文件（可选）

对于镜像的相关配置，您需要保存Dockerfile和一些其他文件（例如自己写的脚本、更改）

根据GeneDock系统设计生信流程

目前GeneDock的生信系统模型包含镜像、工具、工作流三个部分（我们也叫作资源），且三种资源逐个依赖。如何根据GeneDock系统特点，来设计您的生物信息学流程十分重要。

需要考虑以下几个因素：

镜像大小适宜：
- 包含多个软件：由于一个镜像可以供多个工具使用，故镜像中可以包含多个相关的软件。如在基因组分析中，把质控的fastq软件、比对的bwa软件和文件处理的samtools软件均放在一个镜像中。
- 不宜过大：由于过大镜像会浪费传输时间，因此我们建议您镜像大小不超过3G（详见常见问题），且不要把数据放到镜像中。
工具、工作流合理配置：
- 工具和工作流拆分：对于一个多步的生信流程，若将所有的步骤均放到一个工具中会导致无法并行加速而运算时间变长、工具无法复用而流程灵活性差（如，想去掉/添加某个步骤等）；若将所有步骤都拆分会使流程配置成本增加、一个任务有过多作业增加系统调度时间。因此，我们建议您在使用时，权衡多方面的因素（流程运行时间、灵活性等），设计好工具和工作流的拆分。
- 工具合理填写资源申请：工具的配置过程中，需要填写所申请机子的计算资源（详见工具操作）。高配置的机子资源紧张，不容易调度，排队时间可能会长；低配置的机子资源宽松，容易调度，排队时间比较短。

具体建议

镜像配置

使用Dockerfile而非docker commit来创建镜像，方便追溯；
Dockerfile中使用#撰写注释信息，方便其他人阅读和自己之后查看；
Dockerfile中每层少些命令，避免造成单层过大；
镜像的tag尽量避免使用默认的latest，当镜像有多个版本时容易造成混乱；
编写脚本自动化镜像创建、传输步骤。

镜像创建传输脚本示例

#!/usr/bin/env bash

# 设置镜像名称和标签
imagename="<image_name>"        # 例如，bwa
imagetag="<image_tag>"          # 例如，1.0
registry="<image_registry>"     # 例如，cn-beijing-registry.genedock.com

# 切换路径
cd /path/to/<image_name>/<image_tag>/Dockerfile
docker login -e='您的邮箱' -u='用户名@账号名' -p='登陆密码' $registry

# 创建镜像
echo "build image ..."
docker build --rm -t ${registry}/您的账号名/${imagename}:${imagetag} .

# 上传镜像
echo "push image ..."
docker push ${registry}/您的账号名/${imagename}:${imagetag}

工具配置

使用网页版进行工具配置，避免格式、缩进错误；
使用API或者SDK（python版或java版）获取（GetTool API）、更新（PutTool API）工具配置（json或者yaml文件）；
不同字段写清楚，方便通过详情页查看工具信息；
输出项尽量拆分开来，方便之后其他工具使用。

部分字段设置推荐

字段	推荐设置	示例
工具名称（name）（单个步骤）	“生信工具集合名字” + “子命令名称” 中间使用下划线分隔首字母大写	Bwa_mem
工具名称（name）（多个步骤）	“分类” + “功能描述” 可以使用“toolkit”表示一个多步骤的分析单元使用“utility”表示一个小工具使用“report”表示报告相关的	GD-toolkit_bam-processing
描述（description）	包含概述，【license】，【软件版本】，【版本变更】等部分	公共工具Bwa_mem详情页
软件主页（homepage）	需要带协议（http，https等）当有多个url时候，用空格分隔	`https://github.com/lh3/bwa`
输入/输出/参数项名称	避免使用inputfile、outputfile、param1等没有意义的命名使用下划线连接	reference_indexfile
文件格式（format）	支持fastq的，最好也支持fq 支持fasta的，最好也支持fa	fasta,fa
提示信息（hint）	由于详情页中还加了其他信息（文件格式等），提示信息最后以句号结尾	“输入参考基因组fasta文件。”
参数项模板（cmd_template）	加上“set -x”在日志中显示使用的命令方便debug 加上“cd /var/data”由于我们系统使用此路径进行运算	略

工作流配置

使用网页版进行工作流配置，加载工具信息更加准确方便，“预览”可以可视化；
如果工作流过长，目前页面编辑窗口较小，也可以使用文本编译器（例如sublime等）辅助；
公有云客户建议尽量使用“公共工具”，避免重复开发，节省时间；
使用API或者SDK（python版或java版）获取（GetWorkflow API）、更新（PutWorkflow API）工作流配置（json或者yaml文件）；
“编辑”页面中工具的配置尽管是自动生成的，但是建议根据自己需求手动更改一些字段（详见下方表格）。