Escrevendo fluxos de trabalho na WDL Escrevendo fluxos de trabalho no Nextflow Escrevendo fluxos de trabalho no CWL Exemplo de definição de fluxo de trabalho Exemplo de definição de fluxo de trabalho WDL

Escrevendo definições de fluxo de trabalho para fluxos HealthOmics de trabalho

HealthOmics suporta definições de fluxo de trabalho escritas em WDL, Nextflow ou CWL. Para saber mais sobre essas linguagens de fluxo de trabalho, consulte as especificações para WDL, Nextflow ou CWL.

HealthOmics oferece suporte ao gerenciamento de versões para as três linguagens de definição de fluxo de trabalho. Para obter mais informações, consulte Suporte de versão para linguagens HealthOmics de definição de fluxo de trabalho .

Tópicos

Escrevendo fluxos de trabalho na WDL
Escrevendo fluxos de trabalho no Nextflow
Escrevendo fluxos de trabalho no CWL
Exemplo de definição de fluxo de trabalho
Exemplo de definição de fluxo de trabalho WDL

Escrevendo fluxos de trabalho na WDL

As tabelas a seguir mostram como as entradas na WDL são mapeadas para o tipo primitivo correspondente ou tipo JSON complexo. A coerção de tipos é limitada e, sempre que possível, os tipos devem ser explícitos.

Tipos primitivos
Tipo WDL	Tipo JSON	Exemplo de WDL	Exemplo de chave e valor JSON	Observações
`Boolean`	`boolean`	`Boolean b`	`"b": true`	O valor deve estar em minúsculas e sem aspas.
`Int`	`integer`	`Int i`	`"i": 7`	Não deve ser citado.
`Float`	`number`	`Float f`	`"f": 42.2`	Não deve ser citado.
`String`	`string`	`String s`	`"s": "characters"`	As cadeias de caracteres JSON que são um URI devem ser mapeadas para um arquivo WDL para serem importadas.
`File`	`string`	`File f`	`"f": "s3://amzn-s3-demo-bucket1/path/to/file"`	O Amazon S3 e o HealthOmics armazenamento URIs são importados, desde que a função do IAM fornecida para o fluxo de trabalho tenha acesso de leitura a esses objetos. Nenhum outro esquema de URI é suportado (como `file://https://`, e`ftp://`). O URI deve especificar um objeto. Não pode ser um diretório, o que significa que não pode terminar com `/` a.
`Directory`	`string`	`Directory d`	`"d": "s3://bucket/path/"`	O `Directory` tipo não está incluído na WDL 1.0 ou 1.1, então você precisará `version development` adicioná-lo ao cabeçalho do arquivo WDL. O URI deve ser um URI do Amazon S3 e com um prefixo que termine com '/'. Todo o conteúdo do diretório será copiado recursivamente para o fluxo de trabalho como um único download. O `Directory` deve conter somente arquivos relacionados ao fluxo de trabalho.

Os tipos complexos na Biblioteca Digital Mundial são estruturas de dados compostas por tipos primitivos. Estruturas de dados, como listas, serão convertidas em matrizes.

Tipos complexos
Tipo WDL	Tipo JSON	Exemplo de WDL	Exemplo de chave e valor JSON	Observações
`Array`	`array`	`Array[Int] nums`	`“nums": [1, 2, 3]`	Os membros da matriz devem seguir o formato do tipo de matriz WDL.
`Pair`	`object`	`Pair[String, Int] str_to_i`	`“str_to_i": {"left": "0", "right": 1}`	Cada valor do par deve usar o formato JSON do tipo WDL correspondente.
`Map`	`object`	`Map[Int, String] int_to_string`	`"int_to_string": { 2: "hello", 1: "goodbye" }`	Cada entrada no mapa deve usar o formato JSON de seu tipo WDL correspondente.
`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" }`	Os nomes dos membros da estrutura devem corresponder exatamente aos nomes das chaves do objeto JSON. Cada valor deve usar o formato JSON do tipo de WDL correspondente.
`Object`	N/D	N/D	N/D	O `Object` tipo WDL está desatualizado e deve ser substituído por `Struct` em todos os casos.

O mecanismo HealthOmics de fluxo de trabalho não oferece suporte a parâmetros de entrada qualificados ou com espaçamento entre nomes. O tratamento de parâmetros qualificados e seu mapeamento para parâmetros da WDL não são especificados pela linguagem da WDL e podem ser ambíguos. Por esses motivos, a melhor prática é declarar todos os parâmetros de entrada no arquivo de definição do fluxo de trabalho de nível superior (principal) e transmiti-los às chamadas do subfluxo de trabalho usando mecanismos WDL padrão.

Escrevendo fluxos de trabalho no Nextflow

HealthOmics suporta Nextflow e. DSL1 DSL2 Para obter detalhes, consulte Suporte à versão Nextflow.

O Nextflow DSL2 é baseado na linguagem de programação Groovy, portanto, os parâmetros são dinâmicos e a coerção de tipos é possível usando as mesmas regras do Groovy. Os parâmetros e valores fornecidos pelo JSON de entrada estão disponíveis no mapa parameters (params) do fluxo de trabalho.

Tópicos

Usando plug-ins nf-schema e nf-validation
Especificando o armazenamento URIs
Definindo a duração máxima da tarefa usando diretivas de tempo
Exportação do conteúdo da tarefa

Usando plug-ins nf-schema e nf-validation

nota

Resumo do HealthOmics suporte para plug-ins:

v22.04 — sem suporte para plug-ins
v23.10 — suporta e nf-schema nf-validation
v24.10 — suporta nf-schema

HealthOmics fornece o seguinte suporte para plug-ins Nextflow:

Para o Nextflow v23.10, HealthOmics pré-instala o plug-in nf-validation @1 .1.1.
Para o Nextflow v23.10 e versões posteriores, HealthOmics pré-instala o plug-in nf-schema @2 .3.0.
Você não pode recuperar plug-ins adicionais durante a execução de um fluxo de trabalho. HealthOmics ignora todas as outras versões de plug-in que você especificar no nextflow.config arquivo.
Para o Nextflow v24 e superior, nf-schema é a nova versão do plug-in obsoleto. nf-validation Para obter mais informações, consulte nf-schema no repositório Nextflow. GitHub

Especificando o armazenamento URIs

Quando um Amazon S3 ou HealthOmics URI é usado para construir um arquivo Nextflow ou objeto de caminho, ele disponibiliza o objeto correspondente para o fluxo de trabalho, desde que o acesso de leitura seja concedido. O uso de prefixos ou diretórios é permitido para o Amazon S3. URIs Para obter exemplos, consulte Formatos de parâmetros de entrada do Amazon S3.

HealthOmics suporta o uso de padrões globais no Amazon URIs S3 HealthOmics ou no Storage. URIs Use padrões Glob na definição do fluxo de trabalho para a criação de path nossos file canais.

Definindo a duração máxima da tarefa usando diretivas de tempo

HealthOmics fornece uma cota ajustável (consulteHealthOmics cotas de serviço) para especificar a duração máxima de uma execução. Para fluxos de trabalho do Nextflow v23 e v24, você também pode especificar a duração máxima das tarefas usando as diretivas de tempo do Nextflow.

Durante o desenvolvimento de um novo fluxo de trabalho, definir a duração máxima da tarefa ajuda você a capturar tarefas descontroladas e tarefas de longa execução.

Para obter mais informações sobre a diretiva de tempo do Nextflow, consulte a diretiva de tempo na referência do Nextflow.

HealthOmics fornece o seguinte suporte para as diretivas de horário do Nextflow:

HealthOmics suporta granularidade de 1 minuto para a diretiva de tempo. Você pode especificar um valor entre 60 segundos e o valor máximo da duração da execução.
Se você inserir um valor menor que 60, o HealthOmics arredonda para 60 segundos. Para valores acima de 60, HealthOmics arredonda para baixo para o minuto mais próximo.
Se o fluxo de trabalho suportar novas tentativas para uma tarefa, HealthOmics tente novamente a tarefa se o tempo limite atingir o tempo limite.
Se uma tarefa atingir o tempo limite (ou se a última tentativa atingir o tempo limite), a tarefa HealthOmics será cancelada. Essa operação pode ter uma duração de um a dois minutos.
No tempo limite da tarefa, HealthOmics define a execução e o status da tarefa como falha e cancela as outras tarefas na execução (para tarefas com status Inicial, Pendente ou Em execução). HealthOmics exporta as saídas das tarefas concluídas antes do tempo limite para o local de saída designado do S3.
O tempo que uma tarefa passa no status pendente não conta para a duração da tarefa.
Se a execução fizer parte de um grupo de execução e o grupo de execução expirar antes do cronômetro da tarefa, a execução e a tarefa passarão para o status de falha.

Especifique a duração do tempo limite usando uma ou mais das seguintes unidades:ms,,s, mh, oud. Você pode especificar as diretivas de horário no arquivo de configuração do Nextflow e na definição do fluxo de trabalho. A lista a seguir mostra a ordem de precedência, da menor para a maior prioridade:

Configuração global no arquivo de configuração.
Seção de tarefas da definição do fluxo de trabalho.
Seletores específicos de tarefas no arquivo de configuração.

O exemplo a seguir mostra como especificar a configuração global no arquivo de configuração do Nextflow. Ele define um tempo limite global de 1 hora e 30 minutos:


process {
    time = '1h30m'
}

O exemplo a seguir mostra como especificar uma diretiva de horário na seção de tarefas da definição do fluxo de trabalho. Este exemplo define um tempo limite de 3 dias, 5 horas e 4 minutos. Esse valor tem precedência sobre o valor global no arquivo de configuração, mas não tem precedência sobre uma diretiva de tempo específica da tarefa no arquivo de my_label configuração:


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

O exemplo a seguir mostra como especificar diretivas de horário específicas da tarefa no arquivo de configuração do Nextflow, com base nos seletores de nome ou rótulo. Este exemplo define um valor global de tempo limite da tarefa de 30 minutos. Ele define um valor de 2 horas para a tarefa myTask e define um valor de 3 horas para tarefas com rótulomy_label. Para tarefas que correspondem ao seletor, esses valores têm precedência sobre o valor global e o valor na definição do fluxo de trabalho:


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

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

Exportação do conteúdo da tarefa

Para fluxos de trabalho escritos em Nextflow, defina uma diretiva PublishDir para exportar o conteúdo da tarefa para seu bucket de saída do Amazon S3. Conforme mostrado no exemplo a seguir, defina o valor publishDir como/mnt/workflow/pubdir. Para exportar arquivos para o Amazon S3, os arquivos devem estar nesse diretório.


 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
    """
  }

Escrevendo fluxos de trabalho no CWL

Os fluxos de trabalho escritos em Common Workflow Language, ou CWL, oferecem funcionalidade semelhante aos fluxos de trabalho escritos em WDL e Nextflow. Você pode usar o Amazon S3 ou o HealthOmics armazenamento URIs como parâmetros de entrada.

Se você definir a entrada em um SecondaryFile em um subfluxo de trabalho, adicione a mesma definição no fluxo de trabalho principal.

HealthOmics os fluxos de trabalho não oferecem suporte aos processos operacionais. Para saber mais sobre os processos operacionais nos fluxos de trabalho da CWL, consulte a documentação da CWL.

Para converter um arquivo de definição de fluxo de trabalho CWL existente para uso HealthOmics, faça as seguintes alterações:

Substitua todo o contêiner URIs Docker pelo Amazon URIs ECR.
Certifique-se de que todos os arquivos do fluxo de trabalho sejam declarados no fluxo de trabalho principal como entrada e que todas as variáveis estejam definidas explicitamente.
Certifique-se de que todo JavaScript código seja uma reclamação de modo estrito.

Os fluxos de trabalho do CWL devem ser definidos para cada contêiner usado. Não é recomendável codificar a entrada DockerPull com um URI fixo do Amazon ECR.

Veja a seguir um exemplo de um fluxo de trabalho escrito em 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

O arquivo a seguir define a copy.cwl tarefa.



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)"

Veja a seguir um exemplo de um fluxo de trabalho escrito em CWL com um requisito de GPU.


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: []

Exemplo de definição de fluxo de trabalho

O exemplo a seguir mostra a mesma definição de fluxo de trabalho em WDL, Nextflow e CWL.

WDL


version 1.1

task my_task {
   runtime { ... }
   inputs {
       File input_file
       String name
       Int threshold
   }
   
   command <<<
   my_tool --name ~{name} --threshold ~{threshold} ~{input_file}
   >>>
   
   output {
       File results = "results.txt"
   }
}

workflow my_workflow {
   inputs {
       File input_file
       String name
       Int threshold = 50
   }
   
   call my_task {
       input:
          input_file = input_file,
          name = name,
          threshold = threshold
   }
   outputs {
       File results = my_task.results
   }
}

Nextflow


nextflow.enable.dsl = 2

params.input_file = null
params.name = null
params.threshold = 50

process my_task {
   // <directives>
   
   input:
     path input_file
     val name
     val threshold
   
   output:
     path 'results.txt', emit: results
   
   script:
     """
     my_tool --name ${name} --threshold ${threshold} ${input_file}
     """
     
   
}

workflow MY_WORKFLOW {
   my_task(
       params.input_file,
       params.name,
       params.threshold
   )
}

workflow {
   MY_WORKFLOW()
}

CWL


cwlVersion: v1.2
class: Workflow

requirements:
    InlineJavascriptRequirement: {}

inputs:
   input_file: File
   name: string
   threshold: int

outputs:
    result:
        type: ...
        outputSource: ...

steps:
    my_task:
        run:
            class: CommandLineTool
            baseCommand: my_tool
            requirements:
                ...
            inputs:
                name:
                    type: string
                    inputBinding:
                        prefix: "--name"
                threshold:
                    type: int
                    inputBinding:
                        prefix: "--threshold"
                input_file:
                    type: File
                    inputBinding: {}
            outputs:
                results:
                    type: File
                    outputBinding:
                        glob: results.txt

Exemplo de definição de fluxo de trabalho WDL

Os exemplos a seguir mostram definições de fluxo de trabalho privadas para conversão de CRAM para BAM em WDL. O BAM fluxo de trabalho CRAM to define duas tarefas e usa ferramentas do genomes-in-the-cloud contêiner, que são mostradas no exemplo e estão disponíveis publicamente.

O exemplo a seguir mostra como incluir o contêiner Amazon ECR como parâmetro. Isso permite HealthOmics verificar as permissões de acesso ao seu contêiner antes que ele inicie a execução.


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

O exemplo a seguir mostra como especificar quais arquivos usar em sua execução, quando os arquivos estão em um bucket do 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"
  }

Se você quiser especificar arquivos de um armazenamento de sequência, indique isso conforme mostrado no exemplo a seguir, usando o URI para o armazenamento de sequência.


{
      "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"
  }

Em seguida, você pode definir seu fluxo de trabalho na WDL, conforme mostrado a seguir.


 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}"
      }
  }

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Aceleradores de tarefas

Arquivos de modelo de parâmetros