Running a BIDS App
Running a BIDS App locally
Running a BIDS App on a local system can be performed using Docker, which is easy to install on all three major operating systems. After installing and starting docker, download the relevant data, ds005.tar, and untar it in a directory.
ds005
will be our input directory in the following example.
Create an outputs
directory as well.
To run the first stage of the example BIDS App for participant number 01,
open a console (terminal or cmd) and type:
docker run -ti --rm \
-v /Users/srycajal/data/ds005:/bids_dataset:ro \
-v /Users/srycajal/outputs:/outputs \
bids/example:0.0.4 \
/bids_dataset /outputs participant --participant_label 01
This command runs docker with some flags and then binds the input directory on our local machine,
for example, /Users/srycajal/data/ds005
,
to a preset directory inside of the docker container (/bids_dataset
).
You must use the absolute path to both of these directories.
Similarly, we bind the outputs
directory on our local machine
for example, /Users/srycajal/outputs
to the /outputs
directory inside the container.
This is the path where results should be stored.
Next, the command lists the docker container to download from Docker Hub and run: bids/example:0.0.4
.
Finally, --participant_label 01
limits the data that will be used
to just the first subject in the dataset.
If we wanted to run all the participants,
we would simply remove --participant_label 01
.
Or we could select a couple of participants like this: --participant_label 01 03
.
If the BIDS App was not run before on this machine,
the docker image will be automatically downloaded from Docker Hub.
Running a BIDS App on a cluster (HPC)
Before a BIDS App can be run on a cluster, it first needs to be saved to an Apptainer-compatible image file.1 This step needs to be performed outside of the cluster (for example on a laptop) and requires Docker:
docker run --privileged -ti --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /home/srycajal/apptainer_images:/output \
singularityware/docker2singularity \
bids/example:0.0.4
Where /home/srycajal/apptainer_images
is a path where the image will be stored.
After transferring the .img file to a cluster it can be run like any other executable:
./bids_example-0.0.4.img /bids_dataset /outputs participant --participant_label 01
Helpful links
To learn more containers:
- consult this tutorial
- watch the workshop video
BIDS apps tutorials:
- see this intro to BIDS apps