map_nii2bids#

qx_utilities.general.bids.map_nii2bids(sinfo, options, overwrite=False, action='hardlink', session_mapping_file=None)#

map_nii2bids [batchfile=''] [sessionsfolder='.'] [sessions=''] [overwrite='no'] [action='hardlink'] [session_mapping_file=None]

Maps data from the nii folder to the bids folder. Requires session_hcp.txt files. Entities (key-value) pairs should be specified by the user in hcp_mapping.txt file and session_hcp.txt should be created using the create_session_info function. Suffix is inferred from data, but can be specified manually in case of ambiguity (e.g. for fieldmaps).

In case session name contains non-alphanumeric characters, these characters will be replaced with 'x' in the BIDS session name.

See examples below for details.

Parameters

--batchfile (str, default ''):

The batch.txt file with all the sessions information.

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

The path to the study/sessions folder, where the imaging data is supposed to go.

--sessions (str, ''):

The comma separated list of sessions to process. If not specified, all sessions will be processed.

--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 bids folder and redo the mapping.

--action (str, default 'hardlink'):

The type of link that should be used for linking the files from nii to bids folder. The options are:

  • 'hardlink' ... use hard links to link the files

  • 'copy' ... copy the files to the bids folder

--session_mapping_file (str, default None):

The path to the session mapping file in yaml format. Can be used for cases where original session name is not BIDS compliant, see example below. If not specified, the mapping will be done based on the session name.

Examples

We have session_hcp.txt with following content:

session: 01_1
subject: 01
...
7   :FM-Magnitude    :FM magnitude2: run(2): fm(2): suffix(magnitude2)
...
11  :bold3:rest      : acq(fullbrain): run(2): fm(2)

We run the following command:

qunex map_nii2bids               --sourcefolder="/data/studies/fMRI/import_bids_test/sessions/01_1"               --overwrite='yes'

In this example, the following mappings are performed:

  • 7.nii.gz --> sub-01_ses-1_run-2_magnitude2.nii.gz

Note that the suffix has been explicitly defined as magnitude2, otherwise it would implicitly be set to magnitude.

  • 11.nii.gz --> sub-01_ses-1_task-rest_acq-fullbrain_run-1_bold.nii.gz

In this case suffix was inferred from the image type. Key-value pairs not defined in BIDS are ignored (e.g. fm in the above case)

Note that optional BIDS entities (e.g. acq and run) should be specified manually as key-value pairs in hcp_mapping.txt.

If the session name contains non-alphanumeric characters, they will be replaced with 'x' in the BIDS session name. However, if the session name is specified in the session_mapping_file, the session name will be remapped according to the mapping file.

Session mapping file example:

'01':
  '01_1': 'first'
  '01_2': 'second'

In this case, subject name is '01' and session name is '01_1'. The session name will be remapped to 'first' according to the session_mapping_file, and the BIDS session name will be 'sub-01_ses-first'.