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, including DICOM conversion, FreeSurfer recon-all, SimNIBS CHARM, tissue analysis, DWI preprocessing (QSIPrep/QSIRecon), DTI tensor extraction, and subcortical segmentation.

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_recon: bool = False, parallel_recon: bool = False, parallel_cores: 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, run_subcortical_segmentations: 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, FreeSurfer recon-all, SimNIBS CHARM, tissue analysis, QSIPrep/QSIRecon DWI preprocessing, DTI tensor extraction, and subcortical segmentation. Steps are enabled via boolean flags; disabled steps are skipped.

Parameters

subject_ids : iterable of str Subject identifiers without the sub- prefix. convert_dicom : bool, optional Run DICOM-to-NIfTI conversion. run_recon : bool, optional Run FreeSurfer recon-all. parallel_recon : bool, optional Run recon-all in parallel across subjects. parallel_cores : int or None, optional Maximum number of parallel subjects for recon-all. create_m2m : bool, optional Run SimNIBS charm (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. run_subcortical_segmentations : bool, optional Run thalamic-nuclei and hippocampal-subfield segmentations. 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 or a preprocessing step fails. PreprocessCancelled If stop_event is set during execution.

See Also

run_dicom_to_nifti : DICOM-to-NIfTI conversion step. run_recon_all : FreeSurfer recon-all 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_recon: bool = False,
    parallel_recon: bool = False,
    parallel_cores: 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,
    run_subcortical_segmentations: 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, FreeSurfer recon-all, SimNIBS CHARM,
    tissue analysis, QSIPrep/QSIRecon DWI preprocessing, DTI tensor
    extraction, and subcortical segmentation.  Steps are enabled via
    boolean flags; disabled steps are skipped.

    Parameters
    ----------
    subject_ids : iterable of str
        Subject identifiers without the ``sub-`` prefix.
    convert_dicom : bool, optional
        Run DICOM-to-NIfTI conversion.
    run_recon : bool, optional
        Run FreeSurfer ``recon-all``.
    parallel_recon : bool, optional
        Run ``recon-all`` in parallel across subjects.
    parallel_cores : int or None, optional
        Maximum number of parallel subjects for ``recon-all``.
    create_m2m : bool, optional
        Run SimNIBS ``charm`` (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.
    run_subcortical_segmentations : bool, optional
        Run thalamic-nuclei and hippocampal-subfield segmentations.
    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 or a preprocessing step fails.
    PreprocessCancelled
        If *stop_event* is set during execution.

    See Also
    --------
    run_dicom_to_nifti : DICOM-to-NIfTI conversion step.
    run_recon_all : FreeSurfer recon-all 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_recon=run_recon,
        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_recon=run_recon,
            parallel_recon=parallel_recon,
            parallel_cores=parallel_cores,
            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,
            run_subcortical_segmentations=run_subcortical_segmentations,
            skip_existing_outputs=skip_existing_outputs,
            replace_existing_outputs=replace_existing_outputs,
            stop_event=stop_event,
            logger_callback=logger_callback,
            runner=runner,
        )