hcp_pre_freesurfer#

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

hcp_pre_freesurfer [... processing options]

Runs the pre-FS step of the HCP Pipeline (PreFreeSurferPipeline.sh).

Warning

The code expects the input images to be named and present in the specific folder structure. Specifically it will look within the folder:

<session id>/hcp/<session id>

for folders and files:

T1w/\*T1w_MPR[N]\*
T2w/\*T2w_MPR[N]\*

There has to be at least one T1w image present. If there are more than one T1w or T2w images, they will all be used and averaged together.

Depending on the type of distortion correction method specified by the --hcp_avgrdcmethod argument (see below), it will also expect the presence of the following files:

TOPUP:

SpinEchoFieldMap[N]\*/\*_<hcp_sephasepos>_\*
SpinEchoFieldMap[N]\*/\*_<hcp_sephaseneg>_\*

SiemensFieldMap:

FieldMap/<session id>_FieldMap_Magnitude.nii.gz
FieldMap/<session id>_FieldMap_Phase.nii.gz

GeneralElectricFieldMap:

FieldMap/<session id>_FieldMap_GE.nii.gz

PhilipsFieldMap:

FieldMap/<session id>_FieldMap_Magnitude.nii.gz
FieldMap/<session id>_FieldMap_Phase.nii.gz

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_t2 (str, default 't2'):

'NONE' if no T2w image is available and the preprocessing should be run without them, anything else otherwise [t2]. 'NONE' is only valid if 'LegacyStyleData' processing mode was specified.

--hcp_brainsize (int, default 150):

Specifies the size of the brain in mm. 170 is FSL default and seems to be a good choice, HCP uses 150, which can lead to problems with larger heads.

--hcp_t1samplespacing (str, default 'NONE'):

T1 image sample spacing, 'NONE' if not used.

--hcp_t2samplespacing (str, default 'NONE'):

T2 image sample spacing, 'NONE' if not used.

--hcp_gdcoeffs (str, default 'NONE):

Path to a file containing gradient distortion coefficients, alternatively a string describing multiple options (see below), or "NONE", if not used.

--hcp_bfsigma (str, default ''):

Bias Field Smoothing Sigma (optional).

--hcp_avgrdcmethod (str, default 'NONE'):

Averaging and readout distortion correction method. Can take the following values:

  • 'NONE' (average any repeats with no readout correction)

  • 'FIELDMAP' (average any repeats and use Siemens field map for readout correction)

  • 'SiemensFieldMap' (average any repeats and use Siemens field map for readout correction)

  • 'GeneralElectricFieldMap' (average any repeats and use GE field map for readout correction)

  • 'PhilipsFieldMap' (average any repeats and use Philips field map for readout correction)

  • 'TOPUP' (average any repeats and use spin echo field map for readout correction).

--hcp_unwarpdir (str, default 'NONE'):

Readout direction of the T1w and T2w images (x, y, z or NONE); used with either a regular field map or a spin echo field map.

--hcp_echodiff (str, default 'NONE'):

Difference in TE times if a fieldmap image is used, set to NONE if not used.

--hcp_seechospacing (str, default 'NONE'):

Echo Spacing or Dwelltime of Spin Echo Field Map or "NONE" if not used.

--hcp_sephasepos (str, default ''):

Label for the positive image of the Spin Echo Field Map pair.

--hcp_sephaseneg (str, default ''):

Label for the negative image of the Spin Echo Field Map pair.

--hcp_seunwarpdir (str, default 'NONE'):

Phase encoding direction of the Spin Echo Field Map (x, y or NONE).

--hcp_topupconfig (str, default 'NONE'):

Path to a configuration file for TOPUP method or "NONE" if not used.

--hcp_prefs_custombrain (str, default 'NONE'):

Whether to only run the final registration using either a custom prepared brain mask (MASK) or custom prepared brain images (CUSTOM), or to run the full set of processing steps (NONE). If a mask is to be used (MASK) then a "custom_acpc_dc_restore_mask.nii.gz" image needs to be placed in the <session>/T1w folder. If a custom brain is to be used (BRAIN), then the following images in <session>/T1w folder need to be adjusted:

  • T1w_acpc_dc_restore_brain.nii.gz

  • T1w_acpc_dc_restore.nii.gz

  • T2w_acpc_dc_restore_brain.nii.gz

  • T2w_acpc_dc_restore.nii.gz.

--hcp_prefs_template_res (float, default 0.7):

The resolution (in mm) of the structural images templates to use in the preFS step. Note: it should match the resolution of the acquired structural images.

--hcp_prefs_t1template (str, default ""):

Path to the T1 template to be used by PreFreeSurfer. By default the used template is determined through the resolution provided by the hcp_prefs_template_res parameter.

--hcp_prefs_t1templatebrain (str, default ""):

Path to the T1 brain template to be used by PreFreeSurfer. By default the used template is determined through the resolution provided by the hcp_prefs_template_res parameter.

--hcp_prefs_t1template2mm (str, default ""):

Path to the T1 2mm template to be used by PreFreeSurfer. By default the used template is HCP's MNI152_T1_2mm.nii.gz.

--hcp_prefs_t2template (str, default ""):

Path to the T2 template to be used by PreFreeSurfer. By default the used template is determined through the resolution provided by the hcp_prefs_template_res parameter.

--hcp_prefs_t2templatebrain (str, default ""):

Path to the T2 brain template to be used by PreFreeSurfer. By default the used template is determined through the resolution provided by the hcp_prefs_template_res parameter.

--hcp_prefs_t2template2mm (str, default ""):

Path to the T2 2mm template to be used by PreFreeSurfer. By default the used template is HCP's MNI152_T2_2mm.nii.gz.

--hcp_prefs_templatemask (str, default ""):

Path to the template mask to be used by PreFreeSurfer. By default the used template mask is determined through the resolution provided by the hcp_prefs_template_res parameter.

--hcp_prefs_template2mmmask (str, default ""):

Path to the template mask to be used by PreFreeSurfer. By default the used 2mm template mask is HCP's MNI152_T1_2mm_brain_mask_dil.nii.gz.

--hcp_prefs_fnirtconfig (str, default ""):

Path to the used FNIRT config. Set to the HCP's T1_2_MNI152_2mm.cnf by default.

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

A pipe, comma or space separated list of inline sequence information to use in preprocessing of specific image modalities.

Example specifications:

  • all: use all present inline information for all modalities,

  • 'DwellTime': use DwellTime information for all modalities,

  • T1w:all: use all present inline information for T1w modality,

  • SE:EchoSpacing: use EchoSpacing information for Spin-Echo fieldmap images.

  • none: do not use inline information

Modalities: T1w, T2w, SE, BOLD, dMRi Inline information: TR, PEDirection, EchoSpacing DwellTime, ReadoutDirection.

If information is not specified it will not be used. More general specification (e.g. all) implies all more specific cases (e.g. T1w:all).

Output files

The results of this step will be present in the above mentioned T1w and T2w folders as well as MNINonLinear folder generated and populated in the same sessions's root hcp folder.

Notes

Gradient coefficient file specification:

--hcp_gdcoeffs parameter can be set to either 'NONE', a path to a specific file to use, or a string that describes, which file to use in which case. Each option of the string has to be divided by a pipe '|' character and it has to specify, which information to look up, a possible value, and a file to use in that case, separated by a colon ':' character. The information too look up needs to be present in the description of that session. Standard options are e.g.:

institution: Yale
device: Siemens|Prisma|123456

Where device is formatted as <manufacturer>|<model>|<serial number>.

If specifying a string it also has to include a default option, which will be used in the information was not found. An example could be:

"default:/data/gc1.conf|model:Prisma:/data/gc/Prisma.conf|model:Trio:/data/gc/Trio.conf"

With the information present above, the file /data/gc/Prisma.conf would be used.

hcp_pre_freesurfer parameter mapping:

QuNex parameter

HCPpipelines parameter

hcp_prefs_t1template

t1template

hcp_prefs_t1templatebrain

t1templatebrain

hcp_prefs_t1template2mm

t1template2mm

hcp_prefs_t2template

t2template

hcp_prefs_t2templatebrain

t2templatebrain

hcp_prefs_t2template2mm

t2template2mm

hcp_prefs_templatemask

templatemask

hcp_prefs_template2mmmask

template2mmmask

hcp_brainsize

brainsize

hcp_prefs_fnirtconfig

fnirtconfig

hcp_sephaseneg

SEPhaseNeg

hcp_sephasepos

SEPhasePos

hcp_seechospacing

seechospacing

hcp_seunwarpdir

seunwarpdir

hcp_t1samplespacing

t1samplespacing

hcp_t2samplespacing

t2samplespacing

hcp_gdcoeffs

gdcoeffs

hcp_avgrdcmethod

avgrdcmethod

hcp_topupconfig

topupconfig

hcp_bfsigma

bfsigma

hcp_prefs_custombrain

custombrain

hcp_processing_mode

processing-mode
Use:

Runs the PreFreeSurfer step of the HCP Pipeline. It looks for T1w and T2w images in sessions's T1w and T2w folder, averages them (if multiple present) and linearly and nonlinearly aligns them to the MNI atlas. It uses the adjusted version of the HCP that enables the preprocessing to run with of without T2w image(s).

Examples

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

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