Usage
The BIDS format
The NiBabies workflow takes as principal input the path of the dataset that is to be processed. The input dataset is required to be in valid BIDS format, and it must include at least one T1-weighted and one T2-weighted structural image and (unless disabled with a flag) a BOLD series. We highly recommend that you validate your dataset with the free, online BIDS Validator.
The exact command to run NiBabies depends on the Installation method. The common parts of the command follow the BIDS-Apps definition. Example:
$ nibabies data/bids_root/ out/ participant -w work/ --participant-id 01 --age-months 12
Further information about BIDS and BIDS-Apps can be found at the NiPreps portal.
The FreeSurfer license
NiBabies uses FreeSurfer tools, which require a license to run.
To obtain a FreeSurfer license, simply register for free at https://surfer.nmr.mgh.harvard.edu/registration.html.
FreeSurfer will search for a license key file first using the $FS_LICENSE
environment variable and then in the default path to the license key file ($FREESURFER_HOME
/license.txt). If $FS_LICENSE
is set, the nibabies-wrapper
will automatically handle setting the license within the container.
Otherwise, you will need to use the --fs-license-file
flag to ensure the license is available.
Command-Line Arguments
NiBabies: Preprocessing workflows for infants v22.1.2
usage: nibabies [-h] [--version] [--skip_bids_validation]
[--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
[-s SESSION_ID [SESSION_ID ...]] [-t TASK_ID]
[--echo-idx ECHO_IDX] [--bids-filter-file FILE]
[--anat-derivatives PATH] [--bids-database-dir PATH]
[--nprocs NPROCS] [--omp-nthreads OMP_NTHREADS]
[--mem MEMORY_GB] [--low-mem] [--use-plugin FILE]
[--anat-only] [--boilerplate_only] [--md-only-boilerplate]
[--error-on-aroma-warnings] [-v]
[--ignore {fieldmaps,slicetiming,sbref,t2w,flair} [{fieldmaps,slicetiming,sbref,t2w,flair} ...]]
[--longitudinal]
[--output-spaces [OUTPUT_SPACES [OUTPUT_SPACES ...]]]
[--me-output-echos] [--bold2t1w-init {register,header}]
[--bold2t1w-dof {6,9,12}] [--force-bbr] [--force-no-bbr]
[--medial-surface-nan] [--slice-time-ref SLICE_TIME_REF]
[--dummy-scans DUMMY_SCANS] [--random-seed _RANDOM_SEED]
[--use-aroma]
[--aroma-melodic-dimensionality AROMA_MELODIC_DIM]
[--return-all-components]
[--fd-spike-threshold REGRESSORS_FD_TH]
[--dvars-spike-threshold REGRESSORS_DVARS_TH]
[--skull-strip-template SKULL_STRIP_TEMPLATE]
[--skull-strip-fixed-seed]
[--skull-strip-t1w {auto,skip,force}] [--fmap-bspline]
[--fmap-no-demean] [--topup-max-vols TOPUP_MAX_VOLS]
[--use-syn-sdc] [--force-syn] [--fs-license-file FILE]
[--fs-subjects-dir PATH] [--no-submm-recon]
[--cifti-output [{91k,170k}] | --fs-no-reconall]
[--output-layout {bids,legacy}] [-w WORK_DIR]
[--clean-workdir] [--resource-monitor] [--reports-only]
[--config-file FILE] [--write-graph] [--stop-on-first-crash]
[--notrack]
[--debug {compcor,registration,fieldmaps,all} [{compcor,registration,fieldmaps,all} ...]]
[--sloppy] [--age-months AGE_MONTHS]
[--segmentation-atlases-dir SEGMENTATION_ATLASES_DIR]
[--fd-radius FD_RADIUS] [-d DERIVATIVES [DERIVATIVES ...]]
[--deriv-filter-file FILE] [--force-reconall]
bids_dir output_dir {participant}
Positional Arguments
- bids_dir
the root folder of a BIDS valid dataset (sub-XXXXX folders should be found at the top level in this folder).
- output_dir
the output path for the outcomes of preprocessing and visual reports
- analysis_level
Possible choices: participant
processing stage to be run, only “participant” in the case of NiBabies (see BIDS-Apps specification).
Named Arguments
- --version
show program’s version number and exit
Options for filtering BIDS queries
- --skip_bids_validation, --skip-bids-validation
assume the input dataset is BIDS compliant and skip the validation
- --participant-label, --participant_label
a space delimited list of participant identifiers or a single identifier (the sub- prefix can be removed)
- -s, --session-id
a space delimited list of session identifiers or a single identifier
- -t, --task-id
select a specific task to be processed
- --echo-idx
select a specific echo to be processed in a multiecho series
- --bids-filter-file
a JSON file describing custom BIDS input filters using PyBIDS. For further details, please check out https://fmriprep.readthedocs.io/en/latest/faq.html#how-do-I-select-only-certain-files-to-be-input-to-fMRIPrep
- --anat-derivatives
Reuse the anatomical derivatives from another NiBabies run or calculated with an alternative processing tool (NOT RECOMMENDED).
- --bids-database-dir
Path to an existing PyBIDS database folder, for faster indexing (especially useful for large datasets).
Options to handle performance
- --nprocs, --nthreads, --n_cpus, --n-cpus
maximum number of threads across all processes
- --omp-nthreads
maximum number of threads per-process
- --mem, --mem_mb, --mem-mb
upper bound memory limit for NiBabies processes
- --low-mem
attempt to reduce memory usage (will increase disk usage in working directory)
- --use-plugin, --nipype-plugin-file
nipype plugin configuration file
- --anat-only
run anatomical workflows only
- --boilerplate_only
generate boilerplate only
- --md-only-boilerplate
skip generation of HTML and LaTeX formatted citation with pandoc
- --error-on-aroma-warnings
Raise an error if ICA_AROMA does not produce sensible output (e.g., if all the components are classified as signal or noise)
- -v, --verbose
increases log verbosity for each occurence, debug level is -vvv
Default: 0
Workflow configuration
- --ignore
Possible choices: fieldmaps, slicetiming, sbref, t2w, flair
ignore selected aspects of the input dataset to disable corresponding parts of the workflow (a space delimited list)
Default: []
- --longitudinal
treat dataset as longitudinal - may increase runtime
- --output-spaces
Standard and non-standard spaces to resample anatomical and functional images to. Standard spaces may be specified by the form
<SPACE>[:cohort-<label>][:res-<resolution>][...]
, where<SPACE>
is a keyword designating a spatial reference, and may be followed by optional, colon-separated parameters. Non-standard spaces imply specific orientations and sampling grids. Important to note, theres-*
modifier does not define the resolution used for the spatial normalization. To generate no BOLD outputs, use this option without specifying any spatial references. For further details, please check out https://fmriprep.readthedocs.io/en/latest/spaces.html- --me-output-echos
Output individual echo time series with slice, motion and susceptibility correction. Useful for further Tedana processing post-NiBabies.
- --bold2t1w-init
Possible choices: register, header
Either “register” (the default) to initialize volumes at center or “header” to use the header information when coregistering BOLD to T1w images.
Default: “register”
- --bold2t1w-dof
Possible choices: 6, 9, 12
Degrees of freedom when registering BOLD to T1w images. 6 degrees (rotation and translation) are used by default.
Default: 6
- --force-bbr
Always use boundary-based registration (no goodness-of-fit checks)
- --force-no-bbr
Do not use boundary-based registration (no goodness-of-fit checks)
- --medial-surface-nan
Replace medial wall values with NaNs on functional GIFTI files. Only performed for GIFTI files mapped to a freesurfer subject (fsaverage or fsnative).
- --slice-time-ref
The time of the reference slice to correct BOLD values to, as a fraction acquisition time. 0 indicates the start, 0.5 the midpoint, and 1 the end of acquisition. The alias start corresponds to 0, and middle to 0.5. The default value is 0.5.
- --dummy-scans
Number of non steady state volumes.
- --random-seed
Initialize the random seed for the workflow
Specific options for running ICA_AROMA
- --use-aroma
add ICA_AROMA to your preprocessing stream
- --aroma-melodic-dimensionality
Exact or maximum number of MELODIC components to estimate (positive = exact, negative = maximum)
Default: -200
Specific options for estimating confounds
- --return-all-components
Include all components estimated in CompCor decomposition in the confounds file instead of only the components sufficient to explain 50 percent of BOLD variance in each CompCor mask
- --fd-spike-threshold
Threshold for flagging a frame as an outlier on the basis of framewise displacement
Default: 0.5
- --dvars-spike-threshold
Threshold for flagging a frame as an outlier on the basis of standardised DVARS
Default: 1.5
Specific options for ANTs registrations
- --skull-strip-template
select a template for skull-stripping with antsBrainExtraction
Default: UNCInfant:cohort-1
- --skull-strip-fixed-seed
do not use a random seed for skull-stripping - will ensure run-to-run replicability when used with –omp-nthreads 1 and matching –random-seed <int>
- --skull-strip-t1w
Possible choices: auto, skip, force
determiner for T1-weighted skull stripping (‘force’ ensures skull stripping, ‘skip’ ignores skull stripping, and ‘auto’ applies brain extraction based on the outcome of a heuristic to check whether the brain is already masked).
Default: “force”
Specific options for handling fieldmaps
- --fmap-bspline
fit a B-Spline field using least-squares (experimental)
- --fmap-no-demean
do not remove median (within mask) from fieldmap
- --topup-max-vols
maximum number of volumes to use with TOPUP, per-series (EPI or BOLD)
Default: 5
Specific options for SyN distortion correction
- --use-syn-sdc
EXPERIMENTAL: Use fieldmap-free distortion correction
- --force-syn
EXPERIMENTAL/TEMPORARY: Use SyN correction in addition to fieldmap correction, if available
Specific options for FreeSurfer preprocessing
- --fs-license-file
Path to FreeSurfer license key file. Get it (for free) by registering at https://surfer.nmr.mgh.harvard.edu/registration.html
- --fs-subjects-dir
Path to existing FreeSurfer subjects directory to reuse. (default: OUTPUT_DIR/freesurfer)
Surface preprocessing options
- --no-submm-recon
disable sub-millimeter (hires) reconstruction
- --cifti-output
Possible choices: 91k, 170k
output preprocessed BOLD as a CIFTI dense timeseries. Optionally, the number of grayordinate can be specified (default is 91k, which equates to 2mm resolution)
Default: False
- --fs-no-reconall
disable FreeSurfer surface preprocessing.
Other options
- --output-layout
Possible choices: bids, legacy
Organization of outputs. bids (default) places NiBabies derivatives directly in the output directory, and defaults to placing FreeSurfer derivatives in <output-dir>/sourcedata/freesurfer. legacy creates derivative datasets as subdirectories of outputs.
Default: “bids”
- -w, --work-dir
path where intermediate results should be stored
Default: /home/docs/checkouts/readthedocs.org/user_builds/nibabies/checkouts/22.1.2/docs/work
- --clean-workdir
Clears working directory of contents. Use of this flag is notrecommended when running concurrent processes of NiBabies.
- --resource-monitor
enable Nipype’s resource monitoring to keep track of memory and CPU usage
- --reports-only
only generate reports, don’t run workflows. This will only rerun report aggregation, not reportlet generation for specific nodes.
- --config-file
Use pre-generated configuration file. Values in file will be overridden by command-line arguments.
- --write-graph
Write workflow graph.
- --stop-on-first-crash
Force stopping on first crash, even if a work directory was specified.
- --notrack
Opt-out of sending tracking information of this run to the NiBabies developers. This information helps to improve NiBabies and provides an indicator of real world usage crucial for obtaining funding.
- --debug
Possible choices: compcor, registration, fieldmaps, all
Debug mode(s) to enable. ‘all’ is alias for all available modes.
- --sloppy
Use low-quality tools for speed - TESTING ONLY
NiBabies specific options
- --age-months
Age in months
- --segmentation-atlases-dir
Directory containing precalculated segmentations to use for JointLabelFusion.
- --fd-radius
Head radius in mm for framewise displacement calculation.
Default: 45
- -d, --derivatives
One or more directory containing pre-computed derivatives.
- --deriv-filter-file
A JSON file for customizing the derivatives queries.
- --force-reconall
Force traditional FreeSurfer surface reconstruction.
More information on command-line arguments
At minimum, the following positional arguments are required.
bids_dir
- the root folder of a BIDS valid dataset.output_dir
- folder to store outputs and reports.level
- processing stage to be run, currently can only beparticipant
.
However, as infant brains can vastly differ depending on age, providing the following arguments is highly recommended:
--age-months
- participant age in months
Warning
This is required if FreeSurfer is not disabled (--fs-no-reconall
)
--participant-id
- participant ID
Tip
This is recommended when using --age-months
if age varies across participants.
--segmentation-atlases-dir
- directory containing pre-labeled segmentations to use for Joint Label Fusion.
Tip
The segmentation directory layout should consist of one or more template directories containing:
A segmented and labeled NIfTI that includes
Segmentation
in the filename.A brainmasked T1w NIfTI that includes
T1w
in the filename.
Using the nibabies wrapper
The wrapper will generate a Docker or Singularity command line for you, print it out for reporting purposes, and then execute it without further action needed. For installation instructions, please see Installing the nibabies-wrapper
Sample Docker usage
$ nibabies-wrapper docker /path/to/data /path/to/output participant --age-months 12 --fs-license-file /usr/freesurfer/license.txt
RUNNING: docker run --rm -e DOCKER_VERSION_8395080871=20.10.6 -it -v /path/to/data:/data:ro \
-v /path/to/output:/out -v /usr/freesurfer/license.txt:/opt/freesurfer/license.txt:ro \
nipreps/nibabies:21.0.0 /data /out participant --age-months 12
...
Docker usage warning
When using Docker, the wrapper will default to using the same version of nibabies
as the wrapper.
This can be overridden by using the -i
flag to specify a particular Docker image.
Sample Singularity usage
$ nibabies-wrapper singularity /path/to/data /path/to/output participant --age-months 12 -i nibabies-21.0.0.sif --fs-license-file /usr/freesurfer/license.txt
RUNNING: singularity run --cleanenv -B /path/to/data:/data:ro \
-B /path/to/output:/out -B /usr/freesurfer/license.txt:/opt/freesurfer/license.txt:ro \
nibabies-21.0.0.sif /data /out participant --age-months 12
...
Singularity usage warning
Note that the -i
flag is required when using Singularity, and should be the path to the already built Singularity image file.
The command-line interface of the nibabies wrapper
This is a Python wrapper to facilitate running NiBabies through Docker or Singularity services. Docker or Singularity must be installed and running. To test installation, you can use one of the following:
docker info
singularity version
Please report any feedback to our GitHub repository (https://github.com/nipreps/nibabies) and do not forget to credit all the authors of service that NiBabies uses (https://fmriprep.readthedocs.io/en/latest/citing.html).
usage: nibabies-wrapper [-h] [--version] [-i IMG] [-w WORK_DIR]
[--output-spaces [OUTPUT_SPACES [OUTPUT_SPACES ...]]]
[--fs-license-file PATH] [--fs-subjects-dir PATH]
[--config-file PATH] [--anat-derivatives PATH]
[--use-plugin PATH] [--bids-database-dir PATH]
[--segmentation-atlases-dir PATH]
[--derivatives PATH [PATH ...]]
[--bids-filter-file PATH] [--deriv-filter-file PATH]
[--patch PACKAGE=PATH [PACKAGE=PATH ...]] [--shell]
[--config PATH] [-e ENV_VAR value] [-u USER]
[--network NETWORK] [--no-tty]
[{docker,singularity}] [bids_dir] [output_dir]
[{participant}]
Positional Arguments
- service
Possible choices: docker, singularity
- bids_dir
- output_dir
- analysis_level
Possible choices: participant
Named Arguments
- -h, --help
show this help message and exit
- --version
show program’s version number and exit
- -i, --image
image name
Wrapper options
Standard options that require mapping files into the container
- -w, --work-dir
path where intermediate results should be stored
- --output-spaces
Standard and non-standard spaces to resample anatomical and functional images to. Standard spaces may be specified by the form
<TEMPLATE>[:res-<resolution>][:cohort-<label>][...]
, where<TEMPLATE>
is a keyword (valid keywords: “MNI152Lin”, “MNI152NLin2009cAsym”, “MNI152NLin6Asym”, “MNI152NLin6Sym”, “MNIInfant”, “MNIPediatricAsym”, “NKI”, “OASIS30ANTs”, “PNC”, “UNCInfant”, “fsLR”, “fsaverage”, “fsaverage5”, “fsaverage6”) or path pointing to a user-supplied template, and may be followed by optional, colon-separated parameters. Non-standard spaces (valid keywords: anat, T1w, run, func, sbref, fsnative) imply specific orientations and sampling grids. Important to note, theres-*
modifier does not define the resolution used for the spatial normalization.- --fs-license-file
Path to FreeSurfer license key file. Get it (for free) by registering at https://surfer.nmr.mgh.harvard.edu/registration.html
- --fs-subjects-dir
Path to existing Infant FreeSurfer subjects directory to reuse.
- --config-file
Use pre-generated configuration file. Values in file will be overridden by command-line arguments.
- --anat-derivatives
Path to existing NiBabies anatomical derivatives to fasttrack the anatomical workflow.
- --use-plugin
nipype plugin configuration file
- --bids-database-dir
Path to an existing PyBIDS database folder, for faster indexing (especially useful for large datasets).
- --segmentation-atlases-dir
Directory containing prelabeled segmentations to use for JointLabelFusion.
- --derivatives
One or more directory containing pre-computed derivatives
- --bids-filter-file
Filter file
- --deriv-filter-file
Filter file
Developer options
Tools for testing and debugging nibabies
- --patch
local repository to use within container
- --shell
open shell in image instead of running nibabies
- --config
Use custom nipype.cfg file
- -e, --env
Set custom environment variable within container
- -u, --user
Run container as a given user/uid. Additionally, group/gid can beassigned, (i.e., –user <UID>:<GID>)
- --network
Run container with a different network driver (“none” to simulate no internet connection)
- --no-tty
Run docker without TTY flag -it