On specification of processing parameters#

Both HCP Pipelines as well as additional functional processing of images make use of a number of parameters. These parameters can be specified at multiple levels. Specifically, in order of priority, from lower to highest, they can be specified:

  • in the header section of the study batch file

  • in the runlist file

  • as a command line parameter

  • in the session section of the study batch file

  • in the image specification of the session section of the study batch file

Header section of the study batch file#

To run most of processing steps, a batch file needs to be provided (please see batch file specification, for information on how to generate it, see Generating Group Batch Files). A batch file consists of a header section and a list of imaging sessions. The header section provides the possibility to specify the default parameter values that are to be used throughout the study. Specifically, the parameters are provided as _<parameter name>: <parameter value> pairs. An example might be:

--hcp_brainsize          : 150
--hcp_t1samplespacing    : 0.0000021000
--hcp_t2samplespacing    : 0.0000021000
--hcp_unwarpdir          : y

If these parameters are not specified anywhere else, the above values will be used.

QuNex recipe file#

When the run_recipe QuNex command is used, parameters can be specified at the global level, at a specific recipe level, and at an individual command level. The parameters specified will then be passed to the command as command line parameters. For details on the run_recipe command itself and how to specify parameters at different levels within the recipe.yaml file, please see Running QuNex recipes. These parameters will take priority over the parameters specified in the header section of the study batch file.

Command line parameters#

Parameters can be specified when running the command on the command line. Any parameter specified on the command line takes precedence over the parameters specified in the header section of the study batch file.

Batch file individual session section#

The second part of the study batch file consists of information for each individual session. Within the individual session sections the parameters can be specified in the _<parameter name>: <parameter value> format. Any parameter value specified in such a way will override the parameter values specified either in the header section of the study batch file or as command line parameters.

Image details section#

Each image can have a number of parameters associated with it. They are listed as <key>(<value>) pairs separated by colon in the relevant sequence line. The keys currently in use are:

  • phenc – Phase Encoding direction (used for BOLD, SE and DWI images, overriding the hcp_bold_unwarpdir, hcp_seunwarpdir and hcp_dwi_PEdir parameters, respectively)

  • UnwarpDir – Unwarp direction (used for T1w and T2w images, overriding the hcp_unwarpdir parameter)

  • EchoSpacing - Echo Spacing (used for BOLD, SE, and DWI images, overriding the hcp_bold_echospacing, hcp_dwelltime, and hcp_dwi_dwelltime parameters, respectively; note that the value has to be provided in ms for DWI images and in seconds for BOLD and Spin-Echo images)

  • DwellTime – Dwell Time in seconds, overriding hcp_t1samplespacing and hcp_t2samplespacing parameters

  • se - the spin echo pair to use for distortion correction (integer)

  • filename – the exact (unique) name of the BOLD file

An example section from batch.txt file header, individual session section parameter specification and image details section:

--overwrite         : no
--parsesssions      : 1
--parelements       : 4
--hcp_seechospacing : 0.0006029
--hcp_unwarpdir     : y

---
session: OP386_baseline
subject: OP386
dicom: /data/my_study/sessions/OP386_baseline/dicom
raw_data: /data/my_study/sessions/OP386_baseline/nii
hpc: /data/my_study/sessions/OP386_baseline/hpc

age: 21
handedness: right
gender: male
group: control

institution: MR Imaging Center New Amsterdam
device: Siemens|Prisma_fit|123456

--hcp_brainsize : 150
--hcp_fs_no_conf2hires: TRUE

01: Survey
02: T1w:             T1w 0.7mm N2 : se(1): DwellTime(0.0000459): UnwarpDir(z)
03: T2w:             T2w 0.7mm N2 : se(1): DwellTime(0.0000066): UnwarpDir(z)
04: Survey
05: SE-FM-AP:        C-BOLD 3mm 48 2.5s FS-P   : se(1): phenc(AP):
06: SE-FM-PA:        C-BOLD 3mm 48 2.5s FS-A   : se(1): phenc(PA):
07: bold1:rest:      BOLD 3mm 48 2.5s          : se(1): phenc(PA): EchoSpacing(0.0006029): filename(rest_PA)
08: bold2:task:      BOLD 3mm 48 2.5s          : se(1): phenc(PA): EchoSpacing(0.0006029): filename(task1_PA)
09: bold2:task:      BOLD 3mm 48 2.5s          : se(1): phenc(PA): EchoSpacing(0.0006029): filename(task2_PA)

Use scenario#

If the following example call were made in combination with the above example batch.txt file:

qunex hcp_pre_freesurfer \
    --sessionsfolder=/data/mystudy/sessions \
    --batchfile=/data/mystudy/processing/batch.txt \
    --overwrite="yes" \
    --parsesssions=2

The following parameter values would be used:

  • hcp_unwarpdir=z

    as the per sequence value of UnwarpDir(z) would take precedence over general specification of _hcp_unwarpdir : y in the header section of the batch.txt file

  • parsesssions=2

    as the command line parameter --parsesssions=2 would take precedence over the _parsesssions : 1 specification in the header section of the batch.txt file

  • overwrite=yes

    as the command line parameter --overwrite="yes" would take precedence over the _overwrite : no specification in the header section of the batch.txt file

  • hcp_seechospacing=0.0006029

    as this information is not provided anywhere else but in the batch.txt header section