py-simpace 2.0.1

Realistic MRI motion artifact simulation toolkit for structural MRI and fMRI, with deep learning integration.

PySimPace

PySimPace v2.0
Realistic MRI Motion Artifact Simulation Toolkit
(Structural MRI & fMRI Support, Deep Learning Integration Ready)

Author: Snehil Kumar
Contact: [e-mail]
License: MIT License

---

Overview

PySimPace is an open-source Python library for simulating realistic motion artifacts and image artifacts in MRI data, including both structural MRI (3D) and fMRI (4D).

It is designed to:

✅ Provide realistic motion simulation for training deep learning models
✅ Support both structural MRI and fMRI pipelines
✅ Support realistic artifact generation (ghosting, Gibbs ringing, physiological noise)
✅ Provide a simple API + CLI + tutorials
✅ Provide paired datasets for supervised training of motion correction models
✅ Be fast and scalable (supports parallelism)
✅ Be fully open and extensible

---

What's New in v2.0

✅ Modular architecture (TensorFlow-style)
✅ Image-space motion simulation (slice-wise)
✅ Blended k-space motion simulation (realistic, new contribution)
✅ Ghosting artifact simulation
✅ Gibbs ringing artifact simulation
✅ Full fMRI motion simulation with intra-volume motion + physiological noise
✅ ML integration (ml.py) → generate training pairs → ready for PyTorch
✅ Full tutorials in Jupyter format
✅ Unit test scaffolding (tests/)
✅ CLI planned
✅ Ready for ACM paper & PyPI release

---

Motion & Artifact Support (v2.0)

Motion types supported:

• Image-space motion (slice-wise motion blocks)
• K-space motion:
  • Basic k-space motion (combination method)
  • Blended k-space motion (realistic smooth motion) ✅ main contribution

Artifact types supported:

• Ghosting (phase-encoding ghosting, in blended k-space motion)
• Gibbs ringing
• Physiological noise (fMRI only)

Planned for v2.1:

• Spike noise
• Intensity drift
• Susceptibility distortions
• Partial Fourier artifacts

---

Installation

Local installation

git clone https://github.com/snehil03july/py-SimPace.git
cd py-SimPace
pip install -e .

From PyPI (coming soon)

pip install pysimpace

---

Project Structure

pysimpace/
├── __init__.py
├── simulation/
│   ├── structural.py
│   ├── functional.py
│   ├── transforms.py
│   ├── noise.py
│   ├── models.py
├── io.py
├── analysis.py
├── ml.py
├── cli.py
├── gui.py
├── utils.py
docs/
examples/
├── structural_simulation_tutorial.ipynb
├── fmri_simulation_tutorial.ipynb
├── ml_integration_tutorial.ipynb
tests/
setup.py / pyproject.toml
requirements.txt
README.md
LICENSE

---

Quick Usage

Structural MRI motion simulation

from pysimpace.io import load_nifti, save_nifti
from pysimpace.simulation.structural import simulate_structural_motion
from pysimpace.simulation.models import generate_random_affine_transforms

# Load clean MRI
clean_data, affine, header = load_nifti("clean_image.nii.gz")

# Generate random transforms
transforms = generate_random_affine_transforms(5, 5.0, 5.0, clean_data.shape)

# Simulate motion
corrupted_data = simulate_structural_motion(
    clean_data,
    transforms=transforms,
    use_blended=True,
    ghosting=True,
    apply_gibbs=True,
    gibbs_strength=0.05,
    seed=42
)

# Save corrupted image
save_nifti(corrupted_data, affine, header, "corrupted_image.nii.gz")

---

fMRI motion simulation

from pysimpace.io import load_nifti, save_nifti
from pysimpace.simulation.functional import simulate_fmri_motion
from pysimpace.simulation.models import MotionTrajectory, generate_smooth_motion_trajectory

# Load clean fMRI
fmri_data, affine, header = load_nifti("clean_fmri.nii.gz")

# Generate trajectory
n_vols = fmri_data.shape[-1]
n_slices = fmri_data.shape[2]
trajectory = MotionTrajectory(n_volumes=n_vols, n_slices=n_slices)

vol_transforms = generate_smooth_motion_trajectory(
    n_volumes=n_vols, target_fd_mm=0.5, vol_shape=fmri_data.shape[:3], smoothing_sigma=3.0, seed=42
)

for t in range(n_vols):
    trajectory.set_volume_transform(t, vol_transforms[t])

# Simulate motion
corrupted_fmri = simulate_fmri_motion(
    fmri_data,
    trajectory,
    intra=True,
    physio=True,
    parallel=True,
    seed=42
)

# Save corrupted fMRI
save_nifti(corrupted_fmri, affine, header, "corrupted_fmri.nii.gz")

---

ML Integration

Generate paired training data

from pysimpace.ml import generate_training_pairs

generate_training_pairs(
    clean_dir="examples/clean",
    output_dir="examples/training_pairs",
    n_samples=50,
    artifact_configs=None,
    structural=True,
    use_blended=True,
    save_format='nifti',
    seed=42
)

Load paired dataset in PyTorch

from pysimpace.ml import MRIPairedDataset

dataset = MRIPairedDataset("examples/training_pairs/pairs.csv")
clean_img, corrupted_img = dataset[0]

# Example shape: (1, X, Y, Z)

---

Tutorials

👉 Full examples provided in examples/:

✅ structural_simulation_tutorial.ipynb
✅ fmri_simulation_tutorial.ipynb
✅ ml_integration_tutorial.ipynb

---

Tests

Unit tests provided in tests/:

pytest tests/

Test coverage:

• test_structural.py
• test_functional.py
• test_noise.py
• test_ml.py

---

API Documentation

pysimpace.simulation.structural

simulate_structural_motion(...)

pysimpace.simulation.functional

simulate_fmri_motion(...)

pysimpace.simulation.models

generate_random_affine_transforms(...)
generate_smooth_motion_trajectory(...)
MotionTrajectory(...)

pysimpace.simulation.noise

apply_gibbs_ringing(...)
apply_spike_noise(...)  # Coming soon
apply_intensity_drift(...)  # Coming soon
generate_physio_noise(...)

pysimpace.ml

generate_training_pairs(...)
MRIPairedDataset(...)

---

Contributing

Contributions welcome!

To contribute:

1. Fork the repo
2. Clone your fork
3. Create a new branch
4. Implement your feature or bug fix
5. Add unit tests in tests/
6. Ensure all tests pass (pytest tests/)
7. Submit a pull request

Please follow PEP8 + black formatting.

---

Contact

Maintainer: Snehil Kumar
Email: [e-mail]

---

License

MIT License.

---

Citation

If you use this software in your research, please cite:

Snehil Kumar et al., "PySimPace: Realistic MRI Motion Artifact Simulation Toolkit," 2025.
(Submitted to ACM conference)

---

Happy simulating! 🚀