synthBOLD

synthbold is a Python package for synthesizing BOLD fMRI data with controllable macrovascular contributions and corresponding ground-truth labels. The generated datasets can be used to develop, validate, and benchmark fMRI analysis methods without requiring labeled in vivo data.

In particular, it was developed to facilitate methods for identifying and mitigating macrovascular contributions in BOLD fMRI, by providing simulated data with known ground truth for evaluating such methods.

Each BOLD fMRI sample is built from a biophysical forward model of the BOLD signal: randomly placed vascular geometries (vessels and other perturbing structures) are assigned magnetic susceptibility values that generate a surrounding field perturbation (ΔBz), and the complex MRI signal is computed under the static dephasing regime [1], i.e., the intra-voxel signal decay caused by static, susceptibility-induced field inhomogeneities around vessels, following the classic vessel-based BOLD simulation framework of [2].

All generative parameters (vessel geometry, size, orientation, susceptibility, decay rates, echo time, magnetic field strength, etc.) are generated with weak priors and high variance sampling rather than tuned to match any specific real dataset. This domain-randomization strategy (cf. [3, 4]) aims to generate a much broader data distribution than any finite set of real fMRI data acquisitions could provide, so that models trained on synthetic data alone generalize to real fMRI data at test time.

Installation

synthbold can be installed from pypi via

pip install synthbold

Optionally, synthbold.splines exposes a thin wrapper for spline-based vessel generation that relies on synthspline. The dependency is not installed by default. If you need this feature, install it separately from GitHub:

pip install git+https://github.com/haenelt/synthspline.git@main

Usage

To generate a batch of synthetic BOLD data with macrovascular contributions, the synthbold command can be called from the command line as follows:

synthbold --output <output_dir> --n-sample <n_samples> --batch-size <batch_size> --config <config.yaml>

See synthbold --help for the full list of options.

Python API

synthbold can also be used as a library. SynthPipeline is the main entry point. Calling it returns a batch of synthetic BOLD data with macrovascular contributions: magnitude/phase images together with their ground-truth tissue and vessel maps.

from synthbold.config import Config
from synthbold.pipeline import SynthPipeline

config = Config()
pipeline = SynthPipeline(dirname="output", n_samples=100, config=config)
sample, _, params = pipeline(batch_size=4)

Examples

Example code can be found as Jupyter notebooks in the notebooks subfolder.

Contact

If you have questions, problems or suggestions regarding the synthbold package, please feel free to contact me.

References

1. Yablonskiy, D. A., & Haacke, E. M. (1994). Theory of NMR signal behavior in magnetically inhomogeneous tissues: the static dephasing regime. Magnetic Resonance in Medicine, 32, 749–763.
2. Boxerman, J. L., et al. (1995). MR contrast due to intravascular magnetic susceptibility perturbations. Magnetic Resonance in Medicine, 34, 555–566.
3. Tobin, J., et al. (2017). Domain randomization for transferring deep neural networks from simulation to the real world. IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS).
4. Billot, B., et al. (2023). SynthSeg: Segmentation of brain MRI scans of any contrast and resolution without retraining. Medical Image Analysis, 86, 102789.