structural

tit.pre.structural

Preprocessing pipeline orchestration.

This module contains the top-level run_pipeline function that drives all preprocessing steps for one or more subjects: DICOM conversion, SimNIBS CHARM, FastSurfer deep segmentation, tissue analysis, DWI preprocessing (QSIPrep, optional QSIRecon), and DTI tensor extraction (DIPY on QSIPrep output).

Public API

run_pipeline Run the full preprocessing pipeline for one or more subjects.

See Also

tit.pre : Package-level overview and convenience re-exports.

run_pipeline

run_pipeline(subject_ids: Iterable[str], *, convert_dicom: bool = False, run_fastsurfer: bool = False, charm_threads: int | None = None, charm_options: dict | None = None, fastsurfer_threads: int | None = None, run_freesurfer: bool = False, freesurfer_recon_all: bool = True, freesurfer_subregions: list[str] | None = None, freesurfer_threads: int | None = None, create_m2m: bool = False, run_tissue_analysis: bool = False, run_qsiprep: bool = False, run_qsirecon: bool = False, qsiprep_config: dict | None = None, qsi_recon_config: dict | None = None, extract_dti: bool = False, skip_existing_outputs: bool = False, replace_existing_outputs: bool = False, stop_event: object | None = None, logger_callback: Callable | None = None, runner: CommandRunner | None = None) -> int

Run the preprocessing pipeline for one or more subjects.

Orchestrates DICOM conversion, SimNIBS CHARM, FastSurfer deep segmentation, tissue analysis, QSIPrep/QSIRecon DWI preprocessing and DTI tensor extraction. Steps are enabled via boolean flags; disabled steps are skipped.

All step flags default to False; pass keyword arguments only.

Parameters

subject_ids : iterable of str Subject identifiers without the sub- prefix (e.g. ["ernie", "101"]). Subjects run sequentially. convert_dicom : bool, optional Run DICOM-to-NIfTI conversion (sourcedata/sub-<id>/ to sub-<id>/anat/). run_fastsurfer : bool, optional Run FastSurfer --seg_only deep segmentation. charm_threads : int or None, optional Thread count for SimNIBS charm; None uses its default. charm_options : dict or None, optional charm overrides: {"denoise": bool, "segmentation_final_resolution": 0.5-2.0, "skin_facet_size": 0.5-10.0} (keys optional; unknown keys raise ValueError). None keeps the installed defaults. fastsurfer_threads : int or None, optional Thread count for FastSurfer inference. run_freesurfer : bool, optional Run FreeSurfer (requires a FreeSurfer install, which the standard image does not ship). freesurfer_recon_all : bool, optional With run_freesurfer, run recon-all (default True); set False to run only freesurfer_subregions on an existing reconstruction. freesurfer_subregions : list of str or None, optional FreeSurfer subregion segmentations to add: any of "thalamus", "hippo-amygdala". freesurfer_threads : int or None, optional Thread count for FreeSurfer. create_m2m : bool, optional Run SimNIBS charm to build m2m_<id> (also runs subject_atlas for .annot files). run_tissue_analysis : bool, optional Run tissue-volume and thickness analysis. run_qsiprep : bool, optional Run QSIPrep DWI preprocessing via Docker. run_qsirecon : bool, optional Run QSIRecon reconstruction via Docker. qsiprep_config : dict or None, optional Extra configuration passed to run_qsiprep. qsi_recon_config : dict or None, optional Extra configuration passed to run_qsirecon. extract_dti : bool, optional Extract DTI tensor for SimNIBS anisotropic conductivity. skip_existing_outputs : bool, optional Skip selected preprocessing steps when their output already exists. replace_existing_outputs : bool, optional Remove selected existing outputs before rerunning their steps. stop_event : object or None, optional Threading event used to cancel running steps. logger_callback : callable or None, optional Callback used by the GUI to capture log lines. runner : CommandRunner or None, optional Subprocess runner used to stream command output.

Returns

int 0 on success, 1 on failure.

Raises

PreprocessError If no subjects are provided, both skip_existing_outputs and replace_existing_outputs are set, a required input is missing for a selected step (checked for every subject before anything runs), or a preprocessing step fails. PreprocessCancelled If stop_event is set during execution.

Examples

from tit.pre import run_pipeline run_pipeline(["ernie"], convert_dicom=True, create_m2m=True) # doctest: +SKIP 0 run_pipeline(["ernie", "101"], create_m2m=True, ... charm_options={"denoise": True}, ... skip_existing_outputs=True) # doctest: +SKIP 0

See Also

run_dicom_to_nifti : DICOM-to-NIfTI conversion step. run_fastsurfer : FastSurfer deep-segmentation step. run_charm : SimNIBS CHARM head-mesh step. run_tissue_analysis : Tissue analysis step. run_qsiprep : QSIPrep DWI preprocessing step. run_qsirecon : QSIRecon reconstruction step. extract_dti_tensor : DTI tensor extraction step.

Source code in tit/pre/structural.py

def run_pipeline(
    subject_ids: Iterable[str],
    *,
    convert_dicom: bool = False,
    run_fastsurfer: bool = False,
    charm_threads: int | None = None,
    charm_options: dict | None = None,
    fastsurfer_threads: int | None = None,
    run_freesurfer: bool = False,
    freesurfer_recon_all: bool = True,
    freesurfer_subregions: list[str] | None = None,
    freesurfer_threads: int | None = None,
    create_m2m: bool = False,
    run_tissue_analysis: bool = False,
    run_qsiprep: bool = False,
    run_qsirecon: bool = False,
    qsiprep_config: dict | None = None,
    qsi_recon_config: dict | None = None,
    extract_dti: bool = False,
    skip_existing_outputs: bool = False,
    replace_existing_outputs: bool = False,
    stop_event: object | None = None,
    logger_callback: Callable | None = None,
    runner: CommandRunner | None = None,
) -> int:
    """Run the preprocessing pipeline for one or more subjects.

    Orchestrates DICOM conversion, SimNIBS CHARM, FastSurfer deep
    segmentation, tissue analysis, QSIPrep/QSIRecon DWI preprocessing and
    DTI tensor extraction.  Steps are enabled via boolean flags; disabled
    steps are skipped.

    All step flags default to ``False``; pass keyword arguments only.

    Parameters
    ----------
    subject_ids : iterable of str
        Subject identifiers without the ``sub-`` prefix (e.g.
        ``["ernie", "101"]``).  Subjects run sequentially.
    convert_dicom : bool, optional
        Run DICOM-to-NIfTI conversion (``sourcedata/sub-<id>/`` to
        ``sub-<id>/anat/``).
    run_fastsurfer : bool, optional
        Run FastSurfer ``--seg_only`` deep segmentation.
    charm_threads : int or None, optional
        Thread count for SimNIBS ``charm``; ``None`` uses its default.
    charm_options : dict or None, optional
        ``charm`` overrides: ``{"denoise": bool,
        "segmentation_final_resolution": 0.5-2.0,
        "skin_facet_size": 0.5-10.0}`` (keys optional; unknown keys
        raise ``ValueError``).  ``None`` keeps the installed defaults.
    fastsurfer_threads : int or None, optional
        Thread count for FastSurfer inference.
    run_freesurfer : bool, optional
        Run FreeSurfer (requires a FreeSurfer install, which the standard
        image does not ship).
    freesurfer_recon_all : bool, optional
        With *run_freesurfer*, run ``recon-all`` (default ``True``); set
        ``False`` to run only *freesurfer_subregions* on an existing
        reconstruction.
    freesurfer_subregions : list of str or None, optional
        FreeSurfer subregion segmentations to add: any of
        ``"thalamus"``, ``"hippo-amygdala"``.
    freesurfer_threads : int or None, optional
        Thread count for FreeSurfer.
    create_m2m : bool, optional
        Run SimNIBS ``charm`` to build ``m2m_<id>`` (also runs
        ``subject_atlas`` for ``.annot`` files).
    run_tissue_analysis : bool, optional
        Run tissue-volume and thickness analysis.
    run_qsiprep : bool, optional
        Run QSIPrep DWI preprocessing via Docker.
    run_qsirecon : bool, optional
        Run QSIRecon reconstruction via Docker.
    qsiprep_config : dict or None, optional
        Extra configuration passed to ``run_qsiprep``.
    qsi_recon_config : dict or None, optional
        Extra configuration passed to ``run_qsirecon``.
    extract_dti : bool, optional
        Extract DTI tensor for SimNIBS anisotropic conductivity.
    skip_existing_outputs : bool, optional
        Skip selected preprocessing steps when their output already exists.
    replace_existing_outputs : bool, optional
        Remove selected existing outputs before rerunning their steps.
    stop_event : object or None, optional
        Threading event used to cancel running steps.
    logger_callback : callable or None, optional
        Callback used by the GUI to capture log lines.
    runner : CommandRunner or None, optional
        Subprocess runner used to stream command output.

    Returns
    -------
    int
        ``0`` on success, ``1`` on failure.

    Raises
    ------
    PreprocessError
        If no subjects are provided, both *skip_existing_outputs* and
        *replace_existing_outputs* are set, a required input is missing
        for a selected step (checked for every subject before anything
        runs), or a preprocessing step fails.
    PreprocessCancelled
        If *stop_event* is set during execution.

    Examples
    --------
    >>> from tit.pre import run_pipeline
    >>> run_pipeline(["ernie"], convert_dicom=True, create_m2m=True)  # doctest: +SKIP
    0
    >>> run_pipeline(["ernie", "101"], create_m2m=True,
    ...              charm_options={"denoise": True},
    ...              skip_existing_outputs=True)  # doctest: +SKIP
    0

    See Also
    --------
    run_dicom_to_nifti : DICOM-to-NIfTI conversion step.
    run_fastsurfer : FastSurfer deep-segmentation step.
    run_charm : SimNIBS CHARM head-mesh step.
    run_tissue_analysis : Tissue analysis step.
    run_qsiprep : QSIPrep DWI preprocessing step.
    run_qsirecon : QSIRecon reconstruction step.
    extract_dti_tensor : DTI tensor extraction step.
    """
    from tit.telemetry import track_operation
    from tit import constants as _const

    subject_list = [str(s).strip() for s in subject_ids if str(s).strip()]
    if not subject_list:
        raise PreprocessError("No subjects provided.")
    if skip_existing_outputs and replace_existing_outputs:
        raise PreprocessError(
            "skip_existing_outputs and replace_existing_outputs cannot both be true."
        )

    pm = get_path_manager()
    project_dir = pm._root()
    input_problems = find_missing_preprocessing_inputs(
        project_dir,
        subject_list,
        convert_dicom=convert_dicom,
        create_m2m=create_m2m,
        run_fastsurfer=run_fastsurfer,
        run_freesurfer=run_freesurfer,
        freesurfer_recon_all=freesurfer_recon_all,
        freesurfer_subregions=freesurfer_subregions or [],
        run_qsiprep=run_qsiprep,
        run_qsirecon=run_qsirecon,
        extract_dti=extract_dti,
        skip_existing_outputs=skip_existing_outputs,
    )
    if input_problems:
        raise PreprocessError(_format_input_problems(input_problems))

    with track_operation(_const.TELEMETRY_OP_PRE_PIPELINE):
        return _run_pipeline_inner(
            subject_list,
            convert_dicom=convert_dicom,
            run_fastsurfer=run_fastsurfer,
            charm_threads=charm_threads,
            charm_options=charm_options,
            fastsurfer_threads=fastsurfer_threads,
            run_freesurfer=run_freesurfer,
            freesurfer_recon_all=freesurfer_recon_all,
            freesurfer_subregions=freesurfer_subregions,
            freesurfer_threads=freesurfer_threads,
            create_m2m=create_m2m,
            run_tissue_analysis=run_tissue_analysis,
            run_qsiprep=run_qsiprep,
            run_qsirecon=run_qsirecon,
            qsiprep_config=qsiprep_config,
            qsi_recon_config=qsi_recon_config,
            extract_dti=extract_dti,
            skip_existing_outputs=skip_existing_outputs,
            replace_existing_outputs=replace_existing_outputs,
            stop_event=stop_event,
            logger_callback=logger_callback,
            runner=runner,
        )