A pipeline, based on abcd-hcp-pipeline, to process fMRI data for human infants.
The repository contains the Dockerfile, entrypoint.sh, SetupEnv.sh and the app folder containing the BIDS App source. All of this is needed in order for Docker Hub to build the infant-abcd-bids-pipeline.
When a release is made and Docker Hub's auto-build has completed, the Docker image can be loaded on your server as follows:
docker pull dcanumn/infant-abcd-bids-pipeline
Optionally, a user can clone the repository and build the Docker image in place using the build-and-zip.sh script.
This is a "BIDS App" (a portable neuroimaging pipeline that understand BIDS datasets). This software takes a BIDS folder as input, determines parameters to be used, and runs the dcan lab's modified hcp pipeline for infants.
In order to run this software via a container, you will need to acquire a copy of the FreeSurfer License for yourself.
Follow this link for a FreeSurfer License
Before running, you will need to load the image onto your Docker service by running the following command:
docker pull dcanlabs/infant-abcd-hcp-pipeline
If you receive a "no space left on device" error during this pull process, you may need to clean up any old/dangling images and containers from the docker registry, and possibly increase the amount of space allocated to Docker.
To call the Docker image:
docker run --rm \
-v <path to bids_dataset>:/bids_input:ro \
-v <path to outputs>:/output \
-v <path to freesurfer license.txt>:/opt/freesurfer/license.txt \
dcanlabs/infant-abcd-bids-pipeline /bids_input /output [OPTIONS]
usage: run.py [-h] [--aseg PATH] [--atropos-mask-method {REFINE,CREATE,NONE}]
[--atropos-range LOWER UPPER] [--bandstop LOWER UPPER]
[--dcmethod {TOPUP,FIELDMAP,T2_DC,NONE}]
[--freesurfer-license PATH]
[--hyper-normalization-method {ADULT_GM_IP,ROI_IPS,NONE}]
[--jlf-method {T1W,T2W,T1W_ORIG}] [--max-cortical-thickness MM]
[--motion-control-frame FRAME] [--multi-masking-dir PATH]
[--multi-template-dir PATH] [--no-crop]
[--participant-label LABEL [LABEL ...]]
[--session-id [LABEL [LABEL ...]]]
[--smoothing-iterations ITERATIONS]
[--subcortical-map-method {ROI_MAP,MNI_AFFINE}]
[--T1-brain-mask PATH] [--t1-study-template HEAD BRAIN]
[--t2-study-template HEAD BRAIN] [--anat-only]
[--custom-clean PATH] [--file-mapper-json PATH]
[--check-outputs-only] [--ignore-expected-outputs]
[--ncpus NCPUS] [--print-commands-only] [--stage STAGE]
[--version]
bids_dir output_dir
The Developmental Cognition and Neuroimaging (DCAN) lab fMRI Pipeline [1].
This BIDS application initiates a functional MRI processing pipeline built
upon the Human Connectome Project's minimal processing pipelines [2]. The
application requires only a dataset conformed to the BIDS specification, and
little-to-no additional configuration on the part of the user. BIDS format
and applications are explained in detail at http://bids.neuroimaging.io/
positional arguments:
bids_dir path to the input bids dataset root directory. Read
more about bids format in the link in the description.
It is recommended to use the dcan bids gui or dcm2bids
to convert from participant dicoms to bids.
output_dir path to the output directory for all intermediate and
output files from the pipeline, also path in which
logs are stored.
optional arguments:
-h, --help show this help message and exit
--aseg PATH specify path to the aseg file to be used by
FreeSurfer. If this flag is used and the segmentation
is successfully mounted, the pipeline will skip running
joint label fusion and instead copy the externally provided
segmentation into the PreFreeSurfer outputs here:
/files/T1w/aseg_acpc.nii.gz.
Default: aseg generated by PreFreeSurfer.
--atropos-mask-method {REFINE,CREATE,NONE}
We create a mask (T1w_acpc_brain_mask.nii.gz) near the
top of PreFreeSurfer. Later, we refine the mask using
atropos. In some cases we just want to use the mask
that atropos creates during the refinement step to
overwrite the original mask. To do that, set this
option to CREATE. Other times, we may want to keep the
mask as-is, in which case, use NONE. Tip: for neos,
use REFINE; for older babies (8+?) use CREATE.
Default: REFINE.
--atropos-range LOWER UPPER
range to be used for atropos labeling. Defaults: 4 and
5.
--bandstop LOWER UPPER
parameters for motion regressor band-stop filter in bpm
(not Hz). It is recommended for the boundaries to match
the inter-quartile range for participant group respiratory
rate (bpm), or to match bids physio data directly [3].
These parameters are highly recommended for data
acquired with a frequency of approx. 1 Hz or more
(TR<=1.0). Default: no filter
--dcmethod {TOPUP,FIELDMAP,T2_DC,NONE}
specify a distortion correction method. Default: use
auto-detection.
--freesurfer-license PATH
If using docker or singularity, you will need to
acquire and provide your own FreeSurfer license. The
license can be acquired by filling out this form:
https://surfer.nmr.mgh.harvard.edu/registration.html
--hyper-normalization-method {ADULT_GM_IP,ROI_IPS,NONE}
specify the intensity profiles to use for the hyper-
normalization step in FreeSurfer: ADULT_GM_IP adjusts
the entire base image such that the IP of GM in the
target roughly matches the IP of GM of the reference
(i.e., the adult freesurfer atlas). Then the WM is
shifted in the target image to match the histogram of
WM in the reference. ROI_IPS adjusts the intensity
profiles of each ROI (GM, WM, CSF) separately and
reassembles the parts. NONE skips hyper-normalization
step. This allows the user to run PreFreeSurfer, apply
new, experimental hyper-normalization methods and then
restart at FreeSurfer. Default: ADULT_GM_IP.
--jlf-method {T1W,T2W,T1W_ORIG}
specify method to use to perform joint label fusion
Default: T1W.
--max-cortical-thickness MM
maximum cortical thickness to allow in FreeSurfer.
Default: 5 mm.
--motion-control-frame FRAME, --mc-frame FRAME
frame to be used when computing motion-control values.
This choosing different frames to see what works best
for a run. In future, will add an algorithm to
determine best frame(s). Default: 17
--multi-masking-dir PATH
directory for joint label fusion masks.
--multi-template-dir PATH
directory for joint label fusion templates. It should
contain only folders which each contain a
"T1w_brain.nii.gz" and a "Segmentation.nii.gz". Each
subdirectory may have any name and any number of
additional files.
--no-crop alignment in PreFreeSurfer does neck/shoulder
cropping. Some images do not have neck and shoulders,
so do not want this cropping to happen. This option
allows user to turn that off.
--participant-label LABEL [LABEL ...]
optional list of participant ids to run. Default is
all ids found under the bids input directory. A
participant label does not include "sub-"
--session-id [LABEL [LABEL ...]]
filter input dataset by session id. Default is all ids
found under the subject input directory(s). A session
id does not include "ses-"
--smoothing-iterations ITERATIONS
Tell FreeSurfer how many smoothing iterations to run.
Default: 10 iterations.
--subcortical-map-method {ROI_MAP,MNI_AFFINE}
specify method to use to align subcorticals. Default:
ROI_MAP.
--T1-brain-mask PATH specify the path to the mask file. The file specified
must be aligned with the T1w image. The mask will
first be copied into the T1w folder as
T1w_brain_mask.nii.gz. It will then be ACPC aligned,
using the matrix generated when aligning the T1w
image. The result will be written to
T1w/T1w_acpc_brain_mask.nii.gz. Tip: when supplying a
brain-mask, you may want to set --atropos-mask-method
to NONE. Default: mask generated by PreFreeSurfer.
--t1-study-template HEAD BRAIN
T1w template head and brain images for intermediate
nonlinear registration, effective where population
differs greatly from average adult, e.g. in elderly
populations with large ventricles.
--t2-study-template HEAD BRAIN
T2w template head and brain images for intermediate
nonlinear registration, effective where population
differs greatly from average adult, e.g. in elderly
populations with large ventricles.
special pipeline options:
options which pertain to an alternative pipeline or an extra stage.
--anat-only, --ignore-func
Ignore functional files (process anatomy files only).
This option must be set in order to process subjects
for which no functional data was collected.
--custom-clean PATH runs dcan cleaning script after the pipeline completes
successfully, to delete pipeline outputs based on the
file structure specified in the custom-clean json.
--file-mapper-json PATH
runs dcan file-mapper after the pipeline completes
successfully, to copy pipeline outputs to BIDS-
formatted derivatives files based on the file-mapper
json.
runtime options:
Run-time instructions. These options are not passed to the stages. Rather, they control what and how the pipeline is run.
--check-outputs-only checks for the existence of outputs for each stage
then exit. Useful for debugging.
--ignore-expected-outputs
continues pipeline even if some expected outputs are
missing.
--ncpus NCPUS number of cores to use for concurrent processing and
algorithmic speedups. Warning: causes ANTs and
FreeSurfer to produce non-deterministic results.
Default: 1.
--print-commands-only
print run commands for each stage to shell then exit.
--stage STAGE, --stages STAGE
specify a subset of stages to run.If a single stage
name is given, the pipeline with be started at that
stage. If a string with a ":" is given, a stage name
before the ":" will tell run.py where to start and a
stage name after the ":" will tell it where to stop.
If no ":" is found, the pipeline will start with the
stage specified and run to the end. Calling run.py
with: --stage="PreFreeSurfer:PreFreeSurfer" or with:
--stage=":PreFreeSurfer" will cause only PreFreeSurfer
to be run. (This can be useful to do optional
processing betweenPreFreeSurfer and
FreeSurfer.)Calling run.py with:
--stages="FreeSurfer:FMRISurface" will start with
stage FreeSurfer and stop afterFMRISurface (before
DCANBOLDProcessing).Default start is PreFreeSurfer and
default stop is ExecutiveSummary. The specifications:
--stages="PreFreeSurfer:ExecutiveSummary"
--stages=":ExecutiveSummary" --stages="PreFreeSurfer:"
are exactly identical to each other and to sending no
--stage argument. Valid stage names: PreFreeSurfer,
FreeSurfer, PostFreeSurfer, FMRIVolume, FMRISurface,
DCANBOLDProcessing, ExecutiveSummary
--version, -v show program's version number and exit
References
----------
[1] dcan-pipelines (for now, please cite [3] in use of this software)
[2] Glasser, MF. et al. The minimal preprocessing pipelines for the Human
Connectome Project. Neuroimage. 2013 Oct 15;80:105-24.
10.1016/j.neuroimage.2013.04.127
[3] Fair, D. et al. Correction of respiratory artifacts in MRI head motion
estimates. Biorxiv. 2018 June 7. doi: https://doi.org/10.1101/337360
[4] Dale, A.M., Fischl, B., Sereno, M.I., 1999. Cortical surface-based
analysis. I. Segmentation and surface reconstruction. Neuroimage 9, 179-194.
[5] M. Jenkinson, C.F. Beckmann, T.E. Behrens, M.W. Woolrich, S.M. Smith. FSL.
NeuroImage, 62:782-90, 2012
[6] Avants, BB et al. The Insight ToolKit image registration framework. Front
Neuroinform. 2014 Apr 28;8:44. doi: 10.3389/fninf.2014.00044. eCollection 2014.
Running all subjects from a BIDS dataset:
docker run --rm \
-v <path to bids_dataset>:/bids_input:ro \
-v <path to outputs>:/output \
-v <path to freesurfer license.txt>:/opt/freesurfer/license.txt \
dcanlabs/infant-abcd-bids-pipeline /bids_input /output
Running a single subject from the dataset:
docker run --rm \
-v <path to bids_dataset>:/bids_input:ro \
-v <path to outputs>:/output \
-v <path to freesurfer license.txt>:/opt/freesurfer/license.txt \
dcanlabs/infant-abcd-bids-pipeline /bids_input /output --participant-label <label>
Running with different templates:
Babies of different ages require different templates. The templates included in the Docker image are for neonates (0-2 months). To use different templates, just mount them to the location at which the pileline expects them:
docker run --rm \
-v <path to bids_dataset>:/bids_input:ro \
-v <path to outputs>:/output \
-v <path to freesurfer license.txt>:/opt/freesurfer/license.txt \
-v <path to baby_templates folder>:/opt/pipeline/global/templates
dcanlabs/infant-abcd-bids-pipeline /bids_input /output
Note that the mount flag "-v" follows "docker run", as it is a docker option, whereas the "--participant-label" flag follows "infant-abcd-bids-pipeline", as it is an option passed into this pipeline.
The outputs are organized in the following structure:
.
└── sub-<id>
└── ses-<id>
├── files
│ ├── ...
│ ├── MNINonLinear
│ ├── ses-<id>_task-rest_run-01
│ ├── ses-<id>_task-rest_run-02
│ ├── summary_DCANBOLDProc
│ ├── T1w
│ ├── T2w
│ └── ...
└── logs
├── DCANBOLDProcessing
├── ExecutiveSummary
├── FMRISurface
├── FMRIVolume
├── FreeSurfer
├── PostFreeSurfer
└── PreFreeSurfer
- MNINonLinear: contains the final space results of anatomy in 164k resolution.
- MNINonLinear/Results: final space functional data.
- MNINonLinear/fsaverage_32K: final space anatomy in 32k resolution, where functional data is ultimately projected.
- ses-_task-_run-: these folders contain intermediate functional preprocessing files.
- summary_DCANBOLDProc/executive_summary: the .html file within can be opened for quality inspection of pipeline results.
- T1w and T2w: contain native space anatomical data as well as intermediate preprocessing files.
- T1w/: The participant ID folder within T1w is the FreeSurfer subject folder.
The logs folder contains a folder of log files for each stage. In the case of an error consult these files in addition to the standard err/out of the pipeline itself.
- unchecked: 999
- succeeded: 1
- incomplete: 2
- failed: 3
- not started: 4
The --stage option exists so you can restart the pipeline in the case that it terminated prematurely. The name of the stage will correspond exactly (in spelling and in case) to the name of the logs folder for the stage that failed.
NOTE Not all arguments are used in all stages. For example, the bandstop min and max values are used for motion correction in the DCANBOLDProcessing stage, but not in any others. So, if you re-start the pipeline from ExectiveSummary with different bandstop values, the output will not change. Or if you run the pipeline multiple times with --anat-only, using different bandstop values will not change any results, since --anat-only runs only PreFreeSurfer, FreeSurfer, and PostFreeSurfer (anatomy) stages.
The pipeline may take over 36 hours if using too few cores. Most fMRI processing can be done in parallel. It is recommended to use 10 cores and allow for at least 4 GB of memory per core to be safe.