.. HBCD_qMRI_POSTPROC documentation master file, created by
   sphinx-quickstart on Wed Jun  5 10:48:12 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Expected Formatting of Inputs
=============================

BIDS directory
--------------

The BIDS directory should have exactly one T1w and/or T2w image
for each session that will be processed. The T1w and/or T2w image
should already be registered to the segmentation(s) found in the
segmentations directory. If both T1w/T2w images and segmentations
are present, the pipeline will currently (as of 6/5/24) give priority
to registering the relaxometry images to the T2w images in the BIDS directory
by default.

qMRI/relaxometry directory
---------------------------

The quantitative MRI directory should contain derived relaxometry maps, along
with a synthetic T1w and T2w image. At minimum, there should be at least one
T1map, T2map, or PDmap in a subject (or session) quantitative MRI directory. It is assumed that there is
at most one of each image type, and also that all images were derived from the same
acquisition. Following this assumption, all images within this directory should be
registered to one another. The expected names of the files (with \"\*\"
denoting wildcard, and [] denoting optional elements of file path/names) are as follows: ::

   /qmri_dir/sub-<label>[/ses-<label>]/anat/sub-<label>[_ses-<label>]*T1map.nii.gz
   /qmri_dir/sub-<label>[/ses-<label>]/anat/sub-<label>[_ses-<label>]_ses-<label>*T2map.nii.gz
   /qmri_dir/sub-<label>[/ses-<label>]/anat/sub-<label>[_ses-<label>]_ses-<label>*PDmap.nii.gz
   /qmri_dir/sub-<label>[/ses-<label>]/anat/sub-<label>[_ses-<label>]_ses-<label>*T1w.nii.gz
   /qmri_dir/sub-<label>[/ses-<label>]/anat/sub-<label>[_ses-<label>]_ses-<label>*T2w.nii.gz

There may be additional files in the directory that are not used by the pipeline, as
long as they don't match the file patterns mentioned in this section. In HBCD these files are 
currently generated by SyMRI's relaxometry tool, but any tool can be used to generate these files.
In all cases the images must have corresponding json files, which can be empty if there is no
associated metadata.

Beyond the expectation that all images in a given session folder are registered to one another,
it is also assumed that all images have the same dimensions and voxel resolutions. 

BIBSNET Directory (i.e. segmentation directory)
-----------------------------------------------

The segmentations found under this directory should be of the
following form: ::
   
   /segmentation_dir/sub-<label>[/ses-<label>]/anat/sub-<label>[_ses-<label>]*space-<label>_desc-aseg_dseg.nii.gz
   /segmentation_dir/sub-<label>[/ses-<label>]/anat/sub-<label>[_ses-<label>]*space-<label>_desc-brain_mask.nii.gz
   
In the above formatting, the presence of a session folder is optional. The "*" icon denotes
flexibility in the naming convention at a certain point, and the final label entry following "space-"
must either be T1w or T2w. The first file described above is a segmentation with individual brain
regions, and the second file is a binary brain mask that is used to aid in the registration.

In HBCD both of these files are generated by `BIBSNET <https://www.ncbi.nlm.nih.gov/pmc/articles/PMC10055337/>`_, but any segmentations using the naming
convention above with voxel values that correspond to the `FreeSurferColorLUT file <https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/AnatomicalROI/FreeSurferColorLUT>`_ can be used.
No matter what tool is used to generate the segmentations, the FreeSurferColorLUT will first be
loaded, then the segmentation will be loaded, and following a registration procedure any non-zero
value within the segmentation will be mapped to the corresponding label in the FreeSurferColorLUT.
If there is a voxel label that is not found in the FreeSurferColorLUT this will result in an error.

region_groupings_json
---------------------

This file is a json whose keys correspond to user-specified custom names for one
or more groupings of brain regions, and whose values are lists of the brain region
labels that are to be included in each grouping. The labels included in the list
must come directly from the "Label Name" column of the `FreeSurferColorLUT file <https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/AnatomicalROI/FreeSurferColorLUT>`_. When
the tool is given a region_groupings_json, relaxometry statistics will be computed
within all voxels that correspond to a given group.

An example formatting is as follows: ::

   {
       "Cerebral-Cortex": ["Left-Cerebral-White-Matter", "Right-Cerebral-White-Matter"],
       "Cerebral-White-Matter": ["Left-Cerebral-Cortex", "Right-Cerebral-Cortex"]
   }

If there exists a given region grouping where no voxels are found within a segmentation
image, the given grouping will have statistics with NaN values.


.. toctree::
   :maxdepth: 2
   :caption: Contents: