Besonderheiten der WDL-Workflow-Definition

Die folgenden Themen enthalten Einzelheiten zu Typen und Anweisungen, die für WDL-Workflow-Definitionen in verfügbar sind. HealthOmics

Implizite Typkonvertierung in WDL: Nachsichtig

HealthOmics unterstützt die implizite Typkonvertierung in der Datei input.json und der Workflow-Definition. Um die implizite Typumwandlung zu verwenden, geben Sie bei der Erstellung des Workflows für die Workflow-Engine die Option WDL Delient an. WDL Lenient umfasst alle Standard-WDL-Funktionen sowie zusätzliche Kompatibilitätsverhaltensweisen, die für Workflows entwickelt wurden, die von Cromwell migriert wurden. Es unterstützt Kundenrichtlinien von Cromwell und einige nicht konforme Logiken.

WDL Lenient unterstützt die Typkonvertierung für die folgenden Elemente in der Liste der begrenzten Ausnahmen von WDL: https://github.com/openwdl/wdl/blob/wdl-1.1/SPEC.md#-limited-exceptions

Um die implizite Typumwandlung zu verwenden, geben Sie die Workflow-Engine als WDL_LENIENT an, wenn Sie den Workflow oder die Workflow-Version erstellen.

In der Konsole heißt der Workflow-Engine-Parameter Language. In der API heißt der Workflow-Engine-Parameter Engine. Für weitere Informationen siehe Erstellen Sie einen privaten Workflow oder Workflow-Version erstellen.

Namespace-Definition in input.json

HealthOmics unterstützt vollständig qualifizierte Variablen in input.json. Wenn Sie beispielsweise zwei Eingabevariablen mit den Namen number1 und number2 im Workflow deklarieren: SumWorkflow

workflow SumWorkflow {
  input {
    Int number1
    Int number2
  }
}   

Sie können sie als vollständig qualifizierte Variablen in input.json verwenden:

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

Primitive Typen in WDL

Die folgende Tabelle zeigt, wie Eingaben in WDL den entsprechenden primitiven Typen zugeordnet werden. HealthOmics bietet eingeschränkte Unterstützung für Typzwang, daher empfehlen wir, explizite Typen festzulegen.

Komplexe Typen in WDL

Die folgende Tabelle zeigt, wie Eingaben in WDL den entsprechenden komplexen JSON-Typen zugeordnet werden. Komplexe Typen in WDL sind Datenstrukturen, die aus primitiven Typen bestehen. Datenstrukturen wie Listen werden in Arrays konvertiert.

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

Richtlinien in WDL

HealthOmics unterstützt die folgenden Direktiven in allen WDL-Versionen, die dies HealthOmics unterstützen.

Konfigurieren Sie die GPU-Ressourcen

HealthOmics unterstützt Laufzeitattribute acceleratorType und acceleratorCount alle unterstützten GPU-Instanzen. HealthOmics unterstützt auch die Aliase mit dem Namen gpuType undgpuCount, die dieselbe Funktionalität wie ihre Accelerator-Gegenstücke haben. Wenn die WDL-Definition beide Direktiven enthält, werden die Beschleunigerwerte HealthOmics verwendet.

Das folgende Beispiel zeigt, wie diese Direktiven verwendet werden:

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

Konfigurieren Sie die Aufgabenwiederholung für Servicefehler

HealthOmics unterstützt bis zu zwei Wiederholungen für eine Aufgabe, die aufgrund von Dienstfehlern fehlgeschlagen ist (5XX HTTP-Statuscodes). Sie können die maximale Anzahl von Wiederholungen (1 oder 2) konfigurieren und Wiederholungen aufgrund von Servicefehlern deaktivieren. Standardmäßig werden maximal zwei Wiederholungen HealthOmics versucht.

Das folgende Beispiel legt festpreemptible, dass Wiederholungsversuche aufgrund von Servicefehlern deaktiviert werden:

{
  preemptible: 0 
}     

Weitere Hinweise zu Aufgabenwiederholungen in finden Sie HealthOmics unter. Die Aufgabe wird erneut versucht

Konfigurieren Sie die Aufgabenwiederholung, wenn nicht genügend Arbeitsspeicher zur Verfügung steht

HealthOmics unterstützt Wiederholungen für eine Aufgabe, die fehlgeschlagen ist, weil der Speicher knapp wurde (Container-Exit-Code 137, 4XX HTTP-Statuscode). HealthOmics verdoppelt die Speichermenge für jeden Wiederholungsversuch.

In der Standardeinstellung wird bei dieser Art von Fehler HealthOmics kein erneuter Versuch durchgeführt. Verwenden Sie die maxRetries Direktive, um die maximale Anzahl von Wiederholungen anzugeben.

Im folgenden Beispiel wird der maxRetries Wert auf 3 gesetzt, sodass HealthOmics maximal vier Versuche unternommen werden, die Aufgabe abzuschließen (der erste Versuch plus drei Wiederholungen):

runtime {
    maxRetries: 3
}     

Konfigurieren Sie Rückgabecodes

Das ReturnCodes-Attribut bietet einen Mechanismus zum Angeben eines Rückgabecodes oder einer Reihe von Rückgabecodes, der auf eine erfolgreiche Ausführung einer Aufgabe hinweist. Die WDL-Engine berücksichtigt die Rückgabecodes, die Sie im Laufzeitabschnitt der WDL-Definition angeben, und legt den Aufgabenstatus entsprechend fest.

runtime {
    returnCodes: 1
}     

HealthOmics unterstützt auch einen Alias namens continue OnReturnCode, der über dieselben Funktionen wie ReturnCodes verfügt. Wenn Sie beide Attribute angeben, wird der ReturnCodes-Wert HealthOmics verwendet.

Unterstützte WDL-Festplattenformulare

HealthOmics akzeptiert alle WDL disks 1.1-Standardformulare. Der Bereitstellungspfad und der Festplattentypspezifizierer (SSD,HDD) werden ignoriert — nur die numerische Größe wird extrahiert. Wenn mehrere Einträge deklariert sind, werden die Größen zu einer einzigen /tmp Zuordnung summiert.

HealthOmics montiert den gesamten kurzlebigen Speicher auf. /tmp Wenn Ihre Workflow-Definition mehrere disks Einträge deklariert, werden die Größen summiert und die Gesamtmenge wird als einzelnes Volume bereitgestellt. /tmp Weitere Informationen zum disks WDL-Laufzeitattribut finden Sie in der WDL 1.1-Spezifikation. https://github.com/openwdl/wdl/blob/wdl-1.1/SPEC.md#disks

Andere unterstützte Laufzeitattribute

Konfigurieren Sie das Timeout auf Aufgabenebene mit dem Laufzeitattribut OmicsTimeout

HealthOmics bietet ein benutzerdefiniertes omicsTimeout Attribut zum Festlegen einer maximalen Aufgabendauer in Ihrem Workflow. Geben Sie die Timeout-Dauer als Ganzzahl (Sekunden) oder als Zeichenfolge mit einer oder mehreren der folgenden Einheiten an:s, mh, oderd. Beispiel: "40m", "1h30m" oder "1m3s".

Das folgende Beispiel zeigt, wie das omicsTimeout Attribut im runtime Abschnitt einer WDL-Aufgabendefinition angegeben wird. In diesem Beispiel wird ein Timeout von 40 Minuten festgelegt.

    runtime {
        omicsTimeout: "40m"
    }

HealthOmics bietet die folgende Unterstützung für das omicsTimeout WDL-Laufzeitattribut:

Alle Läufe haben eine maximale Dauer, die das einstellbare Kontingent in HealthOmics Servicekontingenten Grenzen hält. Sie können eine Erhöhung dieses Kontingents beantragen.

Aufgaben-Metadaten in WDL

HealthOmics unterstützt die folgenden Metadatenoptionen für WDL-Aufgaben.

Deaktivieren Sie das Caching auf Aufgabenebene mit dem Attribut volatile

Mit dem Attribut volatile können Sie das Caching von Anrufen für bestimmte Aufgaben in Ihrem WDL-Workflow deaktivieren. Wenn eine Aufgabe als flüchtig markiert ist, wird sie immer ausgeführt und verwendet niemals zwischengespeicherte Ergebnisse, auch wenn das Caching für die Ausführung aktiviert ist.

Fügen Sie das Attribut volatile zum Meta-Abschnitt Ihrer Aufgabendefinition hinzu:

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

Beispiel für eine WDL-Workflow-Definition

Die folgenden Beispiele zeigen private Workflow-Definitionen für die Konvertierung von CRAM BAM in WDL. Der CRAM BAM to-Workflow definiert zwei Aufgaben und verwendet Tools aus dem genomes-in-the-cloud Container, der im Beispiel gezeigt wird und öffentlich verfügbar ist.

Das folgende Beispiel zeigt, wie der Amazon ECR-Container als Parameter aufgenommen wird. Auf diese Weise können HealthOmics Sie die Zugriffsberechtigungen für Ihren Container überprüfen, bevor er mit der Ausführung beginnt.

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

Das folgende Beispiel zeigt, wie Sie angeben, welche Dateien in Ihrem Lauf verwendet werden sollen, wenn sich die Dateien in einem Amazon S3-Bucket befinden.

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

Wenn Sie Dateien aus einem Sequenzspeicher angeben möchten, geben Sie dies an, wie im folgenden Beispiel gezeigt, und verwenden Sie dabei den URI für den Sequenzspeicher.

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

Anschließend können Sie Ihren Workflow in WDL definieren, wie im folgenden Beispiel gezeigt.

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