Run Code with Docker

Docker is a boon to research and get's past the issue of "runs on my machine" by making a portable, entirely reproducible environment.

This guide will set you up to run the code via docker.

1. download docker on your machine

2a. via the commandline, type docker pull hbclab/restingstate.
2b. If the above doesn't work (I haven't set it up yet). you need to:

• clone the repository: git clone https://github.com/HBClab/RestingState.git
• build the docker image (while in the same directory as the Dockerfile: docker build -t hbclab/restingstate .

3. Run the image.

Example #1

I have a bid(ish) organized dataset like so

ds005
├── CHANGES
├── dataset_description.json
├── derivatives
│   ├── bet
│   │   └── sub-01
│   │       └── anat
│   │           └── sub-01_desc-brainmask_T1w.nii.gz
│   └── data
│       └── roi_list.txt
├── participants.tsv
├── README
├── sub-01
│   ├── anat
│   │   └── sub-01_T1w.nii.gz
│   └── func
│       ├── sub-01_task-rest_run-01_bold.nii.gz
│       ├── sub-01_task-rest_run-01_events.tsv
│       ├── sub-01_task-rest_run-02_bold.nii.gz
│       └── sub-01_task-rest_run-02_events.tsv
└── task-rest_bold.json

Importantly, I need a bold image (sub-01_task-rest_run-01_bold.nii.gz), an anatomical image (sub-01_T1w.nii.gz) and an anatomical mask (sub-01_desc-brainmask_T1w.nii.gz).

To run docker with this data, I need to give docker access to the bids directory (in this case ds005). I can give docker access to ds005 through binding volumes. The option would look something like this: -v /path/to/ds005:/data

Furthermore, if I've cloned the repository and made some local changes to the code that I want to test in the docker container, I can bind the code directory to the docker container as well. The option would look like this: -v /path/to/RestingState:/opt/RestingState

Here is what the command would look like put together:

docker run -it \
-v /path/to/ds005:/data \
-v /path/to/RestingState:/opt/RestingState \
hbclab/restingstate \
  --epi=/data/sub-01/func/sub-01_task-rest_run-01_bold.nii.gz \
  --t1=/data/sub-01/anat/sub-01_T1w.nii.gz \
  --t1_mask=/data/derivatives/bet/sub-01/anat/sub-01_desc-brainmask_T1w.nii.gz \
  --roiList=/data/derivatives/data/roi_list.txt \
  --compcor

and if you didn't want to patch your local code in, remove -v /path/to/RestingState:/opt/RestingState

docker run -it \
-v /path/to/ds005:/data \
hbclab/restingstate \
  --epi=/data/sub-01/func/sub-01_task-rest_run-01_bold.nii.gz \
  --t1=/data/sub-01/anat/sub-01_T1w.nii.gz \
  --t1_mask=/data/derivatives/bet/sub-01/anat/sub-01_desc-brainmask_T1w.nii.gz \
  --roiList=/data/derivatives/data/roi_list.txt \
  --compcor

Example #2: Running docker image with compcor_global option on CREST data, patching in cloned local scripts

• Steps 1 and 2 are shown below for a single subject. Create a loop script to run the same command on a list of subjects.

1. Run preprocessing, nuisance regression, and extract timeseries data from roi's in roi_list

docker run -it \
-v /Volumes/vosslabhpc/Projects/CREST:/data \
-v /Users/mwvoss/bin/RestingState:/opt/RestingState \
hbclab/restingstate \
   --epi=/data/sub-AMBI003/func/sub-AMBI003_task-rest_bold.nii.gz \
   --t1=/data/derivatives/fmriprep/sub-AMBI003/anat/sub-AMBI003_desc-preproc_T1w.nii.gz \
   --t1_mask=/data/derivatives/fmriprep/sub-AMBI003/anat/sub-AMBI003_desc-brain_mask.nii.gz \
   --roiList=/data/derivatives/rois/roi_list.txt \
   --compcor_global

2. Running additional seeds by calling only seedVoxelCorrelation

docker run -it \
-v /Volumes/vosslabhpc/Projects/CREST:/data \
--entrypoint /opt/RestingState/seedVoxelCorrelation.sh \
hbclab/restingstate \
    --epi=/data/derivatives/rsOut/sub-AMBI003/nuisanceRegression/compcor_global/nonfiltered_smooth_data_bp_res4d_normandscaled.nii.gz \
    --motionscrub \
    --roiList=/data/derivatives/rois/roi_list.txt \
    --compcor_global

3. Extracting roi-roi correlations for each subject with run_getroicorrs-shell-wrapper.sh

docker run -it \
-v /Users/mwvoss/bin/RestingState:/opt/RestingState \
-v /Volumes/vosslabhpc/Projects/CREST:/data \
--entrypoint /opt/RestingState/run_getroicorrs-shell-wrapper.sh \
hbclab/restingstate