convert_source.cs_utils package

Submodules

convert_source.cs_utils.bids_info module

BIDS (Brain Imaging Data Structure) related exceptions, and functions for ascertaining metadata and filenames.

exception convert_source.cs_utils.bids_info.BIDSMetaDataError

Bases: Exception

exception convert_source.cs_utils.bids_info.BIDSNameError

Bases: Exception

convert_source.cs_utils.bids_info.construct_bids_dict(meta_dict=None, json_dict=None, raise_exec=False)

Constructs dictionary of relevant BIDS related information that includes subject and session IDs, in addition to various metadata. Custom BIDS fields can also be added through the metadata dictionary.

More information can be obtained from:

https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html.

Usage example:
>>> bids_dict = construct_bids_dict(meta_dict,
...                                 json_dict)
...
Parameters

  • meta_dict (Optional[Dict]) – Metadata dictionary that contains the relevant BIDS metadata.

  • json_dict (Optional[Dict]) – Dictionary constructed from the BIDS JSON file, or some secondary dictionary.

  • raise_exec (Optional[bool]) – Raises exception in the case that BIDS Metadata is not CamelCase.

Return type

Dict

Returns

Dictionary containing BIDS related metadata.

Raises

  • IndexError – Error that arises if constant variables BIDS_INFO’s keys and BIDS_ORD_ARR are of different lengths.

  • BIDSMetaDataError – Exception that is raised in the case that the one of the metadata fields are not CamelCase.

convert_source.cs_utils.bids_info.construct_bids_name(sub_data, modality_type='', modality_label='', acq='', ce='', task='', acq_dir='', rec='', run='', echo='', case1=False, mag2=False, case2=False, case3=False, case4=False, out_dir='', zero_pad=0)

Constructs BIDS filenames dictionary from input parameter descriptions.

More information can be obtained from:

https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html.

Usage example:
>>> bids_param = construct_bids_name(sub_data=sub_data,
...                                  modality_type='func',
...                                  modality_label='bold',
...                                  task='rest',
...                                  run='01')
...
Parameters

  • sub_data (SubDataInfo) – SubDataInfo object that contains subject and session ID.

  • modality_type (Optional[str]) –

    Modality type associated with the data. Valid modality types include, but are not limited to:

    • anat: Anatomical scans

    • func: Functional scans

    • dwi: Diffusion weighted image scans

    • fmap: Fieldmaps

    • swi: Susceptibility weighted image scans

  • modality_label (Optional[str]) –

    Modality label of associated with the data. Valid modality labels include, but are not limited to:

    • T1w, T2w, PD, FLAIR, T1rho (in the case of anat).

    • bold, cbv, phase (in the case of func).

    Note

    In the case of func modalities, these are referred to as contrast_labels in the BIDS documentation.

  • acq (Optional[str]) – Acquisition description of the associated image data.

  • ce (Optional[str]) – Contrast enhanced description of the associated image data.

  • task (Optional[str]) – Task associated with the image data, required if func is used as the modality_type.

  • acq_dir (Optional[str]) – Acquisition direction of the image (e.g. PA, AP, LR, RL).

  • rec (Optional[str]) – Image reconstruction description.

  • run (Union[int, str, None]) – Run number of the associated image data.

  • echo (Union[int, str, None]) – Echo number of the associated image data (, in the case of multi-echo data).

  • case1 (bool) –

    BIDS fieldmap case 1, set to True if the following files are present:

    • sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phasediff.nii[.gz]

    • sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phasediff.json

    • sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude1.nii[.gz]

    • [ sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude2.nii[.gz] ]

  • mag2 (bool) – Should be set to True, if case 1 contains a second magnitude image.

  • case2 (bool) –

    BIDS fieldmap case 2, set to True if the following files are present:

    • sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase1.nii[.gz]

    • sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase1.json

    • sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase2.nii[.gz]

    • sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase2.json

    • sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude1.nii[.gz]

    • sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude2.nii[.gz]

  • case3 (bool) –

    BIDS fieldmap case 3, set to True if the following files are present:

    • sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude.nii[.gz]

    • sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_fieldmap.nii[.gz]

    • sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_fieldmap.json

  • case4 (bool) –

    BIDS fieldmap case 4, set to True if the following files are present:

    • sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>]_dir-<label>[_run-<index>]_epi.nii[.gz]

    • sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>]_dir-<label>[_run-<index>]_epi.json

  • out_dir (Optional[str]) – Target output directory for a subject’s BIDS files.

  • zero_pad (Optional[int]) – Number of zeroes to zeropad the output value.

Return type

Dict

Returns

Nested dictionary that contains the necessary information to name BIDS files.

Raises

BIDSNameError – Error raised if: * anat is the speicified modality_type, but no modality_label is specified. * func is the speicified modality_type, but no modality_label is specified. * func is the speicified modality_type, but no task is specified. * fmap is the speicified modality_type, but no fieldmap ‘case’ is specified.

convert_source.cs_utils.bids_info.is_camel_case(s, bids_case=True)

Tests if some input string is camel case (CamelCase).

Note

This function is configured for BIDS use cases, in which metadata must be in camel case, with the first letter being uppercase.

Usage example:
>>> is_camel_case("CamelCase", bids_case=True)
True
>>> is_camel_case("camelcase", bids_case=True)
False
>>> is_camel_case("camelCase", bids_case=True)
False
>>> is_camel_case("camelCase", bids_case=False)
True
Parameters

  • s (str) – Input string to test.

  • bids_case (bool) – In addition to being in camel case, the string’s first letter must also be uppercase.

Return type

bool

Returns

Boolean.

convert_source.cs_utils.bids_info.num_runs(directory='', modality_type='', modality_label='', bids_dict=None, zero_pad=None)

Counts the number of similarly named files in a directory to obtain a unique run number. Optimal use of this function requires the:

  • search directory (directory)

  • modality type (modality_type)

  • BIDS filename dictionary (bids_dict)

Note

The optional input bids_dict is a nested dictionary constructed by the function construct_bids_name.

Usage example:
>>> num_runs(directory: str,
...          modality_type='func',
...          modality_label='bold,
...          bids_dict=bids_dict,
...          zero_pad=3)
'001'
Parameters

  • directory (Optional[str]) – Input directory to search.

  • modality_type (Optional[str]) –

    Modality type associated with the data. Valid modality types include, but are not limited to:

    • anat: Anatomical scans

    • func: Functional scans

    • dwi: Diffusion weighted image scans

    • fmap: Fieldmaps

    • swi: Susceptibility weighted image scans

  • modality_label (Optional[str]) –

    Modality label of associated with the data. Valid modality labels include, but are not limited to:

    • T1w, T2w, PD, FLAIR, T1rho (in the case of anat).

    • bold, cbv, phase (in the case of func).

    Note

    In the case of func modalities, these are referred to as “contrast_labels” in the BIDS documentation.

  • bids_dict (Optional[Dict]) – Nested BIDS name dictionary that contains relevant information to naming files.

  • zero_pad (Optional[int]) – Number of zeroes to zeropad the output value.

Return type

Union[int, str]

Returns

Integer (or string should the value be zeropadded).

convert_source.cs_utils.bids_info.search_bids(s, bids_search=None, bids_map=None, modality_type='', modality_label='', task='', bids_name_dict={})

Performs search of BIDS (or related terms) provided there are bids_search, and bids_map dictionaries, and some input string (or file, represented as a string).

Usage example:
>>> bids_name_dict = search_bids("image_file_0001.dcm",
...                              bids_search=bids_search_dict,
...                              bids_map=bids_map_dict,
...                              modality_type="func",
...                              modality_label="bold",
...                              task="rest")
...
Parameters

  • s (str) – Input string (or file, represented as a string).

  • bids_search (Optional[Dict]) – Heurestic BIDS related search terms.

  • bids_map (Optional[Dict]) – Descriptive BIDS terms to be mapped to.

  • modality_type (Optional[str]) – Modality type (e.g. anat, func, dwi etc).

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

  • task (Optional[str]) – Task label.

  • bids_name_dict (Optional[Dict]) – Existing BIDS name dictionary.

Return type

Dict

Returns

Nested dictionary of BIDS descriptive naming related terms.

convert_source.cs_utils.const module

Constants needed for several utility modules in convert_source. The constant variables contained here include:

  • BIDS_INFO: BIDS metadata dictionary of BIDS related fields.

  • BIDS_ORD_ARR: Ordered array of BIDS metadata fields.

  • BIDS_PARAM: BIDS related parameters used for naming NIFTI, and their corresponding JSON files.

convert_source.cs_utils.fileio module

Utility module for classes and functions that pertain to:

  • File, and filename handling

  • Temporary directory, and temporary file handling

  • Logging

  • Wrapper class for command line executables.

class convert_source.cs_utils.fileio.Command(command)

Bases: object

Creates a command and an empty command list for UNIX command line programs/applications. Primary use and use-cases are intended for the subprocess module and its associated classes (i.e. Popen/call/run).

The input argument is a command (string), and a mutable list is returned (, that can later be appended to).

Note

The specified command used must be in system path.

command

Command to be performed on the command line.

cmd_list

Mutable list that can be appended to.

Usage example:
>>> echo = Command("echo")
>>> echo.cmd_list.append("Hi!")
>>> echo.cmd_list.append("I have arrived!")
>>>
>>> echo
echo Hi! I have arrived!
>>>
>>> echo.run()
Hi! I have arrived!
Parameters

command (str) – Command to be used.

Returns

Mutable list that can be appended to.

check_dependency(err_msg=None, path_envs=[])

Checks dependency of some command line executable. Should the dependency not be met, then an exception is raised. Check the system path should problems arise and ensure that the executable of interest is installed.

Usage example:
>>> figlet = Command("figlet")
>>> figlet.check_dependency()   # Raises exception if not in system path
Parameters

  • err_msg (Optional[str]) – Error message to print to screen.

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

Return type

Optional[bool]

Returns

Returns True if dependency is met.

Raises

DependencyError – Dependency error exception is raised if the dependency is not met.

run(log=None, debug=False, dryrun=False, path_envs=[], env={}, stdout='', shell=False)

Uses python’s built-in subprocess class to execute (run) a command from an input command list. The standard output and error can optionally be written to file.

Note

  • The contents of the stdout output file will be empty if shell is set to True.

  • IF check_dependency was used with the path_envs argument, then the default system PATH variable has been updated to include the list of specified paths.

Usage example:
>>> # Create command and cmd_list
>>> echo = Command("echo")
>>> echo.cmd_list.append("Hi!")
>>> echo.cmd_list.append("I have arrived!")
>>>
>>> # Run/execute command
>>> echo.run()
(0, '', '')
Parameters

  • log (Optional[LogFile]) – LogFile object

  • debug (bool) – Sets logging function verbosity to DEBUG level

  • dryrun (bool) – Dry run – does not run task. Command is recorded to log file.

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

  • env (Dict) – Dictionary of environment variables to add to subshell.

  • stdout (str) – Output file to write standard output to.

  • shell (bool) – Use shell to execute command.

Returns

  • Return code for command execution.

  • Standard output writtent to file should the ‘stdout’ option be used.

  • Standard error writtent to file should the ‘stdout’ option be used.

Return type

Tuple

exception convert_source.cs_utils.fileio.ConversionError

Bases: Exception

exception convert_source.cs_utils.fileio.DependencyError

Bases: Exception

class convert_source.cs_utils.fileio.File(file, ext='')

Bases: object

Creates File object that encapsulates a number of methods and properites for file and filename handling.

file

Class variable that is set once class is instantiated.

Type

str

Usage example:
>>> with File("file_name.txt") as file:
...     file.touch()
...     file.write_txt("some text")
...
>>> # or
>>>
>>> file = File("file_name.txt")
>>> file
"file_name.txt"
Parameters

  • file (str) – Input file (need not exist at runtime/instantiated).

  • ext (str) – File extension of input file. If no extension is provided, it is inferred.

abs_path()

Returns absolute path of file.

Usage example:
>>> file_obj = File("file_name.txt")
>>> file_obj.abs_path()
"abspath/to/file_namt.txt"
Return type

str

file: str = ''
file_parts(ext='')

Similar to MATLAB’s fileparts, this function splits a file and its path into its constituent parts:

  • file path

  • filename

  • extension

Usage example:
>>> file_obj = File("file_name.txt")
>>> file_obj.file_parts()
("path/to/file", "filename", ".ext")   # .ext = file extension
Parameters

ext (str) – File extension, needed if the file extension of file object is longer than 4 characters.

Returns

  • Absolute file path, excluding filename.

  • Filename, excluding extension.

  • File extension.

Return type

Tuple

rm_ext(ext='')

Removes file extension from the file.

Usage example:
>>> file_obj = File("file_name.txt")
>>> file_obj.rm_ext()
"file_name"
Parameters

ext (str) – File extension.

Return type

str

Returns

File name with no extension.

touch()

Creates empty file.

Usage example:
>>> file_obj = File("file_name.txt")
>>> file_obj.touch()   # Creates empty file
Return type

None

write_txt(txt='')

Writes/appends text to file.

Usage example:
>>> file_obj = File("file_name.txt")
>>> file_obj.write_txt("<Text to be written>")
Parameters

txt (str) – Text to be written to file.

Return type

None

class convert_source.cs_utils.fileio.LogFile(log_file='', print_to_screen=False)

Bases: convert_source.cs_utils.fileio.File

Class that creates a log file for logging purposes. Due to how this class is constructed - its intended use case requires that this class is instantiated/called once and ONLY once.

Once a class instance has been instantiated, then it and its associated methods can be used.

log_file

Log filename.

Usage examples:
>>> log = LogFile("file.log",False)
>>> log
"file.log"
Parameters

  • file – Log filename (need not exist at runtime).

  • print_to_screen (bool) – If true, prints output to standard output (stdout) as well.

debug(msg='')

Writes debug information to file.

Usage examples:
>>> log = LogFile("file.log")
>>> log.debug("<str>")
Parameters

msg (str) – String to be printed to log file.

Return type

None

error(msg='')

Writes error information to file.

Usage examples:
>>> log = LogFile("file.log")
>>> log.error("<str>")
Parameters

msg (str) – String to be printed to log file.

Return type

None

ext: str
info(msg='')

Writes information to log file.

Usage examples:
>>> log = LogFile("file.log")
>>> log.info("<str>")
Parameters

msg (str) – String to be printed to log file.

Return type

None

log(log_cmd='')

Log function for logging commands and messages to some log file.

Usage examples:
>>> log = LogFile("file.log")
>>> log.log("<str>")
Parameters

log_cmd (str) – Message to be written to log file

Return type

None

warning(msg='')

Writes warnings to file.

Usage examples:
>>> log = LogFile("file.log")
>>> log.warning("<str>")
Parameters

msg (str) – String to be printed to log file.

Return type

None

class convert_source.cs_utils.fileio.NiiFile(file)

Bases: convert_source.cs_utils.fileio.File

NIFTI file class object for handling NIFTI files. Inherits methods and properties from the File class.

file

NIFTI file path.

Type

str

Usage example:
>>> nii_file = NiiFile("file.nii")
>>> nii_file
"file.nii"
ext: str
class convert_source.cs_utils.fileio.TmpDir(tmp_dir, use_cwd=False)

Bases: object

Temporary directory class that creates temporary directories and files given a parent directory.

tmp_dir

Temproary directory.

Type

str

parent_tmp_dir

Input parent directory.

Type

str

Usage example:
>>> with TmpDir("/path/to/temporary_directory",False) as tmp_dir:
...     tmp_dir.mk_tmp_dir()
...     # do more stuff
...     tmp_dir.rm_tmp_dir(rm_parent=False)
...
>>> # or
>>>
>>> tmp_dir = TmpDir("/path/to/temporary_directory")
>>> tmp_dir
"/path/to/temporary_directory"
>>> tmp_dir.rm_tmp_dir(rm_parent=False)
Parameters

  • tmp_dir (str) – Temporary parent directory name/path.

  • use_cwd (bool) – Use current working directory as working direcory.

class TmpFile(tmp_dir, tmp_file='', ext='')

Bases: convert_source.cs_utils.fileio.File

Child/sub-class of TmpDir. Creates temporary files by inheriting File object methods and properties from the File class. Allows for creation of a temporary file in parent class’ temporary directory location. TmpFile also inherits methods from the File class.

tmp_file

Temporary file name.

Type

convert_source.cs_utils.fileio.File

tmp_dir

Temporary directory name.

Type

str

Usage example:
>>> tmp_directory = TmpDir("/path/to/temporary_directory")
>>>
>>> temp_file = TmpDir.TmpFile(tmp_directory.tmp_dir,
...                             ext="txt")
...
>>> temp_file
"/path/to/temporary_directory/temporary_file.txt"
Parameters

  • tmp_dir (str) – Temporary directory name.

  • tmp_file (Optional[str]) – Temporary file name.

  • ext (Optional[str]) – Temporary directory file extension.

tmp_dir: str = ''
tmp_file: convert_source.cs_utils.fileio.File = ''
mk_tmp_dir()

Creates/makes temporary directory.

Usage example:
>>> tmp_directory = TmpDir("/path/to/temporary_directory")
>>> tmp_directory.mk_tmp_dir()
Return type

Optional[str]

parent_tmp_dir: str = ''
rm_tmp_dir(rm_parent=False)

Removes temporary directory.

Usage example:
>>> tmp_directory = TmpDir("/path/to/temporary_directory")
>>> tmp_directory.rm_tmp_dir()
Parameters

rm_parent (bool) – Removes parent directory as well.

Return type

None

tmp_dir: str = ''

convert_source.cs_utils.img_dir module

Determines file paths of child directories that contain medical images, and their corresponding image types from some parent directory. Currently supports use with: DICOM, PAR REC, and NIFTI files.

convert_source.cs_utils.img_dir.generate_img_list(directory, out_prefix, verbose=False)

Generates list of image-containing directories and their corresponding image types from some parent directory. The full path of the child directories that contain the images are written to file, in addition to their respective file types. The written files will contain ‘.dir_list.txt’ and ‘.type_list.txt’ appended to them.

Parameters

  • directory (str) – Input parent directory of that contain medical images somewhere in its directory structure.

  • out_prefix (str) – Output file prefix for written files.

  • verbose (bool) – Enable verbosity.

Returns

  • Child directories that contain medical images.

  • Corresponding file types to ‘dir_names’ list.

  • Output file that contains the contents of ‘dir_names’.

  • Output file that contains the contents of ‘file_types’.

Return type

Tuple

convert_source.cs_utils.img_dir.id_img_file(dir_names, verbose=False)

Creates list of file-types that either contain the label: DCM (DICOM), NII (NIFTI), PAR (PAR REC), or Unknown.

Parameters

  • dir_names (List[str]) – Input directory names list.

  • verbose (bool) – Enable verbose output.

Return type

List[str]

Returns

List of file-types that corresponds to input directory names list.

convert_source.cs_utils.img_dir.img_dir_list(directory, verbose=False)

Creates list of image file directories and file-types for some parent directy. The image file directories list is a sorted list consisting of unique file paths for each image file parent directory. The corresponding file- types list consists of labels that are: DCM (DICOM), NII (NIFTI), PAR (PAR REC), or Unknown - depending on the file-types in the image file parent directories.

Usage example:
>>> img_list, type_list = img_dir_list(img_dir)
Parameters

  • directory (str) – Parent directory that contains subject image data directories

  • verbose (bool) – Enable verbose output

Returns

List of child directory names that contain image data. List of file-types that corresponds to directory names list.

Return type

Tuple

convert_source.cs_utils.img_dir.list_to_file(in_list, out_file)

Writes some input list to some file.

Parameters

  • in_list (List[str]) – List of subjects.

  • out_file (str) – Output filename.

Return type

str

Returns

Output file with list written to file.

convert_source.cs_utils.utils module

File utility functions for convert_source, which encapsulate file reading/writing for JSON files, in addition to subject and session information data collection methods.

class convert_source.cs_utils.utils.BIDSimg(work_dir)

Bases: object

File collection and organization object intended for handling Brain Imaging Data Structure (BIDS) data in the process of being converted from source data to NIFTI.

imgs

List of NIFTI files.

jsons

Corresponding list of JSON sidecar(s).

bvals

Corresponding list of bval file(s).

bvecs

Corresponding list of bvec file(s).

Parameters

work_dir (str) – Input working directory that contains the image files and their associated output files.

copy_img_data(target_dir)

Copies image data and their associated files to some target directory.

Note

This function resets the class attributes of the class instance with the returns of this function.

Parameters

target_dir (str) – Target directory to copy files to.

Returns

  • NIFTI image files

  • Corresponding JSON file(s)

  • Corresponding bval file(s)

  • Corresponding bvec file(s)

Return type

Tuple of four lists

class convert_source.cs_utils.utils.SubDataInfo(sub, data, ses=None, file_id=None)

Bases: object

Class instance that creates a data object that organizes a subject’s identification (ID) number, session ID number, the path to the image data directory, and the unique file ID. This information is then stored for each separate class instance, and can be accessed as shown in the example usage.

sub

Subject ID.

data

Path to image data directory.

ses

Session ID.

file_id

Unique file ID for the source image data.

Usage example:
>>> sub_info = SubDataInfo(sub="002",
...                        data="<path/to/img/data>",
...                        ses="001",
...                        file_id="0000001")
...
>>> sub_info.sub
"002"
>>>
>>> sub_info.ses
"001"
>>> sub_info.file_id
"0000001"
Parameters

  • sub (Union[str, int]) – Subject ID.

  • data (str) – Path to image data directory.

  • ses (Union[int, str, None]) – Session ID.

  • file_id (Union[int, str, None]) – Unique file ID for the source image data.

Raises

SubInfoError – Error that arises from either not specifying the subject ID or the path to the image file.

exception convert_source.cs_utils.utils.SubInfoError

Bases: Exception

convert_source.cs_utils.utils.add_to_zeropadded(num1, num2)

Adds some specified integer to another zeropadded integer.

Usage example:
>>> add_to_zeropadded('005',2)
'007'
Parameters

  • num1 (Union[int, str]) – Input integer, or zeropadded integer represented as a string.

  • num2 (int) – Integer to add to num1.

Return type

str

Returns

Sum of the two perceived integer values, represented as a string.

Raises

  • ValueError – Error that arises if non-integer string representations are passed as an argument for num1.

  • TypeError – Error that arise if non-integer arguments are passed for num2, OR if floats are passed for either num1 or num2.

convert_source.cs_utils.utils.calc_read_time(file, json_file='')

Calculates the effective echo spacing and total readout time provided several combinations of parameters. Several approaches and methods to calculating the effective echo spacing and total readout within this function differ and are dependent on the parameters found within the provided JSON sidecar. Currently, there a four approaches for calculating the effective echo space (all with differing values) and two ways of calculating the total readout time. It should also be noted that several of these approaches are vendor specific (e.g. at the time of writing, 16 Jan 2019, the necessary information for approach 1 is only found in Siemens DICOM headers - the necessary information for approach 2 is only possible if the data is stored in PAR REC format as the WaterFatShift is a private tag in the Philips DICOM header - approaches 3 and 4 are intended for Philips/GE DICOMs as those values are anticipated to exist in their DICOM headers).

Note

This function’s calculation of the Effective Echo Spacing and the Total Readout Time ASSUME that the magnetic field strength is 3T.

The approaches are listed below:

Approach 1 (BIDS method, Siemens):

BWPPPE = BandwidthPerPixelPhaseEncode EffectiveEchoSpacing = 1/[BWPPPE * ReconMatrixPE] TotalReadoutTime = EffectiveEchoSpacing * (ReconMatrixPE - 1)

Approach 2 (Philips method - PAR REC):

EffectiveEchoSpacing = (((1000 * WaterFatShift)/(434.215 * (EchoTrainLength + 1)))/ParallelReductionFactorInPlane) TotalReadoutTime = 0.001 * EffectiveEchoSpacing * EchoTrainLength

Approach 3 (Philips/GE method - DICOM):

EffectiveEchoSpacing = ((1/(PixelBandwidth * EchoTrainLength)) * (EchoTrainLength - 1)) * 1.3 TotalReadoutTime = EffectiveEchoSpacing * (EchoTrainLength - 1)

Approach 4 (Philips/GE method - DICOM):

EffectiveEchoSpacing = ((1/(PixelBandwidth * ReconMatrixPE)) * (ReconMatrixPE - 1)) * 1.3 tot_read_time = EffectiveEchoSpacing * (ReconMatrixPE - 1)

Note

EchoTrainLength is assumed to be equal to ReconMatrixPE for approaches 3 and 4, as these values are generally close.

Note

Approaches 3 and 4 appear to have about a 30% decrease in Siemens data when this was tested. The solution was to implement a fudge factor that accounted for the 30% decrease.

References

Parameters

  • file (str) – Filepath to raw image data file (DICOM or PAR REC)

  • json_file (Optional[str]) – Filepath to corresponding JSON sidecar.

Returns

Tuple of floats or empty strings if unable to determine either of the values.

Return type

Tuple

convert_source.cs_utils.utils.collect_info(parent_dir, database, exclusion_list=None, log=None)

Collects image data information for each subject for a study, provided there exists some parent directory. Certain image files can be excluded provided a list of exclusion keywords/terms.

Usage example:
>>> data = collect_info("<parent/directory>",
...                     "file.db",
...                     ["SWI", "PD", "ProtonDensity"])
...
>>>
>>> data[0].sub
"001"
>>>
>>> data[0].data
"<path/to/data>"
>>>
>>> data[0].ses
"001"
>>>
>>> data[0].file_id
"0000001"
Parameters

  • parent_dir (str) – Parent directory that contains each subject.

  • database (str) – Database filename.

  • exclusion_list (Optional[List[str]]) – Exclusion list that consists of keywords used to exclude files.

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

Return type

List[SubDataInfo]

Returns

List/Array of SubDataInfo objects that corresponds to a subject ID, session ID, path to medical image data, and unique file ID.

convert_source.cs_utils.utils.comp_dict(d1, d2, path='', verbose=False)

Compares 2 dictionaries to see if they have matching keys, and that each key maps to a value (that is NOT of type None). This is performed recursively.

Usage example:
>>> comp_dict(d1, d2)
True
Parameters

  • d1 (Dict) – Input dictionary.

  • d2 (Dict) – Input dictionary.

  • path (Optional[str]) – Visualized path that has been traversed.

  • verbose (bool) – Print verbose output.

Return type

Optional[bool]

Returns

Boolean ‘True’, raises exceptions otherwise.

Raises

KeyError – Error that arises if input dictionaries do not have matching keys.

convert_source.cs_utils.utils.convert_image_data(file, basename, out_dir, cprss_lvl=6, bids=True, anon_bids=True, gzip=True, comment=True, adjacent=False, dir_search=5, nrrd=False, ignore_2D=True, merge_2D=True, text=False, progress=False, verbose=False, write_conflicts='suffix', crop_3D='n', lossless=False, big_endian='o', xml=False, log=None, env=None, dryrun=False, return_obj=False)

Converts medical image data (DICOM, PAR REC, or Bruker) to NIFTI (or NRRD, not recommended) using dcm2niix. This is a wrapper function for dcm2niix (v1.0.20201102+).

Note

IF dcm2niix is not in system path, then its parent’s directory path can be appended to the system’s PATH variable by doing:

>>> from convert_source.cs_utils.fileio import Command
>>> dcm2niix_command = Command("dcm2niix")
>>> dcm2niix_command.check_dependency(path_envs=['<path/to/dcm2niix/dir>'])

One should note that argument passed for the path_envs argument is a list. Additionally, the last statement above should return True if the executable is found, or raise a DependencyError otherwise.

Usage example:
>>> data = convert_image_data("IM00001.dcm",
...                           "img0001",
...                           "<path/to/out/directory>")
>>> data.imgs[0]
"<path/to/image.nii>"
>>>
>>> data.jsons[0]
"<path/to/image.json>"
>>>
>>> data.bvals[0]
"<path/to/image.bval>"
>>>
>>> data.bvecs[0]
"<path/to/image.bvec>"
Parameters

  • file (str) – Absolute path to raw image data file.

  • basename (str) – Output file(s) basename.

  • out_dir (str) – Absolute path to output directory (must exist at runtime).

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

  • bids (bool) – BIDS (JSON) sidecar (default: True).

  • anon_bids (bool) – Anonymize BIDS (default: True).

  • gzip (bool) – Gzip compress images (default: True).

  • comment (bool) – Image comment(s) stored in NifTi header (default: True).

  • adjacent (bool) – Assumes adjacent DICOMs/Image data (images from same series always in same folder) for faster conversion (default: False).

  • dir_search (int) – Directory search depth (default: 5).

  • nrrd (bool) – Export as NRRD instead of NifTi, not recommended (default: False).

  • ignore_2D (bool) – Ignore derived, localizer and 2D images (default: True).

  • merge_2D (bool) – Merge 2D slices from same series regardless of echo, exposure, etc. (default: True).

  • text (bool) – Text notes includes private patient details in separate text file (default: False).

  • progress (bool) – Report progress, slicer format progress information (default: False).

  • verbose (bool) – Enable verbosity (default: False).

  • write_conflicts (str) –

    Write behavior for name conflicts:

    • ’suffix’ = Add suffix to name conflict (default)

    • ’overwrite’ = Overwrite name conflict

    • ’skip’ = Skip name conflict

  • crop_3D (str) – Crop 3D acquisitions (y/n/i, default n, use ‘i’gnore to neither crop nor rotate 3D acquistions).

  • lossless (bool) – Losslessly scale 16-bit integers to use dynamic range (default: True).

  • big_endian (str) –

    Byte order:

    • ’o’ = optimal/native byte order (default)

    • ’n’ = little endian

    • ’y’ = big endian

  • xml (bool) – Slicer format features (default: False).

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

  • return_obj (bool) – Boolean to return object, rather than a tuple of lists.

Return type

Union[BIDSimg, Tuple[List[str], List[str], List[str], List[str]]]

Returns

BIDSimg data object or Tuple of lists

BIDSimg data object:

  • imgs: List of NIFTI image files

  • jsons: Corresponding list of JSON file(s)

  • bvals: Corresponding bval file(s)

  • bvecs: Corresponding bvec file(s)

OR

Tuple:

  • List of NIFTI image files

  • List of corresponding JSON file(s)

  • List of corresponding bval file(s)

  • List of corresponding bvec file(s)

Raises

  • ConversionError – Error that arises if no converted (NIFTI) images are created.

  • IndexError – Error that arises if the specified options arrays/lists are of different lengths.

convert_source.cs_utils.utils.depth(d)

Uses breadth-first search approach to find the depth of a dictionary.

Usage example:
>>> depth(d)
3
Parameters

d (Dict) – Input dictionary.

Return type

int

Returns

Number of levels in dictionary.

convert_source.cs_utils.utils.dict_multi_update(dictionary=None, **kwargs)

Updates a dictionary multiple times depending on the number key word mapped pairs that are provided and returns a separate updated dictionary. The dictionary passed as an argument need not exist at runtime.

Example usage:
>>> new_dict = dict_multi_update(old_dict,
...                              Manufacturer="Philips",
...                              ManufacturersModelName="Ingenia",
...                              MagneticFieldStrength=3,
...                              InstitutionName="CCHMC")
...
Parameters

  • dictionary (Optional[Dict]) – Dictionary of key mapped items to be updated.

  • **kwargs – Key-value (key=value) pairs.

Return type

Dict

Returns

New updated dictionary.

convert_source.cs_utils.utils.get_bvals(bval_file='')

Reads the bvals from the (FSL-style) bvalue file and returns a list of unique non-zero bvalues. If the bval file does not exist or is not provided, then zero is returned in a list.

Parameters

bval_file (Optional[str]) – Bval (.bval) file.

Return type

List[int]

Returns

List of unique, non-zero bvalues (as ints), or zero in a list.

convert_source.cs_utils.utils.get_dcm_scan_tech(dcm_file, search_dict)

Searches DICOM file header for scan technique/MR modality used in accordance with the search terms provided by the nested heursitic search dictionary. The DICOM header field searched is a Philips DICOM private tag (2001,1020) [Scanning Technique Description MR]. In the case that matches are found in that field, is empty, or does not exist - then common DICOM tags are searched which include:

  • Series Description

  • Protocol Name

  • Image Type.

Usage example:
>>> [modality_type, modality_label, task] = get_dcm_scan_tech(dcm_file,
...                                                           search_dict)
...
Parameters

  • dcm_file (str) – DICOM filename.

  • search_dict (Dict) – Nested heursitic search dictionary (from the read_config function).

Returns

  • modality_type: Modality type (e.g. anat, func, etc.)

  • modality_label: Modality label (e.g. T1w, bold, etc.)

  • task: Task name (e.g. rest).

Return type

Tuple

convert_source.cs_utils.utils.get_echo(json_file)

Reads the echo time (TE) from the NIFTI JSON sidecar and returns it.

Parameters

json_file (string) – Absolute path to JSON sidecar.

Return type

float

Returns

Echo time as a float.

convert_source.cs_utils.utils.get_metadata(dictionary=None, modality_type=None, task=None)

Reads the metadata dictionary and looks for keywords to indicate what metadata should be written to which dictionary. For example, the keyword ‘common’ is used to indicate the common information for the imaging protocol and may contain information such as: field strength, phase encoding direction, institution name, etc. Additional keywords that are BIDS sub-directories names (e.g. anat, func, dwi) will return an additional dictionary which contains metadata specific for those modalities. ‘Func’ also has additional keywords based on the task specified. If an empty dictionary is passed as an argument, then this function returns empty dictionaries as a result.

Parameters

  • dictionary (Optional[Dict]) – Nested dictionary of key mapped items from the ‘read_config’ function.

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

  • task (Optional[str]) – Task name to search in the key mapped dictionary.

Returns

  • Common metadata dictionary.

  • Modality specific metadata dictionaries.

Return type

Tuple

convert_source.cs_utils.utils.get_par_scan_tech(par_file, search_dict)

Searches PAR file header for scan technique/MR modality used in accordance with the search terms provided by the nested heursitic search dictionary. A regular expression (regEx) search string is defined and is searched in the PAR header file.

Usage example:
>>> [modality_type, modality_label, task] = get_par_scan_tech(par_file,
...                                                           search_dict)
...
Parameters

  • par_file (str) – PAR header filename.

  • search_dict (Dict) – Nested heursitic search dictionary (from the read_config function).

Returns

  • modality_type: Modality type (e.g. anat, func, etc.)

  • modality_label: Modality label (e.g. T1w, bold, etc.)

  • task: Task name (e.g. rest).

Return type

Tuple

convert_source.cs_utils.utils.get_pix_band(json_file)

Reads pixel bandwidth value from the JSON sidecar.

Parameters

json_file (string) – BIDS JSON file.

Return type

Union[float, str]

Returns

Pixel bandwidth value (as a float if it exists in the file, or as an empty string if not in the file).

convert_source.cs_utils.utils.get_recon_mat(json_file)

Reads ReconMatrixPE (reconstruction matrix phase encode) value from the JSON sidecar.

Parameters

json_file (str) – BIDS JSON file.

Return type

Union[float, str]

Returns

Recon Matrix PE value (as a float if it exists in the file, or as an empty string if not in the file).

convert_source.cs_utils.utils.glob_dcm(dcm_dir)

Globs subject DICOM data directories for the top-most DICOM file in each respective directory.

Example usage:
>>> dcm_files = glob_dcm(dcm_dir)
Parameters

dcm_dir (str) – Subject DICOM data directory.

Return type

List[str]

Returns

List of strings of image files.

convert_source.cs_utils.utils.glob_img(img_dir)

Globs image data files given a subject image data directory. The image file types that are search for are:

  • DICOM

  • PAR REC

  • NIFTI

Example usage:
>>> img_list = glob_img(img_dir)
Parameters

img_dir (str) – Path to image directory.

Return type

List[str]

Returns

List of strings of file paths to images.

convert_source.cs_utils.utils.gunzip_file(file, native=True, log=None)

Gunzips file. Native implementation of gunzipping files is prefered with this function provided that the system is UNIX. Otherwise, a pythonic implementation of gunzipping is performed.

Parameters

  • file (str) – Input file.

  • native (bool) – Uses native implementation of gunzip.

  • log (Optional[LogFile]) – LogFile object that writes to some output log file.

Return type

str

Returns

Gunzipped file.

convert_source.cs_utils.utils.gzip_file(file, cprss_lvl=6, native=True, log=None)

Gzips file. Native implementation of gzipping files is prefered with this function provided that the system is UNIX. Otherwise, a pythonic implementation of gzipping is performed.

Parameters

  • file (str) – Input file.

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

  • native (bool) – Uses native implementation of gzip.

  • log (Optional[LogFile]) – LogFile object that writes to some output log file.

Return type

str

Returns

Gzipped file.

Searches a DICOM or PAR file header for relevant scan technique/parameter information provided a nested heursitic search dictionary of search terms to map scan acquisitions of interest. Any other image file passed as an argument will return a tuple of empty strings.

Usage example:
>>> [modality_type, modality_label, task] = header_search(img_file,
...                                                       search_dict)
...
Parameters

  • img_file (str) – Image file.

  • search_dict (Dict) – Nested heursitic search dictionary (from the read_config function).

Returns

  • modality_type: Modality type (e.g. anat, func, etc.)

  • modality_label: Modality label (e.g. T1w, bold, etc.)

  • task: Task name (e.g. rest).

Return type

Tuple

convert_source.cs_utils.utils.img_exclude(img_list, exclusion_list=None)

Constructs a new list with files that DO NOT contain words in the exclusion list. Should this list be empty, then the original input list is returned.

Usage example:
>>> new_img_list = img_exclude(img_list, ["SWI", "PD","ProtonDensity"])
Parameters

  • img_list (List[str]) – Input list of paths to image files.

  • exclusion_list (Optional[List[str]]) – Exclusion list that consists of keywords used to exclude files.

Return type

List[str]

Returns

List of image files that do not contain words in the exclusion list.

convert_source.cs_utils.utils.list_dict(d)

Creates a list of dictionaries provided a nested dictionary using the top-most level of the dictionaries as list (array) indices.

Usage example:
>>> list_dict(d)
[d1, d2, ..., dn]
Parameters

d (Dict[str, str]) – Input (nested) dictionary.

Return type

List[Dict[str, str]]

Returns

List of dictionaries.

convert_source.cs_utils.utils.list_dir_files(pathname, pattern='', file_name_only=False)

List files and/or directories of some parent directory, in addition to pattern matched globbing if provided.

Note

The output list is sorted.

Usage example:
>>> file_list = _list_dir_files(pathname='/<path>/<to>/<directory>',
...                             pattern='<filename>',
...                             file_name_only=False)
...
Parameters

  • pathname (str) – Pathname/directory path.

  • pattern (Optional[str]) – Pattern to be matched should file globbing need to be performed.

  • dir_file_name_only – If true, only the filenames are returned.

Return type

List[str]

Returns

List of strings that consists of files or file paths.

Raises

FileNotFoundError – Error that arises if the pattern matched file or directory does not exist.

convert_source.cs_utils.utils.list_in_substr(in_list, in_str)

Searches a string using a list that contains substrings. Returns boolean ‘True’ or ‘False’ if any elements of the list are found within the string.

Example usage:
>>> list_in_substr('['T1','TFE']','sub_T1_image_file')
True
>>>
>>> list_in_substr('['T2','TSE']','sub_T1_image_file')
False
Parameters

  • in_list (List[str]) – List containing strings used for matching.

  • in_str (str) – Larger string to be searched for matches within substring.

Return type

bool

Returns

boolean True or False.

convert_source.cs_utils.utils.read_json(json_file)

Reads JavaScript Object Notation (JSON) file.

Parameters

json_file (str) – Input file.

Return type

Dict

Returns

Dictionary of key mapped items from JSON file.

Performs symbolic linking of some input source file or directory to some target output file. The symbolic linking can be performed using the UNIX system’s native linking tools or via python’s linking tools.

Note

  • Windows platforms require running this funciton with elevated privileges as this operation cannot be performed otherwise.

Usage example:
>>> sym_link(src='<source_file/directory>',
             tar='<target_file>',
             native=True)
...
Parameters

  • src (str) – Input source file or directory.

  • tar (str) – Output target file that is linked to the source file or directory.

  • native (Optional[bool]) – Use native UNIX linking tool instead of python’s symbolic linking tool.

Return type

None

Returns

None

Raises

FileNotFoundError – Error that arises should the source directory/file not exist.

convert_source.cs_utils.utils.update_json(json_file, dictionary)

Updates JavaScript Object Notation (JSON) file. If the file does not exist, it is created once this function is called.

Parameters

  • json_file (str) – Input file.

  • dictionary (Dict) – Dictionary of key mapped items to write to JSON file.

Return type

str

Returns

Updated JSON file.

convert_source.cs_utils.utils.write_json(json_file, dictionary)

Writes python dictionary to a JavaScript Object Notation (JSON) file. The speicifed JSON file need not exist.

Usage example:
>>> json_file = write_json("file.json",
...                        example_dict)
...
Parameters

  • json_file (str) – Input JSON file.

  • dictionary (Dict) – Input python dictionary

Return type

str

Returns

String that represents path to written JSON file.

convert_source.cs_utils.utils.zeropad(num, num_zeros=2)

Zeropads a number, should that number be an int or str.

Usage example:
>>> zeropad(5,2)
'05'
>>> zeropad('5',2)
'05'
Parameters

  • num (Union[str, int]) – Input number (as str or int) to zeropad.

  • num_zeros (int) – Number of zeroes to pad with.

Return type

str

Returns

Zeropadded string of the number, or the original string if the input string could not be represented as an integer.

Raises

TypeError – Error that arises if floats are passed as an argument.

Module contents