克伦威尔输出组织者
croo的Python项目详细描述
克伦威尔输出管理器(CROO)
croo是一个python包,用于组织来自Cromwell的输出。
简介
croo解析来自cromwell的输出metadata.json
,并生成一个有组织的目录,其中包含由--out-def-json
指定的输出定义json文件中描述的每个输出文件的副本(或软链接)。
功能
本地/云存储之间的自动文件传输:例如,下面的命令行可以工作。可以为任何命令行参数定义uri而不是本地路径。下面的命令行从远程元数据json文件(
gs://some/where/metadata.json
)和输出定义json文件(s3://over/here/atac.out_def.json
)读取并将有组织的输出写入gs://your/final/out/bucket
。$ croo gs://some/where/metadata.json --out-def-json s3://over/here/atac.out_def.json --out-dir gs://your/final/out/bucket
软链接(仅限本地存储):croo默认为生成软链接,而不是复制以进行本地到本地的文件传输(在元数据json中定义的本地输出文件与由
--out-dir
指定的本地输出目录)。为了强制复制而不是软链接,无论存储类型如何,请使用--method copy
。本地到云和云到本地文件传输始终使用copy
方法。带有可单击链接的文件表:croo生成带有文件表的html报告,该文件表是具有可单击链接的所有输出文件的摘要/说明。示例:ATAC和ChIP。
安装
通过PIP安装。
$ pip install croo
或者git clone
,然后手动将croo
添加到bash启动脚本(~/.bashrc
)中的环境变量PATH
。确保系统上安装了python3
>;=3.3。
$ git clone https://github.com/ENCODE-DCC/croo $ echo"export PATH=\"\$PATH:$PWD/croo/bin\"" >> ~/.bashrc
存储间文件传输
为了在本地/云存储之间使用自动传输,需要为目标存储配置相应的云cli(gsutil
或aws
)。有关详细信息,请参阅here。
WARNING: Croo does not ensure a fail-safe file transfer when it's interrupted by user or system. Also, there can be race conditions if multiple users try to access/copy files. This will be later addressed in the future release. Until then DO NOT interrupt Croo until you see the following
copying done
message.
用法
croo读取从cromwell生成的METADATA_JSON
,并在OUT_DIR_OR_BUCKET
上生成一个有组织的输出目录。与METADATA_JSON
文件关联的WDL需要OUT_DEF_JSON
。有关ATAC-Seq和ChIP-Seq管道,请参见examples。另请参见details了解如何为自己的WDL生成输出定义JSON文件。您还可以定义OUT_DEF_JSON
in your WDL as a comment,以避免在命令行参数中重复定义它。
$ croo [METADATA_JSON] --out-def-json [OUT_DEF_JSON] --out-dir [OUT_DIR_OR_BUCKET]
usage: croo [-h] [--out-def-json OUT_DEF_JSON] [--method {link,copy}]
[--use-rel-path-in-link] [--out-dir OUT_DIR] [--tmp-dir TMP_DIR]
[--use-gsutil-over-aws-s3] [--http-user HTTP_USER]
[--http-password HTTP_PASSWORD]
metadata_json
positional arguments:
metadata_json Path, URL or URI for metadata.json for a workflow
Example: /scratch/sample1/metadata.json,
gs://some/where/metadata.json,
http://hello.com/world/metadata.json
optional arguments:
-h, --help show this help message and exit
--out-def-json OUT_DEF_JSON
Output definition JSON file for a WDL file
corresponding to the specified metadata.json file
--method {link,copy} Method to localize files on output directory/bucket.
"link" means a soft-linking and it's for local
directory only. Original output files will be kept in
Cromwell's output directory. "copy" makes a copy of
Cromwell's original outputs
--use-rel-path-in-link
Use relative path in link in file table in HTML
report. If your output directory is a cloud bucket
(GCS, AWS), then it is recommended not to activate
this flag unless you have correctly set up file
hosting on a cloud bucket. This will be useful if your
output directory is local but hosted by a web server
(e.g. Apache2)
--out-dir OUT_DIR Output directory/bucket (local or remote)
--tmp-dir TMP_DIR LOCAL temporary directory
--use-gsutil-over-aws-s3
Use gsutil instead of aws s3 CLI even for S3 buckets.
--http-user HTTP_USER
Username to download data from private URLs
--http-password HTTP_PASSWORD
Password to download data from private URLs
文件表
croo在html报告文件中创建文件表。该表包括所有输出的描述和绝对路径。你也可以有这些输出的可点击链接。使用--use-rel-path-in-link
创建与html文件相关的链接。如果您有一个由croo在web服务器托管的本地目录上生成的有组织的输出目录,这将非常有用。在云存储桶(gcs和s3)上,建议不要使用--use-rel-path-in-link
,除非您已将存储桶配置为承载文件。
WDL定制
Optional: Add the following comments to your WDL then Croo will be able to find an appropriate output definition JSON file for your WDL. Then you don't have to define them in command line arguments everytime you Croo.
#CROO out_def [URL_OUT_DEF_JSON_FILE_FOR_YOUR_WDL]
输出定义json文件
必须为相应的WDL文件提供输出定义JSON文件。
对于ENCODE ATAC-Seq pipeline的以下示例,atac.bowtie2
是一个在scatter {}
块中调用的任务,该块迭代生物复制,以便工作流级别中的输出变量atac.bowtie2.bam
的类型为Array[File]
。因此,我们需要一个scatter {}
迭代的索引来访问bam
指向的每个文件。像${i}
(基于0)这样的内联表达式允许访问此类索引。${basename}
指原始输出文件的基名。来自atac.bowtie2
的bam和flagstat日志将分别传输到不同的位置align/repX/
和qc/repX/
。atac.qc_report
是收集所有qc日志的工作流的最终任务,因此不会在scatter {}
块中调用它。不应该有像i0
、i1
、j0
和j1
这样的散点索引。
croo还会在--out-dir
上生成最终的html报告croo.report.html
。此HTML报表包含一个文件表,汇总树状结构中的所有输出文件(按/
拆分)。
示例:
{"atac.bowtie2":{"bam":{"path":"align/rep${i+1}/${basename}","table":"Alignment/Replicate ${i+1}/Raw BAM from bowtie2"},"flagstat_qc":{"path":"qc/rep${i+1}/${basename}","table":"QC and logs/Replicate ${i+1}/Samtools flagstat for Raw BAM"}},"atac.qc_report":{"report":{"path":"qc/final_qc_report.html","table":"QC and logs/Final QC HTML report"},"qc_json":{"path":"qc/final_qc.json","table":"QC and logs/Final QC JSON file"}}}
对于子工作流,定义json文件通常如下所示:
{"[WORKFLOW_NAME].[TASK_NAME_OR_ALIAS]":{"[OUT_VAR_NAME_IN_TASK]":{"path":"[OUT_REL_PATH_DEF]","table":"[FILE_TABLE_TREE_ITEM]"}},"[WORKFLOW_NAME].[SUBWORKFLOW_NAME_OR_ALIAS].[SUBSUBWORKFLOW_NAME_OR_ALIAS].[TASK_NAME_OR_ALIAS]":{"[OUT_VAR_NAME_IN_TASK]":{"path":"[OUT_REL_PATH_DEF]","table":"[FILE_TABLE_TREE_ITEM]"}}}
{ "path" : "[OUT_REL_PATH_DEF]", "table": "[FILE_TABLE_TREE_ITEM]" }
定义最终输出目标和文件表树项。[OUT_REL_PATH_DEF]
是一个文件路径,相对于输出目录种类--out-dir
。以下内联表达式允许用于[OUT_REL_PATH_DEF]
和[FILE_TABLE_TREE_ITEM]
。您可以在${}
中使用基本的python表达式。例如,${basename.split(".")[0]}
应该有助于获取像some_prefix.fastqs.gz
这样的文件的前缀。
Built-in variable | Type | Description |
---|---|---|
^{ | str | Basename of file |
^{ | str | Dirname of file |
^{ | str | Full path of file |
^{ | int | 0-based index for main scatter loop |
^{ | int | 0-based index for nested scatter loop |
^{ | int | 0-based index for double-nested scatter loop |
^{ | tuple(int) | tuple of indices for each dim.: (i, j, k, ...) |
要求
gsutil:运行以下命令配置gsutil:
$ gcloud auth login --no-launch-browser $ gcloud auth application-default --no-launch-browser
AWS CLI:运行以下命令为aws cli进行配置:
$ aws configure