【9.3.5.2】CWL and Shell Tools
问题：
- CWL工具描述和CWL工作流之间有什么区别？
- 我们如何创建工具描述符？
- 我们如何在单步工作流程中使用它？
目标：
- 描述工具与其对应的CWL文档之间的关系
- 命名输入和输出时采用良好做法
- 了解如何引用文件进行输入和输出
- 说明只有描述中明确提到的文件才会包含在步骤/工作流的输出中
- 为调试目的，对步骤/工作流生成的所有文件进行批量捕获
- 使用STDIN和STDOUT作为输入和输出
- 捕获写入特定目录、工作目录或输入所在的同一目录的输出
CWL工作流是用YAML语法编写的。这个简短的教程解释了在CWL中使用的YAML的各个部分。CWL文档包含工作流和运行该工作流的要求。所有CWL文件应以两行代码开头：
cwlVersion: v1.2
class:
cwlVersion字符串定义了工具或工作流所需的语言标准。最新版本是v1.2。
class字段定义了这个特定文档是什么。大多数CWL文档将分为两个类之一：CommandLineTool或Workflow。
- CommandLineTool类用于描述命令行工具的接口，
- 而Workflow类用于将这些工具描述连接到工作流中。
在本课中，将解释这两个类之间的差异，如何将数据传递到命令行工具和从命令行工具传递数据，并为这些工具指定工作环境，最后是如何在工作流中使用工具描述。
您应该按照本课中新手教程练习目录中的示例进行操作。
首先进入到文件夹：
cd novice-tutorial-exercises
一、我们的第一个CWL脚本
为了演示工具描述符的基本要求，将检查流行的“Hello world！”演示的CWL描述。
echo.cwl
cwlVersion: v1.2
class: CommandLineTool
baseCommand: echo
inputs:
message_text:
type: string
inputBinding:
position: 1
outputs: []
输入文件：hello_world.yml
message_text: Hello world!
We will use the reference CWL runner, cwltool to run this CWL document (the .cwl workflow file) along with the .yml input file.
cwltool echo.cwl hello_world.yml
输出：
INFO Resolved 'echo.cwl' to 'file:///.../echo.cwl'
INFO [job echo.cwl] /private/tmp/docker_tmprm65mucw$ echo \
'Hello world!'
Hello world!
INFO [job echo.cwl] completed success
{}
INFO Final process status is success
上面显示的输出表明程序已经成功运行，并且它的输出是Hello world！。
让我们更详细地了解echo.cwl脚本。
如上所述，前两行总是相同的，定义了CWL版本和脚本的类。在本例中，类是CommandLineTool，尤其是echo命令。下一行baseCommand包含将要运行的命令（echo）。
inputs:
message_text:
type: string
inputBinding:
position: 1
此代码块包含工具描述的输入部分。本节提供了运行此特定工具所需的所有输入。要运行此示例，我们需要提供一个字符串，该字符串将包含在命令行中。每个输入都有一个名称，以帮助我们区分它们；第一个输入的名称是：messagetext。字段inputBinding是指定输入应如何显示在命令行上的一种方法。这里，位置字段指示输入将在命令行上的哪个位置；在这种情况下，messagetext值将是添加到命令行的第一个值（在baseCommand、echo之后）。
outputs: []
最后是工具描述的输出。这个例子没有正式的输出。文本直接打印在终端中。因此，使用一个空的YAML列表（[]）作为输出。
为了使脚本更具可读性，将输入字段放在输出字段的前面。然而，CWL语法只要求正确定义每个字段，而不要求它们按特定顺序排列。
二、CWL single step workflow
来自引入事件的RNA-seq数据将用于第一个CWL工作流程。RNA测序分析的第一步是使用fastqc工具对RNA读数进行质量控制。该工具已经可以使用，因此无需编写新的CWL工具描述。
rna_seq_workflow_1.cwl
cwlVersion: v1.2
class: Workflow
inputs:
rna_reads_fruitfly: File
steps:
quality_control:
run: bio-cwl-tools/fastqc/fastqc_2.cwl
in:
reads_file: rna_reads_fruitfly
out: [html_file]
outputs:
quality_report:
type: File
outputSource: quality_control/html_file
在workflow中，steps字段必须始终存在。此字段中列出了要运行的工作流任务或步骤。目前，工作流只包含一个步骤：quality_control。在接下来的几集中，将向工作流中添加更多步骤。
让我们仔细看看工作流程。首先将解释inputs字段。
inputs:
rna_reads_fruitfly: File
查看fastqc工具的CWL脚本，它需要一个fastq文件作为输入。在这个例子中，fastq文件由果蝇的RNA读数组成。所以我们调用变量rna_reads_fruitfly，它的类型是File。为了使其他研究人员能够理解这一工作流程，使用了不言自明和合理的变量名称。
给输入和输出一个合理的名称是非常重要的。尽量不要使用inputA或inputB这样的变量名，因为其他人可能不理解它的意思。
脚本的下一部分是step字段。
steps:
quality_control:
run: bio-cwl-tools/fastqc/fastqc_2.cwl
in:
reads_file: rna_reads_fruitfly
out: [html_file]
工作流的每一步都需要一个名称，工作流的第一步称为quality_control。每一步都需要一个run、一个in和一个out。run字段包含要运行的工具的CWL文件的位置。in字段将输入字段连接到fastqc工具。fastqc工具有一个名为reads_file的输入参数，因此它需要将reads_file连接到rna_reads_fruitfly。最后，out字段是要使用的工具的输出参数列表。在本例中，fastqc工具生成一个名为html_file的输出文件。
脚本的最后一部分是输出字段。
outputs:
quality_report:
type: File
outputSource: quality_control/html_file
输出字段中的每个输出都需要自己的名称。在这个例子中，输出被称为qc.html。在qc.html中定义了输出的类型。quality_control步骤的输出是一个文件，因此qc.html类型为file。outputSource字段指的是输出所在的位置，在本例中，它来自步骤quality_control，称为html_file。
当您想要运行此工作流时，您需要提供一个包含工作流所需输入的文件。这个文件类似于上一节中的hello_world.yml文件。输入文件名为workflow_input_1.yml
workflow_input_1.yml
rna_reads_fruitfly:
class: File
location: rnaseq/GSM461177_2_subsampled.fastqsanger
format: http://edamontology.org/format_1930 # FASTA
在输入文件中，提供了在工作流的输入部分中声明的输入的值。工作流将rna_reads_fruitfly作为输入参数，因此我们在输入文件中使用相同的变量名。设置输入时，需要定义对象的类，例如类：File或类：Directory。location字段包含输入文件的位置，在这种情况下，它是一个本地路径，但我们可以直接使用原始url位置：https://zenodo.org/record/4541751/files/GSM461177_2_subsampled.fastqsanger 在本例中，需要最后一行来提供fastq文件的格式。
运行脚本：
cwltool --cachedir cache rna_seq_workflow_1.cwl workflow_input_1.yml
输出：
...
Analysis complete for GSM461177_2_subsampled.fastqsanger
INFO [job quality_control] Max memory used: 179MiB
INFO [job quality_control] completed success
INFO [step quality_control] completed success
INFO [workflow ] completed success
{
"quality_report": {
"location": "file:///.../GSM461177_2_subsampled.fastqsanger_fastqc.html",
"basename": "GSM461177_2_subsampled.fastqsanger_fastqc.html",
"class": "File",
"checksum": "sha1$e820c530b91a3087ae4c53a6f9fbd35ab069095c",
"size": 378324,
"path": "/.../GSM461177_2_subsampled.fastqsanger_fastqc.html"
}
}
INFO Final process status is success
为了保存中间结果以便以后重复使用，我们使用–cachedir缓存；其中，cache是用于存储缓存的目录（它可以被赋予任何名称，这里我们只是为了简单起见而使用cache）。如果需要回收磁盘空间，您可以随时安全地删除缓存目录。
总结：
- A tool description describes the interface to a command line tool.
- A workflow describes which command line tools to use in one or more steps.
- A tool descriptor is defined using the ComandLineTool class.
- FIXME: How can we use a tool descriptor in a single step workflow?
参考资料
