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 a BOLD series (unless using the --anat-only flag).

We highly recommend that you validate your dataset with the free, online BIDS Validator.

Participant Ages¶

NiBabies will attempt to automatically extract participant ages (in months) from the BIDS layout. Specifically, these two files will be checked:

Sessions file: <bids-root>/<subject>/subject_sessions.tsv
Participants file: <bids-root>/participants.tsv

Either file should include age (or if you wish to be more explicit: age_months) columns, and it is recommended to have an accompanying JSON file to further describe these fields, and explicitly state the values are in months.

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.

Example command¶

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-label 01

Further information about BIDS and BIDS-Apps can be found at the NiPreps portal.

Command-Line Arguments¶

NiBabies: Preprocessing workflows for infants v24.0.1

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]
                [-d PACKAGE=PATH [PACKAGE=PATH ...]]
                [--bids-database-dir PATH] [--copy-derivatives]
                [--nprocs NPROCS] [--omp-nthreads OMP_NTHREADS]
                [--mem MEMORY_GB] [--low-mem] [--use-plugin FILE]
                [--md-only-boilerplate] [-v] [--anat-only]
                [--level {minimal,resampling,full}] [--boilerplate-only]
                [--reports-only]
                [--ignore {fieldmaps,slicetiming,sbref,t1w,t2w,flair,fmap-jacobian} [{fieldmaps,slicetiming,sbref,t1w,t2w,flair,fmap-jacobian} ...]]
                [--longitudinal] [--output-spaces [OUTPUT_SPACES ...]]
                [--me-output-echos] [--bold2t1w-init {register,header}]
                [--bold2t1w-dof {6,9,12}]
                [--bold2anat-init {auto,t1w,t2w,header}]
                [--bold2anat-dof {6,9,12}] [--force-bbr] [--force-no-bbr]
                [--medial-surface-nan] [--project-goodvoxels]
                [--slice-time-ref SLICE_TIME_REF] [--dummy-scans DUMMY_SCANS]
                [--random-seed _RANDOM_SEED]
                [--me-t2s-fit-method {curvefit,loglin}]
                [--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-anat {auto,skip,force}] [--fmap-bspline]
                [--fmap-no-demean] [--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]
                [--config-file FILE] [--write-graph] [--stop-on-first-crash]
                [--notrack]
                [--debug {compcor,registration,fieldmaps,pdb,all} [{compcor,registration,fieldmaps,pdb,all} ...]]
                [--sloppy] [--age-months AGE_MONTHS]
                [--segmentation-atlases-dir SEGMENTATION_ATLASES_DIR]
                [--fd-radius FD_RADIUS] [--deriv-filter-file FILE]
                [--force-reconall]
                [--surface-recon-method {infantfs,freesurfer,mcribs,auto}]
                [--reference-anat {T1w,T2w}] [--hmc-bold-frame HMC_BOLD_FRAME]
                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
-d, --derivatives: Search PATH(s) for pre-computed derivatives. These may be provided as named folders (e.g., –derivatives smriprep=/path/to/smriprep).
--bids-database-dir: Path to an existing PyBIDS database folder, for faster indexing (especially useful for large datasets).
--copy-derivatives: Copy any found derivatives into output directory

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

--md-only-boilerplate

skip generation of HTML and LaTeX formatted citation with pandoc

-v, --verbose

increases log verbosity for each occurrence, debug level is -vvv

Default: 0

Options for performing only a subset of the workflow¶

--anat-only

Run anatomical workflows only

--level

Possible choices: minimal, resampling, full

Processing level; may be ‘minimal’ (nothing that can be recomputed), ‘resampling’ (recomputable targets that aid in resampling) or ‘full’ (all target outputs).

Default: 'full'

--boilerplate-only, --boilerplate_only

Generate boilerplate only

--reports-only

Only generate reports, don’t run workflows. This will only rerun report aggregation, not reportlet generation for specific nodes.

Workflow configuration¶

--ignore

Possible choices: fieldmaps, slicetiming, sbref, t1w, t2w, flair, fmap-jacobian

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, the res-* 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

Deprecated - use –bold2anat-init instead.

--bold2t1w-dof

Possible choices: 6, 9, 12

Deprecated - use –bold2anat-dof instead.

--bold2anat-init

Possible choices: auto, t1w, t2w, header

Method of initial BOLD to anatomical coregistration. If auto, a T2w image is used if available, otherwise the T1w image. t1w forces use of the T1w, t2w forces use of the T2w, and header uses the BOLD header information without an initial registration.

Default: 'auto'

--bold2anat-dof

Possible choices: 6, 9, 12

Degrees of freedom when registering BOLD to anatomical 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).

--project-goodvoxels

Exclude voxels whose timeseries have locally high coefficient of variation from surface resampling. 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

--me-t2s-fit-method

Possible choices: curvefit, loglin

The method by which to estimate T2* and S0 for multi-echo data. ‘curvefit’ uses nonlinear regression. It is more memory intensive, but also may be more accurate, than ‘loglin’. ‘loglin’ uses log-linear regression. It is faster and less memory intensive, but may be less accurate.

Default: 'curvefit'

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-anat

Possible choices: auto, skip, force

determiner for anatomical 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

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/24.0.1/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

--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, pdb, 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

--deriv-filter-file

A JSON file for customizing the derivatives queries.

--force-reconall

Force traditional FreeSurfer surface reconstruction.

--surface-recon-method

Possible choices: infantfs, freesurfer, mcribs, auto

Method to use for surface reconstruction

Default: 'auto'

--reference-anat, --reference-anatomical

Possible choices: T1w, T2w

Override which anatomical to use as the structural reference. Generally, this is determined based on availability, age, and surface reconstruction method.

--hmc-bold-frame

Frame to start head motion estimation on BOLD.

Default: 16

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 be participant.

However, as infant brains can vastly differ depending on age, providing the following arguments is highly recommended:

--participant-label - participant ID
--session-id - session ID
--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 --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:23.0.0 /data /out participant
...

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 -i nibabies-23.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-23.0.0.sif /data /out participant
...

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.

Usage¶

The BIDS format¶

Participant Ages¶

The FreeSurfer license¶

Example command¶

Command-Line Arguments¶

Positional Arguments¶

Named Arguments¶

Options for filtering BIDS queries¶

Options to handle performance¶

Options for performing only a subset of the workflow¶

Workflow configuration¶

Specific options for estimating confounds¶

Specific options for ANTs registrations¶

Specific options for handling fieldmaps¶

Specific options for SyN distortion correction¶

Specific options for FreeSurfer preprocessing¶

Surface preprocessing options¶

Other options¶

NiBabies specific options¶

More information on command-line arguments¶

Using the nibabies wrapper¶

Sample Docker usage¶

Sample Singularity usage¶

The command-line interface of the nibabies wrapper¶