流程分析

DCS Cloud大约 24 分钟

流程分析

云平台流程分析（workflow）为研究者提供从流程搭建到运行一站式多组学线上任务分析，可满足快速、批量、标准生信分析需求，提供统一的存储及高性能计算能力，用户无需关注底层资源情况，助力生信研究者灵活、便捷的开启生信分析研究。

支持用户自主构建流程，任务批量投递。已支持时空fastq到表达矩阵的标准分析流程（SAW V5/V6/V7），包括转录组，大芯片，小芯片，mIF等分析。单细胞分析包括scRNA-seq, scATAC-seq分析流程等。

流程分析模块主要分为工作流管理、工具箱管理、工具管理及工具箱配置四个模块。

工作流管理

「流程分析」管理项目内成员自建工作流或从公共库引入的工作流，用户可使用项目内的工作流进行数据分析。

提示

流程标签说明：

表示官方团队发布流程

表示工作流来源，从从公共库复制而来

灰色字体表示自定义标签，用于帮助用户区分流程

新建工作流

新建工作流包含两种方式：1、从公共库中复制、2、在线创建

从公共库复制

从公共库复制可以快速将公共工作流复制到项目内，适用于分析人员，无需代码编译。

具体操作

点击“从公共库复制”按钮，界面展示公共库中的工作流，点击工作流卡片上的“复制”按钮，确认后则可添加到项目中。

线上创建

线上创建，该方式主要适用于有生信分析能力的工具开发者。

具体操作

整体创建工作流依赖步骤包含：构建（或选择）docker镜像、编写WDL流程、准备WDL依赖task（可选，按实际需要）

构建镜像

工作流是在容器里运行，所以定义的WDL里需包含docker参数，需提前准备流程相关的镜像（docker）， WDL所需镜像需在云平台上直接构建、通过平台镜像派生或通过外源导入,具体操作可参考镜像管理

镜像构建成功，点击镜像卡片查看镜像的“URL”

在WDL中通过指定镜像URL的方式指定所需的镜像

注意

workflow运行在容器中，需要通过默认参数指定运行的镜像(docker_url)、内存(req_memory)、CPU(req_cpu)

编写WDL

Step1：点击「流程分析」进入工作流管理页面，点击“新建工作流”新建工作流

Step2：填写工作流的名称、版本、描述、工作流标签、流程设置

提示

工作流名称项目内不可重名
工作流版本平台默认为三位，如1.2.3，起始版本号为1.0.0
工作流标签为自定义标签，方便使用流程的用户通过tag快速知道流程信息
是否公开WDL默认公开，则项目内的用户可查看WDL代码，若不勾选该配置，则不可查看WDL代码
是否标记官方流程仅平台官方流程管理员有权限设置，用于标记平台官方流程
是否内部标准流程仅平台官方流程管理员有权限设置，用户标记需要跳转项目芯片投任务的流程

Step3：进入工作流编辑页面，支持在云平台上编辑或者线下文件导入平台，当本地已有工具包时，也可以上传到云平台调用。

新建工作流常见问题

如何测试流程？

提示

云平台提供测试节点用来调试流程，请进入【个性分析】模块，新建分析后选择编程环境”VSCODE“，选择镜像“stereonote-vscode”，资源选择“1cpu 4mem”开启测试节点。

开启测试节点后，进入terminal环境，类似集群的本地环境。平台支持docker和singularity环境下运行流程，cromwell作为jar文件挂载到共享盘中。

当测试docker环境下的脚本时

注：在docker环境中无法再调用dockerurl，即暂时不支持docker in docker方式，若流程需要使用多个软件，需要将软件打包到一个docker镜像中。

当测试singularity环境下的脚本时

平台支持singularity in docker，但选择启动的镜像需要配置singularity环境，系统提供的stereonote-vscode镜像已配置环境，当选择的镜像没有singularity环境时，可通过以下命令安装：

cd /etc/yum.repos.d/
mkdir bak
mv *.repo bak
wget -O /etc/yum.repos.d/Centos-7.repo http://mirrors1.sz.cngb.org/repository/os/repo/Centos-7.repo
wget -O /etc/yum.repos.d/epel.repo http://mirrors1.sz.cngb.org/repository/os/repo/epel7.repo
yum clean all
yum makecache
yum groupinstall -y 'Development Tools'
yum install -y wget libseccomp-devel glib2-devel squashfs-tools cryptsetup runc
wget http://mirrors1.sz.cngb.org/repository/stomicscloud/golang/go1.19.4.linux-amd64.tar.gz
tar -C /usr/local -xzvf go1.19.4.linux-amd64.tar.gz
rm go1.19.4.linux-amd64.tar.gz
echo 'export PATH=/usr/local/go/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
cd /usr/local/go
wget https://mirror.ghproxy.com/https://github.com/sylabs/singularity/releases/download/v3.8.1/singularity-ce-3.8.1.tar.gz
tar -xzf singularity-ce-3.8.1.tar.gz
cd singularity-ce-3.8.1
./mconfig --without-suid
make -C builddir
make -C builddir install
chmod -R 777 /usr/local/etc/singularity

安装好singularity环境后，修改配置文件/usr/local/etc/singularity/singularity.conf

mount sys = no
mount dev = no
mount proc = no
allow setuid = no

完成上述操作后可在环境中打包镜像文件，具体查看【如何构建sif镜像】

测试节点运行流程或脚本

镜像文件准备好后，参考如下命令调试测试脚本

## 命令行直接运行wdl任务
/share/app/jdk8.0.92/bin/java \
-Dconfig.file=/data/reference.conf \
-jar data/file/cromwell-47.jar  \
run /File/data/test.wdl  \
-i /File/data/test.json
## wdl、R、python脚本串成shell运行
nohup sh test.sh(其中可以包含串起的wdl、python或R脚本)  &
## tesh.sh中内容
1. Rscript File/data/test.R -r test.rds -b 50 -p 0.1
2. Python  File/data/test.py -i test.h5ad -p 0.1

测试完成脚本后在流程分析模块注册流程，若在singularity中运行流程，在流程中无需指定docker url，系统可启动默认环境；若在docker中运行流程，需通过docker url代码块指定镜像地址。

上传本地工具怎么用？

在创建脚本界面点击【选择本地工具】按钮，将zip文件上传到云平台中。

在WDL中使用”import“语句调用，例如："import "SAW-ST-V7.task.wdl" as Visualization_tasks"

注意

本地上传的工具只能是压缩包.zip格式，支持将文件直接压缩或者放在文件夹中压缩，但若放在文件夹中压缩，使用import语句时，需要加上文件夹目录，例如导入的task文件放在文件夹下，import语句需写为 import "spatial visualization lasso v2.0.0.task/spatial visualization lasso v2.0.0.task wdl"as Visualization tasks

注意

若压缩包中包含多个WDL文件，可通过多个import语句调用。

Step4：点击【保存】按钮保存工作流，此时平台会校验WDL语法规范，不符合语法规范的会被保存为草稿。创建成功后的工作流出现在工作流-项目工作流列表。

step5：保存成功后，点击工作流卡片【运行】按钮运行工作流，具体操作参考【运行工作流】章节

WDL怎么写？

WDL(Workflow Definition Language) 是一种流程描述语言，包括 workflow 和 task 两部分。Task用于封装一个调用的unix环境和一个Bash脚本，并且表示为一个可复用的函数；Workflow用于调用封装好的Task，使用任务调用的有向、无循环图。

构成WDL脚本核心结构的5个基本组件：workflow, task, call, command, 和output。

WDL语法规则及数据类型

提示

WDL官方语法说明可查看：https://github.com/openwdl/wdl/blob/main/versions/1.0/SPEC.md#typesopen in new window

WDL内置函数主要分为三大类：

输入输出：stdout, stderr,read_tsv

信息获取类：defined, glob, basename, select_first

变量操作：prefix, sub

在云平台上写WDL的注意事项

云平台上WDL通过docker镜像方式在k8s集群运行，每个task步骤一个镜像，运行目录为云平台后台规划的一级存储，无需用户设置。
请勿在WDL中指定BGI-集群路径，workflow的账号可能没有权限访问该集群路径的权限，会导致用户运行任务失败。推荐通用方式,把需要的文件上传到数据管理，在WDL里定义参数为File类型，运行时从数据管理选择文件入参。且考虑到云平台在AWS和阿里云，重庆，青岛，杭州等分中心部署，集群路径有可能失效。
云平台只展示WDL定义的input参数，中间task参数不展示，在WDL代码编辑时注意将重要、必要入参的参数定义在input参数中。
只有WDL定义output参数才会在流程运行结束后展示在云平台数据管理中，所以需要输出的结果文件需定义在workflow的output中，中间task的output不支持输出。
请注意WDL需包含“input”代码块，否则会导致任务运行失败。
云平台创建WDL通过“minitool”工具校验，校验规则参考如下：

https://miniwdl.readthedocs.io/en/latest/getting_started.htmlopen in new window

runtime 中三个参数写法需要用固定格式：docker_url；req_cpu；req_memory ；内存单位有 M、Mi、G、Gi这几种

在云平台上写WDL的一些案例

WDL中，如何设置方法的选择？

例如：开展某分析时，可以选择使用方法A、B和C，但A-B-C三个软件的参数不同，可实现公共参数x,y,z为必选；选择使用A方法后，填写A方法对应的输出参数a1, a2；选择B方法后，填写参数b1, b2；如果不选择C方法，不需要填写C的参数。参考如下：

version 1.0

workflow exampleWorkflow {
    input {
        String method  # "A", "B", or "C"
        String x
        String y
        String z
        String? a1
        String? a2
        String? b1
        String? b2
        String? c1
        String? c2
    }

    if (method == "A") {
        call methodA {
            input:
                x = x,
                y = y,
                z = z,
                a1 = a1,
                a2 = a2
        }
    }

    if (method == "B") {
        call methodB {
            input:
                x = x,
                y = y,
                z = z,
                b1 = b1,
                b2 = b2
        }
    }

    if (method == "C") {
        call methodC {
            input:
                x = x,
                y = y,
                z = z,
                c1 = c1,
                c2 = c2
        }
    }
}

task methodA {
    input {
        String x
        String y
        String z
        String a1
        String a2
    }

    command {
        echo "Running method A with parameters: ${x}, ${y}, ${z}, ${a1}, ${a2}"
    }

    output {
        String result = read_string(stdout())
    }
}

task methodB {
    input {
        String x
        String y
        String z
        String b1
        String b2
    }

    command {
        echo "Running method B with parameters: ${x}, ${y}, ${z}, ${b1}, ${b2}"
    }

    output {
        String result = read_string(stdout())
    }
}

task methodC {
    input {
        String x
        String y
        String z
        String c1
        String c2
    }

    command {
        echo "Running method C with parameters: ${x}, ${y}, ${z}, ${c1}, ${c2}"
    }

    output {
        String result = read_string(stdout())
    }
}

如何指定软件的输出？

例如，用户遇到一个软件（GFAP），软件来自github，且软件书写可能存在不规范的情况，导致只能在软件目录下执行，在这种情况下。如下：

运行目录为云平台提供的一级存储，不支持在镜像内部路径跑任务，可以考虑把软件拷贝到运行当前目录"./"下运行

是否有策略实现程序的续跑？

例如：第一次运行后产生了部分结果，中间结果实际保留在集群的某个路径下；第二次运行时，是否可以通过诸如“cd /path/to/previous/path”来指定该路径作为计算路径继续分析（即：该路径是否能够支持写入）。

云平台WDL每个任务都会新建运行路径，续跑只能把运行成功的task结果链接到当前目录下，从失败的task开始跑，不支持指定目录

个别软件（mixcr）在运行时需要外部的网络访问，但集团安全策略限制，运行任务节点无法联网，只支持离线运行。
WDL中如何写循环语法？

version 1.0

workflow exampleWorkflow {
    input {
        Array[File] inputFiles
    }

    scatter (file in inputFiles) {
        call processFile {
            input:
                inputFile = file
        }
    }

    output {
        Array[String] processedContents = processFile.fileContent
    }
}

task processFile {
    File inputFile

    command {
        cat ${inputFile}
    }

    output {
        String fileContent = read_string(stdout())
    }
}

运行工作流

项目内成员，可以使用项目内工作流进行项目的数据分析。主要包含数据准备，数据选择，任务参数设置，输出设置，运行投递，任务结果查看。workflow支持两种模式的任务投递：运行界面投递、表格模式投递。

单个任务投递

运行界面输入主要适用于单个任务投递，操作如下：

点击【运行界面输入】，表示以文件路径的方式单个运行流程
填写实体ID，实体ID为流程分析过程中关联任务和数据的标识ID，在时空场景下实体ID填写为SN号，在多组学的场景下，实体ID可填写sample id、样本名称或其他分析所需的真实数据ID，填写后流程产生的任务、结果数据都将关联到此ID下。

点击下一步进入输入设置，在输入设置界面填写WDL的参数取值，参数描述列展示参数的说明信息，可通过下拉框“隐藏参数描述”设置不展示参数描述

当工作流的参数过多时，可通过“展示全部参数”下拉框可筛选参数，分为“展示必填参数”、“展示全部参数”、“优先展示无默认值参数”

根据需求过滤参数后，在取值框手动输入或从数据管理选择文件入参，点击切换【专业模式】按钮，可通过Json代码方式填写参数。

参数类型说明：支持File（文件、当选择文件夹时表示输入文件目录）、String、Int、Bool以及对应的一维数组、二维数组类型。

批量任务投递

当需要批量投递任务时，需要通过表格投递，点击【表格数据输入】操作如下

1.数据准备

用户可通过数据管理模块上传需要分析的数据文件，如需批量分析，可通过表格管理的模块，准备批量投递的数据信息。（创建表格请查看「表格-新增表格open in new window」）

2. 数据选择

选择好所需要使用的流程后，点击运行，选择准备好的表格数据，表格中第一列的id相同的为一个任务，勾选数据后点击【下一步】

提示

当选择官方流程：SAW-ST-V7、SAW-ST-V6时，系统将默认为您选择官方表格“STOmics chip data”表格，且根据默认匹配模板匹配表格与参数的关系。
当前“STOmics chip data”表格关联引用了“Sequencing data”和“Image data”，点击“Sequencing data”或“Image data”表格，可打开表格展示关联表格的数据。
当“Sequencing data”中只有SE或PE数据时，默认全选数据；当同时包含SE和PE数据时，默认只选择PE数据
当“Sequencing data”中无数据不可投递任务。
“Image data”中的数据默认选择第一条数据，可以手动选择替换文件。

3.输入设置

在第二步“输入设置”，此步骤为批量任务的每个参数赋值。为参数选中表格的表头后，系统将批量取该列下的值作为任务运行的参数。

点击取值的下拉框，显示所选中数据表格的表头，依次为参数匹配表头。例如在下述流程投递时，“Fastqs”参数是二维数组，需要匹配“Fastq1”、“Fastq2”两列值，选中后则表示分析“C04042E3”样本时，分析的Fastq数据为[/Files/read1.fq.gz,/Files/read2.fq.gz]

若首次运行，在匹配完成后点击【保存为模板】，后续运行该流程，选择表格后可选择已保存的模板，表格表头和参数会自动匹配。
参数设置完成后，点击任务预览确认要分析的数据和参数，在任务预览中可以点击取值框修改参数取值。

提示

当使用表格“STOmics chip data”投递官方流程SAW-ST-V7、SAW-ST-V6时，在预览界面：

点击FASTQ参数取值框，将弹出“Sequencing data”表格，通过勾选的方式选择fq数据。

如果投递的是V6，点击ImageTar或IPR参数取值框，将弹出“Image data”表格，通过勾选的方式选择图像数据，TAR与IPR文件需成对使用，故勾选图像数据时，TAR与IPR将联动勾选，会将同一行的TAR与IPR数据赋值给参数
V7流程需要3.0以上的图像数据，官方表格仅录入了3.0以下的图像数据，V7流程的图像数据需要从数据管理中选择图像数据

4.输出设置

提交任务时，在第三步进入”输出设置“

点击【修改输出目录】可自定义任务产生的结果文件夹目录和文件名，任务输出的结果文件夹默认存在/Files/resultdata/workflow下，且默认以“TasklD”命名结果文件夹。

Step1可选择修改层级目录，选择层级即表示在层级之下创建结果文件夹。
Step2确定结果文件夹名称，修改完成后点击【确认】，任务分析完成后结果文件夹将按用户自定义名称及目录保存。
当用户未选择修改目录名称，则仍以Taskid命名文件夹。

说明：

文件夹名称需同一层级不能重名，重名需提示用户修改
仅支持英文字母、数字、”-“、”_“、”.“

任务备注可自定义任务信息，方便后续查阅任务

任务备注允许输入200字以内的字符
当生成批量任务时，备注对应批量的每条任务

5.任务投递

数据和任务设置完成后，点击运行，任务将投递到分析队列进行分析。

6.任务查看

任务投递完成后，可在项目任务，查看任务状态和结果。

点击任务详情按钮查看任务的基础信息和日志信息。

详细信息展示分析状态、投递信息、以及流程的输入输出。

想查看输出结果文件夹时，点击”查看结果目录“栏下的文件名称，可跳转至数据管理展示结果文件夹下的目录。

点击输出的操作栏【查看】按钮，可以在线预览文件

运行日志展示流程运行过程的执行日志和运行详情

工作流运行详情展示流程运行每个步骤的信息。

运行步骤可查看【sterr】【stout】【script】【中间结果文件】
【script】仅支持创建者查看
【中间结果文件】在中间文件保存的时间范围内可查看

提示

中间结果文件保存遵循以下规则:

当任务完成，任务的最终结果文件保存到数据管理后，中间结果文件自动删除；

当任务失败或取消，中间结果文件默认保存三天，三天后删除。

查看工作流

当想查看工作流具体信息时，可进入工作流详情界面查看。详情页可编辑、运行、复制、发布、删除工作流

编辑工作流

1、点击详情页、流程卡片上的编辑按钮，可进入工作流编辑页面，分为基本信息编辑和WDL信息编辑页面，仅展示需要编辑的内容

2、在编辑模式下，可编辑名称、版本、标签、设置、描述（markdown）、输入参数描述

3、点击“WDL信息”按钮，进入WDL编辑模式，参考历史编辑功能

4、点击保存按钮即可保存编辑的详情信息

导出、导入工作流

1、当要批量迁移工作流时，使用系统导入、导出功能，进入工作流、工具管理界面可见【导出】按钮

选择要导出的工作流，支持复选，点击【导出】按钮，选择的工作流会导出该工作流的所有版本。批量导出的工作流为1个压缩包，目录层级结构如下：

wf1（每个工作流是一个文件夹，命名：工作流名称）
1. wf1_v1（每个版本是一个文件夹，命名：工作流名称_版本号）
  1. wf1_v1.info（该版本的基础信息，有且只有一个，包括工作流名称、版本、版本描述、WDL 主文件、依赖文件列表
  2. wf1_v1.wdl（主 WDL 文件，有且只有一个）
  3. wf1_v1_dependency.zip（该版本的依赖文件，支持最多 1 个）
2. wf1_v2
  1. wf1_v2.info
  2. wf1_v2.wdl
  3. wf1_v2_dependency.zip
wf2

2、当要将工作流导入到项目中时，点击【导入】按钮，从本地选择文件压缩包导入，导入压缩包的目录结果需与导出目录结构一致，当点击流程管理的【导入】按钮，识别到导入文件有重名工作流时，需选择重名文件处理方式：

替换目标工作流，则以导入的文件覆盖原先项目里已有的工作流，且保留原先的关联关系，可触发公共库的更新发布
跳过并生成副本，则在流程分析中添加新的工作流，在工作流名称后自动添加数字后缀
让我决定每个工作流，选择后可选择指定工作流覆盖

说明：

导入覆盖时无法覆盖预制工作流、工具箱配置的工作流及无编辑权限的工作流
工具和工作流的导入前，需要将镜像迁移到相应的环境。

发布（取消发布）工作流

创建好的工作流可发布到公共库，点击【发布】按钮，确认License后，在公共库中可见项目内发布的工作流，发布时会默认发布所有的版本工作流。

注意

为保证用户复制公共库中的工作流到项目后可以正常运行，您在发布工作流时建议使用公共库中的镜像地址；

若使用个人镜像地址，在发布工作流时将一同发布个人镜像。

点击发布按钮后，操作列表新增“取消发布”按钮

点击取消发布按钮，提示用户“确定取消发布XXX吗，公共库将不显示该工作流（工具\工具箱）”。

用户取消发布后，操作按钮回到最开始的名称“发布”

更新工作流

从公共库复制的工作流，在项目内没有编辑过的情况下，仍可持续获取公共库更新的工作流，公共库更新后，工作流卡片及流程管理页面右上角出现【更新】按钮。

当单个更新工作流时，点击卡片【更新】按钮即可
当想要批量更新工作流时，点击右上角【更新】按钮，更新按钮显示需要更新的数量。

点击更新按钮后，将过滤所有待更新的流程，点击【更新全部】按钮，则待更新的工作流会全部更新；
更新后，则源工作流的最新版本覆盖当前工作流

流程分析

# 流程分析

# 工作流管理

# 新建工作流

# 从公共库复制

# 线上创建

# 新建工作流常见问题

# 如何测试流程？

# 当测试docker环境下的脚本时

# 当测试singularity环境下的脚本时

# 测试节点运行流程或脚本

# 上传本地工具怎么用？

# WDL怎么写？

# WDL语法规则及数据类型

# 在云平台上写WDL的注意事项

# 在云平台上写WDL的一些案例

# 运行工作流

# 单个任务投递

# 批量任务投递

# 查看工作流

# 编辑工作流

# 导出、导入工作流

# 发布（取消发布）工作流

# 更新工作流

流程分析

工作流管理

新建工作流

从公共库复制

线上创建

新建工作流常见问题

如何测试流程？

当测试docker环境下的脚本时

当测试singularity环境下的脚本时

测试节点运行流程或脚本

上传本地工具怎么用？

WDL怎么写？

WDL语法规则及数据类型

在云平台上写WDL的注意事项

在云平台上写WDL的一些案例

运行工作流

单个任务投递

批量任务投递

查看工作流

编辑工作流

导出、导入工作流

发布（取消发布）工作流

更新工作流