Config files

Often, the software you use in your workflow will have parameters; your workflow itself could have parameters. Instead of hardcoding parameter values in the Snakefile, Snakemake allows to define parameters and their values in a config file. This file can be in either YAML or JSON format; here we will focus on YAML, as it is the most user-friendly and the recommended one.

The config file will be parsed by Snakemake when executing the workflow, and parameters and their values will be stored in a dictionary named config. The path to the config file can be specified either in the Snakefile with the line configfile: <path/to/file.yaml> at the top of the file, or it can be specified at runtime with the execution parameter --configfile <path/to/file.yaml>.

Briefly, in the YAML format, parameters are defined with the syntax <name>: <value>. Values can be strings, integers, floating points, booleans ... For a complete overview of available value types, see this list. A parameter can have multiple values, which are then each listed on an indented single line starting with "-". These values will be stored in a Python list when Snakemake parses the config file. Finally, parameters can be nested on indented single lines, and they will be stored as a dictionary when Snakemake parses the config file.

The example below shows a parameter with a single value (lines_number), a parameter with multiple values (samples), and an example of nested parameters (resources):

config.yaml

# Parameter with a single value (string, int, float, bool ...)
lines_number: 5
# Parameter with multiple values
samples:
    - sample1
    - sample2
# Nested parameters
resources:
    threads: 4
    memory: 4G

Then, each parameter can be accessed in Snakefile with the following syntax:

config['lines_number']  # --> 5
config['samples']  # --> ['sample1', 'sample2']
config['resources']  # --> {'threads': 4, 'memory': '4G'}

---

Values stored in the config dictionary cannot be accessed directly within the shell directive. If you need to use a parameter value in shell, define the parameter in params and assign its value from the config dictionary.

The following example shows a Snakefile loading the config file config.yaml defined above and using the value of the parameter lines_number in a rule:

configfile: 'config.yaml'

rule first_step:
    input:
        'data/first_step.txt'
    output:
        'results/first_step.tsv'
    params:
        lines_number = config['lines_number']
    shell:
        'head -n {params.lines_number} {input} > {output}'