A distribution of a general tool for training and inference of QMRI models
Project description
EMCqMRI
The EMCqMRI is a PyTorch-based package designed with the goal to accelerate initial developments in the field of quantitative MRI (qMRI).
It provides the base classes for the implementation of task-specific custom modules and offers a framework for training Deep Learning inference models and prediction of quantitative maps.
Validated qMRI methods, including signal models, likelihood functions and inference methods, are already included within this package.
Installing
Preparing the development enviroment
-
Create a virtual environment for the project:
python3 -m venv venv_example_project
-
Activate the virtual environment:
. venv_example_project/bin/activate
-
Upgrade pip and install wheel:
pip3 install --upgrade pip wheel
(this will make sure you have no errors and warnings during installations with pip)
Installing PyTorch
-
MacOS without CUDA support:
pip3 install torch torchvision
-
MacOS with CUDA support: follow instructions at this URL: https://github.com/pytorch/pytorch#from-source
-
Linux with CUDA support:
pip3 install torch torchvision
-
Windows with CUDA support:
pip3 install torch==1.7.1 torchvision==0.8.2 -f https://download.pytorch.org/whl/torch_stable.html
Installing the EMCqMRI package with PIP
- After activating your virtual enviroment, run:
pip3 install EMCqMRI
.
Validating the installation
Once installed, you can verify if everything is running correctly.
- Start a Python session in your terminal:
python3
- Import the EMCqMRI package:
import EMCqMRI
- Verify the package version:
print(EMCqMRI.__version__)
Support
The following configurations were used and proved to work. Please, let us know if you tested the packaged in a different OS, Python version or PyTorch version.
OS
Python
PyTorch
Projects using the EMCqMRI
- https://gitlab.com/e.ribeirosabidussi/emcqmri_relaxometry
- https://gitlab.com/e.ribeirosabidussi/emcqmri_dti
- https://gitlab.com/e.ribeirosabidussi/emcqmri_relaxometry_resmotion
- https://gitlab.com/e.ribeirosabidussi/emcqmri_motion_relaxometry
- https://gitlab.com/e.ribeirosabidussi/ipim_inverse_problems_rim
Using the EMCqMRI in your project
The documentation for the APIs and implemented modules can be found at: https://emcqmri.readthedocs.io/en/latest/
APIs
-
Signal Model: It provides an interface for the implementation of custom signal models for model-based inference of quantitative MRI parameters.
-
Likelihood Model: This interface allows for the implementation of custom likelihood models for model-based inference methods. In many cases, this model is also referred to as the data consistency model.
-
Inference Model: Interface for the implementation of custom inference models. The EMCqMRI supports model-drive, data-drive and hibrid (data/model-driven) methods.
-
Dataset Model: Interface for the construction of custom dataset models. These might include the generation of simulated data, loading of existing training and testing datasets, pre-processing and data augmentation techniques, etc.
Creating custom modules and configuration
The creation of custom modules is straighforward using the EMCqMRI APIs. You can follow this short tutorial to create the basis of a new project, and learn how to link custom modules to the EMCqMRI core.
You can read more about the configuration files required to use the EMCqMRI here: Configuration Files
Contributing / Reporting issues
Please refer to the project's coding and documentation style for submitting patches and additions. In general, we follow the "fork-and-pull" Git workflow.
- Fork the repo on GitHub
- Clone the project to your own machine
- Commit changes to your own branch
- Push your work back up to your fork
- Submit a Pull request so that we can review your changes
NOTE: Be sure to merge the latest from "upstream" before making a pull request!
Requirements
The EMCqMRI package is based on Python and PyTorch. External dependencies are automatically installed with the package.
Known bugs
There might be differences when using the EMCqMRI with Windows, MacOS and Linux, due to different conventions in the Path style. Please report them by creating an issue on this project.
License
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.