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 and T2w DICOM directories under sourcedata/sub-{subject_id}/ and converts each found modality using dcm2niix. 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`` and ``T2w`` DICOM directories under
    ``sourcedata/sub-{subject_id}/`` and converts each found modality
    using ``dcm2niix``. 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))
        bids_anat_dir.mkdir(parents=True, exist_ok=True)

        converted = False
        for modality in ("T1w", "T2w"):
            dicom_dir = sourcedata_dir / modality / "dicom"
            if _convert_modality(
                dicom_dir, bids_anat_dir, subject_id, modality, logger, runner
            ):
                converted = True

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