WDL 工作流程定義詳細資訊 - AWS HealthOmics
WDL lenient 中的隱含類型轉換input.json 中的命名空間定義WDL 中的主要類型WDL 中的複雜類型WDL 中的指令WDL 工作流程定義範例

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

WDL 工作流程定義詳細資訊

下列主題提供有關 HealthOmics 中 WDL 工作流程定義可用的類型和指令的詳細資訊。

WDL lenient 中的隱含類型轉換

HealthOmics 支援 input.json 檔案和工作流程定義的隱含類型轉換。若要使用隱含類型轉換，請在建立工作流程時將工作流程引擎指定為 WDL 寬鬆。WDL lenient 旨在處理從 Cromwell 遷移的工作流程。它支援客戶 Cromwell 指令和一些不符合的邏輯。

WDL lenient 支援 WDL 有限例外清單中下列項目的類型轉換：

  • 浮動至 Int，其中強制不會導致精確度損失 （例如 1.0 映射至 1)。

  • Int/Float 字串，其中強制不會導致精確度損失。

  • Map【W， X】 到 Array【Pair【Y， Z】】，如果 W 可強制使用 Y，而 X 可強制使用 Z。

  • Array【Pair【W， X】】 到 Map【Y， Z】，如果 W 可強制 Y，X 可強制 Z （例如 1.0 映射至 1)。

若要使用隱含類型轉換，請在建立工作流程或工作流程版本時，將工作流程引擎指定為 WDL_LENIENT。

在 主控台中，工作流程引擎參數名為語言。在 API 中，工作流程引擎參數名為引擎。如需詳細資訊，請參閱 建立私有工作流程 或 建立工作流程版本 。

input.json 中的命名空間定義

HealthOmics 在 input.json 中支援完整變數。例如，如果您在工作流程 SumWorkflow 中宣告兩個名為 number1 和 number2 的輸入變數：

workflow SumWorkflow {
  input {
    Int number1
    Int number2
  }
}

您可以在 input.json 中使用它們做為完整變數：

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

WDL 中的主要類型

下表顯示 WDL 中的輸入如何對應至相符的基本類型。HealthOmics 提供類型強制的有限支援，因此我們建議您設定明確類型。

基本類型
WDL 類型 JSON 類型 範例 WDL 範例 JSON 金鑰和值 備註
Boolean boolean Boolean b "b": true 值必須是小寫且未加上引號。
Int integer Int i "i": 7 必須取消引號。
Float number Float f "f": 42.2 必須取消引號。
String string String s "s": "characters" 做為 URI 的 JSON 字串必須映射至要匯入的 WDL 檔案。
File string File f "f": "s3://amzn-s3-demo-bucket1/path/to/file" 只要為工作流程提供的 IAM 角色具有這些物件的讀取存取權，Amazon S3 和 HealthOmics 儲存 URIs 就會匯入。不支援其他 URI 結構描述 （例如 file://、 https://和 ftp://)。URI 必須指定 物件。它不能是目錄，表示它不能以 結尾/。
Directory string Directory d "d": "s3://bucket/path/" Directory 類型不包含在 WDL 1.0 或 1.1 中，因此您需要將 version development新增至 WDL 檔案的 標頭。URI 必須是 Amazon S3 URI，且字首結尾為 '/'。目錄的所有內容都會以單一下載方式遞迴複製到工作流程。Directory 應該只包含與工作流程相關的檔案。

WDL 中的複雜類型

下表顯示 WDL 中的輸入如何對應至相符的複雜 JSON 類型。WDL 中的複雜類型是由基本類型組成的資料結構。清單等資料結構將轉換為陣列。

複雜類型
WDL 類型 JSON 類型 範例 WDL 範例 JSON 金鑰和值 備註
Array array Array[Int] nums “nums": [1, 2, 3] 陣列的成員必須遵循 WDL 陣列類型的格式。
Pair object Pair[String, Int] str_to_i “str_to_i": {"left": "0", "right": 1} 配對的每個值都必須使用其相符 WDL 類型的 JSON 格式。
Map object Map[Int, String] int_to_string "int_to_string": { 2: "hello", 1: "goodbye" } 映射中的每個項目都必須使用其相符 WDL 類型的 JSON 格式。
Struct object 
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" 
}
結構成員的名稱必須與 JSON 物件金鑰的名稱完全相符。每個值必須使用相符 WDL 類型的 JSON 格式。
Object N/A N/A N/A WDL Object類型已過期，Struct應該在所有情況下取代為 。

WDL 中的指令

HealthOmics 在 HealthOmics 支援的所有 WDL 版本中支援下列指令。

設定 GPU 資源

HealthOmics 支援執行期屬性acceleratorTypeacceleratorCount和所有支援的 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
}
注意

記憶體不足的任務重試需要 GNU findutils 4.2.3+。預設 HealthOmics 映像容器包含此套件。如果您在 WDL 定義中指定自訂映像，請確定映像包含 GNU findutils 4.2.3+。

設定傳回碼

returnCodes 屬性提供指定傳回碼或一組傳回碼的機制，表示任務成功執行。WDL 引擎會遵守您在 WDL 定義執行時間區段中指定的傳回代碼，並相應地設定任務狀態。

runtime {
    returnCodes: 1
}

HealthOmics 也支援名為 continueOnReturnCode 的別名，其功能與 returnCodes 相同。如果您指定這兩個屬性，HealthOmics 會使用 returnCodes 值。

WDL 工作流程定義範例

下列範例顯示用於在 WDL CRAMBAM中從 轉換為 的私有工作流程定義。CRAM 工作流程的 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}"
    }
}