- qx_utilities.general.bids.import_bids(sessionsfolder=None, inbox=None, sessions=None, action='link', overwrite='no', archive='move', bidsname=None, fileinfo=None)#
import_bids [sessionsfolder=.] [inbox=<sessionsfolder>/inbox/BIDS] [sessions="*"] [action=link] [overwrite=no] [archive=move] [bidsname=<inbox folder name>] [fileinfo=short]
Maps a BIDS dataset to the QuNex Suite file structure.
- --sessionsfolder (str, default '.'):
The sessions folder where all the sessions are to be mapped to. It should be a folder within the <study folder>.
- --inbox (str, default <sessionsfolder>/inbox/BIDS):
The location of the BIDS dataset. It can be any of the following: the BIDS dataset top folder, a folder that contains the BIDS dataset, a path to the compressed .zip or .tar.gz package that can contain a single session or a multi-session dataset, or a folder that contains a compressed package. For instance the user can specify "<path>/<bids_file>.zip" or "<path>" to a folder that contains multiple packages. The default location where the command will look for a BIDS dataset is.
- --sessions (str, optional):
An optional parameter that specifies a comma or pipe separated list of sessions from the inbox folder to be processed. Glob patterns can be used. If provided, only packets or folders within the inbox that match the list of sessions will be processed. If inbox is a file sessions has to be a list of session specifications, only those sessions that match the list will be processed. If inbox is a valid bids datastructure folder or archive, then the sessions can be specified either in <subject id>[_<session name>] format or as explicit sub-<subject id>[/ses-<session name>] names.
- --action (str, default 'link'):
How to map the files to QuNex structure. These are the options:
'link' ... the files will be mapped by creating hard links if possible, otherwise they will be copied
'copy' ... the files will be copied
'move' ... the files will be moved.
- --overwrite (str, default 'no'):
The parameter specifies what should be done with data that already exists in the locations to which bids data would be mapped to. Options are:
'no' ... do not overwrite the data and skip processing of the session
'yes' ... remove existing files in nii folder and redo the mapping.
- --archive (str, default 'move'):
What to do with the files after they were mapped. Options are:
'leave' ... leave the specified archive where it is
'move' ... move the specified archive to <sessionsfolder>/archive/BIDS
'copy' ... copy the specified archive to <sessionsfolder>/archive/BIDS
'delete' ... delete the archive after processing if no errors were identified.
Please note that there can be an interaction with the action parameter. If files are moved during action, they will be missing if archive is set to 'move' or 'copy'.
- --bidsname (str, default detailed below):
The optional name of the BIDS dataset. If not provided it will be set to the name of the inbox folder or the name of the compressed package.
- --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.
After running the import_bids command the BIDS dataset will be mapped to the QuNex folder structure and image files will be prepared for further processing along with required metadata.
Files pertaining to the study and not specific subject / session are stored in:
<study folder>/info/bids/<bids bame>
The original BIDS session-level data is stored in:
Image files mapped to new names for QuNex are stored in:
The full description of the mapped files is in:
The output log of BIDS mapping is in:
The study-level BIDS files are in:
The import_bids command consists of two steps:
- Step 1 - Mapping BIDS dataset to QuNex Suite folder structure:
The inbox parameter specifies the location of the BIDS dataset. This path is inspected for a BIDS compliant dataset. The path can point to a folder with extracted BIDS dataset, a .zip or .tar.gz archive or a folder containing one or more .zip or .tar.gz archives. In the initial step, each file found will be assigned either to a specific session or the overall study.
The BIDS files assigned to the study will be saved in the following location:
<bids_dataset_name> can be provided as a bidsname parameter to the command call. If bidsname is not provided, the name will be set to the name of the parent folder or the name of the compressed archive.
The files identified as belonging to a specific session will be mapped to folder:
The <subject>_<session> string will be used as the identifier for the session in all the following steps. If no session is specified in BIDS, session will be the same as subject. If the folder for the session does not exist, it will be created.
When the files are mapped, their filenames will be preserved and the correct folder structure will be reconstructed if it was previously flattened.
- Behavioral data:
Upon import of the BIDS dataset, the behavioral and participant specific data present in the <bids_study>/participants.tsv and <bids_study>/phenotype/*.tsv files, is parsed and split so that data belonging to a specific participant is mapped to that participant's sessions behavior folder (e.g. <QuNex study folder>/sessions/s14_01/behavior/masq01.tsv). In this way the session folder contains all the behavioral data relevant for that participant.
- Step 2 - Mapping image files to QuNex Suite nii folder:
For each session separately, images from the bids folder are mapped to the nii folder and appropriate session.txt file is created per standard QuNex specification.
The second step is achieved by running map_bids2nii on each session folder. This step is run automatically, but can be invoked indepdendently if mapping of bids dataset to QuNex Suite folder structure was already completed. For detailed information about this step, please review map_bids2nii inline help.
- Extra notes:
Please see map_bids2nii inline documentation!
qunex import_bids \ --sessionsfolder="<absolute path to study folder>/sessions" \ --inbox="<absolute path to folder with bids dataset>" \ --archive=move \ --overwrite=yes
The above command would map the entire BIDS dataset located at the specified location into the relevant sessions' folders—creating them when needed—, organize the MR image files in the sessions' nii folder and prepare session.txt file for further processing. Any preexisting data for the sessions present in the BIDS dataset would be removed and replaced. By default, the BIDS files would be hard-linked to the new location.
qunex import_bids \ --sessionsfolder="<absolute path to study folder>/sessions" \ --inbox="<absolute path to folder with bids dataset>" \ --action='copy' \ --archive='leave' \ --overwrite=no
The above command would map the entire BIDS dataset located at the specified location into the relevant sessions' folders—creating them when needed—, organize the MR image files in the sessions' nii folder and prepare session.txt file for further processing. If for any of the sessions bids mapped data already exist, that session will be skipped when processing. The files would be mapped to their destinations by creating a copy rather than hard-linking them.
qunex import_bids \ --sessionsfolder="<absolute path to study folder>/sessions" \ --inbox="<absolute path to folder with bids dataset>" \ --action='copy' \ --archive='leave' \ --overwrite=no \ --fileinfo=full
In the example above, by specifying the --fileinfo parameter as "full" the whole file name (with the exception of the participant id, the session name and the extension) will be printed for each image file in the session.txt file. Use this parameter if file names are not matching the BIDS standard completely and hold important information for later correct file handling.
qunex import_bids \ --sessionsfolder=myStudy \ --overwrite=yes \ --bidsname=swga