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.add_dataset_description(out_dir)

Adds the dataset_description.json (dataset description JSON) file to some BIDS data directory. This is essentially meant to function as a boiler plate dataset_description template.

Note

This template was obtained from: https://bids-specification.readthedocs.io/en/v1.6.0/03-modality-agnostic-files.html#dataset-description Boiler plate dataset_description template.

Usage example:
>>> ds_json = add_dataset_description(out_dir='<path>/<to>/<BIDS>')
Parameters

out_dir (str) – Output BIDS directory.

Return type

str

Returns

File path to dataset_description.json file as a string.

convert_source.batch_convert.add_readme(out_dir)

Adds a BIDS README file to some output BIDS directory.

Usage example:
>>> readme_file = add_readme(out_dir='<path>/<to>/<BIDS>/<directory>')
Parameters

out_dir (str) – BIDS output directory for the README file.

Return type

str

Returns

Absolute file path to README file.

convert_source.batch_convert.batch_proc(study_img_dir, out_dir, config_file, path_envs=[], gzip=True, append_dwi_info=False, zero_pad=2, cprss_lvl=6, verbose=False, write_participants=False, write_subs_scans=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.

  • write_participants (bool) – If true, writes the participants TSV and JSON files to the output BIDS directory.

  • write_subs_scans (bool) – If true, writes each subject’s scan.tsv to their subject directory.

  • 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.create_participant_tsv(out_dir)

Creates or appends/updates the participants TSV file (participants.tsv). If the participants TSV file does not exist at runtime, then it is created. Additionally, the participant JSON file is created. However once created, it is not updated (as this is intended to be maintained by the user).

More information can be obtained from: https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#participants-file

Usage example:
>>> [participant_tsv,
...  participant_json] = create_participant_tsv(out_dir="<path>/<to>/<BIDS>/<directory>")
Parameters

out_dir (str) – BIDS output directory.

Returns

  • Absolute file path to the participants TSV file (participants.tsv)

  • Absolute file path to the participants JSON file (participants.json)

Return type

Tuple of strings that consist of

convert_source.batch_convert.data_to_bids(sub_data, bids_name_dict, out_dir, database, 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,
...                                            database,
...                                            'anat',
...                                            'T1w')
...
Parameters
  • sub_data (SubDataInfo) – Subject data information object.

  • bids_name_dict (Dict) – BIDS name dictionary.

  • out_dir (str) – Output directory.

  • database (str) – Input database filename to be queried and updated.

  • 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.get_dcm2niix_version(log=None)

Gets the version of dcm2niix being used on the current OS.

This function assumes that dependency checks have already been performed, and that dcm2niix is in the system path.

Usage example:
>>> dcm_cmd = Command("dcm2niix)
>>> dcm.check_dependency(
...         path_envs=[ '/<path>/<to>/<dcm2niix>' ])
...
>>> dcm_version = get_dcm2niix_version()
>>> dcm_version
'v1.0.20201102'
Parameters

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

Return type

str

Returns

dcm2niix version used on the current OS.

convert_source.batch_convert.log_file(log, verbose=False)

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.

  • verbose (bool) – Permits verbose logging to screen (stdout).

Return type

LogFile

Returns

LogFile object to be logged to.

convert_source.batch_convert.make_bids_name(bids_name_dict, modality_type, num_imgs=4)

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",
...                num_imgs=1)
...
"sub-001_ses-001_run-01_T1w"
Parameters
  • bids_name_dict (Dict) – BIDS name description dictionary.

  • modality_type (str) – Modality type.

  • num_imgs (Optional[int]) – Number of medical images to be re-named.

Return type

List[str]

Returns

List of BIDS compliant filenames.

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

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.

  • database (str) – Input database filename to be queried and updated.

  • 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.

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

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.read_unknown_subs(mapfile, config='', cprss_lvl=6, verbose=False)

Reads the input JSON or YAML mapfile for unknown BIDS NIFTI files.

Note

Use of this functions requires that the function batch_proc has already been run.

Usage example:
>>> subs_bids_data = read_unknown_subs(mapfile)
Parameters
  • mapfile (str) – JSON or YAML mapfile that specifies the modality_type and modality_label.

  • config (Optional[str]) – Configuration file with search terms.

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

  • verbose (bool) – Enable verbose output.

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.source_to_bids(sub_data, bids_name_dict, out_dir, database, 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,
...                                              database,
...                                              'anat',
...                                              'T1w')
...
Parameters
  • sub_data (SubDataInfo) – Subject data information object.

  • bids_name_dict (Dict) – BIDS name dictionary.

  • out_dir (str) – Output directory.

  • database (str) – Input database filename to be queried and updated.

  • 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.write_unknown_to_file(bids_unknown_dir, out_name, yaml_file=True, json_file=False)

Writes unknown BIDS NIFTIs to either a YAML or JSON file to later be identified and renamed to be BIDS compatible. If both the yaml_file and json_file options are false, an exception is raised.

Note

The out_name argument should only have the file name provided, and not the absolute path, as the bids_unknown_dir path is pre-pended to out_name.

Usage example:
>>> [ unknown_list, yml_file, json_file ] = write_unknown_to_file(bids_unknown_dir='<BIDS rawdata directory>/unknown',
...                                                               out_name='unknown',
...                                                               yaml_file=True,
...                                                               json_file=False)
...
Parameters
  • bids_unknown_dir (str) – Unknown BIDS directory that contains unknown BIDS files.

  • out_name (str) – Output file prefix (i.e. no file extension).

  • yaml_file (bool) – If true, writes the output file as a YAML file.

  • json_file (bool) – If true, writes the output file as a JSON file.

Returns

  • List of unknown BIDS NIFTI files.

  • Output YAML file.

  • Output JSON file.

Return type

Tuple that consists of

Raises
  • FileNotFoundError – Error that arises if the specified unknown BIDS directory does not exist.

  • NameError – Error that arises if both YAML and JSON output options are set to false.

Module contents

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