Workflow Description Language Docs

https://docs.openwdl.org/
Admin
The Workflow Description Language (WDL) is an open standard for describing data processing workflows...
Tokens:31,088
Snippets:313
Trust Score:8.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### WDL Task and Workflow Example

Source: https://docs.openwdl.org/getting-started/quickstart.html

Defines a WDL task 'say_hello' and a workflow 'main' that uses scatter-gather and conditional logic. This example demonstrates basic WDL syntax for tasks, workflows, inputs, outputs, and control flow.

```wdl
version 1.3

task say_hello {
    input {
        String greeting
        String name
    }

    command <<< 
        echo "~{greeting}, ~{name}!"
    >>>

    output {
        String message = read_string(stdout())
    }

    requirements {
        container: "ubuntu:latest"
    }
}

workflow main {
    input {
        String name
        Boolean is_pirate = false
    }

    Array[String] greetings = select_all([
        "Hello",
        "Hallo",
        "Hej",
        (
            if is_pirate
            then "Ahoy"
            else None
        ),
    ])

    scatter (greeting in greetings) {
        call say_hello {
            greeting,
            name,
        }
    }

    output {
        Array[String] messages = say_hello.message
    }
}

```

--------------------------------

### WDL Example: Splitting and Merging VCF Files

Source: https://docs.openwdl.org/design-patterns/multiple-io/index.html

This example demonstrates a WDL workflow that splits a VCF file into two separate files (SNPs and indels) using Picard, and then merges them back together. It highlights tasks with multiple outputs and inputs.

```wdl
version 1.3

# (1) We write a task to split the VCF into multiple VCFs.
task split_vcf {
  input {
    # (a) The task takes in a single input VCF.
    File vcf
  }

  command <<<
    java -jar picard.jar SplitVcfs \
      I="~{vcf}" \
      SNP_OUTPUT="snp.vcf" \
      INDEL_OUTPUT="indel.vcf" \
      STRICT=false
  >>>

  output {
    # (b) The task produces two output VCFs.
    File snp_vcf = "snp.vcf"
    File indel_vcf = "indel.vcf"
  }
}

# (2) We write a task to merge these two VCFs.
task merge_vcfs {
  input {
    # (a) Two input VCFs are accepted.
    File snp_vcf
    File indel_vcf
  }

  command <<<
    java -jar picard.jar MergeVcfs \
      I="~{snp_vcf}" \
      I="~{indel_vcf}" \
      O="combined.vcf"
  >>>

  output {
    # (b) One output VCF is produced.
    File combined = "combined.vcf"
  }
}

# (3) We write a workflow that connects the multiple outputs
# from the `split_vcf` task into the multiple inputs from the
# `merge_vcfs` task.
workflow run {
  input {
    File vcf
  }

  call split_vcf { input: vcf }

  # (a) The outputs are connected to the inputs here.
  call merge_vcfs { input:
    snp_vcf = split_vcf.snp_vcf,
    indel_vcf = split_vcf.indel_vcf,
  }

  output {
    File combined = merge_vcfs.combined
  }
}
```

--------------------------------

### Basic Linear Chaining Example

Source: https://docs.openwdl.org/design-patterns/linear-chaining

Demonstrates a simple linear chain of three tasks: stepA, stepB, and stepC. The output of each task is passed as input to the subsequent task.

```wdl
workflow run {
  # Run the first task.
  call stepA {}

  # Run `stepB`, connecting the `in` input to `stepA`'s `out` output.
  call stepB { input: in = stepA.out }

  # Run `stepC`, connecting the `in` input to `stepB`'s `out` output.
  call stepC { input: in = stepB.out }
}
```

--------------------------------

### Scatter-Gather Workflow Example

Source: https://docs.openwdl.org/design-patterns/scatter-gather/index.html

This WDL code demonstrates the scatter-gather pattern. It scatters a task 'stepA' across multiple input files and then gathers the results in 'stepB'.

```wdl
workflow run {
  inputs {
    Array[File] files
  }

  # Perform `stepA` for each of the inputs in parallel (scatter).
  scatter(file in files) {
    call stepA { input: in = file }
  }

  # Collect the results from the scatter (gather).
  #
  # Note that the outputs from `stepA` are automatically coerced
  # into an `Array` that you can pass in elsewhere.
  call stepB { input: files = stepA.out }
}
```

--------------------------------

### WDL Task Aliasing Example

Source: https://docs.openwdl.org/design-patterns/task-aliasing/index.html

Demonstrates how to use task aliasing to call the same task multiple times. Use 'as' keyword to provide an alias for a task call.

```wdl
# ... task definitions ...

workflow run {
    # `taskA` is run twice—this is enabled using task aliasing.
    call stepA as first {}
    call stepA as second {}

    # `taskB` takes in the output from the `first` task.
    call stepB { input: in = first.out }

    # `taskC` takes in the output from the `second` task.
    call stepC { input: in = second.out }
}
```

--------------------------------

### WDL Workflow Inputs

Source: https://docs.openwdl.org/getting-started/quickstart.html

Example JSON input for the WDL workflow. This specifies the 'name' parameter and optionally 'is_pirate'.

```json
{
  "main.name": "world",
  // "main.is_pirate": true,
}

```

--------------------------------

### Define a Simple WDL Task

Source: https://docs.openwdl.org/language-guide/tasks.html

A representative example of a simple WDL task including input, command, output, and requirements.

```wdl
task say_hello {
  input {
    String greeting
    String name
  }

  command <<<
    echo "~{greeting}, ~{name}!"
  >>>

  output {
    String message = read_string(stdout())
  }

  requirements {
    container: "ubuntu:latest"
  }
}
```

--------------------------------

### Example workflow using custom structs

Source: https://docs.openwdl.org/language-guide/structs.html

Demonstrates how to instantiate and use the custom 'ContactInformation' and 'Address' structs within a WDL workflow. It also shows how to check for the defined status of an optional field.

```wdl
workflow run {
  output {
    ContactInformation john = ContactInformation {
      first_name: "John",
      last_name: "Smith",
      address: Address {
        street_number: 123,
        street_address: "Main Street",
        zip_code: [0, 1, 2, 3, 4 ],
        city: "Somewhere",
        state: "Foobar",
        gate_code: None,
      },
    }

    Boolean has_email = defined(john.email_address)
  }
}
```

--------------------------------

### WDL Workflow Outputs

Source: https://docs.openwdl.org/getting-started/quickstart.html

Example JSON output from the WDL workflow. This shows the 'messages' array, which will include conditional greetings if 'is_pirate' is true.

```json
{
  "messages": [
    "Hello, world!",
    "Hallo, world!",
    "Hej, world!",
    // "Ahoy, world!" is included if `is_pirate` is set to `true` above.
  ]
}

```

--------------------------------

### Create Sequential Integers with range

Source: https://docs.openwdl.org/reference/stdlib/array.html

Use the `range` function to create an array of sequential integers starting from 0 up to a specified length. The length must be non-negative.

```wdl
Array[Int] indexes = range(5)
# `indexes` now contains `[0, 1, 2, 3, 4]`.
```

--------------------------------

### Full Example: Calculating Circle Area via Linear Chaining

Source: https://docs.openwdl.org/design-patterns/linear-chaining

A complete WDL workflow that calculates Pi using Python, then uses that Pi value to compute the area of a circle. This showcases task definition, input/output handling, and linear chaining.

```wdl
version 1.3

# (1) We write a task to calculate π.
task calculate_pi {
  command <<< 
    python3 -c "import math; print(math.pi)"
  >>>

  output {
    # (a) π is output as an _output_ of this task here.
    # It's read from standard input and parsed as a `Float`.
    Float pi = read_float(stdout())
  }
}

# (2) We write a task that takes in the output from the
# previous task and uses it to compute the area of a circle.
task calculate_circle_area {
  input {
    # (a) π is taken as an input here.
    Float pi
    Float radius = 5.0
  }

  command <<< 
    bc -l <<< "~{pi} * ~{radius} ^ 2"
  >>>

  output {
    Float area = read_float(stdout())
  }
}

# (3) We write a workflow that linearly chains the two tasks
# by connecting the output of the first task to the input of
# the second task.
workflow hello {
  # (a) π is calculated in this step.
  call calculate_pi

  # (b) the output from the `calculate_pi` step is passed to
  # the input of the `calculate_circle_area` input here.
  call calculate_circle_area { input: pi = calculate_pi.pi }

  output {
    Float area = calculate_circle_area.area
  }
}

# Now, π will first be calculated by calling `calculate_pi`
# and, once that has completed, `calculate_circle_area` will
# be called using the calculated constant.
```

--------------------------------

### Get Command Stdout as File

Source: https://docs.openwdl.org/reference/stdlib/file.html

Use stdout() to capture the standard output of a command as a File. The engine manages the file's name and location in a temporary directory.

```wdl
File stdout()
```

--------------------------------

### Get Size of File or Directory

Source: https://docs.openwdl.org/reference/stdlib/file.html

Use `size` to determine the size of a file, directory, or a compound value containing files. An optional unit can be specified; defaults to bytes.

```wdl
Float size(File|File?, [String])
```

```wdl
Float size(Directory|Directory?, [String])
```

```wdl
Float size(X|X?, [String])
```

```wdl
Float size = size("foo.txt")
# `size` contains the size of `foo.txt`.
```

--------------------------------

### Get Basename of a File Path

Source: https://docs.openwdl.org/reference/stdlib/file.html

Returns the filename component of a path. Optionally removes a specified suffix if present.

```wdl
String bn = basename("/path/to/file.txt")
# `bn` contains `"file.txt"`.

String bn = basename("/path/to/file.txt", ".txt")
# `bn` contains `"file"`.
```

--------------------------------

### Get Command Stderr as File

Source: https://docs.openwdl.org/reference/stdlib/file.html

Use stderr() to capture the standard error of a command as a File. Similar to stdout(), the engine handles file naming and temporary storage.

```wdl
File stderr()
```

--------------------------------

### Extract Map Values with `values`

Source: https://docs.openwdl.org/reference/stdlib/map.html

Use the `values` function to get an array of all values from a Map. The order of values in the output array corresponds to the order of elements in the input Map.

```wdl
Map[String, Int] x = {"a": 1, "b": 2, "c": 3}

Array[Int] result = values(x)
# `result` now contains [1, 2, 3].
```

--------------------------------

### Select First Non-None Value from Array - WDL

Source: https://docs.openwdl.org/reference/stdlib/array.html

Use select_first to get the first non-None value from an array of optionals. Provide a default value to handle empty arrays or arrays with only None values.

```wdl
Int? maybe_five = 5
Int? maybe_none = None
Int? maybe_three = 3

Int result1 = select_first([maybe_five, maybe_none, maybe_three])
# `result1` now contains `5`.

Int result2 = select_first([maybe_none, maybe_five, maybe_three])
# `result2` now contains `5`.

Int result3 = select_first([], 42)
# `result3` now contains `42`.
```

--------------------------------

### Workflow with Multiple I/O Connections

Source: https://docs.openwdl.org/design-patterns/multiple-io/index.html

Illustrates connecting multiple outputs from one task to multiple inputs of another. Names and types are used to ensure correct connections.

```wdl
workflow run {
  # Run `stepA`.
  call stepA {}

  # Run `stepB`, connecting the `in` input to `stepA`'s `out` output.
  call stepB { input: in = stepA.out }

  # Run `stepC`, connecting the `in1` and `in2` inputs to `stepB`'s
  # `out1` and `out2` outputs, respectively.
  call stepC { input:
    in1 = stepB.out1,
    in2 = stepB.out2
  }
}
```

--------------------------------

### Basic Branch and Merge Workflow

Source: https://docs.openwdl.org/design-patterns/branch-and-merge/index.html

Demonstrates a simple workflow with branching and merging. Tasks stepB and stepC run in parallel after stepA, and their outputs are merged in stepD.

```wdl
workflow run {
  # Run the first task.
  call stepA {}

  # Run `stepB`, connecting the `in` input to `stepA`'s `out` output.
  call stepB { input: in = stepA.out }

  # Run `stepC`, connecting the `in` input to `stepA`'s `out` output.
  call stepC { input: in = stepA.out }

  # Run `stepD`, connecting the `in1` input to `stepB`'s `out` output
  # and the `in2` input to `stepC`'s `out` output.
  call stepD { input: in1 = stepB.out, in2 = stepC.out }
}
```

--------------------------------

### Workflow with Multiple I/O Connections

Source: https://docs.openwdl.org/design-patterns/multiple-io

This workflow demonstrates connecting multiple outputs from one task to multiple inputs of another. Ensure distinct naming for inputs and outputs to avoid conflicts.

```wdl
workflow run {
  # Run `stepA`.
  call stepA {}

  # Run `stepB`, connecting the `in` input to `stepA`'s `out` output.
  call stepB { input: in = stepA.out }

  # Run `stepC`, connecting the `in1` and `in2` inputs to `stepB`'s
  # `out1` and `out2` outputs, respectively.
  call stepC {
    input: in1 = stepB.out1,
    in2 = stepB.out2
  }
}
```

--------------------------------

### Define a Workflow with Task Calls

Source: https://docs.openwdl.org/language-guide/workflows.html

Illustrates how to call tasks within a workflow. Use the 'as' keyword to alias tasks and avoid naming collisions when calling the same task multiple times.

```wdl
task stepA {
  # ...
}

task stepB {
  # ...
}

workflow run {
  # You can instruct the workflow to run `stepA` by `call`-ing it.
  call stepA {}

  # If there are inputs, you can include them within the brackets.
  call stepB { input: foo = bar }

  # Normally, if you wanted to call `stepA` again, there would be
  # a name conflict because the identifier `stepA` would be brought
  # into the workflow's scope twice. You can use the `as` keyword
  # to assign the task an alias.
  call stepA as stepA_again {}
}
```

--------------------------------

### Complex Conditional Logic with Task Variants

Source: https://docs.openwdl.org/language-guide/workflows.html

Shows how to conditionally execute different versions of a task ('standard' or 'alternate') and then conditionally execute another task based on the output of either. Utilizes 'select_first' to aggregate conditional outputs.

```wdl
task stepA {
  # ...
}

task stepA_alternate {
  # ...
}

task stepB {
  # ...
}

workflow run {
  input {
    # `alternate_execution_mode` is a required workflow input.
    Boolean alternate_execution_mode
  }

  # Based on the value passed in as an input, either the alternate
  # execution mode will run, or the standard execution mode will run.
  if (alternate_execution_mode) {
    call stepA_alternate {}
  } else {
    call stepA {}
  }

  # Using `select_first`, we can pick up an output named `qc_passed`
  # in either `stepA` or `stepA_alternate` (whichever ran) and then
  # conditionally run `stepB` based on that result.
  if (select_first([
    stepA.qc_passed,
    stepA_alternate.qc_passed,
  ])) {
    call stepB {}
  }

  # ...
}
```

--------------------------------

### Importing from a local file with default namespace

Source: https://docs.openwdl.org/language-guide/imports.html

Import a WDL file and use its default namespace. Ensure the imported file exists in the same directory or a configured import path.

```wdl
import "foo.wdl"
```

--------------------------------

### Define a basic enum for data formats

Source: https://docs.openwdl.org/language-guide/enumerations.html

Use enums to restrict input parameters to a predefined set of values. This example defines a `DataFormat` enum for CSV, TSV, and JSON.

```wdl
version 1.3

enum DataFormat {
  CSV,
  TSV,
  JSON
}

task parse_data {
  input {
    File infile
    DataFormat format = DataFormat.CSV
  }

  command <<< 
    echo "Parsing ~{format} file: ~{infile}"
  >>>
}

workflow process_data {
  input {
    Array[File] files
    DataFormat format
  }

  scatter (file in files) {
    call parse_data {
      input:
        infile = file,
        format = format
    }
  }
}
```

--------------------------------

### Get Length of Collections and Strings

Source: https://docs.openwdl.org/reference/stdlib/other.html

The `length` function returns the number of elements in an Array, Map, Object, or the number of characters in a String. Ensure the input is one of the supported types.

```wdl
Array[Int] xs = [1, 2, 3]
Map[String, Int] m = {"a": 1, "b": 2}
String s = "ABCDE"

Int xlen = length(xs)
# `xlen` now contains `3`.

Int mlen = length(m)
# `mlen` now contains `2`.

Int slen = length(s)
# `slen` now contains `5`.
```

--------------------------------

### Join Path Components

Source: https://docs.openwdl.org/reference/stdlib/file.html

Constructs an absolute file path by joining multiple path components. The first component can be relative or absolute, and subsequent components must be relative.

```wdl
File path = join_paths(["/usr", "bin", "env"])
# `path` points to `/usr/bin/env`.
```

--------------------------------

### Get Enum Choice Value

Source: https://docs.openwdl.org/reference/stdlib/enum.html

Use the `value` function to retrieve the underlying value of an enum choice. This is useful when you need to work with the raw data associated with an enum member.

```wdl
enum Color {
  Red = "#FF0000",
  Green = "#00FF00",
  Blue = "#0000FF"
}

enum Priority {
  Low = 1,
  Medium = 5,
  High = 10
}

workflow example {
  Color color = Color.Red
  Priority priority = Priority.High

  String choice_name = "~{color}"    # "Red"
  String hex_value = value(color)    # "#FF0000"
  Int priority_num = value(priority) # 10
}
```

--------------------------------

### Expand Glob Pattern to Files

Source: https://docs.openwdl.org/reference/stdlib/file.html

Use `glob` to find all files matching a Bash-style pattern relative to the execution directory. It returns files in the same order as `echo <glob>` would.

```wdl
Array[File] glob(String)
```

```wdl
Array<File> paths = glob("*.py")
# `paths` contains all files with the `.py` extension in the current directory.
```

--------------------------------

### Create Dot Product of Arrays

Source: https://docs.openwdl.org/reference/stdlib/array.html

Use `zip` to combine elements at the same index from two input arrays into pairs. Input arrays must have the same length.

```wdl
Array[Pair[X,Y]] zip(Array[X], Array[Y])
```

```wdl
Array[Int] xs = [1, 2, 3]
Array[String] ys = ["a", "b", "c"]

Array[Pair[Int, String]] result = zip(xs, ys)
# `result` now contains [(1, "a"), (2, "b"), (3, "c")].
```

--------------------------------

### Add Task Metadata in WDL

Source: https://docs.openwdl.org/language-guide/tasks.html

Utilize the meta and parameter_meta sections to document tasks and their inputs/outputs. Keys are typically defined by convention within a project.

```wdl
meta {
    # Example metadata for the task itself
  }
  parameter_meta {
    # Example metadata for task inputs/outputs
  }
```

--------------------------------

### stdout()

Source: https://docs.openwdl.org/reference/stdlib/file.html

Returns the standard output (stdout) of an executed command as a File object. The engine manages the file's name and location in a temporary directory.

```APIDOC
## `stdout` 

### Description
Returns the value of the executed command's standard output (stdout) as a `File`. The engine should give the file a random name and write it in a temporary directory, so as not to conflict with any other task output files.

### Signature
```wdl
File stdout()
```

### Parameters
_None._

### Returns
1. A `File` whose contents are the stdout generated by the command of the task where the function is called.

### Example
```wdl
String message = read_string(stdout())
# `message` contains the output of the process's `stdout`.
```
```

--------------------------------

### Define Multi-line Strings

Source: https://docs.openwdl.org/reference/upgrade-guide.html

Introduces the syntax for defining multi-line strings using triple angle brackets. Useful for embedding large text blocks or configurations.

```wdl
String foo = <<<
  my
  multi-line
  string
>>>
```

--------------------------------

### Split String Using New Standard Library Function

Source: https://docs.openwdl.org/reference/upgrade-guide.html

Replaces custom string splitting logic with the native `split` function. Useful for parsing delimited strings.

```wdl
Array[String] parts = split("a,b,c", ",")  # ["a", "b", "c"]
```

--------------------------------

### WDL Task Command Section

Source: https://docs.openwdl.org/language-guide/tasks.html

Illustrates the required 'command' section of a WDL task, showing variable interpolation.

```wdl
task say_hello {
  input {
    String greeting
    String name
  }

  command <<<
    echo "~{greeting}, ~{name}!"
  >>>

  # ...
}
```

--------------------------------

### Write Lines to File

Source: https://docs.openwdl.org/reference/stdlib/file.html

Writes an array of strings to a file, terminating each string with a newline character. Creates an empty file if the input array is empty.

```wdl
File write_lines(Array[String])
```

```wdl
Array[String] lines = ["first", "second", "third"]

File result = write_lines(lines)
# `result` now points to a file with the contents "first\nsecond\nthird".
```

--------------------------------

### If/Else If/Else Statements in WDL

Source: https://docs.openwdl.org/design-patterns/conditional-statement/index.html

Use 'if', 'else if', and 'else' to create multi-branch conditional logic. This is useful for selecting different analysis paths based on input parameters.

```wdl
workflow run {
  input {
    String mode
  }

  if (mode == "fast") {
    call fast_analysis {}
  } else if (mode == "thorough") {
    call thorough_analysis {}
  } else {
    call standard_analysis {}
  }
}
```

--------------------------------

### Add Prefix to String Array Elements

Source: https://docs.openwdl.org/reference/stdlib/string-array.html

Prepends a specified string to each element in an array. Ensure the input array contains primitive types.

```wdl
Array[String] names = ["John", "Jane", "world"]
String greetings = prefix("Hello, ", names)
# `greetings` now contains `["Hello, John", "Hello, Jane", "Hello, world"]`.
```

--------------------------------

### Specify Task Requirements in WDL

Source: https://docs.openwdl.org/language-guide/tasks.html

Use the requirements section to specify runtime constraints such as container image, CPU cores, and memory. This ensures task portability and reproducibility.

```wdl
requirements {
    # Constrain the container within which this task should run.
    container: "ubuntu:latest",

    # Ensure that 8 cores are requisitioned.
    cpu: 8,

    # Request 16 gibibytes of random-access memory.
    memory: "16 GiB",
  }
```

--------------------------------

### prefix

Source: https://docs.openwdl.org/reference/stdlib/string-array.html

Adds a prefix to each element of the input array of primitive values.

```APIDOC
## `prefix` 

### Description
Adds a prefix to each element of the input array of primitive values.

### Signature
```wdl
Array[String] prefix(String, Array[P])
```

### Parameters
1. **`String`**: The prefix to prepend to each element in the array.
2. **`Array[P]`**: Array with a primitive element type.

### Returns
1. An `Array[String]` with the prefixed elements of the input array.

### Example
```wdl
Array[String] names = ["John", "Jane", "world"]
String greetings = prefix("Hello, ", names)
# `greetings` now contains `["Hello, John", "Hello, Jane", "Hello, world"]`.
```
```

--------------------------------

### Declare Variables in WDL Workflow

Source: https://docs.openwdl.org/language-guide/variables.html

Demonstrates bound and unbound variable declarations, including optional types, within a WDL workflow. Unbound variables require caller-supplied values, while bound variables have defaults. Optional variables can be None.

```wdl
workflow run {
  input {
    Int radius
    Float pi = 3.14
    File? reference
  }
  Int three = 1 + 2
  output {
    Float six = 2 * three
  }
}
```

--------------------------------

### Workflow Connecting Split and Merge VCF Tasks

Source: https://docs.openwdl.org/design-patterns/multiple-io

This workflow orchestrates the splitting and merging of VCF files, demonstrating how to connect multiple outputs from one task to the inputs of another.

```wdl
# (3) We write a workflow that connects the multiple outputs
# from the `split_vcf` task into the multiple inputs from the
# `merge_vcfs` task.
workflow run {
  input {
    File vcf
  }

  call split_vcf { input: vcf }

  # (a) The outputs are connected to the inputs here.
  call merge_vcfs {
    input:
    snp_vcf = split_vcf.snp_vcf,
    indel_vcf = split_vcf.indel_vcf,
  }

  output {
    File combined = merge_vcfs.combined
  }
}
```

--------------------------------

### Importing from a URI

Source: https://docs.openwdl.org/language-guide/imports.html

Import WDL code directly from a remote URL. This is useful for accessing shared libraries or standard libraries hosted online. Ensure the URL is accessible and the content is valid WDL.

```wdl
import "http://example.com/lib/stdlib.wdl"
```

--------------------------------

### Task to Merge Multiple VCF Inputs

Source: https://docs.openwdl.org/design-patterns/multiple-io

This task accepts two VCF files as input and merges them into a single output VCF file using Picard MergeVcfs.

```wdl
# (2) We write a task to merge these two VCFs.
task merge_vcfs {
  input {
    # (a) Two input VCFs are accepted.
    File snp_vcf
    File indel_vcf
  }

  command <<<
    java -jar picard.jar MergeVcfs \
      I="~{snp_vcf}" \
      I="~{indel_vcf}" \
      O="combined.vcf"
  >>>

  output {
    # (b) One output VCF is produced.
    File combined = "combined.vcf"
  }
}
```

--------------------------------

### Use `else if` and `else` for Conditional Logic in WDL

Source: https://docs.openwdl.org/reference/upgrade-guide.html

Employ `else if` and `else` clauses for more expressive conditional logic within workflows, simplifying previously nested or negated `if` statements.

```wdl
version 1.3

workflow example {
  input {
    String mode
  }

  if (mode == "fast") {
    call fast_analysis
  } else if (mode == "thorough") {
    call thorough_analysis
  } else {
    call default_analysis
  }
}
```

--------------------------------

### Define a custom Address struct

Source: https://docs.openwdl.org/language-guide/structs.html

Define a struct named 'Address' with various fields including integers, strings, arrays, and an optional array with a nullable type.

```wdl
struct Address {
  Int street_number
  String street_address
  Array[Int] zip_code
  String city
  String state
  Array[Int]+? gate_code
}
```

--------------------------------

### Read Lines from File

Source: https://docs.openwdl.org/reference/stdlib/file.html

Reads each line of a file into an array of strings. Trailing newline characters are removed. Returns an empty array for empty files.

```wdl
Array[String] read_lines(File)
```

```wdl
Array[String] lines = read_lines("foo.txt")
# `lines` contains the newline-delimited lines read from `foo.txt`.
```

--------------------------------

### Read File Content as String

Source: https://docs.openwdl.org/reference/stdlib/file.html

Read the entire content of a File into a String using read_string(File). Trailing newline characters are stripped, but internal newlines are preserved. An empty file results in an empty string.

```wdl
String read_string(File)
```

--------------------------------

### Task to Split VCF into Multiple Outputs

Source: https://docs.openwdl.org/design-patterns/multiple-io

This task accepts a single VCF file and produces two output VCF files: one for SNPs and one for indels. It uses the Picard SplitVcfs tool.

```wdl
version 1.3

# (1) We write a task to split the VCF into multiple VCFs.
task split_vcf {
  input {
    # (a) The task takes in a single input VCF.
    File vcf
  }

  command <<<
    java -jar picard.jar SplitVcfs \
      I="~{vcf}" \
      SNP_OUTPUT="snp.vcf" \
      INDEL_OUTPUT="indel.vcf" \
      STRICT=false
  >>>

  output {
    # (b) The task produces two output VCFs.
    File snp_vcf = "snp.vcf"
    File indel_vcf = "indel.vcf"
  }
}
```

--------------------------------

### Importing a local file with an alias

Source: https://docs.openwdl.org/language-guide/imports.html

Import a WDL file and assign it a custom namespace alias to avoid naming conflicts or for clarity. This allows you to refer to the imported code using the alias.

```wdl
import "bar.wdl" as baz
```

--------------------------------

### Read Integer from File

Source: https://docs.openwdl.org/reference/stdlib/file.html

Reads a file containing a single integer and optional whitespace. Raises an error if the file is empty or does not contain a valid integer.

```wdl
Int read_int(File)
```

```wdl
Int number = read_int(stdout())
# If `stdout` contains an int, returns the int. Else, an error is raised.
```

--------------------------------

### Round Down with floor()

Source: https://docs.openwdl.org/reference/stdlib/numeric.html

Use `floor()` to round a floating-point number down to the nearest integer. The input must be a Float and the output is an Int.

```wdl
Int three = floor(3.14)
# `three` now contains `3`.
```

--------------------------------

### Basic Conditional Execution in WDL

Source: https://docs.openwdl.org/design-patterns/conditional-statement/index.html

Use an 'if' statement to conditionally execute a block of tasks. The condition can be based on workflow inputs.

```wdl
workflow run {
  inputs {
    Boolean perform_further_work = true
  }

  # Run the first task.
  call stepA {}

  # If the conditional is true, run `stepB` and `stepC`.
  if (perform_further_work) {
    call stepB { input: in = stepA.out }
    call stepC { input: in = stepB.out }
  }
}
```

--------------------------------

### Write Map to TSV with write_map

Source: https://docs.openwdl.org/reference/stdlib/file.html

Writes a Map[String, String] to a tab-separated value (TSV) file. Each map entry becomes a tab-delimited line. The order of lines is preserved from the map. Handles empty maps by writing an empty file.

```wdl
File write_map(Map[String, String])
```

```wdl
Map[String, String] map = {"key1": "value1", "key2": "value2"}
File result = write_map(map)
# `result` points to a file with the contents "key1\tvalue1\nkey2\tvalue2".
```

--------------------------------

### select_first

Source: https://docs.openwdl.org/reference/stdlib/array.html

Selects the first non-None value from an array of optional values. An optional default value can be provided.

```APIDOC
## `select_first` 

### Description
Selects the first non-`None` value from an `Array` of optional values. An optional default value can be provided.

### Signatures
```wdl
X select_first(Array[X?]+)
X select_first(Array[X?], X)
```

### Parameters
1. **`Array[X?]+`**: Non-empty `Array` of optional values.
2. **`X`**: (Optional) The default value.

### Returns
1. The first non-`None` value in the input array, or the default value if it is provided and the array does not contain any non-`None` values.

### Example
```wdl
Int? maybe_five = 5
Int? maybe_none = None
Int? maybe_three = 3

Int result1 = select_first([maybe_five, maybe_none, maybe_three])
# `result1` now contains `5`.

Int result2 = select_first([maybe_none, maybe_five, maybe_three])
# `result2` now contains `5`.

Int result3 = select_first([], 42)
# `result3` now contains `42`.
```
```

--------------------------------

### write_json

Source: https://docs.openwdl.org/reference/stdlib/file.html

Writes a JSON file with the serialized form of a WDL value. Supports serialization of Struct, Object, Map, Array, Int, Float, String, File, Boolean, and None types. Nested types must also be serializable. Returns a File object representing the created JSON file.

```APIDOC
## `write_json` 

Writes a JSON file with the serialized form of a WDL value. The following WDL types can be serialized:
WDL Type| JSON Type  
---|---  
`Struct`| object  
`Object`| object  
`Map[String, X]`| object  
`Array[X]`| array  
`Int`| number  
`Float`| number  
`String`| string  
`File`| string  
`Boolean`| boolean  
`None`| null  
When serializing compound types, all nested types must be serializable or an error is raised.
**Signatures**
wdl```
File write_json(X)
```

**Parameters**
  1. **`X`**: A WDL value of a supported type.

**Returns**
  1. A `File`.

**Example**
wdl```
struct Person {
    String name
    Int age
}

Array[Person] people = [
    Person {
         name: "Jane Doe",
         age: 29,
    },
    Person {
         name: "John Doe",
         age: 28,
    }
]

File result = write_tsv(people)
# `people` points to a file with the contents `"Jane Doe\t29\nJohn Doe\t28"`.
```
```

--------------------------------

### Read Stdout to String

Source: https://docs.openwdl.org/reference/stdlib/file.html

Read the standard output of a command into a String using read_string(stdout()). This is useful for processing command output directly within WDL.

```wdl
String message = read_string(stdout())
# `message` contains the output of the process's `stdout`.
```

--------------------------------

### glob

Source: https://docs.openwdl.org/reference/stdlib/file.html

Returns the Bash expansion of the glob string relative to the task's execution directory, and in the same order. It finds all files (but not directories) as would be matched by running `echo <glob>` in Bash.

```APIDOC
## `glob` 

### Description
Returns the Bash expansion of the glob string relative to the task's execution directory, and in the same order. `glob` finds all of the files (but not the directories) in the same order as would be matched by running `echo <glob>` in Bash from the task's execution directory. At least in standard Bash, glob expressions are not evaluated recursively, i.e., files in nested directories are not included.

### Signature
```
Array[File] glob(String)
```

### Parameters
  1. **`String`**: The glob string.

### Returns
  1. An array of all files matched by the glob.

### Example
```
Array<File> paths = glob("*.py")
# `paths` contains all files with the `.py` extension in the current directory.
```
```

--------------------------------

### zip

Source: https://docs.openwdl.org/reference/stdlib/array.html

Creates an array of Pairs containing the dot product of two input arrays. Elements at the same indices in each array are combined into a Pair.

```APIDOC
## `zip` 

Creates an array of `Pair`s containing the dot product of two input arrays, i.e., the elements at the same indices in each array `X[i]` and `Y[i]` are combined together into (`X[i]`, `Y[i]`) for each `i` in `range(length(X))`. The input arrays must have the same lengths or an error is raised. If the input arrays are empty, an empty array is returned.
**Signatures**
wdl```
Array[Pair[X,Y]] zip(Array[X], Array[Y])
```

**Parameters**
  1. **`Array[X]`**: The first array of length`N`.
  2. **`Array[Y]`**: The second array of length`N`.


**Returns**
  1. An `Array[Pair[X, Y]]` of length `N`.


**Example**
wdl```
Array[Int] xs = [1, 2, 3]
Array[String] ys = ["a", "b", "c"]

Array[Pair[Int, String]] result = zip(xs, ys)
# `result` now contains [(1, "a"), (2, "b"), (3, "c")].
```
```

--------------------------------

### Convert Array of Pairs to Map

Source: https://docs.openwdl.org/reference/stdlib/map.html

Use `as_map` to convert an Array of Pairs into a WDL Map. Ensure all keys in the Pairs are unique, as duplicate keys will raise an error. The order of elements in the Map reflects the order in the input Array.

```wdl
Array[Pair[String, Int]] x = [("a", 1), ("c", 3), ("b", 2)]

Map[String, Int] result = as_map(x)
# `result` now contains {"a": 1, "c": 3, "b": 2}.
```

--------------------------------

### Conditional Execution Based on Task Output in WDL

Source: https://docs.openwdl.org/design-patterns/conditional-statement/index.html

Conditionally execute tasks based on the output of a previous task. This allows for dynamic workflow branching.

```wdl
workflow run {
  # Run the first task.
  call stepA {}

  # If `stepA` determined the sample is of sufficient quality,
  # run `stepB` and `stepC`.
  if (stepA.is_sufficient_quality) {
    call stepB { input: in = stepA.out }
    call stepC { input: in = stepB.out }
  }
}
```

--------------------------------

### cross

Source: https://docs.openwdl.org/reference/stdlib/array.html

Creates an array of Pairs containing the cross product of two input arrays. Each element in the first array is paired with each element in the second array.

```APIDOC
## `cross` 

Creates an array of `Pair`s containing the cross product of two input arrays, i.e., each element in the first array is paired with each element in the second array.
Given `Array[X]` of length `M`, and `Array[Y]` of length `N`, the cross product is `Array[Pair[X, Y]]` of length `M*N` with the following elements: `[(X0, Y0), (X0, Y1), ..., (X0, Yn-1), (X1, Y0), ..., (X1, Yn-1), ..., (Xm-1, Yn-1)]`. If either of the input arrays is empty, an empty array is returned.

**Signatures**
wdl```
Array[Pair[X,Y]] cross(Array[X], Array[Y])
```

**Parameters**
  1. **`Array[X]`**: The first array of length`M`.
  2. **`Array[Y]`**: The second array of length`N`.


**Returns**
  1. An `Array[Pair[X, Y]]` of length `M*N`.


**Example**
wdl```
Array[Int] xs = [1, 2, 3]
Array[String] ys = ["a", "b"]

Array[Pair[Int, String]] result = cross(xs, ys)
# `result` now contains [(1, "a"), (1, "b"), (2, "a"), (2, "b"), (3, "a"), (3, "b")].
```
```

--------------------------------

### size

Source: https://docs.openwdl.org/reference/stdlib/file.html

Determines the size of a file, directory, or the sum total sizes of the files/directories contained within a compound value. The files may be optional values; `None` values have a size of `0.0`. By default, the size is returned in bytes unless an optional second argument specifies a unit.

```APIDOC
## `size` 

### Description
Determines the size of a file, directory, or the sum total sizes of the files/directories contained within a compound value. The files may be optional values; `None` values have a size of `0.0`. By default, the size is returned in bytes unless the optional second argument is specified with a unit. In the second variant of the `size` function, the parameter type `X` represents any compound type that contains `File` or `File?` nested at any depth. If the size cannot be represented in the specified unit because the resulting value is too large to fit in a `Float`, an error is raised. It is recommended to use a unit that will always be large enough to handle any expected inputs without numerical overflow.

### Signatures
```
Float size(File|File?, [String])
Float size(Directory|Directory?, [String])
Float size(X|X?, [String])
```

### Parameters
  1. **`File|File?|Directory|Directory?|X|X?`**: A file, directory, or a compound value containing files/directories, for which to determine the size.
  2. **`String`**: (Optional) The unit of storage; defaults to 'B'.

### Returns
  1. The size of the files/directories as a `Float`.

### Example
```
Float size = size("foo.txt")
# `size` contains the size of `foo.txt`.
```
```

--------------------------------

### Importing specific elements with aliasing

Source: https://docs.openwdl.org/language-guide/imports.html

Import a specific struct, task, or workflow from a WDL file directly into the current namespace, optionally aliasing it to a different name. This is useful for bringing commonly used components into scope without their original namespace.

```wdl
import "person.wdl" alias Person as Individual
```

--------------------------------

### Round to Nearest with round()

Source: https://docs.openwdl.org/reference/stdlib/numeric.html

Use `round()` to round a floating-point number to the nearest integer using standard rounding rules (round half up). The input must be a Float and the output is an Int.

```wdl
Int three = round(3.14)
# `three` now contains `3`.
```

--------------------------------

### Read TSV File (Array of Objects with Header)

Source: https://docs.openwdl.org/reference/stdlib/file.html

Reads a TSV file, treating the first line as a header. Each subsequent row is returned as an object with keys from the header. All rows must have the same length as the header.

```wdl
Array[Object] read_tsv(File, true)
```

```wdl
Array[Object] objects = read_tsv("data.tsv", true)
# `objects` holds an array of objects read in from `data.tsv`.
```

--------------------------------

### Find Minimum Value with min()

Source: https://docs.openwdl.org/reference/stdlib/numeric.html

Use `min()` to return the smaller of two values. The return type is Int if both inputs are Ints, otherwise it is a Float. This is equivalent to a conditional expression.

```wdl
Int value1
Float value2

Float result = min(value1, value2)
# This is equivalent to `if value1 < value2 then value1 else value2`.
```

--------------------------------

### unzip

Source: https://docs.openwdl.org/reference/stdlib/array.html

Creates a Pair of Arrays from an Array of Pairs. The first array contains all the left elements, and the second array contains all the right elements. This is the inverse of the zip function.

```APIDOC
## `unzip` 
Creates a `Pair` of `Arrays`, the first containing the elements from the `left` members of an `Array` of `Pair`s, and the second containing the `right` members. If the array is empty, a pair of empty arrays is returned. This is the inverse of the `zip` function.
**Signatures**
wdl```
Pair[Array[X], Array[Y]] unzip(Array[Pair[X, Y]])
```

**Parameters**
  1. **`Array[Pair[X, Y]]`**: The`Array` of `Pair`s of length `N` to unzip.


**Returns**
  1. A `Pair[Array[X], Array[Y]]` where each `Array` is of length `N`.


**Example**
wdl```
Array[Pair[Int, String]] int_str_arr = [(0, "hello"), (42, "goodbye")]

Pair[Array[Int], Array[String]] result = unzip(int_str_arr)
# `result` now contains ([0, 42], ["hello", "goodbye"])
```
```

--------------------------------

### Write TSV from Array of Arrays

Source: https://docs.openwdl.org/reference/stdlib/file.html

Use this variant to write a TSV file where each row is an array of strings. No header is generated.

```wdl
Array[Array[String]] array = [["one", "two", "three"], ["un", "deux", "trois"]]
File result = write_tsv(array)
# `result` points to a file with the content of `array` written as a TSV.
```

--------------------------------

### Declare Task Outputs in WDL

Source: https://docs.openwdl.org/language-guide/tasks.html

Define task outputs using built-in functions like read_int and glob. Variables declared in the output block are evaluated after the task completes.

```wdl
output {
    # Reads an integer from a file called `threshold.txt`.
    Int threshold = read_int("threshold.txt")

    # Gathers a list of CSV files from the task's execution directory.
    Array[File]+ csvs = glob("*.csv")

    # Examines an existing variable to evaluate a boolean expression.
    Boolean two_csvs = length(csvs) == 2
  }
```
Tokens:
Raw