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. In other words, it provides QuNex with additional imaging information that is required by processing pipelines and cannot be reliably extracted from the imaging data. For this purpose, QuNex uses a mapping file that provides a "bridge" from raw nii files to a given folder hierarchy expectation. In other words, we need to write the mapping file in order to inject additional information about images that is later on required by processing commands. In this document, 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_info command can be used to process the session.txt files and automatically generate the resulting session_<pipeline>.txt files (default name).

  • To use the create_session_info command, a mapping specification file has to be provided. By default the create_session_info command expects the mapping specification file to be present in: <study folder>/sessions/specs/<pipeline>_mapping.txt.

  • 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_study an 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:

  • INPUT --> 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.

  • OUTPUT --> session_<pipeline>.txt- after create_session_info on INPUT files this adjusted session-specific file will contain sequence name|number and sequence descriptor tag info for data mapping into a user-specified naming convention.

Specification for <pipeline>_mapping.txt input files syntax#

  • The file should be a plain text file stored anywhere that QuNex can access it, in the file individual mappings are specified, one per line:

<sequence_name | sequence_number> => <user_defined_sequence_descriptor_tag>

Specification for session_<pipeline>.txt output files syntax#

  • Plain text file with the following:

<sequence_number>:<user_defined_sequence_descriptor_tag>:[<user_defined_sequence_info>:]<sequence_name>