HealthOmics ワークフローのワークフロー定義の記述

HealthOmics は、WDL、Nextflow、または CWL で記述されたワークフロー定義をサポートしています。これらのワークフロー言語の詳細については、WDL、Nextflow、または CWL の仕様を参照してください。

HealthOmics は、3 つのワークフロー定義言語のバージョン管理をサポートしています。詳細については、「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" 
}           

HealthOmics ワークフローエンジンは、修飾入力パラメータまたは名前空間入力パラメータをサポートしていません。修飾パラメータの処理と WDL パラメータへのマッピングは、WDL 言語では指定されておらず、あいまいである可能性があります。このような理由から、ベストプラクティスは、最上位 (メイン) ワークフロー定義ファイル内のすべての入力パラメータを宣言し、標準の WDL メカニズムを使用してサブワークフロー呼び出しに渡すことです。

Nextflow でのワークフローの記述

HealthOmics は Nextflow DSL1 と DSL2 をサポートしています。詳細については、「Nextflow バージョンのサポート」を参照してください。

Nextflow DSL2 は Groovy プログラミング言語に基づいているため、パラメータは動的であり、型強制は Groovy と同じルールを使用して可能です。入力 JSON によって提供されるパラメータと値は、ワークフローのパラメータ (params) マップで使用できます。

nf-schema および nf-validation プラグインの使用

HealthOmics は Nextflow プラグインに対して次のサポートを提供します。

ストレージ URIs指定

Amazon S3 または HealthOmics URI を使用して Nextflow ファイルまたはパスオブジェクトを構築する場合、読み取りアクセスが付与されている限り、一致するオブジェクトをワークフローで使用できます。Amazon S3 URIs では、プレフィックスまたはディレクトリを使用できます。例については「Amazon S3 入力パラメータ形式」を参照してください。

HealthOmics は、Amazon S3 URI または HealthOmics Storage URIs での glob パターンの使用をサポートしています。 URIs HealthOmics path または fileチャネルの作成には、ワークフロー定義で Glob パターンを使用します。

時間ディレクティブを使用した最大タスク期間の設定

HealthOmics は、実行の最大期間を指定するための調整可能なクォータを提供します (「」を参照HealthOmics サービスクォータ）。Nextflow v23 および v24 ワークフローでは、Nextflow 時間ディレクティブを使用して最大タスク期間を指定することもできます。

新しいワークフロー開発中に最大タスク期間を設定すると、実行可能なタスクと長時間実行されるタスクをキャッチするのに役立ちます。

Nextflow 時間ディレクティブの詳細については、Nextflow リファレンスの「時間ディレクティブ」を参照してください。

HealthOmics は、Nextflow 時間ディレクティブに対して次のサポートを提供します。

タイムアウト期間は、、ms、、mhまたは の 1 sつ以上の単位を使用して指定しますd。Nextflow 設定ファイルとワークフロー定義で時間ディレクティブを指定できます。次のリストは、優先順位が最も低いものから最も高いものまでの優先順位を示しています。

次の例は、Nextflow 設定ファイルでグローバル設定を指定する方法を示しています。グローバルタイムアウトを 1 時間 30 分に設定します。

process {
    time = '1h30m'
}     

次の例は、ワークフロー定義のタスクセクションでタイムディレクティブを指定する方法を示しています。この例では、タイムアウトを 3 日、5 時間、4 分に設定します。この値は、設定ファイルのグローバル値よりも優先されますが、設定ファイルの my_labelのタスク固有の時間ディレクティブよりも優先されません。

process myTask {
    label 'my_label'
    time '3d5h4m'
        
    script:
    """
    your-command-here
    """
}     

次の例は、名前またはラベルセレクタに基づいて、Nextflow 設定ファイルでタスク固有の時間ディレクティブを指定する方法を示しています。この例では、グローバルタスクのタイムアウト値を 30 分に設定します。タスクの値は 2 時間に設定myTaskし、ラベルが のタスクの値は 3 時間に設定しますmy_label。セレクターに一致するタスクの場合、これらの値はグローバル値とワークフロー定義の値よりも優先されます。

process {
    time = '30m'
    
    withLabel: 'my_label' {
        time = '3h'  
    }

    withName: 'myTask' {
        time = '2h'  
    }
}     

タスクコンテンツのエクスポート

Nextflow で記述されたワークフローの場合、タスクコンテンツを出力 Amazon S3 バケットにエクスポートする publishDir ディレクティブを定義します。次の例に示すように、publishDir 値を に設定します/mnt/workflow/pubdir。Amazon S3 にファイルをエクスポートするには、ファイルがこのディレクトリにある必要があります。

 nextflow.enable.dsl=2
              
  workflow {
    CramToBamTask(params.ref_fasta, params.ref_fasta_index, params.ref_dict, params.input_cram, params.sample_name)
    ValidateSamFile(CramToBamTask.out.outputBam)
  }
  
  process CramToBamTask {
    container "<account>.dkr.ecr.us-west-2.amazonaws.com/genomes-in-the-cloud"
  
    publishDir "/mnt/workflow/pubdir"
  
    input:
        path ref_fasta
        path ref_fasta_index
        path ref_dict
        path input_cram
        val sample_name
  
    output:
        path "${sample_name}.bam", emit: outputBam
        path "${sample_name}.bai", emit: outputBai
  
    script:
    """
        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
    """
  }
  
  process ValidateSamFile {
    container "<account>.dkr.ecr.us-west-2.amazonaws.com/genomes-in-the-cloud"
  
    publishDir "/mnt/workflow/pubdir"
  
    input:
        file input_bam
  
    output:
        path "validation_report"
  
    script:
    """
        java -Xmx3G -jar /usr/gitc/picard.jar \
        ValidateSamFile \
        INPUT=${input_bam} \
        OUTPUT=validation_report \
        MODE=SUMMARY \
        IS_BISULFITE_SEQUENCED=false
    """
  }   

CWL でのワークフローの記述

Common Workflow Language または CWL で記述されたワークフローは、WDL および Nextflow で記述されたワークフローと同様の機能を提供します。Amazon S3 または HealthOmics ストレージ URIs を入力パラメータとして使用できます。

サブワークフローの secondaryFile で入力を定義する場合は、メインワークフローに同じ定義を追加します。

HealthOmics ワークフローはオペレーションプロセスをサポートしていません。CWL ワークフローのオペレーションプロセスの詳細については、CWL ドキュメントを参照してください。

既存の CWL ワークフロー定義ファイルを HealthOmics を使用するように変換するには、次の変更を行います。

使用するコンテナごとに CWL ワークフローを定義する必要があります。固定 Amazon ECR URI を使用して dockerPull エントリをハードコードすることはお勧めしません。

以下は、CWL で記述されたワークフローの例です。

cwlVersion: v1.2
class: Workflow

inputs:
in_file:
  type: File
  secondaryFiles: [.fai]
 
out_filename: string
docker_image: string


outputs:
copied_file:
  type: File
  outputSource: copy_step/copied_file

steps:
copy_step:
  in:
    in_file: in_file
    out_filename: out_filename
    docker_image: docker_image
  out: [copied_file]
  run: copy.cwl            
      

次のファイルはcopy.cwlタスクを定義します。

cwlVersion: v1.2
class: CommandLineTool
baseCommand: cp

inputs:
in_file:
  type: File
  secondaryFiles: [.fai]
  inputBinding:
    position: 1

out_filename:
  type: string
  inputBinding:
    position: 2
docker_image:
  type: string

outputs:
copied_file:
  type: File
  outputBinding:
      glob: $(inputs.out_filename)

requirements:
InlineJavascriptRequirement: {}
DockerRequirement:
  dockerPull: "$(inputs.docker_image)"      

以下は、GPU 要件を使用して CWL で記述されたワークフローの例です。

cwlVersion: v1.2
class: CommandLineTool
baseCommand: ["/bin/bash", "docm_haplotypeCaller.sh"]
$namespaces:
cwltool: http://commonwl.org/cwltool#
requirements:
cwltool:CUDARequirement:
  cudaDeviceCountMin: 1
  cudaComputeCapability: "nvidia-tesla-t4" 
  cudaVersionMin: "1.0"
InlineJavascriptRequirement: {}
InitialWorkDirRequirement:
  listing:
  - entryname: 'docm_haplotypeCaller.sh'
    entry: |
            nvidia-smi --query-gpu=gpu_name,gpu_bus_id,vbios_version --format=csv   

inputs: []
outputs: []     

ワークフロー定義の例

次の例は、WDL、Nextflow、CWL で同じワークフロー定義を示しています。

WDL ワークフロー定義の例

次の例は、WDL BAMで から CRAM に変換するためのプライベートワークフロー定義を示しています。CRAM から へのBAMワークフローでは、2 つのタスクを定義し、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}"
      }
  }