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.

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.