Overview

The bids function generates a BIDS-like filepath corresponding to its keyword arguments. The generated filepath has the form:

[root]/[sub-{subject}]/[ses-{session]/[prefix]_[sub-{subject}]_[ses-{session}]_[{key}-{val}_ ... ]_[suffix]

Use cases of the bids function include, at simplest, replacing a hard-coded BIDS file with an invocation of the bids function, so

"data/sub-01/ses-01/func/sub-01_ses-01_task-rest_acq-01_run-1_bold.nii.gz"

could become

bids(
    root="data",
    subject="01",
    session="01",
    datatype="func",
    task="rest",
    acq="01",
    run="1",
    suffix="bold.nii.gz"
)

If you wanted to specify that a rule should run on a BIDS file from any subject, session, acquisition, task, and run, you could change those keyword arguments to be snakemake wildcards:

bids(
    root="data",
    subject="{subject}",
    session="{session}",
    datatype="func",
    task="{task}",
    acq="{acq}",
    run="{run}",
    suffix="bold.nii.gz"
)

Using the subject and session keywords as wildcards is common enough that snakebids pre-populates a config variable (subj_wildcards) with these wildcards, allowing the bids call to look like the following:

bids(
    root="data",
    datatype="func",
    task="{task}",
    acq="{acq}",
    run="{run}",
    suffix="bold.nii.gz",
    **inputs.subj_wildcards
)

Now if you want to process all inputs of a given form regardless of how their wildcards resolve, you can use BidsComponent.expand to expand over the entity-values found in your input dataset. As an example, to specify the output of a rule that preprocesses BOLD images (as specified in the example configuration), the following would resolve the subject, session, acquisition, task, and run wildcards:

inputs["bold"].expand(
    bids(
        root="output",
        datatype="func",
        desc="preproc",
        acq="{acq}",
        task="{task}",
        run="{run}",
        **inputs.subj_wildcards
    ),
)