map_hcp_data#

qx_utilities.hcp.process_hcp.map_hcp_data(sinfo, options, overwrite=False, thread=0)#

map_hcp_data [... processing options]

Maps the results of the HCP preprocessing:

T1w.nii.gz
└-> images/structural/T1w.nii.gz
aparc+aseg.nii.gz
└-> images/segmentation/freesurfer/mri/aparc+aseg_t1.nii.gz

└-> images/segmentation/freesurfer/mri/aparc+aseg_bold.nii.gz (2mm iso downsampled version)
fsaverage_LR32k/*
└-> images/segmentation/hcp/fsaverage_LR32k
BOLD_[N][hcp_nifti_tail].nii.gz
└-> images/functional/[boldname][N][qx_nifti_tail].nii.gz
BOLD_[N][hcp_cifti_tail].dtseries.nii
└-> images/functional/[boldname][N][qx_cifti_tail].dtseries.nii
Movement_Regressors.txt
└-> images/functional/movement/[boldname][N]_mov.dat

See Use section for details.

Parameters

--batchfile (str, default ''):: The batch.txt file with all the sessions information.
--sessionsfolder (str, default '.'):: The path to the study/sessions folder, where the imaging data is supposed to go.
--parsessions (int, default 1):: How many sessions to run in parallel.
--overwrite (str, default 'no'):: Whether to overwrite existing data (yes) or not (no).
--hcp_suffix (str, default ''):: Specifies a suffix to the session id if multiple variants are run, empty otherwise.
--hcp_bold_variant (str, default ''):: Optional variant of HCP BOLD preprocessing. If specified, the results will be copied/linked from Results<hcp_bold_variant>.
--bolds (str, default 'all'):: Which bold images (as they are specified in the batch.txt file) to copy over. It can be a single type (e.g. 'task'), a pipe separated list (e.g. 'WM|Control|rest') or 'all' to copy all.
--boldname (str, default 'bold'):: The prefix for the fMRI files in the images folder.
--img_suffix (str, default ''):: Specifies a suffix for 'images' folder to enable support for multiple parallel workflows. Empty if not used.
--qx_nifti_tail (str, default detailed below):: The tail to use for the mapped volume files in the QuNex file structure. If not specified or if set to 'None', the value of hcp_nifti_tail will be used.
--qx_cifti_tail (str, default detailed below):: The tail to use for the mapped cifti files in the QuNex file structure. If not specified or if set to 'None', the value of hcp_cifti_tail will be used.
--bold_variant (str, default ''):: Optional variant for functional images. If specified, functional images will be mapped into functional<bold_variant> folder.

Notes

The parameters can be specified in command call or session.txt file. If possible, the files are not copied but rather hard links are created to save space. If hard links can not be created, the files are copied.

Specific attention needs to be paid to the use of hcp_nifti_tail, hcp_cifti_tail, hcp_suffix, and hcp_bold_variant that relate to file location and naming within the HCP folder structure and qx_nifti_tail, qx_cifti_tail, img_suffix, and bold_variant that relate to file and folder naming within the QuNex folder structure.

hcp_suffix parameter enables the use of a parallel HCP minimal processing stream. To enable the same separation in the QuNex folder structure, img_suffix parameter has to be set. In this case HCP data will be mapped to <sessionsfolder>/<session id>/images<img_suffix> folder instead of the default <sessionsfolder>/<session id>/images folder.

Similarly, if separate variants of bold image processing were run, and the results were stored in MNINonLinear/Results<hcp_bold_variant>, the hcp_bold_variant parameter needs to be set to map the data from the correct location. bold_variant parameter on the other hand enables continued parallel processing of bold data in the QuNex folder structure by mapping bold data to functional<bold_variant> folder instead of the default functional folder.

Based on HCP minimal preprocessing choices, both CIFTI and NIfTI volume files can be marked using different tails. E.g. CIFT files are marked with an _Atlas tail, NIfTI files are marked with _hp2000_clean tail after employing ICAFix procedure. When mapping the data, it is important that the correct files are mapped. The correct tails for NIfTI volume, and CIFTI files are specified using the hcp_nifti_tail and hcp_cifti_tail parameters. When the data is mapped into QuNex folder structure the tails to be used for NIfTI and CIFTI data are specified with qx_nifti_tail and qx_cifti_tail parameters, respectively. If the qx_*_tail parameters are not provided explicitly, the values specified in the hcp_*_tail parameters will be used.

Use:

map_hcp_data maps the results of the HCP preprocessing (in MNINonLinear) to the <sessionsfolder>/<session id>/images<img_suffix> folder structure. Specifically, it copies the files and folders:

T1w.nii.gz
└-> images/structural/T1w.nii.gz
aparc+aseg.nii.gz
└-> images/segmentation/freesurfer/mri/aparc+aseg_t1.nii.gz

└-> images/segmentation/freesurfer/mri/aparc+aseg_bold.nii.gz (2mm iso downsampled version)
fsaverage_LR32k/*
└-> images/segmentation/hcp/fsaverage_LR32k
BOLD_[N][hcp_nifti_tail].nii.gz
└-> images/functional/[boldname][N][qx_nifti_tail].nii.gz
BOLD_[N][hcp_cifti_tail].dtseries.nii
└-> images/functional/[boldname][N][qx_cifti_tail].dtseries.nii
Movement_Regressors.txt
└-> images/functional/movement/[boldname][N]_mov.dat

Examples

Example run from the base study folder with test flag:

qunex map_hcp_data \
    --batchfile="processing/batch.txt" \
    --sessionsfolder="sessions" \
    --parsessions="10" \
    --hcp_cifti_tail="_Atlas" \
    --overwrite="no" \
    --test

Run using absolute paths with scheduler:

qunex map_hcp_data \
    --batchfile="<path_to_study_folder>/processing/batch.txt" \
    --sessionsfolder="<path_to_study_folder>/sessions" \
    --parsessions="4" \
    --hcp_cifti_tail="_Atlas" \
    --overwrite="yes" \
    --scheduler="SLURM,time=24:00:00,cpus-per-task=2,mem-per-cpu=1250,partition=day"

Additional example:

qunex map_hcp_data \
    --batchfile=fcMRI/sessions_hcp.txt \
    --sessionsfolder=sessions \
    --overwrite=no \
    --hcp_cifti_tail=_Atlas \
    --bolds=all

QuNex documentation

map_hcp_data

map_hcp_data#