Sixbox 命令行工具

Sixbox 是运行六点了平台应用的工具集合。 Sixbox-linuxSixbox的linux版本,可实现本地linux机器,集群等linux服务器的快速部署和使用。

安装

提示

bash 窗口执行命令:

wget https://bucket.sixoclock.net/resources/dist/latest/Sixbox_linux64_latest.sh
bash Sixbox_linux64_latest.sh
1
2
  1. 按照安装程序的提示进行操作(如果您不确定任何设置,可以接受默认值)。
  2. 为了使更改生效,请关闭然后重新打开终端窗口。
# 下载并安装sixbox
pip3 install sixbox
1
2

提示

  1. 安装windows 子系统(WSL2)和docker桌面版在新窗口打开
  2. 从微软应用商店安装 Debian操作系统在新窗口打开
  3. 在powershell 窗口执行命令wsl --set-default debian设置Debian 系统为默认WSL2 子系统
  4. 打开docker desktop,依次选择Settings → Resources → WSL Integration,在 "Enable integration with my WSL distros" 选择 "Debian",。
  5. 在powershell 命令窗口下执行命令(同linux):
wget https://bucket.sixoclock.net/resources/dist/latest/Sixbox_linux64_latest.sh
bash Sixbox_linux64_latest.sh
1
2
  1. 为了使更改生效,请关闭然后重新打开终端窗口。

测试sixbox

sixbox -h
sixbox search app bwa
1
2

读写配置文件

sixbox包含多个子命令用于实现不同的功能。为了您能够充分使用sixbox的全部功能,我们建议您先设置Sixbox的配置文件。

sibox config命令能够帮助您迅速设置sixbox的配置文件。您可以通过sixbox config -h来查看config命令的相关使用说明。下面向您介绍config命令的使用。

常规配置

如您需要将从sixoclock在新窗口打开获取的客户端登陆授权token写入配置文件,可使用如下命令:

sixbox config set token $(token)
1

快速配置channel,可使用如下命令:

sixbox config add channel $(channel name)
1

如果您想查看Sixbox配置文件中的内容,可以使用info命令

sixbox config info
1

自定义CWLdb的lib路径

sixbox config set libpath $(libpath)
1

客户端登陆秘钥

如您需要与sixoclock进行交互,需要配置客户端登陆秘钥以便sixbox访问sixoclock网站

登陆sixoclock 官网授权中心在新窗口打开 , 点击新增Token生成登陆秘钥,复制该秘钥以备用。

使用sixbox将上述秘钥写入config.yaml,

sixbox config set token ${token}
1

运行CWL应用

run命令用于运行CWL应用。可以通过sixbox run -h查看参数等帮助信息。运行示例如下:

sixbox run ./soapnuke-filter.cwl ./soapnuke-filter.yaml
1

如果您没有本地CWL应用,可以使用sixbox自带的demo应用,亦或使用pull命令(有关pull命令的使用将在下文进行详细介绍)从sixoclock平台获取相关应用。

运行本地CWL应用,

sixbox run ./soapnuke-filter.cwl./soapnuke-filter.yaml
1

运行本地CWL任务(cwlc格式)

sixbox run ./test.cwlc
1

运行从sixoclock应用商店在新窗口打开下载的CWL应用,

# 拉取应用
sixbox pull app 5847e32d-127e-469b-9f7a-3e1b97f4625a
# 生成应用的模板参数并手动配置
sixbox run --make-template 6oclock/bowtie2-build:v2.2.9 > ./bowtie2-build.yaml
# 运行指定参数配置下的应用
sixbox run  6oclock/bowtie2-build:v2.2.9 ./bowtie2-build.yaml
1
2
3
4
5
6

查看运行结果

您可通过sixbox get jobsixbox get job $(job_id)查看CWL任务运行情况:

name                 status        created                 lastUpdated

 test.cwlc-c3tj78     completed     2022-04-29 16:53:24     2022-04-29 16:53:32
 t-3n1PVL             completed     2022-04-29 17:06:33     2022-04-29 17:06:40
 test.cwlc-1mCNFt     completed     2022-04-29 17:47:10     2022-04-29 17:47:17
 test.cwlc-W5JDHS     completed     2022-04-29 17:55:35     2022-04-29 17:55:41
1
2
3
4
5
6

查看运行日志sixbox log

sixbox log test.cwlc-c3tj78

1
2

结果形如:

[main] CMD: bwa mem -R @RG\tID:NA12878.1\tLB:NA12878\tSM:NA12878\tPL:ILLUMINA -M -k 19 -t 2 /var/lib/cwl/stg57773f34-98e5-4c15-b6d2-3a482e008953/hg19.chrM.fasta /var/lib/cwl/stg43dc07d5-f534-41d9-8e99-c78c36578687/NA12878.WGS-100K_1.fastq.gz /var/lib/cwl/stgb74b32cb-eb07-4a79-82cf-6d6da84c5535/NA12878.WGS-100K_2.fastq.gz
[main] Real time: 1.211 sec; CPU: 2.296 sec
INFO [job bwa_mem] Max memory used: 0MiB
INFO [job bwa_mem] completed success
INFO Final process status is success
{
    "aligned_sam": {
        "location": "file:///home/6oclock/bwa-mem-aligned.bam",
        "basename": "bwa-mem-aligned.bam",
        "class": "File",
        "checksum": "sha1$8c945faa0aa44753b446b423738623320646d89f",
        "size": 13655009,
        "path": "/home/6oclock/bwa-mem-aligned.bam"
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

实时查看运行日志(适用于密集输出型任务)

sixbox log -f ${job_name}
1

查看运行输出

sixbox log ${job_name} -o outcome
1

其输出如下:

{
    "aligned_sam": {
        "location": "file:///home/6oclock/bwa-mem-aligned.bam",
        "basename": "bwa-mem-aligned.bam",
        "class": "File",
        "checksum": "sha1$8c945faa0aa44753b446b423738623320646d89f",
        "size": 13655009,
        "path": "/home/6oclock/bwa-mem-aligned.bam"
    }
}
1
2
3
4
5
6
7
8
9
10

停止CWL 任务

sixbox 支持停止正在运行的CWL 任务,如下:

sixbox stop test.cwlc-c3tj78
1

指定条件运行

运行结果默认输出在当前目录下,也可以通过--outdir指定输出目录:

sixbox run --outdir /home/test ./soapnuke-filter.cwl ./soapnuke-filter.yaml 
1

其中, soapnuke-filter.cwl 为下载自sixoclock应用中心soapnuke-filter软件主文件。 soapnuke-filter.yaml为用户配置可视化运行参数的文件。 resource_id为您从sixoclock应用中心在新窗口打开下载的软件主文件的标识id,该id用于识别区分不同的CWL文件。

您也可以使用--make-template来生成一个YAML格式的参数配置文件,用于手动配置您的软件/应用的参数。

sixbox run --make-template ./soapnuke-filter.cwl > ./soapnuke-filter.yaml
1

考虑到您可能不是docker用户,sixbox提供了--udocker--singularity两个参数,帮助您在系统不支持docker的情况下,运行CWL Workflow

sixbox run --udocker ./soapnuke-filter.cwl ./soapnuke-filter.yaml 
1

或者,

sixbox run --singularity ./soapnuke-filter.cwl ./soapnuke-filter.yaml 
1

以命令行方式运行CWL 应用

您或许注意到以上的例子中,所输入的CWL 应用配置文件并非一个必选项,这是因为sixbox同时支持命令行模式配置参数,为您在运行CWL 应用的时候提供便利

 sixbox run 6oclock/bwa:v0.1 -mem test.fastq
1

最后,

run命令可以根据CWLdb中的CWL 应用对应的tag或是resource_id直接运行CWLdb中保存的CWL 应用,如下所示:

sixbox run $(resource_id)
1

或者,

sixbox run $(tag)
1

从应用商店获取CWL应用

查找应用

sixbox 支持通过命令行从sixoclock应用商店查找指定条件的CWL 应用

sixbox search app bwa
1
tag                   provider      name         resource_id                              description

 666oclock/bwa_mem     666oclock     bwa_mem      8a2c930a-32ce-4737-a0c1-2de01ef6182d     bwa_mem 测试案例
1
2
3

下载应用

sixbox pull命令让您可以便捷的从sixoclock应用中心中获取您需要的应用:

sixbox pull app $(pipe_id)
1

其中,pipe_idsixoclock应用中心在新窗口打开中每个应用的对应id,您可点击应用详情页面右侧sixbox 下载运行按钮获得下载命令,如图所示:

image-20220825155059331

查看CWL应用

您可以使用get app查看保存在$(libPath)/resource/pipe/cwldb/content目录下的CWL应用。

sixbox get app
1
tag                              provider     name              resource_id                              version     
                                                                                                                      
 6oclock/bowtie2-build:v2.2.9     6oclock      bowtie2-build     5847e32d-127e-469b-9f7a-3e1b97f4625a     v2.2.9    
1
2
3

查看指定的CWL 应用

sixbox get app 6oclock/bowtie2-build:v2.2.9
1

查看CWL 应用的指定内容sixbox get app ${app_tag} -o

json格式导出CWL 应用源码,

sixbox get app 666oclock/bwa-mem:v1.5 -o json
1

提交CWL应用至本地CWLdb

如果您想将所有的CWL应用应用进行统一管理(事实上,我们也建议你这样做,以便于您使用sixbox进行统一的操作)。您可以使用commit app命令将CWL应用提交至本地CWLdb中,示例如下:

sixbox commit app ./sixbox-linux/testdata/soapnuke-filter.cwl 666oclock/soapnuke-filter:v1.0
1

666oclock/soapnuke-filter:v1.0为该CWL应用的tag,用于区别其他的CWL应用, 其格式为/:分隔的字符串。我们建议每个字段的内容是$(provider)/$(cwl name):$(cwl version)

例如示例中,666oclockCWL应用的创建者,soapnuke-filter为软件的名称,v1.0为该CWL应用的版本号。

提示

组成CWL tag的各字段,支持的字符为数字英文字母_.以及-组成,且_.以及-不能为字段的开头或结尾。

当您提交CWL应用后,

CWLdb下的metadata目录和content目录中会分别将该CWL应用的元信息和源码保存下来,并为这个CWL应用分配一个唯一的id,以便之后调用该文件。

此外,

如果您所提交的CWL应用的tag已经存在于CWLdb中,sixbox将认为这两个文件属于相同文件,并询问您是否需要替换,如果您选择不替换,则本次提交不会进行。

root@25fad418f511:/home/test/dist# sixbox commit /home/test/testdata/soapnuke-filter.cwl 666oclock/soapnuke-filter:v1.0
INFO sixbox 3.0.20210124104916
INFO Resolved '/home/test/testdata/soapnuke-filter.cwl' to 'file:///home/test/testdata/soapnuke-filter.cwl'
/home/test/testdata/soapnuke-filter.cwl is valid CWL.
INFO: There is a CWL resource with the same name in CWLdb. PLEASE confirm whether to replace the file
Do you want to overwrite the file? Please input Y/N: 
1
2
3
4
5
6

使用sixbox get app命令查看相关信息:

tag                                provider      name                resource_id                              version     
                                                                                                                           
 6oclock/bowtie2-build:v2.2.9       6oclock       bowtie2-build       5847e32d-127e-469b-9f7a-3e1b97f4625a     v2.2.9      
 666oclock/soapnuke-filter:v1.0     666oclock     soapnuke-filter     deacac36-70de-42e8-8069-3fb15fb715e6     v1.0  
1
2
3
4

可以看到,原本存在的CWL应用的相关信息并未发生改变。 如果您选择替换,原有CWL应用将会被新提交的文件替换,其resource_id也将被改变。

tag                                provider      name                resource_id                              version     
                                                                                                                           
 6oclock/bowtie2-build:v2.2.9       6oclock       bowtie2-build       5847e32d-127e-469b-9f7a-3e1b97f4625a     v2.2.9      
 666oclock/soapnuke-filter:v1.0     666oclock     soapnuke-filter     bd9f3559-9047-44a4-bd24-6ea14db48173     v1.0   
1
2
3
4

修改CWL 应用的tag

我们提供sixbox tag命令,用于您修改CWLdb中的CWL Workflow相关信息,方便您更好的管理CWL Workflow

sixbox tag app 30479859-c02d-4a40-8e7d-92f9011ac9b8 6oclock/bwa:v0.1
1

其中30479859-c02d-4a40-8e7d-92f9011ac9b8CWLdbCWL Workflow对应的resouece_id6oclock/bwa:v0.1CWL Workflow新的tag信息。

同时,您也可以通过输入原先的tag和新的tag信息,对CWL Workflowtag信息进行修改

sixbox tag app 6oclock/bwa:v0.1 sixoclock/bwa:v0.2
1

6oclock/bwa:v0.1为原先的tag信息,sixoclock/bwa:v0.2为新的tag信息。

删除CWLdb中的CWL 应用

通过sixbox rm app命令,您可以删除CWLdb中的CWL Workflow,其中输入的参数可以是CWL Workflow对应的resouece_id或是tag

sixbox rm app 30479859-c02d-4a40-8e7d-92f9011ac9b8
1

其中30479859-c02d-4a40-8e7d-92f9011ac9b8CWLdbCWL Workflow对应的resouece_id.

您也可以通过如下方式删除CWLdb中的CWL Workflow

sixbox rm app 6oclock/bwa:v0.1
1

其中6oclock/bwa:v0.1CWLdb中需要删除的CWL Workflow对应的tag

推送CWL 应用到应用商店

sixbox 允许将本地CWLdb中的CWL 应用推送到sixoclock应用商店,以供更多人使用。

提示

推送应用之前,请先确保您已配置sixbox 客户端授权token,参见客户端登陆秘钥

示例如下,

sixbox push app 6oclock/bwa:v0.1
1

其中6oclock/bwa:v0.1CWLdb中的CWL 应用对应的tag

更新

sixbox 提供update功能用于在线更新,也可以使用install命令安装指定版本的sixbox

sixbox update sixbox  #更新sixbox到最新版本
sixbox install sixbox=1.1.20210530094243  #安装1.1.20210530094243版本的sixbox
1
2
pip3 install --upgrade sixbox  #更新sixbox到最新版本
pip3 install --upgrade sixbox=1.1.20210530094243  #安装1.1.20210530094243版本的sixbox
1
2

关于sixbox的几点说明

有关配置文件

在了解Sixbox详细用法之前,您需要知道Sixbox配置文件的相关信息。

Sixbox的配置文件用于Sixbox权限控制、记录sixoclock应用中心在新窗口打开地址源和CWLdb路径,您可以在${HOME}/.sixbox/config.yaml中查看。

Sixbox配置文件中记载了三类信息:

  1. token:记录您在sixoclock获取的授权token

  2. channel:记录sixboxsixoclock在新窗口打开中拉取CWL 应用的地址。

  3. libPath:记录了CWLdb的lib路径,Sixbox默认lib路径在您安装Sixbox-linux的根路径。您也可以通过config中相关命令自定义该路径。

一个Sixbox配置文件的示例:

libPath: /root/.sixbox/lib

channel: https://www.sixoclock.net/api

token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2MzU2NzA0MjYsImlhdCI6MTYzNTY2NjgyNiwidWlkIjoiMTBhOGQ2YzUtZWM4MC00Mzg5LThlYTMtZWYyYTgyY2JlN2M5IiwiaXNfcmVmcmVzaCI6ZmFsc2UsInVuYW1lIjoiNjY2b2Nsb2NrIiwicGVybWlzc2lvbnMiOjIzfQ.ru86vr9cB2hlH-Sgf0i93A9D3_rEX2pk8Zvc1GHaZ
1
2
3
4
5

有关CWLdb

当您在使用Sixbox时,Sixbox会为您在本地自动建立一个名为CWLdbCWL Workflow仓库,以便您管理、运行、查找CWL Workflow

CWLdb的路径默认是在Sixbox安装的目录下,但您也可以通过sixbox config set libPath命令自定义该路径.

关于CWLdb的几点说明:

  1. CWLdb中设置metadata目录用于存放CWL Workflow元信息,其主要记录了CWL Workflow的作者、名称、版本和Sixboxsixoclock为其自动生成的名为resource_id的唯一标识码。这些信息有助于您区分、运行、管理CWL Workflow

  2. CWLdbcontent目录下存放了您通过sixbox commit app提交的CWL Workflow和您从sixoclock官方仓库在新窗口打开中下载的CWL Workflow