The 'expand' syntax

The expand function is a utility implemented in Snakemake to automatically expand a wildcard expression to several wildcard values. It is particularly useful to easily define multiple inputs or outputs that follow a common pattern.

The expand function follows the syntax expand('{wildcard_name}', wildcard_name=<values>), where <values> is an iterable (i.e. list, tuple, set) containing the wildcard values.

As an example, let us consider a rule that aggregates data for three samples:

rule first_step:
    input:
        'data/sample_1.tsv',
        'data/sample_2.tsv',
        'data/sample_3.tsv'
    output:
        'results/all_samples.tsv'
    shell:
        'cat {input} > {output}'

We could simplify the definition of this rule using the expand syntax:

rule first_step:
    input:
        expand('data/sample_{number}.tsv', number=[1, 2, 3])
    output:
        'results/all_samples.tsv'
    shell:
        'cat {input} > {output}'

To make the rule more generic and customizable, we can specify the wildcard values outside of the rule definition:

numbers = [1, 2, 3]

rule first_step:
    input:
        expand('data/sample_{number}.tsv', number=numbers)
    output:
        'results/all_samples.tsv'
    shell:
        'cat {input} > {output}'

With this implementation, samples can be easily added, removed, or updated by only modifying the list stored in numbers.

Note: in this example, the rule first_step will use all three input files to generate a single output file. The expand syntax does not apply the rule separately to the three files! The following example illustrates how the expand syntax can be used to execute a rule on multiple input files:

numbers = [1, 2, 3]

rule first_step:
    input:
        'data/sample_{number}.txt' 
    output:
        'results/sample_{number}_processed.tsv'
    shell:
        'cat {input} | grep "snakemake" > {output}'

rule aggregate:
    input:
        expand('results/sample_{number}_processed.tsv', number=numbers)
    output:
        'results/aggregate.txt'

With these definitions, running snakemake with the target results/aggregate.txt will execute the rule first_step separately on the three input files sample_1.txt, sample_2.txt, sample_3.txt.

---

The expand function can be used on multiple wildcards; by default, the product of wildcard values will be generated:

expand('data/{sample}_{treatment}.tsv, sample=['A', 'B'], treatment=[1, 2]')
'data/A_1.tsv', 'data/A_2.tsv', 'data/B_1.tsv', 'data/B_2.tsv'

For more information on extending the expand syntax, for instance to generate something other than the product of two wildcard values, check the relevant section in the official documentation.