dicom2nifti

tit.pre.dicom2nifti ¶

DICOM-to-NIfTI conversion with BIDS-compliant naming.

Wraps dcm2niix to convert DICOM series into NIfTI files that follow the BIDS naming convention (sub-{id}_{modality}.nii.gz).

Public API¶

run_dicom_to_nifti Convert DICOM files for a subject to BIDS-compliant NIfTI.

run_dicom_to_nifti ¶

run_dicom_to_nifti(project_dir: str, subject_id: str, *, logger, runner: CommandRunner | None = None) -> None

Convert DICOM files to BIDS-compliant NIfTI for a subject.

Looks for T1w, T2w, and dwi DICOM directories under sourcedata/sub-{subject_id}/ (modality folder names are matched case-insensitively) and converts each found modality using dcm2niix. Anatomical images go to the subject anat/ folder and diffusion images to dwi/ (with .bval/.bvec sidecars). DICOM discovery is recursive under each modality's dicom/ directory and includes .dcm and .dicom files. Supported archives (.zip, .tar, .tar.gz, .tgz) placed directly in the modality folder or its dicom/ folder are safely extracted to dicom/extracted_archives/ before discovery.

Parameters¶

project_dir : str BIDS project root directory. subject_id : str Subject identifier without the sub- prefix. logger : logging.Logger Logger for progress messages. runner : CommandRunner or None, optional Subprocess runner for streaming output.

Raises¶

PreprocessError If output NIfTI files already exist for a modality.

See Also¶

run_pipeline : Full preprocessing pipeline.

Source code in tit/pre/dicom2nifti.py

def run_dicom_to_nifti(
    project_dir: str,
    subject_id: str,
    *,
    logger,
    runner: CommandRunner | None = None,
) -> None:
    """Convert DICOM files to BIDS-compliant NIfTI for a subject.

    Looks for ``T1w``, ``T2w``, and ``dwi`` DICOM directories under
    ``sourcedata/sub-{subject_id}/`` (modality folder names are matched
    case-insensitively) and converts each found modality using
    ``dcm2niix``. Anatomical images go to the subject ``anat/`` folder
    and diffusion images to ``dwi/`` (with ``.bval``/``.bvec`` sidecars).
    DICOM discovery is recursive under each modality's ``dicom/``
    directory and includes ``.dcm`` and ``.dicom`` files. Supported
    archives (``.zip``, ``.tar``, ``.tar.gz``, ``.tgz``) placed directly
    in the modality folder or its ``dicom/`` folder are safely extracted
    to ``dicom/extracted_archives/`` before discovery.

    Parameters
    ----------
    project_dir : str
        BIDS project root directory.
    subject_id : str
        Subject identifier without the ``sub-`` prefix.
    logger : logging.Logger
        Logger for progress messages.
    runner : CommandRunner or None, optional
        Subprocess runner for streaming output.

    Raises
    ------
    PreprocessError
        If output NIfTI files already exist for a modality.

    See Also
    --------
    run_pipeline : Full preprocessing pipeline.
    """
    from tit.telemetry import track_operation
    from tit import constants as _const

    with track_operation(_const.TELEMETRY_OP_PRE_DICOM):
        pm = get_path_manager(project_dir)
        sourcedata_dir = Path(pm.sourcedata_subject(subject_id))
        bids_anat_dir = Path(pm.bids_anat(subject_id))
        modality_targets = (
            ("T1w", bids_anat_dir),
            ("T2w", bids_anat_dir),
            ("dwi", Path(pm.bids_dwi(subject_id))),
        )

        converted = False
        for modality, output_dir in modality_targets:
            dicom_dir = _modality_dicom_dir(sourcedata_dir, modality)
            if _convert_modality(
                dicom_dir, output_dir, subject_id, modality, logger, runner
            ):
                converted = True

        if not converted:
            logger.warning("No DICOM files found or converted")