Skip to content

Home

Jump to bottom
Jesús Silva-Rodríguez edited this page Apr 23, 2024 · 10 revisions

Project Goals

The SIMPET project is intended to allow to setup and launch MC simulation in a simple way. It provides functionalities to:

  • Extract simple activity and attenuation maps from PET/MR co-registered images using the brainVISET methodology. -> BrainVISET Original Paper

  • Run MC simulations using SimSET and provide reconstructed images using STIR. -> SimPET implementation

  • Present a framework for the community to validate and use MC models of different scanners in a simple, collaborative framework

Installation

  1. Install Git LFS.
  2. Clone the repository by adding the --recurse-submodules flag:
git clone --recurse-submodules --branch develop https://github.com/txusser/simpet.git
  1. Install python 3.9. If you use apt (most Debian based distros use it):
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.9
  1. Create a python virtual environment from python 3.9, there are several options for this (we recommend Conda):

You can isntall miniconda in Linux with the following code:

mkdir -p ~/miniconda3
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm -rf ~/miniconda3/miniconda.sh

Then restart your shell:

~/miniconda3/bin/conda init bash
~/miniconda3/bin/conda init zsh
  1. Activate the virtual environment and install the requirements with:
pip install -r requirements.txt

Sometimes, even activating the virtual environemnt, the shell will use the wide system pip, you can check it with which pip (in Linux). In that case, you may want to locate the python interpreter of your virtual environment or an alias (most of the times python3.9) then run:

/path/to/your/virtual-environtment/bin/python3.9 -m pip install -r requirements.txt
  1. Install the project with (we recommend to be an user with root privileges):
make install
  1. Decompress dummy data with:
make dummy-data
  1. Activate your virtual environment and run a test with the simulation launcher:
python3.9 scripts/experiment.py

Basic Usage

To make the most of this version of the project is strongly recommended to be familiar with facebook-hydra. The configuration of a given simulation (and reconstruction) is split into 3 groups: global configuration, params, configuration and scanner configuration (examples given below). The scanner group is a subgroup of params group and params is a subgroup of the global configuration.

  • Example of global configuration.
  • Example of params configuration group.
  • Example of scanner configuration group.

This approach allows the user to have several configuration groups and switch between them at no cost. For example, given the following tree of configurations (each subgroup has a "production" configuration and a "test" configuration):

.
└── configs/
    ├── config_prod.yaml  # global configuration group
    ├── config_test.yaml  # global configuration group
    └── params/
        ├── params_prod.yaml
        ├── params_test.yaml
        └── scanner/
            ├── siemens.yaml
            └── discovery.yaml

Using facebook-hydra override syntax and the experiment.py launcher, switching between configurations is trivial:

# Running test configuration with Siemens scanner
python scripts/experiment.py --config-name config_test params/scanner=siemens

# Running prod configuration with test `params` and Discovery scanner
python scripts/experiment.py --config-name config_prod params=params_test params/scanner=discovery

# Running prod configuration with test `params` and Discovery scanner but doing only reconstruction
python scripts/experiment.py --config-name config_prod params=params_test params/scanner=discovery params.do_simulation=0

# Running prod configuration with test `params` and Discovery scanner, doing only reconstruction and overriding the scanner radius
python scripts/experiment.py --config-name config_prod params=params_test params/scanner=discovery params.do_simulation=0 params.scanner.scanner_radius=35

Whole Body Simulation

You can perform whole body simulations following the same logic described in the last section. You may want to add z_min and z_max parameters to the params configuration group. Here you can find the configuration templates:

  • Example of global configuration.
  • Example of params configuration group.

Then you can launch an experiment with the experiment_wholebody.py launcher:

python3.9 scripts/experiment_wholebody.py --config-name <your_config_name>

Even add z_min and z_max on the fly:

python3.9 scripts/experiment_wholebody.py --config-name <your_config_name> +params.z_min=29 +params.z_max=89

Or override them:

python3.9 scripts/experiment_wholebody.py --config-name <your_config_name> params.z_min=29 params.z_max=89

BrainVISET

BrainVISET is an iterative algorithm that allows the generation of activity and attenuation maps from high-resolution CT and MRI images. To run BrainVISET you will need SPM12 and MATLAB MCR. Ensure that the configuration keys matlab_mcr_path (path to MATLAB MCR) and spm_path (path to SPM12) are well set in your configs file. In addition, you must also specify the names (with extension) of the CT, MRI and PET images in your configs/params file (keys ct_image, mri_image and pet_image). Then, you can run BrainVISET using the experiment_brainviset.py launcher:

python3.9 scripts/experiment_brainviset.py --config-name <your_config_name>

Even change image names on the fly (or other parameters):

python3.9 scripts/experiment_brainviset.py --config-name <your_config_name> params.ct_image="my_ct.nii" params.mri_image="my_mri.nii" params.pet_image="my_pet.nii"

GENERAL NOTES ON USAGE:

  • Monte Carlo simulations usually take a lot of space. If you want to change the default Data and Results directories you can do so in the in the global configuration group or using facebook-hydra CLI overriding syntax.
  • The current version of the project can produce only sinograms and LM data using SimSET. Rest of the stuff is coming soon.
  • The repository has only been tested on Ubuntu 22.04.1 LTS.

Contributors

  • Jesús Silva-Rodríguez
  • Pablo Aguiar
  • Aida Ninyerola-Baizan
  • Jeremiah Poveda
  • Francisco Javier López-González
  • Nikos Efthimiou
  • Arnau Farre

References

You may find more information about STIR and SimSET parameters in their official documentation.

[1] SimSET.

SimSET and SimPET simulation

Clone this wiki locally