Run mriqc with docker

Preliminaries

  1. Get the Docker Engine (https://docs.docker.com/engine/installation/)

  2. Have your data organized in BIDS (get BIDS specification, see BIDS paper).

  3. Validate your data (http://incf.github.io/bids-validator/). You can safely use the BIDS-validator since no data is uploaded to the server, works locally in your browser.

Warning

2GB is the default memory setting on a fresh installation of Docker for Mac. We recommend increasing the available memory for Docker containers

When using docker with big datasets (+10GB) docker might fail. Changing the maximum size of the container will solve it:

$ service docker stop
$ dockerd --storage-opt dm.basesize=30G

Warning

On Windows installations, before using the -v switch to mount volumes into the container, it is necessary to enable shared drives.

Running mriqc

  1. Test that the mriqc container works correctly. A successful run will show the current mriqc version in the last line of the output:

docker run -it nipreps/mriqc:latest --version

  1. Run the participant level in subjects 001 002 003:

docker run -it --rm -v <bids_dir>:/data:ro -v <output_dir>:/out nipreps/mriqc:latest /data /out participant --participant_label 001 002 003

  1. Run the group level and report generation on previously processed (use the same <output_dir>) subjects:

docker run -it --rm -v <bids_dir>:/data:ro -v <output_dir>:/out nipreps/mriqc:latest /data /out group

Note

If the argument --participant_label is not provided, then all subjects will be processed and the group level analysis will automatically be executed without need of running the command in item 3.

Warning

Paths <bids_dir> and <output_dir> must be absolute. In particular, specifying relative paths for <output_dir> will generate no error and mriqc will run to completion without error but produce no output.

Warning

For security reasons, we recommend to run the docker command with the options --read-only --tmpfs /run --tmpfs /tmp. This will run the docker image in read-only mode, and map the temporary folders /run and /tmp to the temporal folder of the host.

Explaining the mriqc-docker command line

Let’s dissect this command line:

  • docker run- instructs the docker engine to get and run a certain image (which is the last of docker-related arguments: nipreps/mriqc:latest)

  • -v <bids_dir>:/data:ro - instructs docker to mount the local directory with your input dataset <bids_dir>`into :code:/data` inside the container in a read only mode.

  • -v <output_dir>:/out- instructs docker to mount the local directory <output_dir>`into :code:/out` inside the container. This is where the results of the QC analysis (reports, tables) will be stored.

  • nipreps/mriqc:latest - this tells docker to run MRIQC. latest corresponds to the version of MRIQC. You should replace latest with a version of MRIQC you want to use. Remember not to switch versions while analysing one dataset!

  • /data /scratch/out participant - are the standard arguments of mriqc.