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