Mapping specification files
Mapping specification files#
The QuNex mapping file is an essential element of running QuNex and ensuring that the raw
nii data is onboarded correctly.
The mapping file allows QuNex to map generic
nii data inputs such that a given pipeline can be readily executed. For instance, the HCP pipelines have an idiosyncratic file I|O naming convention. This makes it hard for users to automate their workflows.
Here QuNex uses a
mapping file that provides an I|O "bridge" from raw
nii files to a given folder hierarchy expectation. Here we describe the implementation in the context of HCP minimal processing pipelines:
Specifically, to support correct mapping of
nii files to the
hcp folder hierarchy expectation for HCP pipelines, the
session.txt file has to be expanded, so that each acquired sequence is assigned a unique image descriptor (or "tag").
If a unique mapping is possible between the original acquisition sequence names and their image descriptors the
create_session_infocommand can be used to process the
session.txtfiles and automatically generate the resulting
session_<pipeline>.txtfiles (default name).
To use the
create_session_infocommand, a mapping specification file has to be provided. By default the
create_session_infocommand expects the mapping specification file to be present in:
A comprehensive description of the mapping specification for the Human Connectome Project (HCP) data hierarchy is contained in
~/qunex/python/qx_utilities/templates/hcp_mapping_example.txt. Upon creation of a new study via
create_studyan example mapping file will be generated in the default location for the user to examine.
Mapping File Grammar Specification#
Mapping file operation involves three files:
session.txt- session-specific sequence information containing sequence name and number after dcm2nii conversion.
MAPPING FILE -->
<pipeline>_mapping.txt- mapping specification file for a given study.
INPUTfiles this adjusted session-specific file will contain
sequence descriptor taginfo for data mapping into a user-specified naming convention.
<pipeline>_mapping.txt input files syntax#
The file should be a plain text file in which individual mappings are specified one per line:
<sequence_name | sequence_number> => <user_defined_sequence_descriptor_tag>
session_<pipeline>.txt output files syntax#
Plain text file with the following:
For further details on how to specify and use the mapping files please refer to a general overview on Preparing a study-level mapping file for QuNex workflows pipeline.
Also see more specific details in the context of Preparing data for the HCP pipeline pages.