hcp_fmri_surface

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

hcp_fmri_surface [... processing options]

Runs the fMRI Surface (GenericfMRISurfaceProcessingPipeline.sh) step of the HCP Pipeline .

Warning

The code expects all the previous HCP preprocessing steps (hcp_pre_freesurfer, hcp_freesurfer, hcp_post_freesurfer, hcp_fmri_volume) to have been run and finished successfully. The command will test for presence of key files but do note that it won't run a thorough check for all the required files.

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.

--parelements (int, default 1):

How many elements (e.g.bolds) to run in parallel.

--bolds (str, default 'all'):

Which bold images (as they are specified in the batch.txt file) to process. It can be a single type (e.g. 'task'), a pipe separated list (e.g. 'WM|Control|rest') or 'all' to process all.

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

--logfolder (str, default ''):

The path to the folder where runlogs and comlogs are to be stored, if other than default.

--hcp_folderstructure (str, default 'hcpls'):

If set to 'hcpya' the folder structure used in the initial HCP Young Adults study is used. Specifically, the source files are stored in individual folders within the main 'hcp' folder in parallel with the working folders and the 'MNINonLinear' folder with results. If set to'hcpls' the folder structure used in the HCP Life Span study is used. Specifically, the source files are all stored within their individual subfolders located in the joint 'unprocessed' folder in the main 'hcp' folder, parallel to the working folders and the 'MNINonLinear' folder.

--hcp_filename (str, default 'automated'):

How to name the BOLD files once mapped into the hcp input folder structure. The default ('automated') will automatically name each file by their number (e.g. BOLD_1). The alternative ('userdefined') is to use the file names, which can be defined by the user prior to mapping (e.g. rfMRI_REST1_AP).

--hcp_bold_prefix (str, default 'BOLD'):

The prefix to use when generating BOLD names (see 'hcp_filename') for BOLD working folders and results.

--hcp_lowresmesh (int, default 32):

The number of vertices to be used in the low-resolution grayordinate mesh (in thousands).

--hcp_bold_res (str, default '2'):

The resolution of the BOLD volume data in mm.

--hcp_grayordinatesres (int, default 2):

The size of voxels for the subcortical and cerebellar data in grayordinate space in mm.

--hcp_bold_smoothFWHM (int, default 2):

The size of the smoothing kernel (in mm).

--hcp_regname (str, default 'MSMSulc'):

The name of the registration used.

Output files

The results of this step will be present in the MNINonLinear folder in the sessions's root hcp folder:

study
└─ sessions
   └─ session1_session1
      └─ hcp
         └─ subject1_session1
           └─ MNINonlinear
              └─ Results
                 └─ BOLD_1

Notes

Runs the fMRI Surface (GenericfMRISurfaceProcessingPipeline.sh) step of the HCP Pipeline. It uses the FreeSurfer segmentation and surface reconstruction to map BOLD timeseries to grayordinate representation and generates .dtseries.nii files.

hcp_fmri_surface parameter mapping:

QuNex parameter	HCPpipelines parameter
hcp_lowresmesh	lowresmesh
hcp_bold_res	fmrires
hcp_bold_smoothFWHM	smoothingFWHM
hcp_grayordinatesres	grayordinatesres
hcp_regname	regname
hcp_printcom	printcom

Examples

Example run from the base study folder with --test flag. Here --parsessions specifies how many sessions to run concurrently and --parelements specifies how many elements (e.g. bold images) to process concurrently:

qunex hcp_fmri_surface  \
    --batchfile="processing/batch.txt"  \
    --sessionsfolder="sessions"  \
    --parsessions="10"  \
    --parelements="4"  \
    --overwrite="no"  \
    --test

Run using absolute paths with scheduler:

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

Extra example:

qunex hcp_fmri_surface \
    --batchfile=fcMRI/sessions_hcp.txt \
    --sessionsfolder=sessions \
    --overwrite=no \
    --parsessions=10