On specification of processing parameters#

QuNex commands make use of a large number of parameters — the HCP Pipelines, the additional functional processing of images, and the utility commands that prepare and inspect the data all take their own. Rather than requiring every one of them on every call, QuNex lets you state a value once, at whatever level it belongs to, and picks it up from there.

A parameter value can be specified at five levels. In order of priority, from lowest to highest, they are:

  • the command's own default value

  • the header section of the study batch file

  • the recipe file, when the command is run as a step of a run_recipe call

  • the command line

  • the session section of the study batch file

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

The rule that governs them is simple to state: each level fills a value in, and never overrides one given at a higher level. So a parameter you type on the command line is used as you typed it, whatever the batch file says; and a parameter nobody mentions anywhere keeps the command's own default.

Two things are worth knowing before the details.

These levels apply to every command. The batch file's header is not read only by the HCP pipelines. Any command you give a --batchfile to picks up the parameters it recognises from that file's header, which is what makes the header a good place to record the settings that hold for a whole study. Parameters in the header that a particular command does not take are simply not passed to it.

Every run tells you what it used. You do not have to work the precedence out by hand — each run opens by printing the parameters the command is about to be run with and where each value came from. See What a run reports at the end of this page.

The command's default value#

Every parameter has a default, documented in the command's own help (qunex <command> --help). This is what is used when nothing else states a value, and it is why you only need to specify the parameters you actually want to change.

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

What a run reports#

Working the precedence out by hand is rarely necessary, because every run opens by printing the parameters the command is about to be run with, each one next to the level its value came from:

---> Parameters for hcp_pre_freesurfer

     parameter        source         value
     ---------------------------------------------------------------
     batchfile        command line   /study/processing/batch.txt
     hcp_brainsize    batch file     170
     hcp_t2           batch file     NONE
     overwrite        default        False

The source column names the level, using the same names as the sections above: default, batch file, recipe, command line, and batch file (session) for a value the batch file states for one session alone.

Where a session's own section overrides something, that is reported inside the session, so you can see it against the run it applies to:

---> Parameters for hcp_pre_freesurfer on session OP386_baseline

     parameter       source                 value
     --------------------------------------------------
     hcp_brainsize   batch file (session)   150

The same table is written into the run's log file and into the command's log, so what a run used is a matter of record rather than something to be reconstructed afterwards.

This is also the quickest way to check a study's setup. Processing commands accept a --test flag, which resolves everything and reports what the command would do without doing it — so you can read the table, correct the batch file, and only then commit a long pipeline to it.