hcp_freesurfer#

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

hcp_freesurfer [... processing options]

Runs the FS step of the HCP Pipeline (FreeSurferPipeline.sh).

Warning

The code expects the previous step (hcp_pre_freesurfer) to have run successfully and checks for presence of a few key files and folders. Due to the number of inputs that it requires, it does not make a full check for all of them!

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.

--logfolder (str, default ''):

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

--hcp_processing_mode (str, default 'HCPStyleData'):

Controls whether the HCP acquisition and processing guidelines should be treated as requirements ('HCPStyleData') or if additional processing functionality is allowed ('LegacyStyleData'). In this case running processing w/o a T2w image.

--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 intothe 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_fs_seed (str, default ''):

Recon-all seed value. If not specified, none will be used. (Please note that it will only be used when HCP Pipelines are used. It is not implemented in hcpmodified!)

--hcp_fs_existing_session (str, default 'FALSE'):

Indicates that the command is to be run on top of an already existing analysis/subject. This excludes the -i flag from the invocation of recon-all. If set, the user needs to specify which recon-all stages to run using the --hcp_fs_extra_reconall parameter. Accepted values are 'TRUE' and 'FALSE'. (Please note that it will only be used when HCP Pipelines are used. It is not implemented in hcpmodified!)

--hcp_fs_extra_reconall (str, default ''):

A string with extra parameters to pass to FreeSurfer recon-all. The extra parameters are to be listed in a pipe ('|') separated string. Parameters and their values need to be listed separately. E.g. to pass -norm3diters 3 to reconall, the string has to be: "-norm3diters|3". (Please note that it will only be used when HCP Pipelines are used. It is not implemented in hcpmodified!)

--hcp_fs_flair (str, default 'FALSE'):

If set to 'TRUE' indicates that recon-all is to be run with the -FLAIR/-FLAIRpial options (rather than the -T2/-T2pial options). The FLAIR input image itself should be provided as a regular T2w image. (Please note that it will only be used when HCP Pipelines are used. It is not implemented in hcpmodified!)

--hcp_fs_no_conf2hires (str, default 'FALSE'):

Indicates that (most commonly due to low resolution—1mm or less—of structural image(s), high-resolution steps of recon-all should be excluded. Accepted values are 'TRUE' or 'FALSE'. (Please note that it will only be used when HCP Pipelines are used. It is not implemented in hcpmodified!)

--hcp_t2 (str, default 't2'):

'NONE' if no T2w image is available and the preprocessing should be run without them, anything else otherwise. 'NONE' is only valid if 'LegacyStyleData' processing mode was specified. (Please note, that this setting will only be used when LegacyStyleData processing mode is specified!)

--hcp_expert_file (str, default ''):

Path to the read-in expert options file for FreeSurfer if one is prepared and should be used empty otherwise. (Please note, that this setting will only be used when LegacyStyleData processing mode is specified!)

--hcp_freesurfer_home (str, default ''):

Path for FreeSurfer home folder can be manually specified to override default environment variable to ensure backwards compatiblity and hcp_freesurfer customization. (Please note, that this setting will only be used when LegacyStyleData processing mode is specified!)

Output files

The results of this step will be present in the above mentioned T1w folder as well as MNINonLinear folder in the sessions's root hcp folder.

Notes

Runs the FreeSurfer (FreeSurfer.sh) step of the HCP Pipelines. It takes the T1w and T2w images processed in the previous (hcp_pre_freesurfer) step, segments T1w image by brain matter and CSF, reconstructs the cortical surface of the brain and assigns structure labels for both subcortical and cortical structures. It completes the listed in multiple steps of increased precision and (if present) uses T2w image to refine the surface reconstruction. It uses the adjusted version of the HCP code that enables the preprocessing to run also if no T2w image is present.

hcp_freesurfer parameter mapping:

QuNex parameter

HCPpipelines parameter

hcp_fs_seed

seed

hcp_processing_mode

processing-mode

hcp_fs_existing_session

existing-subject

hcp_fs_extra_reconall

extra-reconall-arg

hcp_fs_no_conf2hires

no-conf2hires

hcp_fs_flair

flair

Examples

Example run from the base study folder with test flag:

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

Example run with absolute paths with scheduler and no T2w image is available:

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

Run from the study folder with FreeSurfer specific details and scheduler:

qunex hcp_freesurfer \
    --batchfile="processing/batch.txt" \
    --sessionsfolder="sessions" \
    --parsessions="10" \
    --overwrite="no" \
    --hcp_freesurfer_home=<absolute_path_to_freesurfer_binary> \
    --scheduler="SLURM,time=03-24:00:00,cpus-per-task=2,mem-per-cpu=1250,partition=week"

Additional examples:

qunex hcp_freesurfer \
    --batchfile=fcMRI/sessions_hcp.txt \
    --sessionsfolder=sessions \
    --overwrite=no \
    --parsessions=10
qunex hcp_freesurfer \
    --batchfile=fcMRI/sessions_hcp.txt \
    --sessionsfolder=sessions \
    --overwrite=no \
    --parsessions=10 \
    --hcp_t2=NONE
qunex hcp_freesurfer \
    --batchfile=fcMRI/sessions_hcp.txt \
    --sessionsfolder=sessions \
    --overwrite=no \
    --parsessions=10 \
    --hcp_t2=NONE \
    --hcp_freesurfer_home=<absolute_path_to_freesurfer_binary>