Rédaction de définitions pour les HealthOmics flux de travail

HealthOmics prend en charge les définitions de flux de travail écrites en WDL, Nextflow ou CWL. Pour en savoir plus sur ces langages de flux de travail, consultez les spécifications de WDL, Nextflow ou CWL.

HealthOmics prend en charge la gestion des versions pour les trois langages de définition du flux de travail. Pour de plus amples informations, veuillez consulter Support de version pour les langages HealthOmics de définition des flux de travail .

Écrire des flux de travail dans WDL

Les tableaux suivants montrent comment les entrées dans WDL correspondent au type primitif ou au type JSON complexe correspondant. La coercition de type est limitée et, dans la mesure du possible, les types doivent être explicites.

Les types complexes dans WDL sont des structures de données composées de types primitifs. Les structures de données telles que les listes seront converties en tableaux.

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

Le moteur HealthOmics de flux de travail ne prend pas en charge les paramètres d'entrée qualifiés ou espacés par des noms. La gestion des paramètres qualifiés et leur mappage aux paramètres WDL ne sont pas spécifiés par le langage WDL et peuvent être ambigus. Pour ces raisons, la meilleure pratique consiste à déclarer tous les paramètres d'entrée dans le fichier de définition du flux de travail de niveau supérieur (principal) et à les transmettre aux appels de sous-flux de travail à l'aide des mécanismes WDL standard.

Écrire des flux de travail dans Nextflow

HealthOmics prend en charge DSL1 Nextflow et. DSL2 Pour en savoir plus, consultez Support de la version Nextflow.

Nextflow DSL2 est basé sur le langage de programmation Groovy, les paramètres sont donc dynamiques et la coercition de type est possible en utilisant les mêmes règles que Groovy. Les paramètres et valeurs fournis par le JSON d'entrée sont disponibles dans la carte parameters (params) du flux de travail.

Utilisation des plugins nf-schema et nf-validation

HealthOmics fournit le support suivant pour les plugins Nextflow :

Spécification du stockage URIs

Lorsqu'un Amazon S3 ou un HealthOmics URI est utilisé pour créer un fichier ou un objet de chemin Nextflow, l'objet correspondant est mis à la disposition du flux de travail, à condition que l'accès en lecture soit accordé. L'utilisation de préfixes ou de répertoires est autorisée pour Amazon S3 URIs. Pour obtenir des exemples, consultez Formats de paramètres d'entrée Amazon S3.

HealthOmics prend en charge l'utilisation de modèles globaux dans Amazon S3 URIs ou HealthOmics Storage URIs. Utilisez des modèles Glob dans la définition du flux de travail pour la création de path file canaux.

Définition de la durée maximale des tâches à l'aide de directives temporelles

HealthOmics fournit un quota ajustable (voirHealthOmics quotas de service) pour spécifier la durée maximale d'une course. Pour les flux de travail Nextflow v23 et v24, vous pouvez également spécifier la durée maximale des tâches à l'aide des directives temporelles Nextflow.

Lors du développement d'un nouveau flux de travail, la définition de la durée maximale des tâches vous permet de détecter les tâches intempestives et les tâches de longue durée.

Pour plus d'informations sur la directive temporelle Nextflow, voir directive time dans la référence Nextflow.

HealthOmics fournit le support suivant pour les directives temporelles de Nextflow :

Spécifiez la durée du délai d'expiration en utilisant une ou plusieurs des unités suivantes :ms,s, mh, oud. Vous pouvez spécifier des directives temporelles dans le fichier de configuration Nextflow et dans la définition du flux de travail. La liste suivante indique l'ordre de priorité, de la priorité la plus faible à la plus élevée :

L'exemple suivant montre comment spécifier une configuration globale dans le fichier de configuration Nextflow. Il définit un délai d'expiration global de 1 heure et 30 minutes :

process {
    time = '1h30m'
}     

L'exemple suivant montre comment spécifier une directive temporelle dans la section des tâches de la définition du flux de travail. Cet exemple définit un délai d'expiration de 3 jours, 5 heures et 4 minutes. Cette valeur est prioritaire sur la valeur globale du fichier de configuration, mais pas sur une directive temporelle spécifique à une tâche car my_label dans le fichier de configuration :

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

L'exemple suivant montre comment spécifier des directives temporelles spécifiques à une tâche dans le fichier de configuration Nextflow, en fonction du nom ou des sélecteurs d'étiquette. Cet exemple définit un délai d'expiration global de la tâche de 30 minutes. Il définit une valeur de 2 heures pour la tâche myTask et une valeur de 3 heures pour les tâches avec étiquettemy_label. Pour les tâches correspondant au sélecteur, ces valeurs ont priorité sur la valeur globale et sur la valeur de la définition du flux de travail :

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

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

Exporter le contenu des tâches

Pour les flux de travail écrits dans Nextflow, définissez une directive PublishDir pour exporter le contenu des tâches vers votre compartiment Amazon S3 de sortie. Comme indiqué dans l'exemple suivant, définissez la valeur PublishDir sur. /mnt/workflow/pubdir Pour exporter des fichiers vers Amazon S3, les fichiers doivent se trouver dans ce répertoire.

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

Écrire des flux de travail dans CWL

Les flux de travail écrits en langage de flux de travail commun, ou CWL, offrent des fonctionnalités similaires à celles des flux de travail écrits en WDL et Nextflow. Vous pouvez utiliser Amazon S3 ou le HealthOmics stockage URIs comme paramètres d'entrée.

Si vous définissez une entrée dans un fichier secondaire dans un sous-flux de travail, ajoutez la même définition dans le flux de travail principal.

HealthOmics les flux de travail ne prennent pas en charge les processus opérationnels. Pour en savoir plus sur les processus opérationnels dans les flux de travail CWL, consultez la documentation CWL.

Pour convertir un fichier de définition de flux de travail CWL existant à utiliser HealthOmics, apportez les modifications suivantes :

Les flux de travail CWL doivent être définis pour chaque conteneur utilisé. Il n'est pas recommandé de coder en dur l'entrée DockerPull avec un URI Amazon ECR fixe.

Voici un exemple de flux de travail écrit en 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            
      

Le fichier suivant définit la copy.cwl tâche.

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

Voici un exemple de flux de travail écrit en CWL avec une exigence 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: []     

Exemple de définition de flux de travail

L'exemple suivant montre la même définition de flux de travail dans WDL, Nextflow et CWL.

Exemple de définition de flux de travail WDL

Les exemples suivants présentent des définitions de flux de travail privés pour la conversion de CRAM vers BAM dans WDL. Le BAM flux CRAM de travail to définit deux tâches et utilise les outils du genomes-in-the-cloud conteneur, qui est illustré dans l'exemple et est accessible au public.

L'exemple suivant montre comment inclure le conteneur Amazon ECR en tant que paramètre. Cela permet HealthOmics de vérifier les autorisations d'accès à votre conteneur avant qu'il ne commence l'exécution.

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

L'exemple suivant montre comment spécifier les fichiers à utiliser lors de votre exécution, lorsque les fichiers se trouvent dans un compartiment 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"
  }       

Si vous souhaitez spécifier des fichiers à partir d'un magasin de séquences, indiquez-le comme indiqué dans l'exemple suivant, en utilisant l'URI du magasin de séquences.

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

Vous pouvez ensuite définir votre flux de travail dans WDL comme indiqué ci-dessous.

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