

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Specifiche di definizione del flusso di lavoro WDL

I seguenti argomenti forniscono dettagli sui tipi e sulle direttive disponibili per le definizioni dei flussi di lavoro WDL in. HealthOmics

**Topics**
+ [Conversione implicita dei tipi in WDL lenient](#workflow-wdl-type-conversion)
+ [Definizione dello spazio dei nomi in input.json](#workflow-wdl-namespace-defn)
+ [Tipi primitivi in WDL](#workflow-wdl-primitive-types)
+ [Tipi complessi in WDL](#workflow-wdl-complex-types)
+ [Direttive in WDL](#workflow-wdl-directives)
+ [Altri attributi di runtime supportati](#workflow-wdl-other-runtime-attributes)
+ [Metadati delle attività in WDL](#workflow-wdl-task-metadata)
+ [Esempio di definizione del flusso di lavoro WDL](#wdl-example)

## Conversione implicita dei tipi in WDL lenient
<a name="workflow-wdl-type-conversion"></a>

HealthOmics supporta la conversione implicita dei tipi nel file input.json e nella definizione del flusso di lavoro. Per utilizzare la conversione implicita dei tipi, specificate il motore del flusso di lavoro come WDL lenient al momento della creazione del flusso di lavoro. WDL lenient include tutte le funzionalità WDL standard oltre a comportamenti di compatibilità aggiuntivi progettati per i flussi di lavoro migrati da Cromwell. Supporta le direttive Cromwell dei clienti e alcune logiche non conformi.

WDL lenient supporta la conversione dei tipi per i seguenti elementi nell'elenco delle eccezioni limitate di WDL: [https://github.com/openwdl/wdl/blob/wdl-1.1/SPEC.md#-limited-exceptions](https://github.com/openwdl/wdl/blob/wdl-1.1/SPEC.md#-limited-exceptions)
+ Float to Int, dove la coercizione non comporta alcuna perdita di precisione (ad esempio 1.0 mappato a 1).
+ String to Int/Float, dove la coercizione non comporta alcuna perdita di precisione.
+ Associa [W, X] a Array [Pair [Y, Z]], nel caso in cui W sia coercibile a Y e X sia coercibile a Z.
+ Array [Pair [W, X]] to Map [Y, Z], nel caso in cui W sia coercibile con Y e X sia coercibile con Z (ad esempio 1.0 mappato a 1).

Per utilizzare la trasmissione implicita dei tipi, specificate il motore del flusso di lavoro come WDL\_LENIENT quando create il flusso di lavoro o la versione del flusso di lavoro.

Nella console, il parametro del motore di workflow è denominato Language. ** ** Nell'API, il parametro del motore di flusso di lavoro è denominato ** engine**. Per ulteriori informazioni, consulta [Crea un flusso di lavoro privato](create-private-workflow.md) o [Crea una versione del flusso di lavoro](workflows-version-create.md).

## Definizione dello spazio dei nomi in input.json
<a name="workflow-wdl-namespace-defn"></a>

HealthOmics supporta variabili completamente qualificate in input.json. Ad esempio, se dichiari due variabili di input denominate numero1 e numero2 nel flusso di lavoro: ** SumWorkflow **

```
workflow SumWorkflow {
  input {
    Int number1
    Int number2
  }
}
```

 Puoi usarle come variabili complete in input.json: 

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

## Tipi primitivi in WDL
<a name="workflow-wdl-primitive-types"></a>

La tabella seguente mostra come gli input in WDL corrispondono ai tipi primitivi corrispondenti. HealthOmics fornisce un supporto limitato per la coercizione dei tipi, pertanto consigliamo di impostare tipi espliciti. 


**Tipi primitivi**  

| Tipo WDL | Tipo JSON | Esempio WDL | Esempio di chiave e valore JSON | Note | 
| --- | --- | --- | --- | --- | 
| Boolean | boolean | Boolean b | "b": true | Il valore deve essere minuscolo e senza virgolette. | 
| Int | integer | Int i | "i": 7 | Non deve essere citato. | 
| Float | number | Float f | "f": 42.2 | Non deve essere quotato. | 
| String | string | String s | "s": "characters" | Le stringhe JSON che sono un URI devono essere mappate su un file WDL per essere importate. | 
| File | string | File f | "f": "s3://amzn-s3-demo-bucket1/path/to/file" | Amazon S3 e gli URI HealthOmics di storage vengono importati a condizione che il ruolo IAM fornito per il flusso di lavoro abbia accesso in lettura a questi oggetti. Non sono supportati altri schemi URI (ad esempiofile://,https://, eftp://). L'URI deve specificare un oggetto. Non può essere una directory, il che significa che non può terminare con un/. | 
| Directory | string | Directory d | "d": "s3://bucket/path/" | Il Directory tipo non è incluso in WDL 1.0 o 1.1, quindi dovrai aggiungerlo version development all'intestazione del file WDL. L'URI deve essere un URI Amazon S3 e con un prefisso che termina con «/». Tutti i contenuti della directory verranno copiati ricorsivamente nel flusso di lavoro come singolo download. DirectoryDovrebbe contenere solo file relativi al flusso di lavoro. | 

## Tipi complessi in WDL
<a name="workflow-wdl-complex-types"></a>

La tabella seguente mostra come gli input in WDL corrispondono ai tipi JSON complessi corrispondenti. I tipi complessi in WDL sono strutture di dati composte da tipi primitivi. Le strutture di dati come gli elenchi verranno convertite in matrici.


**Tipi complessi**  

| Tipo WDL | Tipo JSON | Esempio WDL | Esempio di chiave e valore JSON | Note | 
| --- | --- | --- | --- | --- | 
| Array | array | Array[Int] nums | “nums": [1, 2, 3] | I membri dell'array devono seguire il formato del tipo di array WDL. | 
| Pair | object | Pair[String, Int] str\_to\_i | “str\_to\_i": {"left": "0", "right": 1} | Ogni valore della coppia deve utilizzare il formato JSON del tipo WDL corrispondente. I nomi delle chiavi di stringa nelle rappresentazioni JSON di WDL Pair vengono confrontati senza distinzione tra maiuscole e minuscole. Ad esempio, {"left»: «0", «right»: 1} e {"LEFT»: «0", «Right»: 1} vengono considerati equivalenti quando vengono deserializzati in un tipo Pair. | 
| Map | object | Map[Int, String] int\_to\_string | "int\_to\_string": { 2: "hello", 1: "goodbye" } | Ogni voce nella mappa deve utilizzare il formato JSON del tipo WDL corrispondente. | 
| Struct | object | <pre>struct SampleBamAndIndex { <br />  String sample_name <br />  File bam <br />  File bam_index <br />} SampleBamAndIndex b_and_i</pre>  |  <pre>"b_and_i": { <br />   "sample_name": "NA12878", <br />   "bam": "s3://amzn-s3-demo-bucket1/NA12878.bam", <br />   "bam_index": "s3://amzn-s3-demo-bucket1/NA12878.bam.bai" <br />}           </pre>  | I nomi dei membri della struttura devono corrispondere esattamente ai nomi delle chiavi dell'oggetto JSON. Ogni valore deve utilizzare il formato JSON del tipo WDL corrispondente. | 
| Object | N/A | N/A | N/A | Il Object tipo WDL è obsoleto e deve essere sostituito da Struct in tutti i casi. | 

## Direttive in WDL
<a name="workflow-wdl-directives"></a>

HealthOmics supporta le seguenti direttive in tutte le versioni WDL supportate. HealthOmics 

### Configura le risorse GPU
<a name="workflow-wdl-directive-gpu"></a>

HealthOmics supporta gli attributi di runtime **acceleratorType** e **acceleratorCount** con tutte le istanze [ GPU supportate. ](https://docs.aws.amazon.com/omics/latest/dev/task-accelerators.html) HealthOmics supporta anche alias denominati **gpuType** e**gpuCount**, che hanno le stesse funzionalità delle loro controparti acceleratrici. Se la definizione WDL contiene entrambe le direttive, HealthOmics utilizza i valori dell'acceleratore.

L'esempio seguente mostra come utilizzare queste direttive:

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

### Configura il fallback delle risorse con **fumetti ResourceFallbackOrder**
<a name="workflow-wdl-directive-fallback"></a>

HealthOmics supporta la direttiva **omicsResourceFallbackOrder** runtime per definire un elenco ordinato di profili di risorse di acceleratori (o GPU) e CPU per un'attività. Quando il tipo di acceleratore richiesto non è disponibile, passa HealthOmics automaticamente al profilo successivo nell'elenco. È possibile includere un CPU-only profilo come opzione finale.

L'esempio seguente prova `nvidia-l40s` prima`nvidia-l4`, poi torna alla CPU se nessuno degli acceleratori è disponibile:

```json
runtime {
    docker: "my-registry/align-multi-arch:latest"
    omicsResourceFallbackOrder: [
        {"acceleratorType": "nvidia-l40s", "acceleratorCount": 1, "cpu": 8, "memory": "32 GiB", "omicsResourceWaitTimeoutInMin": 45},
        {"acceleratorType": "nvidia-l4",   "acceleratorCount": 1, "cpu": 8, "memory": "32 GiB"},
        {"cpu": 32, "memory": "128 GiB"}
    ]
}
```

HealthOmics imposta automaticamente la variabile di **AWS\_HEALTHOMICS\_RESOURCE\_TYPE** ambiente nel contenitore. Il suo valore è il tipo di acceleratore del profilo attivo (ad esempio,`nvidia-l40s`) o `cpu` per un CPU-only profilo. Usalo per ramificare il comando quando i percorsi di codice della GPU e della CPU sono diversi.

Se tutti i profili dell'elenco sono esauriti, l'operazione ha esito negativo e il motivo dell'errore è fallito. `ALL_PROFILES_INSTANCE_RESERVATION_FAILED` I tentativi di OOM e service-error vengono eseguiti all'interno del profilo corrente e non passano a quello successivo.

Per ulteriori informazioni, vedere [Configurazione avanzata delle risorse](advanced-resource-configuration.md) e per i tipi di acceleratori supportati vedere. [Acceleratori di attività in un HealthOmics definizione del flusso di lavoro](task-accelerators.md)

### Configura il nuovo tentativo dell'operazione per gli errori di servizio
<a name="workflow-wdl-task-retry"></a>

HealthOmics supporta fino a due tentativi per un'operazione non riuscita a causa di errori di servizio (codici di stato HTTP 5XX). È possibile configurare il numero massimo di tentativi (1 o 2) e disattivare i tentativi per errori di servizio. Per impostazione predefinita, HealthOmics tenta un massimo di due tentativi. 

L'esempio seguente imposta `preemptible` la disattivazione dei tentativi per errori di servizio:

```
{
  preemptible: 0 
}
```

Per ulteriori informazioni sui tentativi di riavvio delle attività HealthOmics, vedere. [Ritentativi di attività](monitoring-runs.md#run-status-task-retries)

### Configurare il ritentativo dell'operazione in caso di memoria esaurita
<a name="workflow-wdl-retries"></a>

HealthOmics supporta i tentativi per un'operazione non riuscita perché esaurita la memoria (codice di uscita del contenitore 137, codice di stato HTTP 4XX). HealthOmics raddoppia la quantità di memoria per ogni tentativo di nuovo tentativo.

Per impostazione predefinita, HealthOmics non riprova per questo tipo di errore. Utilizzate la `maxRetries` direttiva per specificare il numero massimo di tentativi.

L'esempio seguente viene impostato `maxRetries` su 3, in modo da HealthOmics tentare un massimo di quattro tentativi per completare l'attività (il tentativo iniziale più tre tentativi):

```json
runtime {
    maxRetries: 3
}
```

**Nota**  
Il ritentativo dell'operazione per esaurimento della memoria richiede GNU findutils 4.2.3\+. Il contenitore di immagini predefinito include questo pacchetto. HealthOmics Se specificate un'immagine personalizzata nella definizione WDL, assicuratevi che l'immagine includa GNU findutils 4.2.3\+.

### Configurate i codici di restituzione
<a name="workflow-wdl-directive-returnCodes"></a>

L'**attributo ** ReturnCodes fornisce un meccanismo per specificare un codice di ritorno, o un set di codici di ritorno, che indica la corretta esecuzione di un'attività. Il motore WDL rispetta i codici di ritorno specificati nella ** sezione ** runtime della definizione WDL e imposta lo stato delle attività di conseguenza. 

```json
runtime {
    returnCodes: 1
}
```

HealthOmics supporta anche un alias denominato ** continue OnReturnCode**, che ha le stesse funzionalità di ReturnCodes. ** ** Se si specificano entrambi gli attributi, viene HealthOmics utilizzato il valore ReturnCodes**. **

### Dischi WDL supportati, moduli ``
<a name="workflow-wdl-disks-forms"></a>

HealthOmics accetta tutti i moduli WDL 1.1 standard. `disks` Il percorso di montaggio e l'identificatore del tipo di disco (`SSD`,`HDD`) vengono ignorati: viene estratta solo la dimensione numerica. Se vengono dichiarate più voci, le dimensioni vengono sommate in un'unica allocazione. `/tmp`


| Modulo accettato | Esempio | Dimensione risolta | 
| --- | --- | --- | 
| Numero intero | disks: 700 | 700 GiB | 
| Stringa | disks: "700" | 700 GiB | 
| Stringa con unità | disks: "700 GiB" o "700 GB" | 700 GiB | 
| Cromwell-style con percorso e tipo | disks: "local-disk 700 SSD" | 700 GiB (percorso e tipo ignorati) | 
| Comma-separated voci | disks: "local-disk 300 SSD, /scratch 200 SSD" | 500 GiB (sommati) | 
| Gamma di stringhe | disks: ["/tmp 300 GiB", "/scratch 200 GiB"] | 500 GiB (sommati) | 

HealthOmics monta tutti gli archivi effimeri su. `/tmp` Se la definizione del flusso di lavoro dichiara più `disks` voci, le dimensioni vengono sommate e il totale viene fornito come un unico volume. `/tmp` Per ulteriori informazioni sull'attributo `disks` runtime WDL, consultate la specifica WDL 1.1. [https://github.com/openwdl/wdl/blob/wdl-1.1/SPEC.md#disks](https://github.com/openwdl/wdl/blob/wdl-1.1/SPEC.md#disks)

## Altri attributi di runtime supportati
<a name="workflow-wdl-other-runtime-attributes"></a>

### Configurare il timeout a livello di attività con l'attributo di runtime OMICsTimeout ``
<a name="workflow-wdl-omics-timeout"></a>

HealthOmics fornisce un `omicsTimeout` attributo personalizzato per impostare una durata massima dell'attività nel flusso di lavoro. Specifica la durata del timeout come numero intero (secondi) o stringa utilizzando una o più delle seguenti unità:`s`, `m``h`, o. `d` Ad esempio, `"40m"`, `"1h30m"` o `"1m3s"`.

L'esempio seguente mostra come specificare l'`omicsTimeout`attributo nella `runtime` sezione di una definizione di attività WDL. Questo esempio imposta un timeout di 40 minuti.

```json
    runtime {
        omicsTimeout: "40m"
    }
```

HealthOmics fornisce il seguente supporto per l'attributo `omicsTimeout` runtime WDL:

1. HealthOmics supporta una granularità di 1 minuto per il valore di timeout. È possibile specificare un valore compreso tra 60 secondi e il valore massimo della durata dell'esecuzione.

1. Se si immette un valore inferiore a 60, lo HealthOmics arrotonda a 60 secondi. Per valori superiori a 60, HealthOmics arrotonda per difetto al minuto più vicino.

1. Se un'attività scade, la HealthOmics annulla. Questa operazione può avere una durata da uno a due minuti.

1. Al termine del timeout dell'attività, HealthOmics imposta l'esecuzione e lo stato dell'attività su Non riuscita e annulla le altre attività in esecuzione (per le attività in stato Avvio, In sospeso o In esecuzione). HealthOmics esporta gli output delle attività completate prima del timeout nella posizione di output S3 designata.

1. Il tempo trascorso da un'attività in stato di sospeso non viene conteggiato ai fini della durata dell'attività.

1. Se l'esecuzione fa parte di un gruppo di esecuzione e il gruppo di esecuzione scade prima del timer dell'attività, l'esecuzione e l'attività passano allo stato di errore.

Tutte le esecuzioni hanno una durata massima rispetto alla quota regolabile nei [HealthOmics quote di servizio](service-quotas.md) controlli. Puoi richiedere un aumento di questa quota.

## Metadati delle attività in WDL
<a name="workflow-wdl-task-metadata"></a>

HealthOmics supporta le seguenti opzioni di metadati per le attività WDL.

### Disabilita la memorizzazione nella cache a livello di task con l'attributo volatile
<a name="workflow-wdl-volatile-attribute"></a>

L'**attributo ** volatile consente di disattivare la memorizzazione nella cache delle chiamate per attività specifiche nel flusso di lavoro WDL. Quando un'operazione è contrassegnata come volatile, verrà sempre eseguita e non utilizzerà mai i risultati memorizzati nella cache, anche quando la memorizzazione nella cache è abilitata per l'esecuzione.

Aggiungi l'**attributo ** volatile alla ** ** metasezione della definizione dell'attività:

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

## Esempio di definizione del flusso di lavoro WDL
<a name="wdl-example"></a>

Gli esempi seguenti mostrano le definizioni dei flussi di lavoro privati per la conversione da `CRAM` a `BAM` in WDL. Il `BAM` flusso di lavoro `CRAM` to definisce due attività e utilizza gli strumenti del `genomes-in-the-cloud` contenitore, illustrato nell'esempio e disponibile al pubblico. 

L'esempio seguente mostra come includere il contenitore Amazon ECR come parametro. Ciò consente di HealthOmics verificare le autorizzazioni di accesso al contenitore prima che inizi l'esecuzione.

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

L'esempio seguente mostra come specificare quali file utilizzare nell'esecuzione, quando i file si trovano in un bucket Amazon S3.

```json
{
    "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 desideri specificare i file da un archivio di sequenze, indicalo come mostrato nell'esempio seguente, utilizzando l'URI per l'archivio di sequenze.

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

È quindi possibile definire il flusso di lavoro in WDL come mostrato nell'esempio seguente. 

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