map_hcpls2nii#

qx_utilities.hcp.import_hcp.map_hcpls2nii(sourcefolder='.', overwrite='no', report=None, filesort=None, _log=None)#

map_hcpls2nii [sourcefolder='.'] [overwrite='no'] [report=<study>/info/hcpls/parameters.txt] [filesort=<file sorting option>]

Map HCPLS organized data to nii folder structure.

Warning

.bvec and .bval files:

.bvec and .bval files are expected to be present along with dMRI files in each session folder. If they are present in another 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 are present.

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

Whether to overwrite existing data (yes) or not (no). Note that previous data is deleted before the run, so in the case of a failed command run, previous results are lost.

--report (str, default None):

The path to the file that will hold the information about the images that are relevant for HCP Pipelines. Will not write it by default.

--filesort (str, default 'name_type_se'):

An optional parameter that specifies how the files should be sorted before mapping to nii folder and inclusion in session_hcp.txt. The sorting is specified by a string of sort keys separated by '_'.

The available sort keys are:

  • 'name' ... sort by the name of the file

  • 'type' ... sort by the type of the file (T1w, T2w, rfMRI, tfMRI, Diffusion

  • 'se' ... sort by the number of the related pair of the SE fieldmap images.

The files will be sorted in the order of the listed keys.

NOTE:

  • SE field map pair will always come before the first image in the sorted list that references it.

  • Diffusion images will always be listed jointly in a fixed order.

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 hcpls2nii.log will be in the hcpls 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
hcpls: /Volumes/tigr/MBLab/fMRI/bidsTest/sessions/06_retest/hcpls
raw_data: /Volumes/tigr/MBLab/fMRI/bidsTest/sessions/06_retest/nii
hcp: /Volumes/tigr/MBLab/fMRI/bidsTest/sessions/06_retest/hcp

01: T1w
02: bold1:rest1
03: bold2:rest1
04: bold3:rest2
05: bold4:rest2
06: bold5:CARIT
07: bold6:FACENAME
08: bold7:VISMOTOR
09: dwi

For each of the listed images there will be a corresponding NIfTI file in the nii subfolder (e.g. 04.nii.gz for resting state 2 PA). 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 first underscore (_) character.

hcpls2nii.log file:

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

Notes

The command is used to map data organized according to HCPLS specification, residing in hcpls 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 hcpls to nii folder. The exact mapping is noted in file hcpls2nii.log that is saved to the hcpls 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 hcpls 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 sessions'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_hcpls2nii \
    --folder=. \
    --overwrite=yes

qunex map_hcpls2nii \
    --sessionsfolder="/data/my_study/sessions" \
    --sessions="AP*" \
    --overwrite=yes