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.
Note
README template obtained from: https://github.com/bids-standard/bids-starter-kit/tree/master/templates
- 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’sPATH
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 is01
).cprss_lvl (
int
) – Compression level [1 - 9] - 1 is fastest, 9 is smallest.verbose (
bool
) – Enable verbose output.write_participants (
bool
) – If true, writes theparticipants
TSV and JSON files to the output BIDS directory.write_subs_scans (
bool
) – If true, writes each subject’sscan.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
- 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 keywordsbids_search
andbids_map
, respectively. If these keywords are not specified, then empty dictionaries are returned. Should exclusions be provided (via the keyexclude
) 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 themodality_type
andmodality_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
andjson_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 thebids_unknown_dir
path is pre-pended toout_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.