Preprocess Workflow#

Raw DWI/T1/T2 preprocessing workflow that converts vendor-style inputs into an HCP-compatible output layout under data/processed/<patient_id>/T1w/. Wraps TOPUP, Eddy, DTIFit, BedpostX, N4 bias correction, SynthStrip/SynthSeg, and optional ANTs registration / template-label transform steps.

Workflow entry point#

Raw-to-HCP-compatible diffusion preprocessing workflow.

thesis.workflows.preprocess.workflow.build_workflow(*, t1, t2, dwi_ap, dwi_ap_bval, dwi_ap_bvec, dwi_pa, config, context)[source]#

Build the preprocess workflow for one raw patient dataset.

Parameters:

t1 (Path | None)
t2 (Path | None)
dwi_ap (Path | None)
dwi_ap_bval (Path | None)
dwi_ap_bvec (Path | None)
dwi_pa (Path | None)
config (PipelineConfig)
context (ProcessingContext)

Return type:

Workflow

thesis.workflows.preprocess.workflow.verify_requirements(config, context, *, t1=None, t2=None, dwi_ap=None, dwi_ap_bval=None, dwi_ap_bvec=None, dwi_pa=None, **_)[source]#

Preflight checks: required inputs exist, required binaries on PATH.

Parameters:

config (PipelineConfig)
context (ProcessingContext)
t1 (Path | None)
t2 (Path | None)
dwi_ap (Path | None)
dwi_ap_bval (Path | None)
dwi_ap_bvec (Path | None)
dwi_pa (Path | None)
_ (object)

Return type:

list[str]

Configuration#

Configuration for the preprocessing workflow.

This module provides Pydantic models for validating and managing preprocessing workflow parameters, including input file patterns, acquisition parameters, BET settings, BedpostX configuration, SynthSeg options, registration chains, and output naming conventions.

class thesis.workflows.preprocess.config.AcqParamsConfig[source]#

Bases: BaseConfig

Acquisition parameters for TOPUP distortion correction.

create_acqparams_file derives the readout time from bandwidth and phase_encoding_dirs and emits fixed AP/PA encoding rows, so only these two fields are needed.

Variables:

bandwidth – Effective readout bandwidth in Hz per pixel.
phase_encoding_dirs – Number of phase-encoding lines used to derive the readout time.

Parameters:

data (Any)

bandwidth: float#

phase_encoding_dirs: int#

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class thesis.workflows.preprocess.config.BetConfig[source]#

Bases: BaseConfig

Brain extraction (BET) parameters for different modalities.

Variables:

frac_dwi – Fractional intensity threshold for DWI brain extraction (0-1).
frac_t1 – Fractional intensity threshold for T1 brain extraction (0-1).
frac_t2 – Fractional intensity threshold for T2 brain extraction (0-1).
robust – Whether to use robust brain center estimation.
padding – Whether to apply padding (improves BET performance).
radius – Optional brain radius in mm (if not specified, BET estimates it).

Parameters:

data (Any)

frac_dwi: float#

frac_t1: float#

frac_t2: float#

robust: bool#

padding: bool#

radius: int | None#

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class thesis.workflows.preprocess.config.BedpostXConfig[source]#

Bases: BaseConfig

BedpostX fibre orientation estimation parameters.

Variables:

n_fibres – Number of fibre populations to model per voxel (1-3).
model – Model type (1 = single-shell, 2 = multi-shell, 3 = ball-and-sticks).
burn_in – Number of MCMC burn-in jumps.
n_jumps – Total number of MCMC jumps.
sample_every – Sample every Nth jump.
use_gpu – Whether to use GPU acceleration (requires CUDA-enabled BedpostX).
weight – ARD weight (only for model 3).

Parameters:

data (Any)

n_fibres: int#

model: int#

burn_in: int#

n_jumps: int#

sample_every: int#

use_gpu: bool#

weight: float#

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class thesis.workflows.preprocess.config.PreprocessSynthSegConfig[source]#

Bases: BaseConfig

SynthSeg segmentation parameters for the preprocessing workflow.

Variables:

run_on_t1 – Whether to run SynthSeg on T1-weighted image.
run_on_t2 – Whether to run SynthSeg on T2-weighted image.
parc – Whether to generate cortical parcellation.
robust – Whether to use robust mode.
fast – Whether to use fast mode.
vol – Whether to write volumes CSV.
qc – Whether to write QC CSV.
crop – Optional crop size.
cpu – Whether to force CPU execution.
threads – CPU thread count when cpu=True.
options – Additional SynthSeg command-line options.

Parameters:

data (Any)

run_on_t1: bool#

run_on_t2: bool#

parc: bool#

robust: bool#

fast: bool#

vol: bool#

qc: bool#

crop: int | None#

cpu: bool#

threads: int#

options: Dict[str, Any]#

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class thesis.workflows.preprocess.config.RegistrationStepConfig[source]#

Bases: BaseConfig

Configuration for a single registration step.

Variables:

method – Registration method (ants, fsl, etc.).
metric – Similarity metric (MI, CC, etc.).
transform_type – Transform type (Rigid, Affine, SyN).
interpolation – Interpolation method (Linear, BSpline, etc.).
use_float – Whether to use float precision.
collapse_output_transforms – Whether to collapse output transforms.
write_composite_transform – Whether to write composite transform.

Parameters:

data (Any)

method: str#

metric: str#

transform_type: str#

interpolation: str#

use_float: bool#

collapse_output_transforms: bool#

write_composite_transform: bool#

classmethod validate_method(v)[source]#

Validate registration method.

Parameters:: v (str)
Return type:: str

classmethod validate_transform_type(v)[source]#

Validate transform type.

Parameters:: v (str)
Return type:: str

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class thesis.workflows.preprocess.config.RegistrationChainConfig[source]#

Bases: BaseConfig

Multi-step registration chain configuration.

Variables:

dwi_to_t1 – Registration from DWI space to T1 space.
t2_to_t1 – Registration from T2 space to T1 space.
t1_to_template – Registration from T1 space to template space.

Parameters:

data (Any)

dwi_to_t1: RegistrationStepConfig#

t2_to_t1: RegistrationStepConfig#

t1_to_template: RegistrationStepConfig#

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class thesis.workflows.preprocess.config.LabelTransformConfig[source]#

Bases: BaseConfig

Label transformation and atlas warping configuration.

Variables:

transform_mni_labels – Whether to transform MNI atlas labels to subject space.
use_hcp_template – Whether to use HCP MNI template as reference.
mni_labels_list – List of MNI atlas label files to transform.
interpolation – Interpolation method for label images (NearestNeighbor, etc.).
use_inverse_warp – Whether to use inverse warp (template→subject).

Parameters:

data (Any)

transform_mni_labels: bool#

use_hcp_template: bool#

mni_labels_list: List[str]#

interpolation: str#

use_inverse_warp: bool#

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class thesis.workflows.preprocess.config.DTIFitConfig[source]#

Bases: BaseConfig

DTIFit configuration for tensor estimation.

Variables:

use_wls – Whether to use weighted least squares fitting.
compute_kurt – Whether to compute kurtosis parameters.
save_tensor – Whether to save full tensor components.

Parameters:

data (Any)

use_wls: bool#

compute_kurt: bool#

save_tensor: bool#

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class thesis.workflows.preprocess.config.PreprocessConfig[source]#

Bases: BaseConfig

Comprehensive configuration for the preprocessing workflow.

Variables:

patterns (# Input file)
t1_image – T1-weighted image file pattern or path.
t2_image – Optional T2-weighted image file pattern or path.
dwi_ap – Anterior-posterior DWI image.
dwi_ap_bval – b-values file for AP acquisition.
dwi_ap_bvec – b-vectors file for AP acquisition.
dwi_pa – Posterior-anterior DWI image (for TOPUP).
parameters (# SynthSeg)
acq_params – TOPUP acquisition parameters.
parameters
bet – Brain extraction parameters for different modalities.
parameters
bedpostx – Fibre orientation estimation parameters.
parameters
synthseg – Segmentation parameters.
chain (# Registration)
registration – Multi-step registration configuration.
transformation (# Label)
label_transform – Label transformation and atlas warping config.
options (# DTIFit)
dtifit – DTI tensor estimation options.
naming (# Output)
t1_final – Output T1 filename.
t2_final – Output T2 filename.
diffusion_dir – Output diffusion directory name.
bedpostx_dir – Output BedpostX directory name.
flags (# Workflow control)
run_topup – Whether to run TOPUP distortion correction.
run_eddy – Whether to run eddy current correction.
run_dtifit – Whether to run DTIFit.
run_bedpostx – Whether to run BedpostX.
run_synthseg – Whether to run SynthSeg.
run_coregistration – Whether to run the intra-subject coregistration chain (DWI->T1, T2->T1, MNI-label warps).

Parameters:

data (Any)

t1_image: str#

t2_image: str | None#

dwi_ap: str#

dwi_ap_bval: str#

dwi_ap_bvec: str#

dwi_pa: str | None#

acq_params: AcqParamsConfig#

bet: BetConfig#

bedpostx: BedpostXConfig#

synthseg: PreprocessSynthSegConfig#

registration: RegistrationChainConfig#

label_transform: LabelTransformConfig#

dtifit: DTIFitConfig#

t1_final: str#

t2_final: str#

diffusion_dir: str#

bedpostx_dir: str#

run_topup: bool#

run_eddy: bool#

run_dtifit: bool#

run_bedpostx: bool#

run_synthseg: bool#

run_coregistration: bool#

run_robustfov: bool#

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class thesis.workflows.preprocess.config.PreprocessPaths[source]#

Bases: TypedDict

Resolved filesystem paths for the preprocessing workflow.

input_dir: Path#

output_dir: Path#

t1_image: Path | None#

t2_image: Path | None#

dwi_ap: Path#

dwi_ap_bval: Path#

dwi_ap_bvec: Path#

dwi_pa: Path | None#

diffusion_dir: Path#

bedpostx_dir: Path#

t1_final: Path#

t2_final: Path | None#

thesis.workflows.preprocess.config.prepare_preprocess_paths(config, context)[source]#

Resolve preprocessing input/output paths from config and context.

Parameters:

config (PipelineConfig)
context (ProcessingContext)

Return type:

PreprocessPaths

Nodes#

Distortion correction node builders for preprocessing workflows.

thesis.workflows.preprocess.nodes.distortion.prepare_extract_b0_node(input_dwi, output_path, name='extract_b0')[source]#

Create FSL ExtractROI node to extract first b0 volume.

Parameters:

input_dwi (str) – Path to input 4D DWI NIfTI file
output_path (str) – Path for output b0 volume
name (str) – Nipype node name (must be unique within a workflow)

Return type:

Node

Returns:

Configured Nipype Node for ExtractROI

Example

>>> node = prepare_extract_b0_node(
...     input_dwi="dwi.nii.gz",
...     output_path="b0.nii.gz"
... )

thesis.workflows.preprocess.nodes.distortion.prepare_merge_b0_node(output_path, name='merge_b0')[source]#

Create FSL Merge node to combine AP and PA b0 volumes.

The caller is responsible for wiring in_files via a workflow connection (use nipype.interfaces.utility.Merge upstream to assemble the list). Never set in_files statically here: a conditional assignment that fires only when the files already exist produces a different hash on first run vs. subsequent runs, causing Nipype to re-execute the node even when no real inputs changed.

Parameters:

output_path (str) – Path for output merged b0 file
name (str) – Nipype node name (must be unique within a workflow)

Return type:

Node

Returns:

Configured Nipype Node for Merge

Example

>>> node = prepare_merge_b0_node(output_path="b0_merged.nii.gz")

thesis.workflows.preprocess.nodes.distortion.prepare_topup_node(acqparams_file, output_base, name='topup')[source]#

Create FSL TOPUP node for susceptibility distortion correction.

Parameters:

acqparams_file (str) – Path to acquisition parameters file (–datain)
output_base (str) – Base name for output files (without extension)
name (str) – Nipype node name (must be unique within a workflow)

Return type:

Node

Returns:

Configured Nipype Node for TOPUP

Example

>>> node = prepare_topup_node(
...     acqparams_file="acqparams.txt",
...     output_base="topup_results"
... )

Note

Uses standard FSL b02b0.cnf configuration file. The acquisition parameters file should contain one line per input volume with format: phase_encode_direction readout_time (e.g., “0 1 0 0.05” for PA).

thesis.workflows.preprocess.nodes.distortion.prepare_brain_extraction_node(method='synthstrip', frac=0.3, name='brain_extract', use_gpu=False, gpu_device=None, robust=False, padding=False, radius=None)[source]#

Create brain extraction node using SynthStrip or BET.

Parameters:

method (str) – Brain extraction method (‘synthstrip’ or ‘bet’)
frac (float) – Fractional intensity threshold for BET (0-1, default 0.3)
name (str) – Nipype node name (must be unique within a workflow)
use_gpu (bool) – Whether SynthStrip should request GPU execution.
gpu_device (int | None) – Optional CUDA device index for SynthStrip.
robust (bool) – BET-only. Use robust brain-center estimation (FSL -R). Ignored when method is ‘synthstrip’.
padding (bool) – BET-only. Apply slice padding to improve BET on small FOVs (FSL -Z). Ignored when method is ‘synthstrip’.
radius (int | None) – BET-only. Head radius in mm (FSL -r); when None, BET estimates it. Ignored when method is ‘synthstrip’.

Return type:

Node

Returns:

Configured Nipype Node for brain extraction

Raises:

ValueError – If method is not ‘synthstrip’ or ‘bet’

Example

>>> node = prepare_brain_extraction_node(method="synthstrip")
>>> node = prepare_brain_extraction_node(method="bet", frac=0.4)

Note

SynthStrip (FreeSurfer) typically produces more accurate results than BET, especially for clinical data with pathology. The robust / padding / radius tuning options apply only to the BET path; SynthStrip ignores them.

thesis.workflows.preprocess.nodes.distortion.prepare_eddy_node(acqparams_file, index_file, bvals, bvecs, output_base, use_cuda=True, name='eddy')[source]#

Create FSL Eddy node for eddy current and motion correction.

Parameters:

acqparams_file (str) – Path to acquisition parameters file (–acqp)
index_file (str) – Path to index file mapping volumes to acqparams rows (–index)
bvals (str) – Path to b-values file
bvecs (str) – Path to b-vectors file
output_base (str) – Base name for output files
use_cuda (bool) – If True, attempt to use GPU-accelerated eddy_cuda
name (str) – Nipype node name (must be unique within a workflow)

Return type:

Node

Returns:

Configured Nipype Node for Eddy

Example

>>> node = prepare_eddy_node(
...     acqparams_file="acqparams.txt",
...     index_file="index.txt",
...     bvals="bvals",
...     bvecs="bvecs",
...     output_base="eddy_corrected",
...     use_cuda=True
... )

Note

When use_cuda=True, attempts eddy_cuda10.2 first, then falls back to standard eddy if CUDA is not available. Enables outlier replacement (repol=True) and assumes single-shell or multi-shell data (is_shelled=True).

thesis.workflows.preprocess.nodes.distortion.prepare_convert_to_short_node(output_path, name='convert_short')[source]#

Create FSL ImageMaths node to convert to short datatype.

Converts image data to 16-bit signed integer (short) format for compatibility with 3D Slicer and reduced file size.

Parameters:

output_path (str) – Path for output converted file
name (str) – Nipype node name (must be unique within a workflow)

Return type:

Node

Returns:

Configured Nipype Node for ImageMaths

Example

>>> node = prepare_convert_to_short_node(
...     output_path="dwi_short.nii.gz"
... )

Note

This conversion is often necessary for visualization in 3D Slicer, which has limitations with certain data types.

Diffusion MRI processing node builders for DTIFit and BedpostX.

This module provides factory functions to create configured Nipype nodes for: - DTIFit: Tensor fitting using FSL’s dtifit - BedpostX: Bayesian estimation of diffusion parameters using FSL’s bedpostx_gpu/bedpostx

thesis.workflows.preprocess.nodes.diffusion.prepare_dtifit_node(use_wls=True, save_tensor=True, compute_sse=True, compute_kurt=False, name='dtifit')[source]#

Create a configured DTIFit node for tensor fitting.

Uses FSL’s dtifit to fit diffusion tensors to DWI data and compute derived metrics (FA, MD, eigenvalues, eigenvectors).

Parameters:

use_wls (bool) – Use weighted least squares fitting (–wls flag). Recommended for better handling of noise and outliers.
save_tensor (bool) – Save the full diffusion tensor elements.
compute_sse (bool) – Compute sum of squared errors between model and data.
compute_kurt (bool) – Compute kurtosis tensors (–kurt flag). Requires additional high b-value shells.
name (str) – Node name for workflow visualization.

Return type:

Node

Returns:

Configured Nipype Node wrapping FSL DTIFit interface.

Raises:

ValueError – If name is empty.

Example

>>> node = prepare_dtifit_node(use_wls=True, compute_kurt=False)
>>> node.inputs.dwi = "dwi.nii.gz"
>>> node.inputs.mask = "brain_mask.nii.gz"
>>> node.inputs.bvecs = "bvecs"
>>> node.inputs.bvals = "bvals"
>>> node.inputs.base_name = "dti"

thesis.workflows.preprocess.nodes.diffusion.prepare_bedpostx_node(n_fibres=3, model=2, burn_in=1000, n_jumps=1250, sample_every=25, use_gpu=True, name='bedpostx')[source]#

Create a configured BedpostX node for Bayesian diffusion parameter estimation.

Uses FSL’s BEDPOSTX5 to estimate up to 5 crossing fiber populations per voxel using Markov Chain Monte Carlo (MCMC) sampling. Supports GPU acceleration.

Parameters:

n_fibres (int) – Number of fiber populations to model per voxel (1-5). More fibers allow modeling complex crossings but increase computation time.
model (int) – Diffusion model type: 1 = Ball and stick (single fiber orientation per population) 2 = Ball and sticks with ARD (automatic relevance determination) 3 = Ball and Bingham (allows fanning/spreading of fibers)
burn_in (int) – Number of MCMC burn-in iterations to discard. Default 1000.
n_jumps (int) – Number of MCMC jumps after burn-in. Default 1250.
sample_every (int) – Sample every Nth MCMC iteration. Default 25. Total samples = n_jumps / sample_every = 50 by default.
use_gpu (bool) – Attempt to use GPU-accelerated bedpostx_gpu if available. Falls back to CPU version if GPU not detected.
name (str) – Node name for workflow visualization.

Return type:

Node

Returns:

Configured Nipype Node wrapping FSL BEDPOSTX5 interface.

Raises:

ValueError – If n_fibres not in range [1, 5], model not in [1, 2, 3], or name is empty.

Example

>>> node = prepare_bedpostx_node(n_fibres=3, model=2, use_gpu=True)
>>> node.inputs.dwi = "dwi.nii.gz"
>>> node.inputs.mask = "brain_mask.nii.gz"
>>> node.inputs.bvecs = "bvecs"
>>> node.inputs.bvals = "bvals"

Node builders for structural preprocessing workflows.

This module provides node builders for structural MRI preprocessing including: - N4 bias field correction (ANTs) - Robust field-of-view cropping (FSL) - Image thresholding (FSL) - SynthSeg segmentation (FreeSurfer) - Tissue type conversion (GM/WM/CSF) - Tractography mask creation

thesis.workflows.preprocess.nodes.structural.prepare_n4_bias_correction_node(dimension=3, bspline_fitting_distance=300, shrink_factor=3, n_iterations=None, name='n4_bias_correction')[source]#

Prepare Nipype node for ANTs N4 bias field correction.

N4 is a variant of the popular N3 (nonparametric nonuniform normalization) retrospective bias correction algorithm. It improves on N3 by using a B-spline approximation to smooth the bias field.

Parameters:

dimension (int) – Image dimension (2 or 3)
bspline_fitting_distance (int) – B-spline fitting distance in mm
shrink_factor (int) – Shrink factor for speed (higher = faster but less accurate)
n_iterations (list[int] | None) – Number of iterations at each resolution level. Defaults to [50, 50, 30, 20].
name (str) – Name for the Nipype node

Return type:

Node

Returns:

Configured Nipype Node wrapping ANTs N4BiasFieldCorrection

Example

>>> node = prepare_n4_bias_correction_node(
...     dimension=3,
...     bspline_fitting_distance=300,
...     shrink_factor=3,
...     n_iterations=[50, 50, 30, 20]
... )
>>> node.inputs.input_image = "T1.nii.gz"
>>> node.inputs.output_image = "T1_corrected.nii.gz"

thesis.workflows.preprocess.nodes.structural.prepare_robust_fov_node(brainsize=150, name='robust_fov')[source]#

Prepare Nipype node for FSL RobustFOV to crop field of view.

RobustFOV reduces the field of view to remove lower head and neck regions, which can improve registration and reduce computation time.

Parameters:

brainsize (int) – Brain size parameter in mm (typical range: 100-200)
name (str) – Name for the Nipype node

Return type:

Node

Returns:

Configured Nipype Node wrapping FSL RobustFOV

Example

>>> node = prepare_robust_fov_node(brainsize=150)
>>> node.inputs.in_file = "T1.nii.gz"
>>> node.inputs.out_roi = "T1_cropped.nii.gz"

thesis.workflows.preprocess.nodes.structural.prepare_threshold_node(thresh, direction='below', name='threshold')[source]#

Prepare Nipype node for FSL image thresholding.

Parameters:

thresh (float) – Threshold value
direction (str) – Thresholding direction - “below” zeros values below thresh, “above” zeros values above thresh
name (str) – Name for the Nipype node

Return type:

Node

Returns:

Configured Nipype Node wrapping FSL Threshold

Raises:

ValueError – If direction is not “below” or “above”

Example

>>> node = prepare_threshold_node(thresh=0.5, direction="below")
>>> node.inputs.in_file = "image.nii.gz"
>>> node.inputs.out_file = "image_thresholded.nii.gz"

thesis.workflows.preprocess.nodes.structural.prepare_synthseg_node(parc=True, robust=True, fast=True, name='synthseg')[source]#

Prepare Nipype node for FreeSurfer SynthSeg segmentation.

SynthSeg is a learning-based tool for brain segmentation and parcellation that is robust to different MRI contrasts, resolutions, and acquisition artifacts.

Parameters:

parc (bool) – If True, output parcellation (191 labels); if False, segmentation (32 labels)
robust (bool) – If True, use robust version for images with lesions and low contrast
fast (bool) – If True, use fast approximate mode
name (str) – Name for the Nipype node

Return type:

Node

Returns:

Configured Nipype Node wrapping the custom SynthSeg interface

Example

>>> node = prepare_synthseg_node(parc=True, robust=True, fast=True)
>>> node.inputs.input_image = "T1.nii.gz"
>>> node.inputs.output_segmentation = "synthseg.nii.gz"
>>> node.inputs.output_volumes = "volumes.csv"
>>> node.inputs.output_qc = "qc.csv"
>>> node.inputs.output_resampled = "resampled.nii.gz"

thesis.workflows.preprocess.nodes.structural.prepare_gm_wm_csf_converter_node(name='convert_gm_wm_csf')[source]#

Prepare Nipype node to convert SynthSeg labels to GM/WM/CSF tissue types.

This node converts a SynthSeg segmentation to a simplified tissue type map: - 0 = background - 1 = gray matter (GM) - 2 = white matter (WM) - 3 = cerebrospinal fluid (CSF)

Parameters:: name (str) – Name for the Nipype node
Return type:: Node
Returns:: Configured Nipype Node wrapping convert_synthseg_to_gm_wm_csf via Function interface

Example

>>> node = prepare_gm_wm_csf_converter_node()
>>> node.inputs.input_image = "synthseg.nii.gz"
>>> node.inputs.output_image = "tissue_types.nii.gz"

thesis.workflows.preprocess.nodes.structural.prepare_tract_masks_creator_node(name='create_tract_masks')[source]#

Prepare Nipype node to create tractography masks from SynthSeg labels.

This node creates three binary masks for tractography: 1. Cerebellar right + cerebral left white matter 2. Cerebellar left + cerebral right white matter 3. CSF (exclusion mask)

Parameters:: name (str) – Name for the Nipype node
Return type:: Node
Returns:: Configured Nipype Node wrapping create_tractography_masks via Function interface

Example

>>> node = prepare_tract_masks_creator_node()
>>> node.inputs.input_image = "synthseg.nii.gz"
>>> node.inputs.output_prefix = "derivatives/masks/sub-01"

Node builders for ANTs registration workflows.

This module provides node builders for ANTs-based image registration including: - ANTs Registration (Rigid, Affine, SyN) - ANTs ApplyTransforms (forward and inverse)

thesis.workflows.preprocess.nodes.registration.prepare_ants_registration_node(transform_type='Rigid', num_threads=1, name='registration')[source]#

Create ANTs Registration node with appropriate settings for the transform type.

Parameters:

transform_type (str) – Type of registration transform. Options: “Rigid”, “Affine”, “SyN”
num_threads (int) – Number of parallel threads for ANTs (default: 1)
name (str) – Node name (default: “registration”)

Return type:

Node

Returns:

Configured Nipype Node with ANTs Registration interface

Raises:

ValueError – If transform_type is not one of “Rigid”, “Affine”, “SyN”

Example

>>> node = prepare_ants_registration_node(transform_type="Rigid", num_threads=4)
>>> node.inputs.moving_image = "T1.nii.gz"
>>> node.inputs.fixed_image = "DWI_b0.nii.gz"

thesis.workflows.preprocess.nodes.registration.make_ants_apply_transforms_interface(dimension=3, interpolation='BSpline')[source]#

Build a configured ANTs ApplyTransforms interface.

Returns the bare interface (not wrapped in a Node) so callers can plug it into a Node or a MapNode without first constructing a throwaway Node and reaching into its .interface.

Parameters:

dimension (int) – Image dimension (2 or 3, default: 3)
interpolation (str) – Interpolation method. Options: “BSpline”, “Linear”, “NearestNeighbor”, “MultiLabel” (default: “BSpline”)

Return type:

ApplyTransforms

Returns:

Configured ANTs ApplyTransforms interface

Raises:

ValueError – If dimension is not 2 or 3
ValueError – If interpolation is not valid

thesis.workflows.preprocess.nodes.registration.prepare_ants_apply_transforms_node(dimension=3, interpolation='BSpline', name='apply_transforms')[source]#

Create ANTs ApplyTransforms node for applying transformations to images.

Parameters:

dimension (int) – Image dimension (2 or 3, default: 3)
interpolation (str) – Interpolation method. Options: “BSpline”, “Linear”, “NearestNeighbor”, “MultiLabel” (default: “BSpline”)
name (str) – Node name (default: “apply_transforms”)

Return type:

Node

Returns:

Configured Nipype Node with ANTs ApplyTransforms interface

Raises:

ValueError – If dimension is not 2 or 3
ValueError – If interpolation is not valid

Example

>>> node = prepare_ants_apply_transforms_node(interpolation="Linear")
>>> node.inputs.input_image = "T1.nii.gz"
>>> node.inputs.reference_image = "DWI_b0.nii.gz"
>>> node.inputs.transforms = ["0GenericAffine.mat"]

Utility node builders for file operations.

This module provides Nipype Function node builders that wrap file manipulation operations from operations.file_ops. These nodes can be integrated into preprocessing workflows.

thesis.workflows.preprocess.nodes.utils.prepare_modify_bval_node(name='modify_bval')[source]#

Create a Nipype node for modifying bval files.

This node wraps the modify_bval operation, which replaces standalone “100” values with “101” in bval files.

Parameters:: name (str) – Name for the Nipype node
Return type:: Node
Returns:: Configured Nipype Function Node

Example

>>> node = prepare_modify_bval_node("modify_bval")
>>> node.inputs.input_bval = "input.bval"
>>> node.inputs.output_bval = "output.bval"
>>> result = node.run()

thesis.workflows.preprocess.nodes.utils.prepare_create_index_node(name='create_index')[source]#

Create a Nipype node for creating index files.

This node wraps the create_index_file operation, which creates an index file with “1” for each b-value in the bval file.

Parameters:: name (str) – Name for the Nipype node
Return type:: Node
Returns:: Configured Nipype Function Node

Example

>>> node = prepare_create_index_node("create_index")
>>> node.inputs.bval_file = "input.bval"
>>> node.inputs.output_index = "index.txt"
>>> result = node.run()

Operations#

Label manipulation operations for SynthSeg segmentation masks.

This module provides pure Python implementations for converting SynthSeg labels to tissue type maps and creating binary masks for tractography.

thesis.workflows.preprocess.operations.label_ops.convert_synthseg_to_gm_wm_csf(input_image, output_image)[source]#

Convert SynthSeg labels to GM/WM/CSF tissue type map.

Takes a SynthSeg segmentation and converts it to a simplified tissue type map using the following mapping: - 0 = background - 1 = gray matter (GM) - 2 = white matter (WM) - 3 = cerebrospinal fluid (CSF)

All label values > 1000 are mapped to 1 (GM) to handle FreeSurfer-style high-value labels.

Parameters:

input_image (str) – Path to input SynthSeg segmentation (.nii or .nii.gz)
output_image (str) – Path to output tissue type map (.nii or .nii.gz)

Return type:

str

Returns:

Absolute path to the output image

Raises:

FileNotFoundError – If input image doesn’t exist
FileIOError – If unable to read input or write output

Example

>>> output_path = convert_synthseg_to_gm_wm_csf(
...     "synthseg.nii.gz",
...     "tissue_types.nii.gz"
... )
>>> print(f"Created tissue map: {output_path}")

thesis.workflows.preprocess.operations.label_ops.create_tractography_masks(input_image, output_prefix)[source]#

Create three binary masks for tractography from SynthSeg labels.

Creates the following masks: 1. Cerebellar right + cerebral left: labels [2, 46] 2. Cerebellar left + cerebral right: labels [7, 41] 3. CSF (exclusion mask): labels [4, 5, 14, 15, 24, 43, 44]

Output files are named: - {output_prefix}_cerebellar_right_cerebral_left.nii.gz - {output_prefix}_cerebellar_left_cerebral_right.nii.gz - {output_prefix}_csf.nii.gz

Parameters:

input_image (str) – Path to input SynthSeg segmentation (.nii or .nii.gz)
output_prefix (str) – Path prefix for output masks (without extension)

Returns:

“cerebellar_right_cerebral_left”: right cerebellar + left cerebral WM
”cerebellar_left_cerebral_right”: left cerebellar + right cerebral WM
”csf”: CSF exclusion mask

Return type:

Dict[str, str]

Raises:

FileNotFoundError – If input image doesn’t exist
FileIOError – If unable to read input or write outputs

Example

>>> masks = create_tractography_masks(
...     "synthseg.nii.gz",
...     "derivatives/masks/sub-01"
... )
>>> for name, path in masks.items():
...     print(f"{name}: {path}")

File manipulation utilities for preprocessing workflows.

This module provides utility functions for manipulating dMRI-related files including bval/bvec files, index files, acquisition parameters, and creating HCP-compatible directory structures.

thesis.workflows.preprocess.operations.file_ops.modify_bval(input_bval, output_bval)[source]#

Modify bval file by replacing standalone “100” values with “101”.

This function reads a bval file and replaces all standalone occurrences of “100” with “101”, which can be useful for preprocessing workflows that require distinct b-values. Handles both space and tab separators.

Parameters:

input_bval (str) – Path to input bval file
output_bval (str) – Path to output bval file

Return type:

str

Returns:

Absolute path to the output bval file as a string

Raises:

FileNotFoundError – If input_bval does not exist
FileIOError – If unable to read or write the file

Example

>>> output = modify_bval("input.bval", "output.bval")
>>> # File containing "0 100 1000 100" becomes "0 101 1000 101"

thesis.workflows.preprocess.operations.file_ops.create_index_file(bval_file, output_index)[source]#

Create an index file with “1” for each b-value in the bval file.

This function reads a bval file, counts the number of values, and creates an index file with “1” for each value. The whitespace structure (spaces, tabs, newlines) is preserved from the input bval file.

Parameters:

bval_file (str) – Path to input bval file
output_index (str) – Path to output index file

Return type:

str

Returns:

Absolute path to the output index file as a string

Raises:

FileNotFoundError – If bval_file does not exist
FileIOError – If unable to read or write files

Example

>>> output = create_index_file("input.bval", "index.txt")
>>> # If input.bval contains "0 100 1000", output contains "1 1 1"

thesis.workflows.preprocess.operations.file_ops.create_acqparams_file(output_path, bandwidth, phase_encoding_dirs)[source]#

Create acquisition parameters file for FSL eddy/topup.

This function calculates the readout time from bandwidth and phase encoding directions, then creates a two-line file specifying AP and PA phase encoding directions with the calculated readout time.

Parameters:

output_path (str) – Path to output acqparams file
bandwidth (float) – Bandwidth in Hz
phase_encoding_dirs (int) – Number of phase encoding directions

Return type:

str

Returns:

Absolute path to the output acqparams file as a string

Raises:

FileIOError – If unable to write the file
ValueError – If bandwidth <= 0 or phase_encoding_dirs <= 1

Example

>>> output = create_acqparams_file("acqparams.txt", 2300.0, 96)
>>> # Creates file with readout time = (96-1)/2300.0 = 0.0413

thesis.workflows.preprocess.operations.file_ops.create_hcp_output_structure(output_dir, patient_id)[source]#

Create HCP-compatible directory structure for processing outputs.

This function creates the standard HCP directory structure used by tools like BedpostX and ProbTrackX2. All directories are created relative to the provided output_dir.

Parameters:

output_dir (Path) – Base output directory
patient_id (str) – Patient identifier (for logging purposes)

Returns:

“base”: output_dir
”t1w”: T1w/
”diffusion”: T1w/Diffusion/
”bedpostx”: T1w/Diffusion.bedpostX/
”registration”: registration/
”synthseg”: synthseg/
”dti”: dti/
”dti_wls”: dti/WLS/

Return type:

Dict[str, Path]

Raises:

FileIOError – If unable to create directories

Example

>>> dirs = create_hcp_output_structure(Path("/output"), "DTI_001")
>>> print(dirs["diffusion"])
/output/T1w/Diffusion