hcp_fmri_volume#

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

hcp_fmri_volume [... processing options]

Runs the fMRI Volume (GenericfMRIVolumeProcessingPipeline.sh) step of HCP Pipeline. It preprocesses BOLD images and linearly and nonlinearly registers them to the MNI atlas. It makes use of the PreFS and FS steps of the pipeline. It enables the use of a number of parameters to customize the specific preprocessing steps.

Warning

The code expects the first two HCP preprocessing steps (hcp_pre_freesurfer and hcp_freesurfer) to have been run and finished successfully. It also tests for the presence of fieldmap or spin-echo images if they were specified. It does not make a thorough check for PreFS and FS steps due to the large number of 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_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 with slice timing correction, external BOLD reference, or without a distortion correction method.

--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_biascorrection (str, default 'NONE'):

Whether to perform bias correction for BOLD images. NONE, LEGACY or SEBASED. With SEBASED must also use hcp_bold_dcmethod.

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

Whether to apply the jacobian of the distortion correction to fMRI data.

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

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

--hcp_bold_echospacing (float, default 0.00035):

Echo Spacing or Dwelltime of BOLD images.

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

Whether BOLD Reference images should be used - NONE or USE.

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

--hcp_bold_dcmethod (str, default 'TOPUP'):

BOLD image deformation correction that should be used: TOPUP, FIELDMAP / SiemensFieldMap, GeneralElectricFieldMap, PhilipsFieldMap or NONE.

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

Delta TE for BOLD fieldmap images or NONE if not used.

--hcp_bold_sephasepos (str, default ''):

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

--hcp_bold_sephaseneg (str, default ''):

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

--hcp_bold_unwarpdir (str, default 'y'):

The direction of unwarping. Can be specified separately for LR/RL : 'LR=x|RL=-x|x' or separately for PA/AP : 'PA=y|AP=y-|y-'.

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

Target image resolution. 2mm recommended.

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

Gradient distortion correction coefficients or NONE.

--hcp_bold_topupconfig (str, default detailed below):

A full path to the topup configuration file to use. Do not set if the default is to be used or if TOPUP distortion correction is not used.

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

Whether to do slice timing correction 'TRUE' or 'FALSE'.

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

Whether to use custom slice timing file 'TRUE' or 'FALSE'.

--hcp_bold_slicetimerparams (str, default ''):

A comma or pipe separated string of parameters for FSL slicetimer.

--hcp_bold_stcorrdir (str, default 'up'):

The direction of slice acquisition ('up' or 'down'). This parameter is deprecated. If specified, it will be added to --hcp_bold_slicetimerparams.

--hcp_bold_stcorrint (str, default 'odd'):

Whether slices were acquired in an interleaved fashion ('odd') or not ('empty'). This parameter is deprecated. If specified, it will be added to --hcp_bold_slicetimerparams.

--hcp_bold_preregistertool (str, default 'epi_reg'):

What tool to use to preregister BOLDs before FSL BBR is 'run', 'epi_reg' (default) or 'flirt'.

--hcp_bold_movreg (str, default 'MCFLIRT'):

Whether to use 'FLIRT' (usually for multiband images) or 'MCFLIRT' (default) for motion correction.

--hcp_bold_movref (str, default 'independent'):

What reference to use for movement correction ('independent', 'first'). This parameter is only valid when running HCPpipelines using the LegacyStyleData processing mode!

--hcp_bold_seimg (str, default 'independent'):

What image to use for spin-echo distortion correction ('independent' | 'first'). This parameter is only valid when running HCPpipelines using the LegacyStyleData processing mode!

--hcp_bold_refreg (str, default 'linear'):

Whether to use only 'linear' (default) or also 'nonlinear' registration of motion corrected bold to reference. This parameter is only valid when running HCPpipelines using the LegacyStyleData processing mode!

--hcp_bold_mask (str, default 'T1_fMRI_FOV'):

Specifies what mask to use for the final bold:

T1_fMRI_FOV ... combined T1w brain mask and fMRI FOV masks (the default and HCPStyleData compliant)
T1_DILATED_fMRI_FOV ... a once dilated T1w brain based mask combined with fMRI FOV
T1_DILATED2x_fMRI_FOV ... a twice dilated T1w brain based mask combined with fMRI FOV
fMRI_FOV ... a fMRI FOV mask.

This parameter is only valid when running HCPpipelines using the LegacyStyleData processing mode!

Output files

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

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

Notes

These last parameters enable fine-tuning of preprocessing and deserve additional information. In general the defaults should be appropriate for multiband images, single-band can profit from specific adjustments. Whereas FLIRT is best used for motion registration of high-resolution BOLD images, lower resolution single-band images might be better motion aligned using MCFLIRT (--hcp_bold_movreg).

As a movement correction target, either each BOLD can be independently registered to T1 image, or all BOLD images can be motion correction aligned to the first BOLD in the series and only that image is registered to the T1 structural image (--hcp_bold_moveref). Do note that in this case also distortion correction will be computed for the first BOLD image in the series only and applied to all subsequent BOLD images after they were motion-correction aligned to the first BOLD.

Similarly, for distortion correction, either the last preceding spin-echo image pair can be used (independent) or only the first spin-echo pair is used for all BOLD images (first; --hcp_bold_seimg). Do note that this also affects the previous motion correction target setting. If independent spin-echo pairs are used, then the first BOLD image after a new spin-echo pair serves as a new starting motion-correction reference.

If there is no spin-echo image pair and TOPUP correction was requested, an error will be reported and processing aborted. If there is no preceding spin-echo pair, but there is at least one following the BOLD image in question, the first following spin-echo pair will be used and no error will be reported. The spin-echo pair used is reported in the log.

When BOLD images are registered to the first BOLD in the series, due to larger movement between BOLD images it might be advantageous to use also nonlinear alignment to the first bold reference image (--hcp_bold_refreg).

Lastly, for lower resolution BOLD images it might be better not to use subject specific T1 image based brain mask, but rather a mask generated on the BOLD image itself or based on the dilated standard MNI brain mask.

Gradient coefficient file specification:

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

Slice timing correction:

Slice timing correction is performed using FSL slicetimer. For the correction to be done correctly, the data needs to be carefully inspected and the hcp_bold_slicetimerparams parameter has to be prepared with the valid information. For complex slice timing acquisition (e.g., multiband acquisition) it is best to prepare a slice timing file. The slice timing file has to be saved in the same folder as the respective BOLD file. It has to be named the same as the BOLD file with _slicetimer.txt tail and extension. The slice timing file can be prepared automatically using the `setup_hcp <../../api/gmri/setup_hcp.rst>`__ command, if JSON sidecar files for BOLD images exist and have the correct slice timing information. Alternatively prepare_slice_timing command can be used. See the respective inline help for more information.

Movement and spin-echo references:

Whereas most of the options should be clear, the ones specifying movement and spin-echo reference present the most significant change from the original way fMRIVolume is run and should be explained more in detail. Originally, each fMRI image is processed independently and registered to the individual's T1w image. Whereas this works well for high-resolution multiband fMRI images, in our experience the results are not optimal for legacy (non-multiband) fMRI images of lower resolution. Due to slight changes in the optimal registration to T1w image, fMRI images would not be optimally spatially aligned to one another, which would lead to increased within-subject noise across fMRI images. Using the hcp_bold_movref parameter it is possible to instead align the first fMRI image to the T1w image and then align all the following fMRI images to the first fMRI rather than registering each of them separately and independently to T1w image.

The original registration procedure (the steps in brackets are based on previously completed steps):

bold1 -> T1w [-> MNI atlas]
bold2 -> T1w [-> MNI atlas]
bold3 -> T1w [-> MNI atlas]

can be changed to:

bold1 -> T1w [-> MNI atlas]
bold2 -> bold1 [-> T1w -> MNI atlas]
bold3 -> bold1 [-> T1w -> MNI atlas]

To use the original procedure and align each BOLD independently to T1w image, the hcp_bold_movref parameter has to be set to independent. To use the modified procedure set the parameter to first. To remove additional mismatches that can arise due to changes in distortion because of larger head movements between acquisition of individual BOLD images, linear registration of references between BOLD images can be enhanced with additional nonlinear registration. To make use of the latter, set the hcp_bold_refreg parameter to nonlinear instead of linear. Note that using the non-linear registration is not compliant with the HCPStyleData processing mode.

The additional advantage of registration to the first BOLD image is reduction in processing as the previously computed distortion correction can be re-used. This can lead to noticeable reduction in processing time.

When recording is interrupted for any reason (e.g. subject had to go to a toilet, or the recording was completed in two sessions), a novel spin-echo image might be acquired to account for movement and allow better registration with BOLD images. In such a case, if hcp_bold_seimg parameter is set to independent, the modified HCP pipeline will use for each BOLD image the last spin-echo recorded before the BOLD image in question. In this case, if BOLD registration target is set to the first BOLD image (using hcp_bold_movref), the BOLD image registration target will be also changed to the fist BOLD image after the new spin-echo pair. Specifically with independent hcp_bold_seimg an example sequence might be:

se-pair1
bold1 -> se-pair1 -> T1w [-> MNI atlas]
bold2 -> bold1 [se-pair1 -> T1w -> MNI atlas]
bold3 -> bold1 [se-pair1 -> T1w -> MNI atlas]
se-pair2
bold4 -> se-pair2 -> T1w [-> MNI atlas]
bold5 -> bold4 [se-pair2 -> T1w -> MNI atlas]
bold6 -> bold4 [se-pair2 -> T1w -> MNI atlas]

If the hcp_bold_seimg parameter is set to first, only the first spin-echo pair of images will be considered and all others will be ignored. The above sequence would then be changed to:

se-pair1
bold1 -> se-pair1 -> T1w [-> MNI atlas]
bold2 -> bold1 [se-pair1 -> T1w -> MNI atlas]
bold3 -> bold1 [se-pair1 -> T1w -> MNI atlas]
se-pair2
bold4 -> bold1 [se-pair1 -> T1w -> MNI atlas]
bold5 -> bold1 [se-pair1 -> T1w -> MNI atlas]
bold6 -> bold1 [se-pair1 -> T1w -> MNI atlas]

In the rare cases, where a spin-echo pair of images would be recorded after the first BOLD image, the first spin-echo image found after the BOLD image would be used for distortion correction. An example of such a situation might be the following sequence:

bold1 -> se-pair1 -> T1w [-> MNI atlas]
bold2 -> bold1 [se-pair1 -> T1w -> MNI atlas]
bold3 -> bold1 [se-pair1 -> T1w -> MNI atlas]
se-pair1
bold4 -> bold1 [se-pair1 -> T1w -> MNI atlas]
bold5 -> bold1 [se-pair1 -> T1w -> MNI atlas]
bold6 -> bold1 [se-pair1 -> T1w -> MNI atlas]

In our testing, using the following combination of settings resulted in smallest differences between registered BOLD legacy (non-multiband) images:

# batch.txt settings
--hcp_bold_movreg    : MCFLIRT
--hcp_bold_movref    : first
--hcp_bold_seimg     : first
--hcp_bold_refreg    : nonlinear
--hcp_bold_mask      : T1_DILATED2x_fMRI_FOV

Do note that the best performing settings are study dependent and need to be evaluated on a study by study basis.

hcp_fmri_volume parameter mapping:

QuNex parameter

HCPpipelines parameter

hcp_bold_res

fmrires

hcp_bold_biascorrection

biascorrection

hcp_bold_echodiff

echodiff

hcp_gdcoeffs

gdcoeffs

hcp_bold_dcmethod

dcmethod

hcp_bold_echospacing

echospacing

hcp_bold_unwarpdir

unwarpdir

hcp_bold_topupconfig

topupconfig

hcp_bold_dof

dof

hcp_printcom

printcom

hcp_bold_usejacobian

usejacobian

hcp_bold_movreg

mctype

hcp_bold_preregistertool

preregistertool

hcp_processing_mode

processing-mode

hcp_bold_doslicetime

slicetimerparams

hcp_bold_slicetimerparams

slicetimerparams

hcp_bold_slicetimingfile

slicetimerparams

hcp_bold_stcorrdir

slicetimerparams

hcp_bold_stcorrint

slicetimerparams

hcp_bold_refreg

fmrirefreg

hcp_bold_mask

fmrimask

QuNex parameter	HCPpipelines parameter
`hcp_bold_res`	`fmrires`
`hcp_bold_biascorrection`	`biascorrection`
`hcp_bold_echodiff`	`echodiff`
`hcp_gdcoeffs`	`gdcoeffs`
`hcp_bold_dcmethod`	`dcmethod`
`hcp_bold_echospacing`	`echospacing`
`hcp_bold_unwarpdir`	`unwarpdir`
`hcp_bold_topupconfig`	`topupconfig`
`hcp_bold_dof`	`dof`
`hcp_printcom`	`printcom`
`hcp_bold_usejacobian`	`usejacobian`
`hcp_bold_movreg`	`mctype`
`hcp_bold_preregistertool`	`preregistertool`
`hcp_processing_mode`	`processing-mode`
`hcp_bold_doslicetime`	`slicetimerparams`
`hcp_bold_slicetimerparams`	`slicetimerparams`
`hcp_bold_slicetimingfile`	`slicetimerparams`
`hcp_bold_stcorrdir`	`slicetimerparams`
`hcp_bold_stcorrint`	`slicetimerparams`
`hcp_bold_refreg`	`fmrirefreg`
`hcp_bold_mask`	`fmrimask`

Examples

Example run from the base study folder with test flag:

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

Run using absolute paths with additional options and scheduler:

qunex hcp_fmri_volume  \
    --batchfile="<path_to_study_folder>/processing/batch.txt"
    --sessionsfolder="<path_to_study_folder>/sessions"  \
    --parsessions="4"  \
    --parelements="2"  \
    --hcp_bold_doslicetime="TRUE"  \
    --hcp_bold_movereg="MCFLIRT"  \
    --hcp_bold_moveref="first"  \
    --hcp_bold_mask="T1_DILATED2x_fMRI_FOV"  \
    --overwrite="yes"  \
    --scheduler="SLURM,time=24:00:00,cpus-per-task=2,mem-per-cpu=1250,partition=day"

Additional examples:

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

qunex hcp_fmri_volume \
    --batchfile=fcMRI/sessions_hcp.txt \
    --sessionsfolder=sessions \
    --overwrite=no \
    --parsessions=10 \
    --hcp_bold_movref=first \
    --hcp_bold_seimg=first \
    --hcp_bold_refreg=nonlinear \
    --hcp_bold_mask=DILATED

QuNex documentation

hcp_fmri_volume

hcp_fmri_volume#