nibabies (`CBRAIN Tool Config ID: 7838 <https://portal.cbrain.mcgill.ca/tool_configs/7838/boutiques_descriptor.json>`_)
------------------------------------------------------------------------------------------------------------------------

* **Container**: docker://nipreps/nibabies:25.0.0rc1
* **Documentation**: https://nibabies.readthedocs.io/
* **Boutiques Descriptor**: https://portal.cbrain.mcgill.ca/tool_configs/7838/boutiques_descriptor.json
* **name**: nibabies
* **description**: NiBabies is an open-source software pipeline designed to process anatomical and functional magnetic resonance imaging data.


External Requirements
*********************

These are file-based requirements, external to the pipeline, that must be satisfied for processing to occur.
The "Argument IDs" field corresponds to input "id"s within the tool Boutiques Descriptor. "Value"s correspond
to either specific configuration files (if there is a numeric value), or otherwise broader file types
within CBRAIN (if the entry is text-based).

.. list-table::
   :header-rows: 1

   * - Argument ID
     - Flag
     - Value
     - Description
   * - subject\_dir
     - n/a
     - BidsSubject
     - Subject folder for BIDS (folders name should be sub-XXXXX).
   * - cabinet\_output
     - --derivatives
     - BibsnetOutput
     - FileCollection containing CABINET precomputed output.
   * - cabinet\_output\_json
     - n/a
     - 4942229
     - The json descriptor of the CABINET precomputed output.
   * - fs\_license\_file
     - --fs-license-file
     - 4323067
     - Path to FreeSurfer license key file. Get it (for free) by registering at https\://surfer.nmr.mgh.harvard.edu/registration.html


Ancestor Pipelines
******************

This pipeline utilizes outputs from the following pipelines that
are also ran in CBRAIN:

- bibsnet


Other Processing Settings
*************************

These additional settings cover everything outside of files that are used as inputs during processing.
The settings cover numeric values, flags, outputs directories, and other settings that are used to
configure processing.

.. list-table::
   :header-rows: 1

   * - Argument ID
     - Flag
     - Value
     - Description
   * - output\_dir\_name
     - n/a
     - qwerty
     - The name of the output for the outcomes of preprocessing and visual reports. When processing is ran via CBRAIN only subject-specific files/folders will be saved, so the naming of the output folder will not influence the final naming/destination of files/folders.
   * - derivatives\_prefix
     - n/a
     - 
     - Folders to put before the pipeline specific folder. By default this will look like DataProvider/derivatives/PipelineName, where pipeline name is specific to the current pipeline. The provided string must end in /
   * - surface\_recon\_method
     - --surface-recon-method
     - mcribs
     - Method to use for surface reconstruction.
   * - project\_goodvoxels
     - --project-goodvoxels
     - true
     - Remove high variance voxels from surface projection.
   * - cifti\_output
     - --cifti-output
     - 91k
     - Output preprocessed BOLD as a CIFTI dense timeseries. Optionally, the number of grayordinate can be specified (default is 91k, which equates to 2mm resolution). Possible choices 91k, 170k.
   * - output\_spaces
     - --output-spaces
     - MNI152NLin6Asym\:res-2 fsnative anat func
     - 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
   * - dummy\_scans
     - --dummy-scans
     - 4
     - Number of non steady state volumes.
   * - multi\_step\_reg
     - --multi-step-reg
     - true
     - For certain adult templates (MNI152NLin6Asym), perform two step registrations (native -> MNIInfant -> template) and concatenate into a single xfm.
   * - stop\_on\_first\_crash
     - --stop-on-first-crash
     - true
     - Force stopping on first crash, even if a work directory was specified.




Pipeline Outputs
*************************

Following processing, a number of files and folders are identified as outputs
that should be saved for future reference. In the following table the 'Path Relative to
Working Directory' column specifies the location of files that should be saved (with '*'
denoting wildcards). The output location for these files in the final 'DataProvider' is specified
in the 'Path in Output Data Provider' column. In the case of HBCD the [DERIVATIVES_PREFIX]
entry is empty.

.. list-table::
   :header-rows: 1

   * - ID
     - Path Relative to Working Directory
     - Path in Output DataProvider
     - Description
   * - nibabies\_output\_dir
     - [OUTPUT\_DIR]/[SUBJECT\_DIR]
     - [DERIVATIVES\_PREFIX]nibabies
     - This is the directory where the nibabies outputs are to be stored.
   * - freesurfer\_output\_dir
     - [OUTPUT\_DIR]/sourcedata/freesurfer/[SUBJECT\_DIR]\*
     - [DERIVATIVES\_PREFIX]freesurfer
     - This is the directory where the freesurfer-like outputs are to be stored.
   * - mcribs\_output\_dir
     - [OUTPUT\_DIR]/sourcedata/mcribs/[SUBJECT\_DIR]\*
     - [DERIVATIVES\_PREFIX]mcribs
     - This is the directory where the mcribs outputs are to be stored.
   * - nibabies\_html\_report
     - [OUTPUT\_DIR]/[SUBJECT\_DIR]\*.html
     - [DERIVATIVES\_PREFIX]nibabies
     - This is the html report generated by nibabies.



Command Line Template
*********************

The following code-snippet highlights how the tool is referenced on the command-line.
The code being displayed is executed within the tool's container. Some of the directives
may describe file manipulations to prepare for processing, and other directives will describe
the primary processing command. At the time of processing, the text in brackets will be replaced
by text that has been provided to configure processing. ::

   true [DERIVATIVES_PREFIX]; nibabies [SUBJECT_DIR] [OUTPUT_DIR] participant --skip_bids_validation [TASK_ID] [SESSION_ID] [ECHO_IDX] [ANAT_DERIVATIVES_PATH] --nthreads 4 --omp-nthreads 4 --mem_mb 30000 [USE_PLUGIN] [ANAT_ONLY] [BOILERPLATE_ONLY] [MD_ONLY_BOILERPLATE] [VERBOSE] [IGNORE] [LONGITUDINAL] [OUTPUT_SPACES] [ME_OUTPUT_ECHOS] [BOLD2ANAT_INIT] [BOLD2ANAT_DOF] [FORCE_BBR] [FORCE_NO_BBR] [MEDIAL_SURFACE_NAN] [SLICE_TIME_REF] [DUMMY_SCANS] [RANDOM_SEED] [RETURN_ALL_COMPONENTS] [FD_SPIKE_THRESHOLD] [DVARS_SPIKE_THRESHOLD] [SKULL_STRIP_TEMPLATE] [SKULL_STRIP_FIXED_SEED] [SKULL_STRIP_ANAT] [FMAP_BSPLINE] [FMAP_NO_DEMEAN] [USE_SYN_SDC] [FORCE_SYN] [FS_LICENSE_FILE] [NO_SUBMM_RECON] [CIFTI_OUTPUT] [FS_NO_RECONALL] --work-dir work [RESOURCE_MONITOR] [REPORTS_ONLY] [CONFIG_FILE] [WRITE_GRAPH] [STOP_ON_FIRST_CRASH] [NOTRACK] [DEBUG] [SLOPPY] [AGE_MONTHS] [SEGMENTATION_ATLASES_DIR] [FD_RADIUS] [CABINET_OUTPUT] [DERIV_FILTER_FILE] [FORCE_RECONALL] [PROJECT_GOODVOXELS] [SURFACE_RECON_METHOD] [COPY_DERIVATIVES] [NORM_CSF] [MULTI_STEP_REG]

File Selection For Processing
*****************************

The first step of selecting a candidate for processing is determining whether
the right files are present. In HBCD processing, pipelines are always run on
one session worth of data at a time. With that in mind, we (mostly) query the
contents of a subject's session folder to determine if processing should occur
and also which files should be included in processing. For every pipeline there will be
at least one requirement group that determines what files are needed for processing to occur. Within
a requirement group, there may be criteria that address multiple file (or modality) types, which are known as 'File Groups'.
For processing to occur, the minumum number of files surviving all Included/Excluded
terms for a given 'File Group' must be satisfied.

To allow for more flexible selection of
files for processing, there are often multiple 'Requirement Groups'. The contents of each 'File Group'
across 'Requirement Groups' must be the same, but which 'File Groups' are defined can be different.
If multiple 'Requirement Groups' are present for the current pipeline, there will be multiple tables
in this section. Only one 'Requirement Group' needs to be satisfied for processing to occur. If one
requirement group is satisfied, then files from all 'File Groups' will be included in processing.

Beyond the files that are chosen from this procedure, other associated files
defined via the table :doc:`here <../associated_files>` will also
be included in processing.

Requirement Group: nibabies_1
~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1

   * - File Group
     - How Many To Keep
     - Term
     - Included (True)/Excluded (False)
   * - T1
     - 1
     - T1w.nii.gz
     - True
   * -   
     -   
     - rec-undistorted
     - False
   * -   
     -   
     - acq-svslocalizer
     - False
   * -   
     -   
     - acq-mrsLoc
     - False
   * -   
     -   
     - \_QALAS.nii.gz
     - False
   * - T2
     - 1
     - T2w.nii.gz
     - True
   * -   
     -   
     - rec-undistorted
     - False
   * -   
     -   
     - acq-svslocalizer
     - False
   * -   
     -   
     - acq-mrsLoc
     - False
   * -   
     -   
     - \_QALAS.nii.gz
     - False
   * - FMRI
     - All
     - bold.nii.gz
     - True
   * -   
     -   
     - rec-undistorted
     - False
   * -   
     -   
     - rec-biascorrected
     - False
   * - AP\_FMAP
     - All
     - epi.nii.gz
     - True
   * -   
     -   
     - dir-AP
     - True
   * - PA\_FMAP
     - All
     - epi.nii.gz
     - True
   * -   
     -   
     - dir-PA
     - True
   * - scans.tsv
     - All
     - scans.tsv
     - True
   * - sessions.tsv
     - All
     - sessions.tsv
     - True


Requirement Group: nibabies_2
~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1

   * - File Group
     - How Many To Keep
     - Term
     - Included (True)/Excluded (False)
   * - T2
     - 1
     - T2w.nii.gz
     - True
   * -   
     -   
     - rec-undistorted
     - False
   * -   
     -   
     - acq-svslocalizer
     - False
   * -   
     -   
     - acq-mrsLoc
     - False
   * -   
     -   
     - \_QALAS.nii.gz
     - False
   * - FMRI
     - All
     - bold.nii.gz
     - True
   * -   
     -   
     - rec-undistorted
     - False
   * -   
     -   
     - rec-biascorrected
     - False
   * - AP\_FMAP
     - All
     - epi.nii.gz
     - True
   * -   
     -   
     - dir-AP
     - True
   * - PA\_FMAP
     - All
     - epi.nii.gz
     - True
   * -   
     -   
     - dir-PA
     - True
   * - scans.tsv
     - All
     - scans.tsv
     - True
   * - sessions.tsv
     - All
     - sessions.tsv
     - True


Quality Control Selection Information
**************************************

The previous section of this page highlighted how to look at a file's name to determine
whether it may belong to a specific 'File Group' (such as T2w images) that are needed
for processing. Beyond this, it is often necessary
to look at some QC criteria to determine whether a file should be included in processing. This section
defines the QC criteria that is used to evaluate specific images. These QC criteria always operate
on one file group at a time. If a file group uses QC criteria to select images, at least one table will be
displayed below. Depending on the context, these criteria will be used to exclude certain images from processing,
to find the best available image(s) within a specific category, or to exclude a session from processing.
If sorting is the goal, the first row will be considered the most important criteria. In certain cases, not all
images will have ratings for a specific QC field. In this case, a backup table (which will be displayed after
the first table if available), will be used for that file group.

File Group: T1
~~~~~~~~~~~~~~

Processing will look for best 1 file(s) to keep using the following criteria(s).

.. list-table::
   :header-rows: 1

   * - scans.tsv Field
     - Operator
     - Value
   * - QC
     - equals
     - 1
   * - QU\_motion
     - less\_than
     - 2
   * - aqc\_motion
     - less\_than
     - 10000
   * - brain\_SNR
     - greater\_than
     - -1000



.. list-table::
   :header-rows: 1

   * - scans.tsv Field
     - Operator
     - Value
   * - QC
     - equals
     - 1
   * - aqc\_motion
     - less\_than
     - 10000
   * - brain\_SNR
     - greater\_than
     - -1000



File Group: T2
~~~~~~~~~~~~~~

Processing will look for best 1 file(s) to keep using the following criteria(s).

.. list-table::
   :header-rows: 1

   * - scans.tsv Field
     - Operator
     - Value
   * - QC
     - equals
     - 1
   * - QU\_motion
     - less\_than
     - 2
   * - aqc\_motion
     - less\_than
     - 10000
   * - brain\_SNR
     - greater\_than
     - -1000



.. list-table::
   :header-rows: 1

   * - scans.tsv Field
     - Operator
     - Value
   * - QC
     - equals
     - 1
   * - aqc\_motion
     - less\_than
     - 10000
   * - brain\_SNR
     - greater\_than
     - -1000



File Group: FMRI
~~~~~~~~~~~~~~~~

Processing will include all files passing the following criteria.

.. list-table::
   :header-rows: 1

   * - scans.tsv Field
     - Operator
     - Value
   * - QC
     - equals
     - 1



File Group: AP_FMAP
~~~~~~~~~~~~~~~~~~~

Processing will include all files passing the following criteria.

.. list-table::
   :header-rows: 1

   * - scans.tsv Field
     - Operator
     - Value
   * - QC
     - equals
     - 1



File Group: PA_FMAP
~~~~~~~~~~~~~~~~~~~

Processing will include all files passing the following criteria.

.. list-table::
   :header-rows: 1

   * - scans.tsv Field
     - Operator
     - Value
   * - QC
     - equals
     - 1