dicomtools module

clabtoolkit.dicomtools.progress_indicator(future)[source]

A simple progress indicator for the concurrent futures :param future: future object

clabtoolkit.dicomtools.org_conv_dicoms(in_dic_dir, out_dic_dir, demog_file=None, ids_file=None, ses_id=None, nosub=False, booldic=True, boolcomp=False, force=False, nthreads=0)[source]

This method organizes the DICOM files in sessions and series. It could also use the demographics file to define the session ID.

Parameters:

  • in_dic_dir (str) – Directory containing the subjects. It assumes all individual folders inside the directory as individual subjects. The subjects directory should start with ‘sub-’ otherwise the subjects will not be considered unless the “nosub” variable is set to True.

  • out_dic_dir (str) – Output directory where the organized DICOM files will be saved. A new folder called ‘Dicom’ will be created inside this directory.

  • demog_file (str, optional) – Demographics file containing the information about the subjects. The file should contain the following mandatory columns: ‘participant_id’, ‘session_id’, ‘acq_date’. Other columns such as ‘birth_date’, ‘sex’, ‘group_id’ or ‘scanner_id’ could be added.

  • ids_file (str, optional) – Text file containing the list of subject IDs to be considered. The file should contain the subject IDs in a single column.

  • ses_id (str, optional) – Session ID to be added to the session name. If not provided, the session ID will be the date of the study or the session ID extracted from the demographics table.

  • nosub (bool, optional, default=False) – Boolean variable to consider the subjects that do not start with ‘sub-‘.

  • booldic (bool, optional, default=True) – Boolean variable to organize the DICOM files. If False it will leave the folders as they are.

  • boolcomp (bool, optional, default=False) – Boolean variable to compress the sessions containing the organized DICOM files. If True it will compress the sessions.

  • force (bool, optional, default=False) – Boolean variable to force the copy of the DICOM file if the file already exists.

  • nthreds (int, optional, default=0) – Number of threads to be used in the process. Default is 0 that means automatic selection of the number of cores.

Returns:

This method performs file organization operations and does not return a value.

Return type:

None

Raises:

  • FileNotFoundError – If the input directory does not exist.

  • ValueError – If the demographics file is provided but does not contain the mandatory columns.

  • PermissionError – If there are insufficient permissions to write to the output directory.

Examples

>>> # Basic usage with input and output directories
>>> organize_dicom_files('/path/to/input/dicoms', '/path/to/output')

>>> # Using demographics file and custom session ID
>>> organize_dicom_files(
...     in_dic_dir='/path/to/input/dicoms',
...     out_dic_dir='/path/to/output',
...     demog_file='/path/to/demographics.csv',
...     ses_id='session01'
... )

>>> # Process only specific subjects with compression
>>> organize_dicom_files(
...     in_dic_dir='/path/to/input/dicoms',
...     out_dic_dir='/path/to/output',
...     ids_file='/path/to/subject_ids.txt',
...     boolcomp=True,
...     nthreds=4
... )
clabtoolkit.dicomtools.copy_dicom_file(dic_file, subj_id, out_dic_dir, ses_id=None, date_times=None, demogbool=False, demog_tab=None, force=False)[source]

Function to copy the DICOM files to the output directory.

Parameters:

  • dic_file (str) – Path to the DICOM file.

  • subj_id (str) – Subject ID.

  • out_dic_dir (str) – Output directory where the DICOM files will be saved.

  • ses_id (str) – Session ID to be added to the session name. If not provided, the session ID will be the date of the study or the session ID extracted from the demographics table.

  • date_times (list) – List containing the date and time of all the studies for that subject ID.

  • demogbool (bool) – Boolean variable to use the demographics table for the session id definition.

  • demog_tab (pd.DataFrame) – Demographics table containing the information about the subjects.

  • force (bool) – Boolean variable to force the copy of the DICOM file.

Returns:

dest_dic_dir – Destination directory where the DICOM file was copied.

Return type:

str

clabtoolkit.dicomtools.create_session_series_names(dataset)[source]

Function to create names from a DICOM object.

Parameters:

dataset (pydicom.dataset.FileDataset) – DICOM dataset object.

Returns:

  • ses_id (str) – Session ID.

  • ser_id (str) – Series ID.

clabtoolkit.dicomtools.uncompress_dicom_session(dic_dir, boolrmtar=False, subj_ids=None)[source]

Uncompress session folders containing the DICOM files for all the series.

Parameters:

  • dic_dir (str) – Directory containing the subjects. It assumes an organization in: <subj_id>/<session_id>/<series_id>

  • boolrmtar (bool, optional, default=False) – Boolean variable to remove the tar files after uncompressing the session.

  • subj_ids (str, list of str, or None, optional) – Subject IDs to be considered. Can be: - None: consider all subjects in the directory (default) - str: path to text file containing subject IDs (one per line) - list of str: explicit list of subject IDs

Returns:

List of tar files that failed to be uncompressed. Empty list if all successful.

Return type:

list of str

Raises:

  • FileNotFoundError – If the specified directory does not exist.

  • ValueError – If subj_ids is not None, str, or list, or if subject IDs file cannot be read.

  • tarfile.TarError – If there are issues with reading or extracting tar files.

  • PermissionError – If there are insufficient permissions to extract files or remove tar archives.

  • OSError – If there are filesystem-related errors during extraction.

Examples

>>> # Basic usage - uncompress all sessions in directory
>>> failed = uncompress_dicom_session('/path/to/dicom/directory')
>>> if not failed:
...     print("All sessions uncompressed successfully")

>>> # Uncompress sessions and remove tar files after extraction
>>> failed = uncompress_dicom_session('/path/to/dicom/directory', boolrmtar=True)

>>> # Uncompress sessions for specific subjects only
>>> failed = uncompress_dicom_session(
...     dic_dir='/path/to/dicom/directory',
...     subj_ids=['sub-001', 'sub-002', 'sub-003']
... )

>>> # Use subject IDs from file
>>> failed = uncompress_dicom_session(
...     dic_dir='/path/to/dicom/directory',
...     subj_ids='/path/to/subject_ids.txt',
...     boolrmtar=True
... )
clabtoolkit.dicomtools.compress_dicom_session(dic_dir, subj_ids=None, remove_original=True)[source]

Compress session folders containing DICOM files into tar.gz archives.

Parameters:

  • dic_dir (str) – Directory containing the subjects. It assumes an organization in: <subj_id>/<session_id>/<series_id>

  • subj_ids (str, list of str, or None, optional) – Subject IDs to be considered. Can be: - None: consider all subjects in the directory (default) - str: path to text file containing subject IDs (one per line) - list of str: explicit list of subject IDs

  • remove_original (bool, optional, default=True) – Whether to remove the original session directories after successful compression.

Returns:

List of session directories that failed to be compressed. Empty list if all successful.

Return type:

list of str

Raises:

  • FileNotFoundError – If the specified directory does not exist.

  • ValueError – If subj_ids is not None, str, or list, or if subject IDs file cannot be read.

  • tarfile.TarError – If there are issues with creating or writing tar files.

  • PermissionError – If there are insufficient permissions to compress files or remove directories.

  • OSError – If there are filesystem-related errors during compression.

Examples

>>> # Basic usage - compress all sessions in directory
>>> failed = compress_dicom_session('/path/to/dicom/directory')
>>> if not failed:
...     print("All sessions compressed successfully")

>>> # Compress sessions but keep original directories
>>> failed = compress_dicom_session(
...     dic_dir='/path/to/dicom/directory',
...     remove_original=False
... )

>>> # Compress sessions for specific subjects only
>>> failed = compress_dicom_session(
...     dic_dir='/path/to/dicom/directory',
...     subj_ids=['sub-001', 'sub-002', 'sub-003']
... )

>>> # Use subject IDs from file
>>> failed = compress_dicom_session(
...     dic_dir='/path/to/dicom/directory',
...     subj_ids='/path/to/subject_ids.txt'
... )
clabtoolkit.dicomtools.get_dicom_info(dicom_file, tags=None, missing_tag_behavior='warn')[source]

Extracts metadata from a DICOM file and returns it as a dictionary.

Can extract all metadata or only specific tags based on the parameters provided.

Parameters:

  • dicom_file (str) – Path to the DICOM file.

  • tags (str, list of str, or None, optional) – DICOM tags (keywords) to extract. If None, all tags are extracted. Can be a single tag as a string or multiple tags as a list. Default is None (extract all tags).

  • missing_tag_behavior ({'warn', 'ignore', 'raise'}, optional) – How to handle missing tags: - ‘warn’: Print a warning and skip the tag (default) - ‘ignore’: Silently skip the tag - ‘raise’: Raise an AttributeError Default is ‘warn’.

Returns:

A dictionary containing the extracted metadata from the DICOM file. Keys are tag keywords, values are the corresponding tag values.

Return type:

dict

Raises:

  • FileNotFoundError – If the specified DICOM file does not exist.

  • pydicom.errors.InvalidDicomError – If the specified file is not a valid DICOM file.

  • AttributeError – If a requested tag does not exist and missing_tag_behavior=’raise’.

  • ValueError – If missing_tag_behavior is not one of {‘warn’, ‘ignore’, ‘raise’}.

Examples

Extract all metadata: >>> metadata = get_dicom_info(‘/path/to/dicom/file.dcm’) >>> print(metadata.keys()) dict_keys([‘PatientID’, ‘StudyDate’, ‘Modality’, …])

Extract specific tags (as list): >>> tags_to_extract = [‘PatientID’, ‘StudyDate’, ‘Modality’] >>> metadata = get_dicom_info(‘/path/to/dicom/file.dcm’, tags=tags_to_extract) >>> print(metadata) {‘PatientID’: ‘12345’, ‘StudyDate’: ‘20210101’, ‘Modality’: ‘MR’}

Extract a single tag (as string): >>> metadata = get_dicom_info(‘/path/to/dicom/file.dcm’, tags=’PatientID’) >>> print(metadata) {‘PatientID’: ‘12345’}

Handle missing tags: >>> metadata = get_dicom_info( … ‘/path/to/dicom/file.dcm’, … tags=[‘PatientID’, ‘NonExistentTag’], … missing_tag_behavior=’ignore’ … ) >>> print(metadata) {‘PatientID’: ‘12345’}

The dicomtools module provides DICOM file organization and BIDS conversion capabilities with multi-threaded processing for efficient handling of large datasets.

Key Features

  • Multi-threaded DICOM file organization

  • BIDS conversion workflows from DICOM to NIfTI

  • Demographics data integration

  • Session and acquisition management

  • Batch processing of DICOM archives

  • Quality control for DICOM conversion

Main Functions

DICOM Organization

  • org_conv_dicoms(): Organize and convert DICOM files

  • copy_dicom_file(): Copy DICOM file

  • create_session_series_names(): Create session series names

  • uncompress_dicom_session(): Uncompress DICOM session

  • compress_dicom_session(): Compress DICOM session

  • progress_indicator(): Progress indicator for DICOM operations

Common Usage Examples

Basic DICOM organization with multi-threaded DICOM processing:

from clabtoolkit.dicomtools import org_conv_dicoms

# Organize DICOM files into structured format
org_conv_dicoms(
    in_dic_dir="/path/to/raw/dicoms",
    out_dic_dir="/path/to/organized/dicoms",
    nthreads=4,
    nosub=True
)

Compressing the DICOM sessions:

# Organize DICOMs and compress the sessions
org_conv_dicoms(
    in_dic_dir="/path/to/raw/dicoms",
    out_dic_dir="/path/to/organized/dicoms",
    nthreads=4,
    boolcomp=True
)
Session management::

# Compress processed DICOM session compress_dicom_session(

dic_dir=”/path/to/bids_dataset”,

)