map_bids2nii#

qx_utilities.general.bids.map_bids2nii(sourcefolder='.', overwrite='no', fileinfo=None, add_json_info='all', merge_multi_echo='no', _log=None)#

map_bids2nii [sourcefolder='.'] [overwrite='no'] [fileinfo='short'] [add_json_info='all'] [merge_multi_echo='no']

Maps BIDS organized data to QuNex nii folder.

Warning

File order:

The files are ordered according to best guess sorted primarily by modality. This can be problematic for further HCP processing when different fieldmap files are used for different BOLD and structural files. In the future version the files will be organized so that fieldmaps will precede the files to which they correspond, according to HCP processing expectations.

.bvec and .bval files:

.bvec and .bval files are expected to be present along with dwi files in each session folder. If they are only present in the main folder, they are currently not mapped to the .nii folder.

Image format:

The function assumes that all the images are saved as .nii.gz files!

Parameters

--sourcefolder (str, default '.'):

The base session folder in which bids folder with data and files for the session is present.

--overwrite (str, default 'no'):

Parameter that specifies what should be done in cases where there are existing data stored in nii folder. The options are:

  • 'no' ... do not overwrite the data, skip session

  • 'yes' ... remove existing files in nii folder and redo the mapping.

--fileinfo (str, default 'short'):

What file information to include in the session.txt file. Options are:

  • 'short' ... only provide the short description based on the identified BIDS tags

  • 'full' ... list the full file name excluding the participant id, session name and extension.

--add_json_info (str, default 'all'):

A comma or space separated string, listing which info present in .json sidecar files to include in the sequence information. Options are:

  • phenc ... phase encoding direction

  • DwellTime

  • UnwarpDir ... unwarp direction

  • EchoSpacing

  • 'all' ... all of the above listed information, if present in the .json sidecar file.

--merge_multi_echo (str, default 'no'):

Whether to merge multi-echo BOLD and sbref files into a single 4D image. If set to 'yes', the echoes will be merged using fslmerge -t and the resulting file will be mapped to the nii folder.

Output files

After running the mapped nifti files will be in the nii subfolder, named with sequential image number. session.txt will be in the base session folder and bids2nii.log will be in the bids folder.

session.txt file:

The session.txt will be placed in the session base folder. It will contain the information about the session id, subject id location of folders and a list of created NIfTI images with their description.

An example session.txt file would be:

id: 06_retest
subject: 06
bids: /Volumes/tigr/MBLab/fMRI/bidsTest/sessions/06_retest/bids
raw_data: /Volumes/tigr/MBLab/fMRI/bidsTest/sessions/06_retest/nii
hcp: /Volumes/tigr/MBLab/fMRI/bidsTest/sessions/06_retest/hcp

01: T1w
02: bold covertverbgeneration
03: bold fingerfootlips
04: bold linebisection
05: bold overtverbgeneration
06: bold overtwordrepetition
07: dwi

For each of the listed images there will be a corresponding NIfTI file in the nii subfolder (e.g. 04.nii.gz for the line bisection BOLD sequence). The generated session.txt files form the basis for the following HCP and other processing steps. id field will be set to the full session name, subject will be set to the text preceeding the underscore (_) character.

bids2nii.log file:

The bids2nii.log provides the information about the date and time the files were mapped and the exact information about which specific file from the bids folder was mapped to which file in the nii folder.

Notes

The command is used to map data organized according to BIDS specification, residing in bids session subfolder to nii folder as expected by QuNex functions. The command checks the imaging data and compiles a list in the following order:

  • anatomical images

  • fieldmap images

  • functional images

  • diffusion weighted images.

Once the list is compiled, the files are mapped to nii folder to files named by ordinal number of the image in the list. To save space, files are not copied but rather hard links are created. Only image, bvec and bval files are mapped from the bids to nii folder. The exact mapping is noted in file bids2nii.log that is saved to the bids folder. The information on images is also compiled in session.txt file that is generated in the main session folder. For every image all the information present in the bids filename is listed.

Multiple sessions and scheduling:

The command can be run for multiple sessions by specifying sessions and optionally sessionsfolder and parsessions parameters. In this case the command will be run for each of the specified sessions in the sessionsfolder (current directory by default). sessions limits the run to the specified id codes, and an optional filter parameter selects the sessions whose batch file entry matches a key. (for more information see online documentation). sourcefolder will be filled in automatically as each session's folder. Commands will run in parallel where the degree of parallelism is determined by parsessions (1 by default).

If scheduler parameter is set, the command will be run using the specified scheduler settings (see qunex schedule --help for more information). If set in combination with sessions parameter, sessions will be processed over multiple nodes, core parameter specifying how many sessions to run per node. Optional scheduler_environment, scheduler_workdir, scheduler_sleep, and nprocess parameters can be set.

Set optional logfolder parameter to specify where the processing logs should be stored. Otherwise the processor will make best guess, where the logs should go.

Do note that as this command only performs file mapping and no image or file processing, the best performance might be achieved by running on a single node and a single core.

Examples

qunex map_bids2nii \
    --folder=. \
    --overwrite=yes