synthbold.pipeline

Orchestration of individual synthesis models into an end-to-end pipeline.

class synthbold.pipeline.SynthParams(theta: Tensor, phi: Tensor, chi: Tensor, t2: Tensor, te: Tensor)

Bases: NamedTuple

Shared parameters used to generate a SynthSample.

Variables:

  • theta (torch.Tensor) – B0 polar angle, shape (B,).

  • phi (torch.Tensor) – B0 azimuthal angle, shape (B,).

  • chi (torch.Tensor) – Susceptibility values of shape (n_total,), where n_total is the sum, over batch elements, of each element’s largest label id (cylinder plus distractor labels).

  • t2 (torch.Tensor) – T2 values, shape (n_total,). Same layout as chi.

  • te (torch.Tensor) – Echo time of shape (B,).

chi: Tensor

Alias for field number 2

phi: Tensor

Alias for field number 1

t2: Tensor

Alias for field number 3

te: Tensor

Alias for field number 4

theta: Tensor

Alias for field number 0

class synthbold.pipeline.SynthPipeline(dirname: Path, n_samples: int, config: Config, indices: list[int] | None = None, include_spheres: bool = False, include_tetrahedra: bool = False, include_cubes: bool = False, include_toroids: bool = False)

Bases: RandomGeneratorMixin

End-to-end orchestration of geometry, model, and transform components into a single callable that synthesizes batches of BOLD samples.

On construction, label maps for cylinders, background shapes, and any requested distractor geometries (spheres, tetrahedra, cubes, toroids) are generated once and cached to ZARR under <dirname>/labels so that __call__ only ever samples from precomputed data. Each call draws a random batch of these label maps, runs them through the background, foreground, distractor, and perturbation models, and applies the signal model to produce magnitude/phase images alongside ground-truth tissue and perturber volume fraction maps.

Parameters:

  • dirname – Root directory for cached label maps.

  • n_samples – Number of label maps to pre-generate for each geometry type.

  • config – Configuration object shared by all sub-models and geometry generators.

  • indices – Subset of label-map indices, into the range [0, n_samples), to sample from in __call__. Defaults to all indices.

  • include_spheres – Whether to use sphere distractor labels.

  • include_tetrahedra – Whether to use tetrahedron distractor labels.

  • include_cubes – Whether to use cube distractor labels.

  • include_toroids – Whether to use toroid distractor labels.

property attrs: dict[str, Any]

Common metadata for ZARR/NIfTI storage.

benchmark(batch_size: int = 4, n: int = 10, warmup: int = 10) → float

Benchmark the average runtime of __call__.

property cubes_zarr: Any

Lazily opened cube label maps.

property cylinders_zarr: Any

Lazily opened cylinder label maps.

property shapes_zarr: Any

Lazily opened shape label maps.

property spheres_zarr: Any

Lazily opened sphere label maps.

property tetrahedra_zarr: Any

Lazily opened tetrahedron label maps.

property toroids_zarr: Any

Lazily opened toroid label maps.

class synthbold.pipeline.SynthSample(magnitude: Tensor, phase: Tensor, tissue: Tensor, vf: Tensor, dbz_mean: Tensor, dbz_variance: Tensor, dbz_skewness: Tensor, dbz_kurtosis: Tensor)

Bases: NamedTuple

A batch of synthesized samples.

Variables:

  • magnitude (torch.Tensor) – Synthesized magnitude image of shape (B, x, y, z).

  • phase (torch.Tensor) – Synthesized phase image of shape (B, x, y, z).

  • tissue (torch.Tensor) – Ground-truth tissue map of shape (B, x, y, z).

  • vf (torch.Tensor) – Ground-truth vf map of shape (B, x, y, z).

  • dbz_mean (torch.Tensor) – Mean of the ΔBz distribution of shape (B, x, y, z).

  • dbz_variance (torch.Tensor) – Variance of the ΔBz distribution of shape (B, x, y, z).

  • dbz_skewness (torch.Tensor) – Skewness of the ΔBz distribution of shape (B, x, y, z).

  • dbz_kurtosis (torch.Tensor) – Kurtosis of the ΔBz distribution of shape (B, x, y, z).

dbz_kurtosis: Tensor

Alias for field number 7

dbz_mean: Tensor

Alias for field number 4

dbz_skewness: Tensor

Alias for field number 6

dbz_variance: Tensor

Alias for field number 5

magnitude: Tensor

Alias for field number 0

phase: Tensor

Alias for field number 1

tissue: Tensor

Alias for field number 2

vf: Tensor

Alias for field number 3