Metadata-Version: 2.1
Name: mdreg
Version: 0.3.2
Summary: Open-source, platform independent library for Model Driven Registration (MDR) in quantitative renal MRI
Home-page: https://github.com/QIB-Sheffield/mdreg
Author: Kanishka Sharma, Joao Almeida e Sousa and Steven Sourbron
Author-email: kanishka.sharma@sheffield.ac.uk, j.g.sousa@sheffield.ac.uk, s.sourbron@sheffield.ac.uk
License: Apache Software License (http://www.apache.org/licenses/LICENSE-2.0)
Keywords: python,medical imaging,DICOM,MRI,renal,kidney,motion correction,registration
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.6, <4
Description-Content-Type: text/markdown
Requires-Dist: dbdicom (==0.0.6)
Requires-Dist: itk-elastix
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pdoc3
Requires-Dist: Pillow
Requires-Dist: requests
Requires-Dist: scipy
Requires-Dist: SimpleITK
Requires-Dist: tqdm

# Description
Python implementation of model-based image coregistration 
for quantitative medical imaging applications. 

The distribution comes with a number of common signal models and uses [ITK-Elastix](https://github.com/InsightSoftwareConsortium/ITKElastix) for deformable image registration.

## Installation
Run `pip install mdreg`. 

## Example data
Example data in [DICOM format](https://shorturl.at/rwCUV) are provided for testing the setup.

## How to use
Input data must be image arrays in numpy format, with dimensions `(x,y,z,t)` or `(x,y,t)`. 
To perform MDR on an image array `im` with default settings do: 

```python
from mdreg import MDReg

mdr = MDReg()
mdr.set_array(im)
mdr.fit()
```

When fitting is complete the motion-corrected data are in `mdr.coreg` in the same dimensions 
as the original `im`. The calculated deformation fields in format `(x,y,d,t)` or `(x,y,z,d,t)` 
can be found as `mdr.deformation`. The dimension `d` holds `x`, `y` components 
of the deformation field, and a third `z` component if the input array is 3D.

The default settings will apply a linear signal model and coregistration 
as defined in the elastix parameter file `Bsplines.txt`. 

# Customization

MDR can be configured to apply different signal models and elastix coregistration settings.
A number of example models and alternative elastix parameter files are included 
in the distribution as templates.

The following example fits a mono-exponential decay, uses a mask `im_mask` for co-registration and applies an elastix parameter file `par_file` optimized for a previous DTI-MRI study:

```python
from mdreg import MDReg
from mdreg.models import exponential_decay

mdr = MDReg()
mdr.set_array(im)
mdr.set_mask(im_mask)
mdr.signal_model = exponential_decay
mdr.read_elastix(par_file)
mdr.fit()
```

`im_mask` must be a binary (0s and 1s) or boolean (Trues and Falses) image array in numpy format with the same dimensions as `im`.

The signal model often depends on fixed constants and signal parameters 
such as sequence parameters in MRI, or patient-specific constants. These 
should all be grouped in a list and set before running the signal model. 

Equally elastix parameters can be fine tuned, either by importing a 
dedicated elastix file, or by modifying the settings. 

You may also choose if you wish to run the process in multiple cores (`parallel`) and to print the co-registration progress to the terminal plus a text file (`log`) or not.

Then, a number of parameters are available to optimize MDR such as 
the precision (stopping criterion) and maximum number of iterations.

Some examples:

```python
from mdreg import MDReg
from mdreg.models import exponential_decay

t = [0.0, 1.25, 2.50, 3.75]     # time points for exponential in sec

mdr = MDReg()
mdr.set_array(im)
mdr.signal_parameters = t
mdr.signal_model = exponential_decay
mdr.set_elastix(MaximumNumberOfIterations = 256)   # change defaults
mdr.precision = 0.5         # default = 1
mdr.max_iterations = 3      # default = 5
mdr.parallel = False        # default = True
mdr.log = True              # default = False
mdr.fit()
```

`mdreg` comes with a number of options to 
export results and diagnostics:

```python
mdr.export_unregistered = True      # export parameters and fit without registration
mdr.export_path = filepath          # default is a results folder in the current working directory
mdr.export()                        # export results after calling fit. 
```

This export creates movies of original images, motion corrected images, 
modelfits, and maps of the fitted parameters.

# Model fitting without motion correction

`MDReg` also can be used to perform model fitting 
without correcting the motion. The following script 
fits a linearised exponential model to each pixel and exports data 
of model and fit:

```python
from mdreg import MDReg
from mdreg.models import exponential_decay

mdr = MDReg()
mdr.set_array(im)
mdr.signal_model = linear_exponential_decay
mdr.fit_signal()
mdr.export_data()
mdr.export_fit()
```

# Defining new MDR models

A model must be defined as a separate module or class with two required functions `main()` and `pars()`.

`pars()` must return a list of strings specifying the names of the model parameters.
`main(im, const)` performs the pixel based model fitting and has two required arguments. 
`im` is a numpy ndarray with dimensions `(x,y,z,t)`, `(x,y,t)` or `(x,t)`. `const` is a list 
of any constant model parameters.

The function must return the fit to the model as an numpy ndarray with the same dimensions 
as `im`, and an ndarray `pars` with dimensions `(x,y,z,p)`, `(x,y,p)` or `(x,p)`. Here `p` enumerates 
the model parameters. 

## Context

`mdreg` was first developed for use in quantitative renal MRI in the iBEAt study, 
and validated against group-wise model-free registration 
(Tagkalakis F, et al. Model-based motion correction outperforms a model-free method in quantitative renal MRI. Abstract-1383, ISMRM 2021).

## Acknowledgement

The iBEAt study is part of the BEAt-DKD project. The BEAt-DKD project has received funding from the Innovative Medicines Initiative 2 Joint Undertaking under grant agreement No 115974. This Joint Undertaking receives support from the European Union’s Horizon 2020 research and innovation programme and EFPIA with JDRF. For a full list of BEAt-DKD partners, see www.beat-dkd.eu.

## Authors

Kanishka Sharma, Joao Almeida e Sousa, Steven Sourbron


