WDL 工作流程定义细节

以下主题提供了有关中可用于 WDL 工作流定义的类型和指令的 HealthOmics详细信息。

WDL 中的隐式类型转换 lenient

HealthOmics 支持 input.json 文件和工作流程定义中的隐式类型转换。要使用隐式类型转换，请在创建工作流时将工作流引擎指定为 WDL lenient。WDL lenient 包括所有标准 WDL 功能以及专为从 Cromwell 迁移的工作流程设计的其他兼容性行为。它支持客户的克伦威尔指令和一些不符合要求的逻辑。

WDL lenient 支持 WDL 有限例外列表中的以下项目的类型转换：https://github.com/openwdl/wdl/blob/wdl-1.1/SPEC.md#-limited-exceptions

要使用隐式类型转换，请在创建工作流或工作流程版本时将工作流引擎指定为 WDL_LENIENT。

在控制台中，工作流引擎参数名为语言。在 API 中，工作流引擎参数被命名为引擎。有关更多信息，请参阅 创建私有工作流程或 创建工作流程版本。

input.json 中的命名空间定义

HealthOmics 支持 input.json 中的完全限定变量。例如，如果您在工作流程中声明了两个名为 number1 和 number2 的输入变量：SumWorkflow

workflow SumWorkflow {
  input {
    Int number1
    Int number2
  }
}   

你可以在 input.json 中将它们用作完全限定变量：

{
    "SumWorkflow.number1": 15,
    "SumWorkflow.number2": 27
}   

WDL 中的原始类型

下表显示了 WDL 中的输入如何映射到匹配的原始类型。 HealthOmics 对类型强制的支持有限，因此我们建议您设置显式类型。

WDL 中的复杂类型

下表显示了 WDL 中的输入如何映射到匹配的复杂 JSON 类型。WDL 中的复杂类型是由原始类型组成的数据结构。诸如列表之类的数据结构将转换为数组。

struct SampleBamAndIndex { 
  String sample_name 
  File bam 
  File bam_index 
} SampleBamAndIndex b_and_i

"b_and_i": { 
   "sample_name": "NA12878", 
   "bam": "s3://amzn-s3-demo-bucket1/NA12878.bam", 
   "bam_index": "s3://amzn-s3-demo-bucket1/NA12878.bam.bai" 
}           

WDL 中的指令

HealthOmics 在所有支持的 WDL 版本中 HealthOmics 支持以下指令。

配置 GPU 资源

HealthOmics 支持运行时属acceleratorType性和acceleratorCount所有支持的 GPU 实例。 HealthOmics 还支持名为gpuType和的别名gpuCount，其功能与加速器对应的别名相同。如果 WDL 定义包含这两个指令，则 HealthOmics 使用加速器值。

以下示例显示如何使用这些指令：

runtime {
    gpuCount: 2
    gpuType: "nvidia-tesla-t4"
} 

为服务错误配置任务重试

HealthOmics 对于因服务错误（5XX HTTP 状态码）而失败的任务，最多支持两次重试。您可以配置最大重试次数（1 或 2），也可以选择不因服务错误而重试。默认情况下，最多 HealthOmics 尝试两次重试。

以下示例设置preemptible为针对服务错误选择不重试：

{
  preemptible: 0 
}     

有关中的任务重试的更多信息 HealthOmics，请参阅任务重试次数。

为内存不足配置任务重试

HealthOmics 支持重试因内存不足而失败的任务（容器退出代码 137，4XX HTTP 状态码）。 HealthOmics 每次重试的内存量都会增加一倍。

默认情况下， HealthOmics 不会针对此类失败重试。使用该maxRetries指令指定最大重试次数。

以下示例设置maxRetries为 3，因此最多 HealthOmics 尝试四次尝试完成任务（初始尝试加上三次重试）：

runtime {
    maxRetries: 3
}     

配置返回码

ret urnCodes 属性提供了一种机制，用于指定返回码或一组返回代码，以指示任务的成功执行。WDL 引擎遵循您在 WDL 定义的运行时部分中指定的返回代码，并相应地设置任务状态。

runtime {
    returnCodes: 1
}     

HealthOmics 还支持名为 continue 的别名 OnReturnCode，它具有与 returnC odes 相同的功能。如果您同时指定这两个属性，则 HealthOmics 使用返回代码值。

支持的 WDL 磁盘表单

HealthOmics 接受所有标准 WDL 1.1 disks 表单。挂载路径和磁盘类型说明符 (SSD,HDD) 被忽略——仅提取数字大小。如果声明了多个条目，则将大小相加到单个/tmp分配中。

HealthOmics 将所有临时存储器安装在。/tmp如果您的工作流程定义声明了多个disks条目，则将汇总大小并将总数配置为单/tmp个卷。有关 WDL disks 运行时属性的更多信息，请参阅 WDL 1.1 规范。

其他支持的运行时属性

使用 OmicStime O ut 运行时属性配置任务级超时

HealthOmics 提供自定义omicsTimeout属性来设置工作流程中的最长任务持续时间。使用以下一个或多个单位将超时持续时间指定为整数（秒）或字符串：sm、h、或d。例如，"40m"、"1h30m" 或 "1m3s"。

以下示例说明如何在 WDL 任务定义的runtime部分中指定omicsTimeout属性。此示例将超时设置为 40 分钟。

    runtime {
        omicsTimeout: "40m"
    }

HealthOmics 为 WDL omicsTimeout 运行时属性提供以下支持：

所有跑步的最大持续时间都在可调整配额的HealthOmics 服务配额控制范围内。您可以申请增加此配额。

WDL 中的任务元数据

HealthOmics 支持 WDL 任务的以下元数据选项。

使用 volatile 属性禁用任务级缓存

volatil e 属性允许您禁用 WDL 工作流程中特定任务的呼叫缓存。当任务被标记为 volatile 时，它将始终执行并且永远不会使用缓存的结果，即使为运行启用了缓存也是如此。

将 vol atile 属性添加到任务定义的元部分：

task my_volatile_task {
    meta {
        volatile: true
    }
    
    input {
        String input_file
    }
    
    command {
        echo "Processing ${input_file}" > output.txt
    }
    
    output {
        File result = "output.txt"
    }
}

WDL 工作流程定义示例

以下示例显示了BAM在 WDL 中从CRAM转换为的私有工作流程定义。t CRAM o BAM 工作流程定义了两个任务并使用genomes-in-the-cloud容器中的工具，该工具如示例所示，并且是公开可用的。

以下示例显示如何将 Amazon ECR 容器作为参数包括在内。这 HealthOmics 允许在容器开始运行之前验证对容器的访问权限。

{
   ...
   "gotc_docker":"<account_id>.dkr.ecr.<region>.amazonaws.com/genomes-in-the-cloud:2.4.7-1603303710"
}       

以下示例说明当文件位于 Amazon S3 存储桶中时，如何指定在运行中使用哪些文件。

{
    "input_cram": "s3://amzn-s3-demo-bucket1/inputs/NA12878.cram",
    "ref_dict": "s3://amzn-s3-demo-bucket1/inputs/Homo_sapiens_assembly38.dict",
    "ref_fasta": "s3://amzn-s3-demo-bucket1/inputs/Homo_sapiens_assembly38.fasta",
    "ref_fasta_index": "s3://amzn-s3-demo-bucket1/inputs/Homo_sapiens_assembly38.fasta.fai",
    "sample_name": "NA12878"
}       

如果要指定序列存储中的文件，请使用序列存储的 URI 进行指示，如以下示例所示。

{
    "input_cram": "omics://429915189008.storage.us-west-2.amazonaws.com/111122223333/readSet/4500843795/source1",
    "ref_dict": "s3://amzn-s3-demo-bucket1/inputs/Homo_sapiens_assembly38.dict",
    "ref_fasta": "s3://amzn-s3-demo-bucket1/inputs/Homo_sapiens_assembly38.fasta",
    "ref_fasta_index": "s3://amzn-s3-demo-bucket1/inputs/Homo_sapiens_assembly38.fasta.fai",
    "sample_name": "NA12878"
}       

然后，您可以在 WDL 中定义您的工作流程，如以下示例所示。

 version 1.0
workflow CramToBamFlow {
    input {
        File ref_fasta
        File ref_fasta_index
        File ref_dict
        File input_cram
        String sample_name
        String gotc_docker = "<account>.dkr.ecr.us-west-2.amazonaws.com/genomes-in-the-
cloud:latest"
    }
    #Converts CRAM to SAM to BAM and makes BAI.
    call CramToBamTask{
         input:
            ref_fasta = ref_fasta,
            ref_fasta_index = ref_fasta_index,
            ref_dict = ref_dict,
            input_cram = input_cram,
            sample_name = sample_name,
            docker_image = gotc_docker,
     }
     #Validates Bam.
     call ValidateSamFile{
        input:
           input_bam = CramToBamTask.outputBam,
           docker_image = gotc_docker,
     }
     #Outputs Bam, Bai, and validation report to the FireCloud data model.
     output {
         File outputBam = CramToBamTask.outputBam
         File outputBai = CramToBamTask.outputBai
         File validation_report = ValidateSamFile.report
      }
}
#Task definitions.
task CramToBamTask {
    input {
       # Command parameters
       File ref_fasta
       File ref_fasta_index
       File ref_dict
       File input_cram
       String sample_name
       # Runtime parameters
       String docker_image
    }
   #Calls samtools view to do the conversion.
   command {
       set -eo pipefail

       samtools view -h -T ~{ref_fasta} ~{input_cram} |
       samtools view -b -o ~{sample_name}.bam -
       samtools index -b ~{sample_name}.bam
       mv ~{sample_name}.bam.bai ~{sample_name}.bai
    }
    
    #Runtime attributes:
    runtime {
        docker: docker_image
    }

    #Outputs a BAM and BAI with the same sample name
     output {
         File outputBam = "~{sample_name}.bam"
         File outputBai = "~{sample_name}.bai"
    }
}

#Validates BAM output to ensure it wasn't corrupted during the file conversion.
task ValidateSamFile {
   input {
      File input_bam
      Int machine_mem_size = 4
      String docker_image
   }
   String output_name = basename(input_bam, ".bam") + ".validation_report"
   Int command_mem_size = machine_mem_size - 1
   command {
       java -Xmx~{command_mem_size}G -jar /usr/gitc/picard.jar \
       ValidateSamFile \
       INPUT=~{input_bam} \
       OUTPUT=~{output_name} \
       MODE=SUMMARY \
       IS_BISULFITE_SEQUENCED=false
    }
    runtime {
    docker: docker_image
    }
   #A text file is generated that lists errors or warnings that apply.
    output {
        File report = "~{output_name}"
    }
}