synthbold.config¶

Validated configuration structures and custom validators used throughout the synthBOLD package to parse and ensure data synthesis parameters are correct.

class synthbold.config.Config(*, seed: int = 42, device: str = 'cpu', transform_prob: float = 1.0, geom: GeometryParams = GeometryParams(input_shape=(64, 64, 64), output_shape=(32, 32, 32), fov=(32.0, 32.0, 32.0), padding=64, cylinder_num=None, cylinder_vf=Range(min=0.005, max=0.01), cylinder_diameter=Range(min=0.25, max=2.0), cylinder_allow_overlap=True, tree_num=None, tree_vf=Range(min=0.005, max=0.01), tree_diameter=Range(min=0.25, max=2.0), tree_allow_overlap=True, tree_segment_length=Range(min=2.0, max=6.0), tree_branch_prob=0.35, tree_branch_angle=Range(min=0.2618, max=0.7854), tree_max_depth=6, tree_min_radius_fraction=0.15, spline_nb_levels=1, spline_tree_density=LogNormalRange(mean=0.01, std=0.01), spline_tortuosity=LogNormalRange(mean=5.0, std=3.0), spline_radius=LogNormalRange(mean=0.1, std=0.02), spline_radius_change=LogNormalRange(mean=1.0, std=0.1), spline_nb_children=LogNormalRange(mean=5.0, std=5.0), spline_radius_ratio=LogNormalRange(mean=0.7, std=0.1), sphere_num=None, sphere_vf=Range(min=0.005, max=0.01), sphere_diameter=Range(min=0.2, max=2.0), sphere_allow_overlap=True, tetrahedron_num=None, tetrahedron_vf=Range(min=0.005, max=0.01), tetrahedron_diameter=Range(min=0.4, max=4.0), tetrahedron_allow_overlap=True, cube_num=None, cube_vf=Range(min=0.005, max=0.01), cube_diameter=Range(min=2.0, max=10.0), cube_allow_overlap=True, toroid_num=None, toroid_vf=Range(min=0.005, max=0.01), toroid_diameter=Range(min=2.0, max=10.0), toroid_tube_ratio=Range(min=0.1, max=0.4), toroid_allow_overlap=True), physio: PhysioParams = PhysioParams(label_displacement_shape=(4, 4, 4), label_J=8, label_scale=0.2, background_mu=Range(min=10.0, max=100.0), background_std=Range(min=5.0, max=10.0)), physics: PhysicsParams = PhysicsParams(b0=7.0, gamma=267522.1, chi=Range(min=-1e-08, max=1e-07), t2=Range(min=5.0, max=50.0), te=Range(min=5.0, max=100.0), theta=Range(min=0.0, max=3.141592653589793), phi=Range(min=0.0, max=6.283185307179586), spin_echo=64.0), transform: TransformParams = TransformParams(bias_lowres_shape=(4, 4, 4), bias_amplitude=Range(min=0.0, max=1.0), gamma_exponent=Range(min=0.5, max=2.0), gnoise_mu=Range(min=-0.2, max=0.2), gnoise_std=Range(min=0.0, max=0.1), spike_num=(1, 3), spike_intensity=Range(min=1.0, max=3.0), mgamma_shape=Range(min=2.0, max=50.0), perlin_base_shape=(4, 4, 4), perlin_octaves=4, perlin_persistence=0.5, perlin_amplitude=Range(min=0.0, max=0.1), pnoise_peak=Range(min=0.0001, max=0.001), rnoise_std=Range(min=0.0, max=2.0), ncchi_std=Range(min=0.0, max=1e-09), ncchi_dof=4, speckle_std=Range(min=0.0, max=0.5), flip_prob=1.0, sphere_radius=Range(min=80.0, max=100.0), sphere_prob=0.5, sphere_deform_amplitude=0.3, sphere_deform_shape=(4, 4, 4), gsmooth_sigma=Range(min=0.001, max=1.0), gsmooth_kernel_size=3, gsmooth_isotropic=True, sharpen_sigma=Range(min=0.001, max=1.0), sharpen_amount=Range(min=0.5, max=2.0), sharpen_kernel_size=3, gibbs_cutoff=Range(min=0.5, max=1.0), elastic_sigma=20.0, elastic_max_disp=20.0, caliber_sigma=10.0, caliber_alpha=2.0))¶

Bases: BaseModel

Root configuration object.

device: str¶

classmethod from_dict(data: dict) → Self¶: Load configuration parameters from dictionary.

classmethod from_yaml(path: str | Path) → Self¶: Load configuration parameters from yaml file.

geom: GeometryParams¶

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

physics: PhysicsParams¶

physio: PhysioParams¶

save(path: str | Path) → None¶: Saves the configuration to a JSON file.

seed: int¶

transform: TransformParams¶

transform_prob: float¶

class synthbold.config.GeometryParams(*, input_shape: tuple[int, int, int] = (64, 64, 64), output_shape: tuple[int, int, int] = (32, 32, 32), fov: tuple[float, float, float] = (32.0, 32.0, 32.0), padding: int = 64, cylinder_num: int | None = None, cylinder_vf: Range = Range(min=0.005, max=0.01), cylinder_diameter: Range = Range(min=0.25, max=2.0), cylinder_allow_overlap: bool = True, tree_num: int | None = None, tree_vf: Range = Range(min=0.005, max=0.01), tree_diameter: Range = Range(min=0.25, max=2.0), tree_allow_overlap: bool = True, tree_segment_length: Range = Range(min=2.0, max=6.0), tree_branch_prob: float = 0.35, tree_branch_angle: Range = Range(min=0.2618, max=0.7854), tree_max_depth: int = 6, tree_min_radius_fraction: float = 0.15, spline_nb_levels: int = 1, spline_tree_density: LogNormalRange = LogNormalRange(mean=0.01, std=0.01), spline_tortuosity: LogNormalRange = LogNormalRange(mean=5.0, std=3.0), spline_radius: LogNormalRange = LogNormalRange(mean=0.1, std=0.02), spline_radius_change: LogNormalRange = LogNormalRange(mean=1.0, std=0.1), spline_nb_children: LogNormalRange = LogNormalRange(mean=5.0, std=5.0), spline_radius_ratio: LogNormalRange = LogNormalRange(mean=0.7, std=0.1), sphere_num: int | None = None, sphere_vf: Range = Range(min=0.005, max=0.01), sphere_diameter: Range = Range(min=0.2, max=2.0), sphere_allow_overlap: bool = True, tetrahedron_num: int | None = None, tetrahedron_vf: Range = Range(min=0.005, max=0.01), tetrahedron_diameter: Range = Range(min=0.4, max=4.0), tetrahedron_allow_overlap: bool = True, cube_num: int | None = None, cube_vf: Range = Range(min=0.005, max=0.01), cube_diameter: Range = Range(min=2.0, max=10.0), cube_allow_overlap: bool = True, toroid_num: int | None = None, toroid_vf: Range = Range(min=0.005, max=0.01), toroid_diameter: Range = Range(min=2.0, max=10.0), toroid_tube_ratio: Range = Range(min=0.1, max=0.4), toroid_allow_overlap: bool = True)¶

Bases: BaseModel

Spatial parameters for input and output tensors.

Parameters:

input_shape – Shape of source volume.
output_shape – Shape of target volume (after static dephasing downsampling).
fov – Field-of-view of source volume in mm.
padding – Voxel padding for calculating field perturbation.
cylinder_num – Number of generated cylinders.
cylinder_vf – Volume fraction of cylinders.
cylinder_diameter – Range of cylinder diameters in mm.
cylinder_allow_overlap – Allow cylinders to overlap.
tree_num – Number of generated cylinder trees.
tree_vf – Volume fraction of cylinder trees.
tree_diameter – Range of cylinder tree root diameters in mm.
tree_allow_overlap – Allow cylinder trees to overlap.
tree_segment_length – Range of individual segment lengths in mm.
tree_branch_prob – Probability that a segment bifurcates.
tree_branch_angle – Range of parent-child branch angles in radians.
tree_max_depth – Maximum number of branching generations below the root.
tree_min_radius_fraction – Radius fraction below which a branch stops growing.
spline_nb_levels – Number of hierarchical levels in the spline vessel tree.
spline_tree_density – Log-normal distribution of trees per mm^3.
spline_tortuosity – Log-normal distribution of tortuosity (cord / length).
spline_radius – Log-normal distribution of the root radius in mm.
spline_radius_change – Log-normal distribution of radius variation along splines.
spline_nb_children – Log-normal distribution of the number of spline branches.
spline_radius_ratio – Log-normal distribution of the child/parent radius ratio.
sphere_num – Number of generated spheres.
sphere_vf – Volume fraction of spheres.
sphere_diameter – Range of sphere diameters in mm.
sphere_allow_overlap – Allow spheres to overlap.
tetrahedron_num – Number of generated tetrahedra.
tetrahedron_vf – Volume fraction of tetrahedra.
tetrahedron_diameter – Range of tetrahedron circumdiameters in mm.
tetrahedron_allow_overlap – Allow tetrahedra to overlap.
cube_num – Number of generated cubes.
cube_vf – Volume fraction of cubes.
cube_diameter – Range of cube circumdiameters in mm.
cube_allow_overlap – Allow cubes to overlap.
toroid_num – Number of generated toroids.
toroid_vf – Volume fraction of toroids.
toroid_diameter – Range of toroid major diameters in mm.
toroid_tube_ratio – Range of toroid tube-to-major radius ratios.
toroid_allow_overlap – Allow toroids to overlap.

classmethod check_divisible_output(v: tuple[int, ...], info: ValidationInfo) → tuple[int, ...]¶

Validates that input_shape is divisible by output_shape in every dim.

Parameters:

v – The value of output_shape.
info – Validation context containing other fields.

Returns:

The validated output_shape value.

Raises:

ValueError – If any input_shape dimension is not evenly divisible by the corresponding output_shape dimension.

cube_allow_overlap: bool¶

cube_diameter: Range¶

cube_num: int | None¶

cube_vf: Range¶

cylinder_allow_overlap: bool¶

cylinder_diameter: Range¶

cylinder_num: int | None¶

cylinder_vf: Range¶

fov: tuple[float, float, float]¶

input_shape: tuple[int, int, int]¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

output_shape: tuple[int, int, int]¶

padding: int¶

sphere_allow_overlap: bool¶

sphere_diameter: Range¶

sphere_num: int | None¶

sphere_vf: Range¶

spline_nb_children: LogNormalRange¶

spline_nb_levels: int¶

spline_radius: LogNormalRange¶

spline_radius_change: LogNormalRange¶

spline_radius_ratio: LogNormalRange¶

spline_tortuosity: LogNormalRange¶

spline_tree_density: LogNormalRange¶

tetrahedron_allow_overlap: bool¶

tetrahedron_diameter: Range¶

tetrahedron_num: int | None¶

tetrahedron_vf: Range¶

toroid_allow_overlap: bool¶

toroid_diameter: Range¶

toroid_num: int | None¶

toroid_tube_ratio: Range¶

toroid_vf: Range¶

tree_allow_overlap: bool¶

tree_branch_angle: Range¶

tree_branch_prob: float¶

tree_diameter: Range¶

tree_max_depth: int¶

tree_min_radius_fraction: float¶

tree_num: int | None¶

tree_segment_length: Range¶

tree_vf: Range¶

class synthbold.config.LogNormalRange(*, mean: float, std: float)¶

Bases: BaseModel

Mean and standard deviation of a log-normal parameter distribution.

mean: float¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

std: float¶

class synthbold.config.PhysioParams(*, label_displacement_shape: tuple[int, int, int] = (4, 4, 4), label_J: int = 8, label_scale: float = 0.2, background_mu: Range = Range(min=10.0, max=100.0), background_std: Range = Range(min=5.0, max=10.0))¶

Bases: BaseModel

Parameters for shape and cylinder maps.

Parameters:

label_displacement_shape – Shape of noise map for smooth displacement field.
label_J – Number of tissue classes.
label_scale – Scale factor of the noise map.
background_mu – Mean intensity range for different tissue compartments.
background_std – Standard deviation range for intensities within tissue types.

background_mu: Range¶

background_std: Range¶

label_J: int¶

label_displacement_shape: tuple[int, int, int]¶

label_scale: float¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class synthbold.config.Range(*, min: float, max: float)¶

Bases: BaseModel

Defines a numerical range.

classmethod check_range(v: float, info: ValidationInfo) → float¶

Validates that the maximum value is greater than or equal to the minimum.

Parameters:

v – The value of max.
info – Validation context containing other fields.

Returns:

The validated max value.

Raises:

ValueError – If max is less than min.

max: float¶

min: float¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].