Skip to content

Run Code with Docker

Jump to bottom
Michelle Voss edited this page Feb 18, 2019 · 13 revisions

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 .
  1. 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

Using docker container (following from steps above about how to pull it):

docker run -it \
-v /Volumes/vosslabhpc/Projects/CREST:/data \
-v /Users/mwvoss/bin/RestingState:/opt/RestingState \
hbclab/restingstate:v0.3.0 \
   --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

Here is an example of the contents of roi_list.txt:

/data/derivatives/rois/AH_MTL_HF.nii.gz
/data/derivatives/rois/AH_MTL_HF_Rhemi.nii.gz
/data/derivatives/rois/UIUC_DMN_core.nii.gz

The same call but patching in local code (assuming it's up to date or you're testing a feature branch):

docker run -it \
-v /Volumes/vosslabhpc/Projects/CREST:/data \
-v /Users/mwvoss/bin/RestingState:/opt/RestingState \
hbclab/restingstate:v0.3.0 \
   --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:v0.3.0 \
    --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 /Volumes/vosslabhpc/Projects/CREST:/data \
--entrypoint /opt/RestingState/run_getroicorrs_shell_wrapper.sh \
hbclab/restingstate:v0.3.0 /data/derivatives/rsOut/ /data/derivatives/sublists/sublist.txt /data/derivatives/sublists/sublist_rois.txt
  • Three path arguments passed into the shell wrapper, from perspective of docker container:

  1. Parent directory where output of these scripts has gone

  2. Path to a text file listing subjects one per new line. Here is an example:

sub-AMBI002
sub-AMBI003
sub-AMBI005
sub-AMBI006
sub-AMBI007
  1. Path to an roi list, one per new line, without nifti extensions. Here is an example:
AH_MTL_HF
AH_MTL_HF_Rhemi
UIUC_DMN_core

Clone this wiki locally