Configuration#

Hierarchical YAML configuration system built on Pydantic v2.

The package re-exports the most commonly used configuration classes, while the canonical API documentation lives on the concrete submodules below.

thesis.core.config.manager#

Configuration manager for hierarchical config loading and merging.

class thesis.core.config.manager.ConfigManager[source]#

Bases: object

Manages configuration loading, merging, and validation.

Supports hierarchical configuration with defaults, environment-specific overrides, and patient-specific configs. Uses Pydantic for validation and type safety.

Config hierarchy (later configs override earlier): 1. Default config 2. Hardware config 3. Protocol config 4. Patient-specific config 5. Runtime overrides

Example

>>> manager = ConfigManager(config_dir="./config")
>>> config = manager.load_config("default")
>>> config = manager.add_overrides(config, patient_id="DTI_LDF001")

Parameters:: config_dir (Union[str, Path, None])

__init__(config_dir=None)[source]#

Initialize the configuration manager.

Parameters:: config_dir (Union[str, Path, None]) – Base directory for config files. If None, uses ‘./config’

load_config(config_name='default', patient_id=None, protocol=None, overrides=None, protocol_required=False)[source]#

Load a configuration with optional overrides.

Parameters:

config_name (str) – Name of the base config to load
patient_id (Optional[str]) – Optional patient ID for patient-specific config
protocol (Optional[str]) – Optional protocol name for protocol-specific config
overrides (Optional[Mapping[str, object]]) – Optional dictionary of runtime overrides
protocol_required (bool) – If True, raise ConfigurationError when protocol is given but no matching file exists. Set this when the protocol was explicitly requested by the user (e.g. via --protocol) rather than supplied as a workflow’s default_protocol fallback.

Return type:

PipelineConfig

Returns:

Validated PipelineConfig object

Raises:

ConfigurationError – If the base config_name file is missing, or if protocol_required is True and the protocol file is missing.

Example

>>> config = manager.load_config(
...     config_name="default",
...     patient_id="DTI_LDF001",
...     overrides={"preprocessing": {"threads": 8}}
... )

load_config_dict(name, subdir=None)[source]#

Load a raw config dictionary without validation.

Parameters:

name (str) – Config file name without the extension.
subdir (Optional[str]) – Optional config subdirectory.

Return type:

Optional[dict[str, object]]

Returns:

Raw config dictionary, or None when the file does not exist.

save_config(config, name, subdir=None)[source]#

Save a configuration to a YAML file.

Parameters:

config (Union[PipelineConfig, dict[str, object]]) – Configuration to save (PipelineConfig or dict)
name (str) – Name for the config file
subdir (Optional[str]) – Optional subdirectory

Return type:

Path

Returns:

Path to saved file

list_configs(subdir=None)[source]#

List available config files.

Parameters:: subdir (Optional[str]) – Optional subdirectory to search
Return type:: list[str]
Returns:: List of config names (without .yaml extension)

get_config_dir(subdir=None)[source]#

Get the path to a config directory.

Parameters:: subdir (Optional[str]) – Optional subdirectory
Return type:: Path
Returns:: Path object

clear_cache()[source]#

Clear the configuration cache.

Return type:: None

thesis.core.config.validators#

Pydantic models for configuration validation.

These models ensure that configurations have the correct structure and valid values before being used in processing pipelines.

class thesis.core.config.validators.NormalizationMethod[source]#

Bases: str, Enum

Method for normalizing streamline density volumes before atlas combination.

Variables:

WAYTOTAL – Divide by waytotal (total streamline count). Default method for the FSL ProbTrackX2 backend; produces values representing the fraction of total streamlines passing through each voxel.
MAX – Divide by the maximum voxel value in the volume. Scales each volume to [0, 1] range.
SOFTMAX – Apply softmax normalization (exp(x) / sum(exp(x))). Produces a probability distribution that sums to 1.0 across the volume.
STREAMLINE_DENSITY – MRtrix3 counterpart of WAYTOTAL. Divides by the value stored in waytotal, which the MRtrix3 workflow writes as the sum of SIFT2 per-streamline weights when SIFT2 is enabled (matching the SIFT2-weighted TDI numerator) or the raw streamline count when SIFT2 is off. Produces a streamline fraction in [0, 1].

WAYTOTAL = 'waytotal'#

MAX = 'max'#

SOFTMAX = 'softmax'#

STREAMLINE_DENSITY = 'streamline_density'#

__new__(value)#

class thesis.core.config.validators.BaseConfig[source]#

Bases: BaseModel

Base config model that rejects unknown fields to catch typos early.

Parameters:: data (Any)

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

class thesis.core.config.validators.PathConfig[source]#

Bases: BaseConfig

Configuration for file paths and directories.

The three read-only/output roots are independent — none is a parent of the others:

Variables:

inputs_dir – Per-patient source data root. The patient’s input directory is inputs_dir / <patient_id>.
assets_dir – Cohort-shared, read-only assets (templates, atlases, ROIs, reference images). Anchors DataFile/DataDir lookups.
output_dir – Root for all workflow outputs/derivatives. The patient’s output directory is output_dir / <patient_id>.
scratch_dir – Optional temporary/scratch directory override. When unset, scratch defaults to output_dir / <patient_id> / temp.
log_dir – Directory for runtime logs.
scripts_dir – Optional directory of user-supplied workflow scripts (*.py).

Parameters:

data (Any)

inputs_dir: Path#

assets_dir: Path#

output_dir: Path#

scratch_dir: Path | None#

log_dir: Path#

scripts_dir: Path | None#

classmethod convert_to_path(v)[source]#: Convert string paths to Path objects, expanding ~ and env vars.

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

class thesis.core.config.validators.HardwareConfig[source]#

Bases: BaseConfig

Configuration for hardware and computational resources.

Variables:

threads – CPU threads available to workflow execution.
memory_gb – Memory budget in gigabytes.
gpu_enabled – Whether GPU-aware execution is enabled.
gpu_device – Optional GPU device index.
n_gpu_procs – Number of scheduler GPU worker slots.
n_gpus – Physical GPUs exposed per worker slot.

Parameters:

data (Any)

threads: int#

memory_gb: int#

gpu_enabled: bool#

gpu_device: int | None#

n_gpu_procs: int#

n_gpus: int#

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

class thesis.core.config.validators.AtlasConfig[source]#

Bases: BaseConfig

Atlas workflow configuration.

Parameters:: data (Any)

presence_value: float#

cov_mean_threshold_pct: float#

normalization_method: NormalizationMethod#

tractography_relpath: str#

output_subdir: str#

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

class thesis.core.config.validators.AtlasQCConfig[source]#

Bases: BaseConfig

Configuration for atlas workflow QC outputs.

Variables:

enabled – Whether atlas QC generation is enabled.
generate_group_plots – Whether cohort-level atlas summary plots are requested.
generate_patient_reports – Whether per-patient atlas QC outputs are requested.
outlier_sd_threshold – Number of standard deviations from the cohort mean used to flag atlas-derived outliers.
subject_density_threshold – Minimum normalized streamline density for a subject voxel to be considered present.
group_core_threshold – Minimum proportion of subjects that must have a valid streamline (above subject_density_threshold) for a voxel to be part of the core.
leave_one_out – Whether to compute leave-one-out statistics for each subject.
leave_one_out_min_subjects – Minimum number of subjects required to run leave-one-out validation.
compute_cv – Whether to compute Coefficient of Variation (CV) maps.
cv_mean_threshold – Fraction of atlas mean maximum required to compute CV.
compute_log_stats – Whether to compute statistics in log space.
log_offset – Small offset added to zero values before log transformation.

Parameters:

data (Any)

enabled: bool#

generate_group_plots: bool#

generate_patient_reports: bool#

outlier_sd_threshold: float#

subject_density_threshold: float#

group_core_threshold: float#

leave_one_out: bool#

leave_one_out_min_subjects: int#

compute_cv: bool#

cv_mean_threshold: float#

compute_log_stats: bool#

log_offset: float#

output_subdir: str#

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

class thesis.core.config.validators.S3Config[source]#

Bases: BaseConfig

Configuration for S3 data download.

Variables:

enabled – Whether S3 download is enabled.
bucket – S3 bucket name.
region – AWS region.
prefix – Bucket prefix (e.g., ‘HCP_1200’).
cache_policy – Download behavior when files exist locally.
max_retries – Maximum retry attempts for failed downloads.
retry_backoff – Exponential backoff multiplier for retries.
required_patterns – File patterns that must be downloaded.
optional_patterns – File patterns that should be downloaded if available.

Parameters:

data (Any)

enabled: bool#

bucket: str#

region: str#

prefix: str#

cache_policy: str#

max_retries: int#

retry_backoff: float#

required_patterns: List[str]#

optional_patterns: List[str]#

classmethod validate_cache_policy(v)[source]#

Validate cache policy is one of the allowed values.

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.core.config.validators.NipypeConfig[source]#

Bases: BaseConfig

Configuration for Nipype workflow execution.

Variables:

working_dir – Base working directory.
crash_dir – Optional crash dump directory.
plugin – Nipype execution plugin.
plugin_args – Plugin arguments passed to workflow.run.
stop_on_first_crash – Whether execution stops after the first crash.
remove_unnecessary_outputs – Whether intermediate outputs are cleaned.
keep_inputs – Whether node input files remain in the working directory.
hash_method – Caching hash strategy.
use_profiler – Whether the Nipype profiler is enabled.

Parameters:

data (Any)

working_dir: Path#

crash_dir: Path | None#

plugin: str#

plugin_args: Dict[str, Any]#

stop_on_first_crash: bool#

remove_unnecessary_outputs: bool#

keep_inputs: bool#

hash_method: str#

use_profiler: bool#

classmethod validate_plugin(v)[source]#

Validate the Nipype execution plugin against the supported allow-list.

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.core.config.validators.PreprocessingConfig[source]#

Bases: BaseConfig

Configuration for preprocessing pipeline.

Variables:

denoise – Whether denoising is enabled.
bias_correction – Whether bias correction is enabled.
brain_extraction – Whether brain extraction is enabled.
brain_extraction_method – Selected extraction backend.
motion_correction – Whether motion correction is enabled.
eddy_correction – Whether eddy-current correction is enabled.
topup – Whether TOPUP distortion correction is enabled.
acq_params – Optional TOPUP acquisition parameters.

Parameters:

data (Any)

denoise: bool#

bias_correction: bool#

brain_extraction: bool#

brain_extraction_method: str#

motion_correction: bool#

eddy_correction: bool#

topup: bool#

acq_params: Dict[str, Any] | None#

classmethod validate_bet_method(v)[source]#: Validate brain extraction method.

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

class thesis.core.config.validators.FireantsRegistrationConfig[source]#

Bases: BaseConfig

Configuration for the FireANTs registration backend.

Variables:

device – Torch device string used by FireANTs.
scales – Multi-resolution registration scales.
affine_iterations – Iterations per scale for affine registration.
deformable_iterations – Iterations per scale for deformable registration.
optimizer – FireANTs optimizer name.
affine_lr – Learning rate for affine registration.
deformable_lr – Learning rate for deformable registration.
cc_kernel_size – Cross-correlation kernel size.
deformation_type – FireANTs deformation model.
dtype – Torch dtype name.
loss_type – Similarity metric for the staged registration (cc/mi/mse/ fusedcc/fusedmi); auto-fused on CUDA.
normalize – Min-max normalize intensities to [0, 1] before registration.

Parameters:

data (Any)

device: str#

scales: List[int]#

affine_iterations: List[int]#

deformable_iterations: List[int]#

optimizer: str#

affine_lr: float#

deformable_lr: float#

cc_kernel_size: int#

loss_type: str#

normalize: bool#

deformation_type: str#

dtype: str#

do_moments: bool#

do_rigid: bool#

moments_scale: int#

moments_moments: int#

rigid_iterations: List[int]#

rigid_lr: float#

deform_algo: str#

driver: str#

deformable_max_spacing_mm: float | None#

inverse_method: str#

inverse_max_iterations: int#

inverse_tolerance: float#

classmethod validate_deform_algo(v)[source]#

Validate the FireANTs deformable engine.

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

classmethod validate_inverse_method(v)[source]#

Validate the reverse-warp reconstruction method.

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

classmethod validate_driver(v)[source]#

Validate the FireANTs driver.

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

classmethod validate_optimizer(v)[source]#

Validate the FireANTs optimizer.

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

classmethod validate_deformation_type(v)[source]#

Validate the FireANTs deformation type.

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

classmethod validate_dtype(v)[source]#

Validate the FireANTs torch dtype.

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

classmethod validate_loss_type(v)[source]#

Validate the FireANTs similarity metric.

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

validate_scale_lengths()[source]#

Ensure per-scale iteration lists match the configured scales.

Return type:: FireantsRegistrationConfig

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

class thesis.core.config.validators.RegistrationViewerConfig[source]#

Bases: BaseConfig

Configuration for registration QC viewer launching.

Variables:

enabled – Whether viewer launching is enabled.
backend – Viewer backend name.
auto_open – Whether the viewer should be launched automatically.
overlay_opacity – Default overlay opacity for the transformed patient image.

Parameters:

data (Any)

enabled: bool#

backend: str#

auto_open: bool#

overlay_opacity: float#

classmethod validate_backend(v)[source]#

Validate the registration QC viewer backend.

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.core.config.validators.RegistrationJobConfig[source]#

Bases: BaseConfig

Configuration for a single named registration job.

A job overrides the shared RegistrationConfig defaults for one patient-to-template registration. All override fields default to None (meaning “inherit the shared value”); only name is required. The fireants field, when set, is a sparse dict merged onto registration.fireants via model_copy(update=...) (which re-validates).

Variables:

name – Unique job name used in node/output naming and referenced by transforms.jobs[*].from_registration.
method – Optional registration-backend override.
moving_modality – Optional moving-image modality override.
moving_image – Optional explicit moving-image path override.
fixed_image – Optional fixed-image path override.
interpolation – Optional interpolation-mode override.
metric – Optional similarity-metric override.
transform_type – Optional transform-family override.
use_float – Optional float-precision override.
fireants – Optional sparse FireANTs override block.

Parameters:

data (Any)

name: str#

method: str | None#

moving_modality: str | None#

moving_image: str | None#

fixed_image: str | None#

interpolation: str | None#

metric: str | None#

transform_type: str | None#

use_float: bool | None#

fireants: Dict[str, Any] | None#

classmethod validate_method(v)[source]#

Validate the per-job registration method (None inherits the shared value).

Parameters:: v (Optional[str])
Return type:: Optional[str]

classmethod validate_moving_modality(v)[source]#

Validate the per-job moving-image modality (None inherits the shared value).

Parameters:: v (Optional[str])
Return type:: Optional[str]

classmethod validate_interpolation(v)[source]#

Validate the per-job interpolation method (None inherits the shared value).

Parameters:: v (Optional[str])
Return type:: Optional[str]

classmethod validate_transform_type(v)[source]#

Validate the per-job transform family (None inherits the shared value).

Parameters:: v (Optional[str])
Return type:: Optional[str]

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

class thesis.core.config.validators.RegistrationConfig[source]#

Bases: BaseConfig

Configuration for image registration.

Variables:

enabled – Whether the registration workflow is enabled.
method – Registration backend.
moving_modality – Structural modality used as the moving image.
moving_image – Optional explicit moving-image override.
fixed_image – Template-space fixed image.
interpolation – Interpolation mode.
metric – Similarity metric.
transform_type – Transform family.
use_float – Whether float precision is used.
collapse_output_transforms – Whether ANTs should collapse output transforms.
write_composite_transform – Whether ANTs should emit composite transforms.
output_subdir – Output subdirectory under the patient output dir.
fireants – FireANTs backend settings.
viewer – Registration QC viewer settings.

Parameters:

data (Any)

enabled: bool#

method: str#

moving_modality: str#

moving_image: str | None#

fixed_image: str#

interpolation: str#

metric: str#

transform_type: str#

use_float: bool#

collapse_output_transforms: bool#

write_composite_transform: bool#

output_subdir: str#

fireants: FireantsRegistrationConfig#

viewer: RegistrationViewerConfig#

jobs: List[RegistrationJobConfig]#

classmethod validate_method(v)[source]#: Validate registration method.

classmethod validate_moving_modality(v)[source]#

Validate the selected moving-image modality.

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

classmethod validate_transform_type(v)[source]#

Validate the selected transform family.

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.core.config.validators.SegmentationConfig[source]#

Bases: BaseConfig

Configuration for segmentation.

Variables:

method – Segmentation backend.
tissue_types – Tissue classes to segment.
create_masks – Whether binary masks are emitted.
labels – Optional label-name to integer mapping.

Parameters:

data (Any)

method: str#

tissue_types: List[str]#

create_masks: bool#

labels: Dict[str, int] | None#

classmethod validate_method(v)[source]#: Validate segmentation method.

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

class thesis.core.config.validators.AtlasSourceConfig[source]#

Bases: BaseConfig

Configuration for one atlas label-map source.

Variables:

name – Unique source name.
roi_file – Template-space atlas image path.
transform – Optional named transform to use for this source.
label_file – Optional label CSV path.
waypoint_labels – ROI extraction mapping for this source.

Parameters:

data (Any)

name: str#

roi_file: str#

transform: str | None#

label_file: str | None#

waypoint_labels: 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.core.config.validators.AtlasTransformConfig[source]#

Bases: BaseConfig

Named atlas-to-patient transform configuration.

Variables:

template_to_patient – One transform path or an ordered transform chain.
reference_image – Patient-space reference image for resampling.

Parameters:

data (Any)

template_to_patient: str | List[str]#

reference_image: str#

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

class thesis.core.config.validators.TransformJobConfig[source]#

Bases: BaseConfig

Configuration for a single image transformation job.

A job maps a set of input images to a transformed output using a named transform direction from TransformsConfig. Multiple jobs can be defined to process different sets of images (e.g. mean maps, std maps, probability maps) in a single workflow run.

Variables:

name – Unique job name used in output filenames and Nipype node names.
input_files – Explicit paths to the images to transform. Each path may contain {patient_id} which is substituted at runtime.
direction – Transform direction — template_to_patient uses transforms.template_to_patient / transforms.reference_image; patient_to_template uses transforms.patient_to_template / transforms.template_reference_image.
interpolation – ANTs interpolation method applied to every input image.
output_subdir – Subdirectory under the patient output directory where transformed images are written.

Parameters:

data (Any)

name: str#

input_files: List[str]#

direction: str#

interpolation: str#

output_subdir: str#

reference_image: str | None#

from_registration: str | None#

classmethod validate_direction(v)[source]#

Validate transform direction.

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

classmethod validate_interpolation(v)[source]#

Validate ANTs interpolation method.

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.core.config.validators.TransformsConfig[source]#

Bases: BaseConfig

Configuration for pre-computed transforms.

Variables:

base_dir – Optional base directory prepended to relative transform paths.
patient_to_template – Patient-to-template warp path.
template_to_patient – Template-to-patient transform or transform chain.
reference_image – Patient-space reference image.
template_reference_image – Template-space reference image.
atlas_transforms – Named atlas-specific transform configurations.
jobs – Transform jobs executed by the standalone transform workflow.

Parameters:

data (Any)

base_dir: str | None#

patient_to_template: str#

template_to_patient: str | List[str]#

reference_image: str#

template_reference_image: str#

atlas_transforms: Dict[str, AtlasTransformConfig]#

jobs: List[TransformJobConfig]#

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

class thesis.core.config.validators.SynthSegConfig[source]#

Bases: BaseConfig

Configuration for standalone or embedded SynthSeg execution.

Variables:

t1_image – Optional explicit T1-weighted input path.
parc – Whether cortical parcellation output is requested.
robust – Whether robust mode is enabled.
fast – Whether fast mode is enabled.
vol – Whether a volumes CSV is written.
qc – Whether a QC CSV is written.
crop – Optional crop size.
cpu – Whether CPU mode is forced.
threads – CPU thread count used in CPU mode.

Parameters:

data (Any)

t1_image: Path | None#

parc: bool#

robust: bool#

fast: bool#

vol: bool#

qc: bool#

crop: int | None#

cpu: bool#

threads: int#

gpu_runtime_env: Dict[str, str] | None#

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

class thesis.core.config.validators.TractographyConfig[source]#

Bases: BaseConfig

Configuration for tractography.

Variables:

method – Tractography backend.
run_tractography – Optional workflow-level execution toggle.
n_samples – Streamlines per seed voxel.
n_steps – Maximum steps per streamline.
step_length – Step length in millimetres.
curvature_threshold – Maximum curvature threshold.
hemisphere – Which hemisphere(s) to run tractography for.
atlas_sources – Optional atlas ROI source list.
roi_labels – Legacy single-atlas ROI configuration.
synthseg_roi_labels – Optional SynthSeg-derived ROI configuration.
force_dir – Whether ProbTrackX2 uses --forcedir.
opd – Whether ProbTrackX2 writes orientation distribution outputs.

Parameters:

data (Any)

method: str#

run_tractography: bool | None#

n_samples: int#

n_steps: int#

step_length: float#

curvature_threshold: float#

loop_check: bool#

dist_thresh: float#

fibst: int#

rand_fib: int#

mod_euler: bool#

hemisphere: str#

mem_gb_gpu: float#

mem_gb_cpu: float#

gpu_runtime_env: Dict[str, str] | None#

use_waypoints: bool#

waypoint_files: Dict[str, Path] | None#

roi_files: List[Path] | None#

seed_roi: Path | None#

waypoint_masks: List[Path] | None#

atlas_sources: List[AtlasSourceConfig] | None#

roi_labels: Dict[str, Any] | None#

synthseg_roi_labels: Dict[str, Any] | None#

force_dir: bool#

opd: bool#

tckgen_algorithm: str#

tckgen_select: int#

tckgen_seeds: int#

tckgen_minlength: float#

tckgen_maxlength: float#

tckgen_backtrack: bool#

tckgen_crop_at_gmwmi: bool#

tckgen_cutoff: float | None#

response_algorithm: str#

fod_algorithm: str#

use_mtnormalise: bool#

fivett_algorithm: str#

mask_source: str#

mask_dilate_voxels: int#

use_sift2: bool#

seed_strategy: str#

gmwmi_apply_roi_filters: bool#

classmethod validate_method(v)[source]#: Validate tractography method.

classmethod warn_unprefixed_gpu_runtime_env(v)[source]#

Warn on keys that will not survive singularity exec --cleanenv.

Only SINGULARITYENV_/APPTAINERENV_-prefixed variables are forwarded into the container past --cleanenv. A bare key (e.g. LD_PRELOAD) would be set in the wrapper’s host shell and then silently stripped, so it would never reach probtrackx2 — a confusing no-op we surface here rather than letting it fail at runtime.

Parameters:: v (Optional[Dict[str, str]])
Return type:: Optional[Dict[str, str]]

classmethod validate_response_algorithm(v)[source]#

Validate dwi2response algorithm.

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

classmethod validate_fod_algorithm(v)[source]#

Validate dwi2fod algorithm.

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

classmethod validate_fivett_algorithm(v)[source]#

Validate 5ttgen backend.

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

classmethod validate_mask_source(v)[source]#

Validate brain-mask source.

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

classmethod validate_seed_strategy(v)[source]#

Validate tckgen seed source.

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

classmethod validate_hemisphere(v)[source]#

Validate hemisphere value.

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.core.config.validators.ValidationConfig[source]#

Bases: BaseConfig

Configuration for post-processing validation checks.

Variables:

check_rois – Whether warped ROI validation is enabled.
min_voxels – Minimum non-zero voxel count per ROI.
singularity_threshold – Minimum affine determinant magnitude.
volume_ratio_min – Lower acceptable warped-to-original voxel ratio.
volume_ratio_max – Upper acceptable warped-to-original voxel ratio.

Parameters:

data (Any)

check_rois: bool#

min_voxels: int#

singularity_threshold: float#

volume_ratio_min: float#

volume_ratio_max: float#

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

class thesis.core.config.validators.QCConfig[source]#

Bases: BaseConfig

Configuration for QC visualisation outputs.

Controls automatic generation of quality-control overlay images (ROI placement on anatomical backgrounds, track density maps on template images) after workflow execution, as well as extended QC checks (SynthSeg quality, outlier detection, etc.).

Variables:

generate_overlays – Whether to produce ROI overlay PNGs at the end of the HCP workflow.
track_density_thresholds – Percentile thresholds used when rendering track density figures (applied to non-zero voxels of fdt_paths.nii.gz).
synthseg_qc_threshold – Minimum acceptable SynthSeg QC score. Subjects below this threshold are flagged.
outlier_sd_threshold – Number of standard deviations from the batch mean to flag a subject as an outlier.

Parameters:

data (Any)

generate_overlays: bool#

track_density_thresholds: List[float]#

synthseg_qc_threshold: float#

outlier_sd_threshold: float#

classmethod validate_thresholds(v)[source]#

Validate that all thresholds are valid percentiles in (0, 100).

Parameters:: v (List[float])
Return type:: List[float]

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

class thesis.core.config.validators.OutputSettingsConfig[source]#

Bases: BaseConfig

Configuration for CLI output behavior (YAML-level defaults).

CLI flags -v, -q, --summary, --no-progress override values set here at runtime.

Variables:

verbosity – Default verbosity level ("quiet", "normal", "verbose").
summary – Summary detail ("off", "compact", "full").
progress – Whether to show progress bars/spinners. "auto" enables progress for TTY and disables for pipes/CI.
output_format – Output format ("human", "json").

Parameters:

data (Any)

verbosity: str#

summary: str#

progress: str#

output_format: str#

classmethod validate_verbosity(v)[source]#

Validate verbosity value.

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

classmethod validate_summary(v)[source]#

Validate summary value.

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

classmethod validate_progress(v)[source]#

Validate progress value.

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

classmethod validate_output_format(v)[source]#

Validate output format value.

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.core.config.validators.SideThresholdConfig[source]#

Bases: BaseConfig

Binarisation threshold for one side (subject or atlas) of a tract comparison.

Variables:

mode – "fraction" applies value * max(volume) as the cutoff; "absolute" uses value directly as a raw voxel-intensity cutoff.
value – Threshold value. Must be in (0, 1) when mode="fraction"; any positive number when mode="absolute".

Parameters:

data (Any)

mode: Literal['fraction', 'absolute']#

value: float#

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

class thesis.core.config.validators.HcpLooConfig[source]#

Bases: BaseConfig

Configuration for the tract_similarity_hcp_loo workflow.

Controls the per-HCP-subject leave-one-out comparison against the cohort atlas. LOO is mathematically valid at N=2 (the LOO atlas becomes the other subject’s volume), but a floor of 3 enforces a meaningful cohort reference.

Variables:

minimum_subjects – Minimum cohort size required to run the workflow.
write_volumes – If True, write the four NIfTI volumes per subject (subject_normalized.nii.gz, atlas_normalized.nii.gz, subject_mask.nii.gz, atlas_mask.nii.gz) alongside metrics.json. If False, only metrics.json is written.
learned_prediction_relpath – Optional relative path under each subject directory to a learned-atlas per-subject prediction NIfTI (template space). Empty (default) disables the learned-template 3rd arm.
learned_support_threshold – Density threshold defining the held-out subject’s true support for the non-circular learned-arm metrics.

Parameters:

data (Any)

minimum_subjects: int#

write_volumes: bool#

learned_prediction_relpath: str#

learned_support_threshold: float#

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

class thesis.core.config.validators.TractSimilarityConfig[source]#

Bases: BaseConfig

Configuration for the tract_similarity analysis workflow.

Controls the per-patient comparison between the native-space probtrackx2 tract density and the warped cohort mean atlas, plus the cohort-level aggregation of those per-patient metrics.

Variables:

fdt_relpath – Relative path under the patient output directory to the native-space fdt_paths.nii.gz.
waytotal_relpath – Relative path to the waytotal text file.
atlas_relpath – Relative path (or glob pattern) under the patient output directory that points at the warped atlas mean volume.
subject_threshold – Binarisation threshold applied to the subject’s probtrackx2 volume before overlap / distance metrics.
atlas_threshold – Binarisation threshold applied to the warped atlas volume before overlap / distance metrics.
n_bins – Histogram bin count for normalised mutual information.
output_subdir – Subdirectory under the patient output directory where metrics.json is written.
cohort_output_subdir – Subdirectory under the cohort output directory where the aggregated summary is written.

Parameters:

data (Any)

probtrackx_relpath: str#

fdt_name: str#

waytotal_name: str#

atlas_relpath: str#

subject_threshold: SideThresholdConfig#

atlas_threshold: SideThresholdConfig#

n_bins: int#

output_subdir: str#

cohort_output_subdir: str#

hcp_loo: HcpLooConfig#

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

class thesis.core.config.validators.ThresholdGridConfig[source]#

Bases: BaseConfig

Grid specification for one binarisation-threshold axis of the sweep.

Provide either start/stop/step (inclusive endpoint within float tolerance) or an explicit values list. All entries must lie in (0, 1) because the sweep operates in "fraction" mode.

Parameters:: data (Any)

start: float | None#

stop: float | None#

step: float | None#

values: List[float] | None#

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

class thesis.core.config.validators.TractSimilaritySweepConfig[source]#

Bases: BaseConfig

Configuration for the tract_similarity_sweep cohort grid search.

Sweeps the subject_threshold.value and atlas_threshold.value knobs (both in "fraction" mode) and reports the cell that maximises the chosen aggregation of Dice across the cohort.

Parameters:: data (Any)

subject_threshold_grid: ThresholdGridConfig#

atlas_threshold_grid: ThresholdGridConfig#

aggregation: Literal['mean', 'median']#

output_subdir: str#

emit_heatmap: bool#

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

class thesis.core.config.validators.HCPConfig[source]#

Bases: BaseConfig

Configuration for HCP preprocessed data.

Variables:

diffusion_dir – Diffusion subdirectory under the subject input directory.
bedpostx_dir – BedpostX output directory.
t1_image – T1-weighted image path.
t2_image – Optional T2-weighted image path.
n_fibers – Number of BedpostX fibres.
mask_name – Default diffusion brain-mask filename.
mask_path – Optional full mask-path override.

Parameters:

data (Any)

diffusion_dir: str#

bedpostx_dir: str#

t1_image: str#

t2_image: str | None#

n_fibers: int#

mask_name: str#

mask_path: str | None#

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

class thesis.core.config.validators.PipelineConfig[source]#

Bases: BaseModel

Root configuration model for thesis pipelines.

Aggregates all sub-configurations and provides convenience methods.

Variables:

paths – Filesystem paths.
hardware – Compute resources.
atlas – Atlas generation settings.
s3 – S3 data download settings (optional).
preprocessing – Generic preprocessing steps.
preprocess – Workflow-specific raw-to-HCP preprocessing settings.
registration – Image registration.
segmentation – Brain segmentation.
tractography – Tractography parameters.
hcp – HCP-specific overrides.
transforms – Pre-computed transform settings.
nipype – Nipype execution settings.
validation – ROI validation settings.
qc – QC generation settings.
atlas_qc – Atlas QC generation settings.
synthseg – Optional SynthSeg-specific overrides.
output – CLI output defaults.
patient_id – Optional patient identifier.
protocol – Optional protocol name.

Parameters:

data (Any)

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

paths: PathConfig#

hardware: HardwareConfig#

atlas: AtlasConfig#

s3: S3Config | None#

preprocessing: PreprocessingConfig#

preprocess: Dict[str, Any]#

mrtrix3: Dict[str, Any]#

registration: RegistrationConfig#

segmentation: SegmentationConfig#

tractography: TractographyConfig#

hcp: HCPConfig#

transforms: TransformsConfig#

nipype: NipypeConfig#

slurm: SLURMConfig#

validation: ValidationConfig#

qc: QCConfig#

atlas_qc: AtlasQCConfig#

synthseg: SynthSegConfig | None#

output: OutputSettingsConfig#

tract_similarity: TractSimilarityConfig#

tract_similarity_sweep: TractSimilaritySweepConfig#

patient_id: str | None#

protocol: str | None#

classmethod from_dict(config_dict)[source]#

Create a PipelineConfig from a dictionary.

Convenience wrapper around model_validate that provides a domain-specific name and ensures the return type is narrowed.

Parameters:: config_dict (Dict[str, Any]) – Dictionary of configuration values
Return type:: PipelineConfig
Returns:: Validated PipelineConfig object

Example

>>> config_dict = {"hardware": {"threads": 8}}
>>> config = PipelineConfig.from_dict(config_dict)

to_dict()[source]#

Convert config to dictionary.

Return type:: Dict[str, Any]
Returns:: Dictionary representation of config

Example

>>> config_dict = config.to_dict()

merge_with(other)[source]#

Merge this config with another config or dict.

Parameters:: other (Union[PipelineConfig, Dict[str, Any]]) – Another PipelineConfig or dict to merge
Return type:: PipelineConfig
Returns:: New PipelineConfig with merged values

Example

>>> merged = config.merge_with({"hardware": {"threads": 16}})

thesis.core.config.loaders#

YAML configuration loaders and utilities.

thesis.core.config.loaders.load_yaml(file_path)[source]#

Load a YAML configuration file.

Parameters:

file_path (str | Path) – Path to YAML file

Return type:

dict[str, object]

Returns:

Dictionary with config data

Raises:

FileNotFoundError – If file doesn’t exist
ValueError – If YAML is invalid

Example

>>> config = load_yaml("./config/default.yaml")
>>> print(config["preprocessing"]["threads"])

thesis.core.config.loaders.save_yaml(config, file_path)[source]#

Save a configuration to a YAML file.

Parameters:

config (dict[str, object]) – Configuration dictionary to save
file_path (str | Path) – Path where to save the file

Return type:

None

Example

>>> config = {"threads": 4}
>>> save_yaml(config, "./my_config.yaml")

thesis.core.config.loaders.merge_configs(*configs)[source]#

Merge multiple configurations with later configs overriding earlier ones.

Deep merges dictionaries, with later configs taking precedence.

Parameters:: *configs (dict[str, object]) – Variable number of config dictionaries to merge
Return type:: dict[str, object]
Returns:: Merged dictionary

Example

>>> base = {"a": 1, "b": {"x": 2}}
>>> override = {"b": {"y": 3}, "c": 4}
>>> merged = merge_configs(base, override)
>>> print(merged["b"])  # {"x": 2, "y": 3}