HCP Pipeline Mapping in QuNex
Contents
HCP Pipeline Mapping in QuNex#
To be able to process neuroimaging data, the HCP minimal processing pipeline needs to be provided with the correct files. When importing data to QuNex—e.g. from raw DICOM files—the information about the session is recorded in the session acquisition information files, or session.txt
. The information stored, however, often does not enable automatic identification of the image types, e.g., which sequence to use as a high-resolution T1w structural image for atlas registration and brain tissue segmentation. To enable easy and robust identification of sequences, these session.txt
files are converted to HCP session pipeline information files (session_hcp.txt
) by adding descriptors that identify sequence type and (in the case of BOLD and DWI images) provide additional relevant information.
The QuNex session file (session.txt
)#
Session acqusition information files, or QuNex session files, are text files. They are expected to be present in each <study>/sessions/<session id>
folder, and are usually automatically generated on data import (eg. import_dicom
). For an overview of the format, please see information on session acquisition information files. Below is an example of what one might look like:
session: <session_id>
subject: <subject_id>
dicom: <path_to_study_folder/sessions/<session_id>/dicom
raw_data: <path_to_study_folder/sessions/<session_id>/nii
hcp: <path_to_study_folder/sessions/<session_id>/hcp
11: SequenceName_for_Localizer
21: SequenceName_for_T1_Scan
31: SequenceName_for_T2_Scan
41: SequenceName_for_SpinEchoDirection_AnteriorPosterior
51: SequenceName_for_SpinEchoDirection_PosteriorAnterior
61: SequenceName_for_BOLD_Task_SingleBandReference
71: SequenceName_for_BOLD_Task
81: SequenceName_for_BOLD_Rest_SingleBandReference
91: SequenceName_for_BOLD_Rest
101: SequenceName_for_DiffusionSequenceDirection_AnteriorPosterior_90directions
111: SequenceName_for_DiffusionSequenceDirection_PosteriorAnterior_90directions
121: SequenceName_for_DiffusionSequenceDirection_AnteriorPosterior_91directions
131: SequenceName_for_DiffusionSequenceDirection_PosteriorAnterior_91directions
HCP session pipeline information file (session_hcp.txt
)#
Similar to QuNex session files, HCP session pipeline information files, or HCP session files, are expected to be present in each <study>/sessions/<session id>
folder. These files are created by adapting the QuNex session file, and can be done so manually or in batches by using a mapping file in conjunction with create_session_info
.
Each of the images collected that are to be used and processed via the HCP pipeline need to be described using standard names, which are used for proper HCP folder mapping. For a table of accepted HCP tags, see HCP descriptor tags below.
For each individual image you want to process, you must add the above standard names where appropriate. So, in the case of the previous example, the new session_hcp.txt
file would look like:
session: <session_id>
subject: <subject_id>
dicom: <path_to_study_folder/sessions/<session_id>/dicom
raw_data: <path_to_study_folder/sessions/<session_id>/nii
hcp: <path_to_study_folder/sessions/<session_id>/hcp
hcpready: true
11: :SequenceName_for_Localizer
21: T1w :SequenceName_for_T1_Scan
31: T2w :SequenceName_for_T2_Scan
41: SE-FM-AP :SequenceName_for_SpinEchoDirection_AnteriorPosterior
51: SE-FM-PA :SequenceName_for_SpinEchoDirection_PosteriorAnterior
61: boldref1:task :SequenceName_for_BOLD_Task_SingleBandReference
71: bold1:task :SequenceName_for_BOLD_Task
81: boldref2:rest :SequenceName_for_BOLD_Rest_SingleBandReference
91: bold2:rest :SequenceName_for_BOLD_Rest
101: DWI:dir90_AP :SequenceName_for_DiffusionSequenceDirection_AnteriorPosterior_90directions
111: DWI:dir90_PA :SequenceName_for_DiffusionSequenceDirection_PosteriorAnterior_90directions
121: DWI:dir91_AP :SequenceName_for_DiffusionSequenceDirection_AnteriorPosterior_91directions
131: DWI:dir91_PA :SequenceName_for_DiffusionSequenceDirection_PosteriorAnterior_91directions
*Note that BOLD files have a sequential number appended to bold
specification. This is the number that will be used in many of the QuNex commands and functions. Each BOLD needs to have a unique number, preferentially starting with 1 and increasing in a sequential order. In addition each BOLD file also has an additional descriptor specifying the kind of BOLD that was recorded (task
, control
and rest
above). These descriptors can be used in the QuNex commands to specify which BOLD files to run specific steps on. Finally, note that for DWI data there is a specification that denotes number of directions and the phase-encoding direction (e.g. dir90_PA).
Once generated for each session, these files are then used by the setup_hcp
command to copy and map imported session images (located in <study>/sessions/<session id>/nii
) into an HCP friendly folder structure inside the session folder (<study>/sessions/<session id>/hcp/<session id>
)
HCP session file creation using a mapping file#
Though the above file can be created manually, the process can be simplified using the create_session_info
command.
This command produces the HCP session file, by default session_hcp.txt
, in each session directory.
To run, the create_session_info
command needs 2 plain text input files. The first, sourcefile
, is the aformentioned QuNex session file containing sequence/image names and numbers. This file should automatically be generated upon using a QuNex data import command.
The second, mapping
, must be created by the user. This will be used to assign each sequence to the corresponding standard name specified in your mapping file. This is particularly useful if each sequence name uniquely pairs with an HCP descriptor.
The default location of this mapping file is
/<path_to_sessions_folder>/sessions/specs/
. When the initial QuNex study hierarchy is generated usingcreate_study
, an example mapping text file will be generated here to allow users to proceed.If not specified otherwise, the command will look for the
/<path_to_sessions_folder>/sessions/specs/hcp_mapping.txt
.
Example mapping file#
To create the above HCP session file based off the provided example QuNex session file, one would create the following mapping file:
SequenceName_for_T1_Scan => T1w
SequenceName_for_T2_Scan => T2w
SequenceName_for_SpinEchoDirection_AnteriorPosterior => SE-FM-AP
SequenceName_for_SpinEchoDirection_PosteriorAnterior => SE-FM-PA
SequenceName_for_BOLD_Task_SingleBandReference => boldref:task
SequenceName_for_BOLD_Task => bold:task
SequenceName_for_BOLD_Rest_SingleBandReference => boldref:rest
SequenceName_for_BOLD_Rest => bold:rest
SequenceName_for_DiffusionSequenceDirection_AnteriorPosterior_90directions => DWI:dir90_AP
SequenceName_for_DiffusionSequenceDirection_PosteriorAnterior_90directions => DWI:dir90_PA
SequenceName_for_DiffusionSequenceDirection_AnteriorPosterior_91directions => DWI:dir91_AP
SequenceName_for_DiffusionSequenceDirection_PosteriorAnterior_91directions => DWI:dir91_PA
Creating the mapping file#
General mapping guidelines#
The file should be a plain text file in which individual mappings are specified one per line:
SequenceName_for_T1_Scan => T1w
Lines that include
=>
will be interpreted as mapping descriptions with the convention<string_a> => <string_b>
The
<string_a>
before the=>
is mapped to<string_b>
.Any spaces before or after each string are ignored.
Any lines not including
=>
or starting with#
are ignored.Multiple sources for the same target can be specified.
Sequences can be mapped by specifying a unique sequence name that can be obtained from the session.txt
file to be assigned a unique user defined sequence descriptor tag:
<sequence_name> => <user_defined_sequence_descriptor_tag>
SequenceName_for_T1_Scan => T1w
-> the following line specifies that the sequence namedSequenceName_for_T1_Scan
will be mapped to the descriptor tagT1w
.Note that if using the <sequence_name> specification in the mapping file then this sequence has to always be associated with the same name throughout the study across all sessions and subjects.
If a unique paring between <sequence_name> and an HCP descriptor tag is not possible, the sequence can be identified using the unique number (often the order of acquisition) that can be obtained from the session.txt
file to be assigned a unique user defined sequence descriptor tag:
<sequence_number> => <user_defined_sequence_descriptor_tag>
20 => T1w
-> the following line specifies that the acquisition sequence in the session that is associated with the number20
will always be mapped to the sequence descriptor tagT1w
across all sessions.
Sometimes, it is not possible to uniquely map all sequences for a study using just one mapping (For example, some sessions may have an additional T1w
scan due to scan interruption or poor quality). In these situations, users are encouraged to create multiple mapping files and selectively run create_session_info
on the appropriate sessions.
Functional data mapping#
In the case of BOLD sequences mapping can become more complicated, as users will also want to specifiy additional sequence info:
<sequence_name OR sequence_number> => <user_defined_sequence_descriptor_tag>:[<user_defined_sequence_info>:]
SequenceName_for_BOLD_Rest => bold:rest
-> the following line specifies that the acquisition sequence calledSequenceName_for_BOLD_Rest
will always be mapped to the sequence descriptor tagbold:rest
across all sessions wherebold
represents the<user_defined_sequence_descriptor_tag>
andrest
represents the optional user defined<sequence_info>
.You will also want to do the same with the corresponding reference if present:
SequenceName_for_BOLD_Task_SingleBandReference => boldref:task
.The number of the BOLD image should not be provided as it is added automatically. The number can be explicitly specified under certain conditions (see the section below).
For BOLD images the mapping file can handle
SpinEcho
field maps. When runningcreate_session_info
these(<pair number>)
will be added automatically using the following logic:the first spin-echo pair will be assigned number 1,
the next spin-echo pair will be assigned number 2, etc.
structural and functional images will be assigned the number of the immediately preceding spin-echo pair
if no spin-echo pair was present before the structural or functional image, it will be assigned the number of the first following spin-echo pair.
Similarly, if EPI fieldmaps are present (for Siemens this would be a pair of images tagged as
FM-Magnitude
andFM-Phase
, or a singleFM-GE
image), then these images will be assigned afm(<pair number>)
descriptor, and structural and functional images will receive the same descriptor using the logic described above.
Please note that the logic for associating spin-echo and EPI sequence-based field map images
depends on the images being listed in the order they were acquired. This might not be the case if
the session.txt
file was not generated by QuNex when importing DICOM or PAR/REC files. For
instance, if the session.txt
file was generated when importing images from BIDS datasets, the order
of the files is determined by image modalities, image types, and BIDS labels since sequence numbers
might not be available or can't be reliably extracted. In this case, the automatic assignment feature
should not be used when there are multiple field map images. Currently, the automatic assignment of
fm([N])
and se([N])
can be augmented if that information is provided in the session.txt
file or the mapping file, and the exact semantics is described in this section.
Explicitly assigning bold numbers#
By default, QuNex sequentially assigns a bold number to each bold image, starting from 1.
Internally, QuNex uses the bold tag (e.g., in bold1:rest
rest is the bold tag) to select and
filter bold scans for processing. However, this behavior can be overridden by defining the
bold_num(<N>)
tag for certain BOLD scans in the mapping file. For BOLD scans mapped without the
bold_num
tag, their bold number will still be assigned sequentially starting from 1, and any
number used in the bold_num(<N>)
tag will be skipped.
*Note this will only work if the bold number can be uniquely assigned to a single BOLD scan.
For example, consider the following three sessions:
session: sess01
...
11: TASK1
21: TASK2
31: REST
41: REST
session: sess02
...
11: TASK2
21: REST
session: sess03
...
11: TASK2
21: REST
31: REST
41: REST
By defining the bold_num
tag in the following mapping file, it is possible to achieve more
consistent bold numbering across sessions.
TASK1 => bold:task1 : bold_num(3)
TASK2 => bold:task2 : bold_num(4)
REST => bold:rest
With this mapping file, TASK1
scans will always get the bold number 3 and TASK2
scans will
always get the bold number 4.
session: sess01
...
11: bold3:task1 : TASK1
21: bold4:task2 : TASK2
31: bold1:rest : REST
41: bold2:rest : REST
session: sess02
...
11: bold4:task2 : TASK2
21: bold1:rest : REST
In this case, image 04
gets bold5
because bold3
is reserved for TASK1
in the mapping file.
session: sess03
...
11: bold4:task2 : TASK2
21: bold1:rest : REST
31: bold2:rest : REST
41: bold5:rest : REST
Explicitly associating field maps#
The algorithm automatically associating field maps with structural and functional images has two
phases. The first phase identifies valid consecutive field map pairs with associativity that favors
field maps appearing later. Specifically, in the following example, both 11/21 and 21/31 can be
considered a valid pair. Here we favor the latter case since it is more common. The field map pairs
are numbered sequentially, starting from one(1), and spin-echo (se
) and EPI field maps (fm
) are
numbered separately.
# mapping
SpinEcho_AP => SE-FM-AP
SpinEcho_PA => SE-FM-PA
# session_hcp
session: sess01
...
11: : SpinEcho_PA
21: SE-FM-AP : SpinEcho_AP : se(1)
31: SE-FM-PA : SpinEcho_PA : se(1)
The second phase of the algorithm associates field map pairs identified in the previous step with other images with the logic described in previous sections.
The se
/fm
descriptors can be added to session and mapping files. User-defined se/fm descriptors
are treated differently when defined on field map images versus structural and functional images.
If any se/fm descriptors are defined on spin-echo or EPI field map images, the first phase of the
algorithm will not execute, so only user-defined se
/fm
descriptors will be used. The se
/fm
descriptors defined on structural/functional images do not affect the first stage of the algorithm
in any way.
During the second phase, if se
/fm
descriptors are defined on structural and functional images,
we will verify that the referred field map pair exists. Otherwise, we will follow the same rule as
described previously. By allowing custom field map pairing, the images in a pair are no longer
guaranteed to be consecutive. We define relative order between field maps and other images by only
looking at the position of the first image in a field map pair.