convert_source package

Submodules

convert_source.batch_convert module

Batch conversion wrapper and its associated classes and functions for the convert_source package.

convert_source.batch_convert.batch_proc(study_img_dir, out_dir, config_file, path_envs=[], gzip=True, append_dwi_info=True, zero_pad=2, cprss_lvl=6, verbose=False, env={}, dryrun=False)

Batch processes a study’s source image data provided a configuration, the parent directory of the study’s imaging data, and an output directory to place the BIDS NIFTI data.

Usage example:
>>> subs_bids_data = batch_proc(config_file,
...                             study_img_dir,
...                             out_dir)
...
Parameters

  • study_img_dir (str) – Path to study image parent directory that contains all the subjects’ source image data.

  • out_dir (str) – Output directory.

  • config_file (str) – Configuration file.

  • path_envs (List[str]) – List of directory paths to append to the system’s ‘PATH’ variable.

  • gzip (bool) – Gzip output NIFTI files.

  • append_dwi_info (bool) – RECOMMENDED: Appends DWI acquisition information (unique non-zero b-values, and TE, in msec.) to BIDS acquisition filename.

  • zero_pad (int) – Number of zeroes to pad the run number up to (zero_pad=2 is ‘01’).

  • cprss_lvl (int) – Compression level [1 - 9] - 1 is fastest, 9 is smallest.

  • verbose (bool) – Enable verbose output.

  • env (Optional[Dict]) – Path environment dictionary.

  • dryrun (bool) – Perform dryrun (creates the command, but does not execute it).

Returns

  • List of NIFTI images.

  • Corresponding list of JSON sidecars.

  • Corresponding list of bval files.

  • Corresponding list of bvec files.

Return type

Tuple of lists that consists of

convert_source.batch_convert.bids_id(s, search_dict, bids_search=None, bids_map=None, bids_name_dict=None, parent_dir='', modality_type='', modality_label='', task='', mod_found=False)

Performs identification of descriptive BIDS information relevant for file naming, provided a BIDS search dictionary and a BIDS map dictionary. The resulting information is then placed in nested dictionary of BIDS related descriptive terms.

Usage example:
>>> bids_example_dict = bids_id("ImageFile00001.dcm")
Parameters

  • s (str) – Input str/file to be searched.

  • search_dict (Dict) – Dictionary of modality specific search terms.

  • bids_search (Optional[Dict]) – Dictionary of BIDS specific search terms.

  • bids_map (Optional[Dict]) – Dictionary of BIDS related terms to be mapped to BIDS search terms.

  • bids_name_dict (Optional[Dict]) – Existing BIDS name dictionary. If provided, an updated copy of this dictionary is returned.

  • parent_dir (Optional[str]) – Parent or study image directory of the image file. This path is removed from the string search to prevent false positives.

  • modality_type (Optional[str]) – (BIDS) modality type (e.g. ‘anat’, ‘func’, etc).

  • modality_label (Optional[str]) – (BIDS) modality label (e.g. ‘T1w’, ‘bold’, etc).

  • task (Optional[str]) – (BIDS) task label (e.g. ‘rest’,’nback’, etc).

  • mod_found (bool) – Boolean value that indicates if the (BIDS) modality or matching modality has been identified/found.

Returns

  • Nested dictionary of BIDS descriptive naming related terms.

  • Modality type.

  • Modality label.

  • Task label.

Return type

Tuple that consists of

convert_source.batch_convert.bids_ignore(out_dir)

Writes ‘.bidsignore’ file. This file functions similarly to the ‘.gitignore’ file.

Usage example:
>>> ignore = bids_ignore(out_dir)
Parameters

out_dir (str) – Output directory to place the file.

Return type

str

Returns

String of the file path to the ‘.bidsignore’ file.

convert_source.batch_convert.data_to_bids(sub_data, bids_name_dict, out_dir, modality_type='', modality_label='', task='', meta_dict={}, mod_dict={}, gzip=True, append_dwi_info=True, zero_pad=2, cprss_lvl=6, verbose=False, log=None, env={}, dryrun=False)

Converts source data to BIDS compliant data. This functions also renames already existing NIFTI data so that it can be BIDS compliant.

Usage example:
>>> [imgs, jsons, bvals, bvecs] = data_to_bids(sub_obj,
...                                            bids_name_dict,
...                                            output_dir,
...                                            'anat',
...                                            'T1w')
...
Parameters

  • sub_data (SubDataInfo) – Subject data information object.

  • bids_name_dict (Dict) – BIDS name dictionary.

  • out_dir (str) – Output directory.

  • modality_type (Optional[str]) – Modality type (BIDS label e.g. ‘anat’, ‘func’, etc).

  • modality_label (Optional[str]) – Modality label (BIDS label e.g. ‘T1w’, ‘bold’, etc).

  • task (Optional[str]) – Task label (BIDS filename task label, e.g. ‘rest’, ‘nback’, etc.)

  • meta_dict (Optional[Dict]) – BIDS common metadata dictoinary.

  • mod_dict (Optional[Dict]) – Modality specific metadata dictionary.

  • gzip (bool) – Gzip output NIFTI files.

  • append_dwi_info (bool) – Appends DWI acquisition information (unique non-zero b-values, and TE, in msec.) to BIDS acquisition filename.

  • zero_pad (int) – Number of zeroes to pad the run number up to (zero_pad=2 is ‘01’).

  • cprss_lvl (int) – Compression level [1 - 9] - 1 is fastest, 9 is smallest (dcm2niix option).

  • verbose (bool) – Enable verbose output (dcm2niix option).

  • log (Optional[LogFile]) – LogFile object for logging.

  • env (Optional[Dict]) – Path environment dictionary.

  • dryrun (bool) – Perform dryrun (creates the command, but does not execute it).

Returns

  • List of image data file(s). Empty string is returned if this file does not exist.

  • List of corresponding JSON (sidecar) file(s). Empty string is returned if this file does not exist.

  • List of corresponding FSL-style bval file(s). Empty string is returned if this file does not exist.

  • List of corresponding FSL-style bvec file(s). Empty string is returned if this file does not exist.

Return type

Tuple of lists that contains

convert_source.batch_convert.log_file(log)

Initializes log file object for logging purposes.

Usage example:
>>> logger = log(log_file)
>>>
>>> logger.info("Some information")
>>> logger.warning("Some warning")
Parameters

log (str) – Log file name.

Return type

LogFile

Returns

LogFile object to be logged to.

convert_source.batch_convert.make_bids_name(bids_name_dict, modality_type)

Creates a BIDS compliant filename given a BIDS name description dictionary, and the modality type.

Usage example:
>>> make_bids_name(bids_name_dict=bids_dict,
...                 modality_type="anat")
...
"sub-001_ses-001_run-01_T1w"
Parameters

  • bids_name_dict (Dict) – BIDS name description dictionary.

  • modality_type (str) – Modality type.

Return type

Tuple[str, str, str, str]

Returns

BIDS compliant filename string.

convert_source.batch_convert.nifti_to_bids(sub_data, bids_name_dict, out_dir, modality_type='', modality_label='', task='', meta_dict={}, mod_dict={}, gzip=True, append_dwi_info=True, zero_pad=2, cprss_lvl=6)

Converts existing NIFTI data to BIDS raw data.

Usage example:
>>> [imgs, jsons, bvals, bvecs] = nifti_to_bids(sub_obj,
...                                             bids_name_dict,
...                                             output_dir,
...                                             'anat',
...                                             'T1w')
...
Parameters

  • sub_data (SubDataInfo) – Subject data information object.

  • bids_name_dict (Dict) – BIDS name dictionary.

  • out_dir (str) – Output directory.

  • modality_type (Optional[str]) – Modality type (BIDS label e.g. ‘anat’, ‘func’, etc).

  • modality_label (Optional[str]) – Modality label (BIDS label e.g. ‘T1w’, ‘bold’, etc).

  • task (Optional[str]) – Task label (BIDS filename task label, e.g. ‘rest’, ‘nback’, etc.)

  • meta_dict (Optional[Dict]) – BIDS common metadata dictoinary.

  • mod_dict (Optional[Dict]) – Modality specific metadata dictionary.

  • gzip (bool) – Gzip output NIFTI files.

  • append_dwi_info (bool) – Appends DWI acquisition information (unique non-zero b-values, and TE, in msec.) to BIDS acquisition filename.

  • zero_pad (int) – Number of zeroes to pad the run number up to (zero_pad=2 is ‘01’).

  • cprss_lvl (int) – Compression level [1 - 9] - 1 is fastest, 9 is smallest.

Returns

  • List of image data file(s). Empty string is returned if this file does not exist.

  • List of corresponding JSON (sidecar) file(s). Empty string is returned if this file does not exist.

  • List of corresponding FSL-style bval file(s). Empty string is returned if this file does not exist.

  • List of corresponding FSL-style bvec file(s). Empty string is returned if this file does not exist.

Return type

Tuple of lists that contains

convert_source.batch_convert.read_config(config_file='', verbose=False)

Reads configuration file and creates a dictionary of search terms for each modality provided that each BIDS modality is used as a key via the keyword ‘modality_search’. Should BIDS related parameter descriptions need to be used when renaming files, the related search and mapping terms can included via the keywords ‘bids_search’ and ‘bids_map’, respectively. If these keywords are not specified, then empty dictionaries are returned. Should exclusions be provided (via the key ‘exclude’) then an exclusion list is created. Should this not be provided, then an empty list is returned.

BIDS modalities:
  • anat:

    • T1w, T2w, FLAIR, etc.

  • func:
    • bold
      • task:

        • resting state, <task-name>

  • dwi

  • fmap

Usage example:
>>> [search_dict, bids_search, bids_map, meta_dict, exclusion_list] = read_config(config_file)
Parameters

  • config_file (Optional[str]) – File path to yaml configuration file. If no file is used, then the default configuration file is used.

  • verbose (Optional[bool]) – Prints additional information to screen.

Returns

  • search_dict: Nested dictionary of heuristic modality search terms for BIDS modalities.

  • bids_search: Nested dictionary of heuristic BIDS search terms.

  • bids_map: Corresponding nested dictionary of BIDS mapping terms to rename files to.

  • meta_dict: Nested dictionary of metadata terms to write to JSON file(s).

  • exclusion_list: List of exclusion terms.

Return type

Tuple of dictionaries and a list that consists of

Raises

ConfigFileReadError – Error that arises if no heuristic search terms are provided.

convert_source.batch_convert.source_to_bids(sub_data, bids_name_dict, out_dir, modality_type='', modality_label='', task='', meta_dict={}, mod_dict={}, gzip=True, append_dwi_info=True, zero_pad=2, cprss_lvl=6, verbose=False, log=None, env={}, dryrun=False)

Converts source data to BIDS raw data.

Usage example:
>>> [imgs, jsons, bvals, bvecs] = source_to_bids(sub_obj,
...                                              bids_name_dict,
...                                              output_dir,
...                                              'anat',
...                                              'T1w')
...
Parameters

  • sub_data (SubDataInfo) – Subject data information object.

  • bids_name_dict (Dict) – BIDS name dictionary.

  • out_dir (str) – Output directory.

  • modality_type (Optional[str]) – Modality type (BIDS label e.g. ‘anat’, ‘func’, etc).

  • modality_label (Optional[str]) – Modality label (BIDS label e.g. ‘T1w’, ‘bold’, etc).

  • task (Optional[str]) – Task label (BIDS filename task label, e.g. ‘rest’, ‘nback’, etc.)

  • meta_dict (Optional[Dict]) – BIDS common metadata dictoinary.

  • mod_dict (Optional[Dict]) – Modality specific metadata dictionary.

  • gzip (bool) – Gzip output NIFTI files.

  • append_dwi_info (bool) – Appends DWI acquisition information (unique non-zero b-values, and TE, in msec.) to BIDS acquisition filename.

  • zero_pad (int) – Number of zeroes to pad the run number up to (zero_pad=2 is ‘01’).

  • cprss_lvl (int) – Compression level [1 - 9] - 1 is fastest, 9 is smallest (dcm2niix option).

  • verbose (bool) – Enable verbose output (dcm2niix option).

  • log (Optional[LogFile]) – LogFile object for logging.

  • env (Optional[Dict]) – Path environment dictionary.

  • dryrun (bool) – Perform dryrun (creates the command, but does not execute it).

Returns

  • List of image data file(s). Empty string is returned if this file does not exist.

  • List of corresponding JSON (sidecar) file(s). Empty string is returned if this file does not exist.

  • List of corresponding FSL-style bval file(s). Empty string is returned if this file does not exist.

  • List of corresponding FSL-style bvec file(s). Empty string is returned if this file does not exist.

Return type

Tuple of lists that contains

Module contents

Python package used for the conversion of source DICOM, PAR REC, or NIFTI data to raw BIDS NIFTI data.