Adds IVIM example. (#48)

AthenaEPI · May 1, 2019 · cb4b54a · cb4b54a
1 parent 81ebad5
commit cb4b54a
Show file tree

Hide file tree

Showing 3 changed files with 594 additions and 22 deletions.
diff --git a/README.md b/README.md
@@ -34,7 +34,7 @@ Dmipy allows the user to do Microstructure Imaging research at the highest level
 - clone repository
 - python setup.py install
 
-See solutions to [common issues](https://github.com/AthenaEPI/mipy/blob/master/common_issues.md)
+See solutions to [common issues](https://github.com/AthenaEPI/dmipy/blob/master/common_issues.md)
 ## Dependencies
 Recommended to use Anaconda Python distribution.
 - numpy >= 1.13
@@ -47,47 +47,48 @@ Recommended to use Anaconda Python distribution.
 
 ## Getting Started
 To get a feeling for how to use Dmipy, we provide a few tutorial notebooks:
-- [Setting up an acquisition scheme](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/tutorial_setting_up_acquisition_scheme.ipynb)
-- [Simulating and fitting data using a simple Stick model](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/tutorial_simulating_and_fitting_using_a_simple_model.ipynb)
-- [Combining biophysical models into a Microstructure model](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/tutorial_combining_biophysical_models_into_microstructure_model.ipynb)
+- [Setting up an acquisition scheme](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/tutorial_setting_up_acquisition_scheme.ipynb)
+- [Simulating and fitting data using a simple Stick model](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/tutorial_simulating_and_fitting_using_a_simple_model.ipynb)
+- [Combining biophysical models into a Microstructure model](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/tutorial_combining_biophysical_models_into_microstructure_model.ipynb)
 - [Creating a dispersed and/or distributed axon bundle representation](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/tutorial_distributed_model_representations.ipynb)
-- [Imposing parameter links and constraints](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/tutorial_imposing_parameter_links.ipynb)
-- [Parameter Cascading: Using a simple model to initialize a complex one](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/tutorial_parameter_cascading_and_simulating_nd_datasets.ipynb)
+- [Imposing parameter links and constraints](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/tutorial_imposing_parameter_links.ipynb)
+- [Parameter Cascading: Using a simple model to initialize a complex one](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/tutorial_parameter_cascading_and_simulating_nd_datasets.ipynb)
 
 ## Explanations and Illustrations of Dmipy Contents
 ### Biophysical Models and Distributions
-- [Cylinder Models (Axons, e.g. [Assaf et al. 2004])](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/example_cylinder_models.ipynb)
-- [Sphere Models (Tumor cells, e.g. [Panagiotaki et al. 2014])](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/example_sphere_models.ipynb)
-- [Parameter Distribution Models (Axon Diameter Distribution, e.g. [Assaf et al. 2008])](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/example_diameter_distributions.ipynb)
-- [Gaussian Models (Extra-axonal, e.g. [Behrens et al. 2003])](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/example_gaussian_models.ipynb)
+- [Cylinder Models (Axons, e.g. [Assaf et al. 2004])](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_cylinder_models.ipynb)
+- [Sphere Models (Tumor cells, e.g. [Panagiotaki et al. 2014])](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_sphere_models.ipynb)
+- [Parameter Distribution Models (Axon Diameter Distribution, e.g. [Assaf et al. 2008])](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_diameter_distributions.ipynb)
+- [Gaussian Models (Extra-axonal, e.g. [Behrens et al. 2003])](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_gaussian_models.ipynb)
 - Tissue Response Function Models and Estimation (WM/GM/CSF, e.g. [Jeurissen et al. 2014])
-- [Spherical Distribution Models (Axon Dispersion, e.g. [Kaden et al. 2007])](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/example_watson_bingham.ipynb)
-- [Spherical Mean of any Compartment Model](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/example_spherical_mean_models.ipynb)
+- [Spherical Distribution Models (Axon Dispersion, e.g. [Kaden et al. 2007])](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_watson_bingham.ipynb)
+- [Spherical Mean of any Compartment Model](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_spherical_mean_models.ipynb)
 ### Global Multi-Compartment Optimizers
 - [Brute Force to Gradient Descent (Brute2Fine)](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_brute_force_optimization.ipynb)
 - [Stochastic (MIX) [Farooq et al. 2016]](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_stochastic_mix_optimization.ipynb)
 ### Constrained Spherical Deconvolution Optimizers
 - [Generalized Multi-Shell Multi-Compartment CSD [Tournier et al. 2007, Jeurissen et al. 2014]](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_generalized_csd_optimizer.ipynb)
 ## Dmipy implementations of Microstructure Models in Literature
-Dmipy uses HCP data to illustrate microstructure model examples. To reproduce these examples, dmipy provides a direct way to download HCP data (using your own AWS credentials) in the [HCP tutorial](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/tutorial_human_connectome_project_aws.ipynb).
+Dmipy uses HCP data to illustrate microstructure model examples. To reproduce these examples, dmipy provides a direct way to download HCP data (using your own AWS credentials) in the [HCP tutorial](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/tutorial_human_connectome_project_aws.ipynb).
 ### Single Bundle Models
-- [Ball and Stick [Behrens et al. 2003]](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/example_ball_and_stick.ipynb)
-- [Ball and Racket [Sotiropoulos et al. 2012]](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/example_ball_and_racket.ipynb)
-- [NODDI-Watson [Zhang et al. 2012]](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/example_noddi_watson.ipynb)
-- [NODDI-Bingham [Tariq et al. 2016]](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/example_noddi_bingham.ipynb)
-- [AxCaliber [Assaf et al. 2008]](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/example_axcaliber.ipynb)
+- [Ball and Stick [Behrens et al. 2003]](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_ball_and_stick.ipynb)
+- [Ball and Racket [Sotiropoulos et al. 2012]](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_ball_and_racket.ipynb)
+- [NODDI-Watson [Zhang et al. 2012]](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_noddi_watson.ipynb)
+- [NODDI-Bingham [Tariq et al. 2016]](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_noddi_bingham.ipynb)
+- [AxCaliber [Assaf et al. 2008]](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_axcaliber.ipynb)
 - [AxCaliber with Extra-Axonal Diffusion Time-Dependence [De Santis et al. 2016]](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_axcaliber_temporal_zeppeline.ipynb)
 
 ### Crossing Bundle Models
-- [Ball and Sticks [Behrens et al. 2003]](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/example_ball_and_sticks.ipynb)
-- [NODDI in Crossings (NODDIx) [Farooq et al. 2016]](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/example_mix_microstructure_imaging_in_crossings.ipynb)
+- [Ball and Sticks [Behrens et al. 2003]](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_ball_and_sticks.ipynb)
+- [NODDI in Crossings (NODDIx) [Farooq et al. 2016]](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_mix_microstructure_imaging_in_crossings.ipynb)
 
 ### Tumor Models
-- [VERDICT [Panagiotaki et al. 2014]](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/example_verdict.ipynb)
+- [IVIM [Le Bihan et al. 1988, Gurney-Champion et al. 2018]](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_ivim.ipynb)
+- [VERDICT [Panagiotaki et al. 2014]](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_verdict.ipynb)
 ### Spherical Mean-Based Models
 Any Spherical Mean model can also estimate parametric FODs.
 - [Spherical Mean Technique [Kaden et al. 2015]](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_spherical_mean_technique.ipynb)
-- [Multi-Compartment Microscopic Diffusion Imaging [Kaden et al. 2016]](http://nbviewer.jupyter.org/github/AthenaEPI/mipy/blob/master/examples/example_multi_compartment_spherical_mean_technique.ipynb)
+- [Multi-Compartment Microscopic Diffusion Imaging [Kaden et al. 2016]](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_multi_compartment_spherical_mean_technique.ipynb)
 ### Spherical Deconvolution-Based Models
 Constrained spherical deconvolution (CSD) models are primarily used for Fiber Orientation Distribution (FOD) estimation. Multi-Tissue CSD models improve FOD estimation by separating WM/GM/CSF signal contributions using multiple tissue response functions.
 - [Multi-Shell Multi-Compartment CSD [model-based version of Jeurissen et al. 2014]](http://nbviewer.jupyter.org/github/AthenaEPI/dmipy/blob/master/examples/example_multi_compartment_constrained_spherical_deconvolution.ipynb)

diff --git a/dmipy/custom_optimizers/intra_voxel_incoherent_motion.py b/dmipy/custom_optimizers/intra_voxel_incoherent_motion.py
@@ -0,0 +1,80 @@
+from dmipy.signal_models.gaussian_models import G1Ball
+from dmipy.core.modeling_framework import MultiCompartmentModel
+import numpy as np
+from time import time
+
+
+def ivim_Dstar_fixed(acquisition_scheme, data, mask=None, Dstar_value=7e-9,
+                     solver='brute2fine', **fit_args):
+    """
+    Implementation of second best performing IVIM algorithm following [1]_.
+    Basically, it is just a non-linear least squares fit with fixing the
+    blood diffusivity Dstar to 7e-3 mm^2/s. This value apparently improves the
+    stability of the fit (in healthy volunteers) [2]_.
+
+    The optimization range for the tissue diffusivity is set to
+    [0.5 - 6]e-3 mm^2/s to improve precision [3]_.
+
+    In the fitted ivim_fit model, partial_volume_0 and G1Ball_1_lambda_iso
+    represent the tissue fraction and diffusivity, and partial_volume_1 and
+    G1Ball_2_lambda_iso represent the blood fraction and diffusivity.
+
+    Parameters
+    ----------
+    acquisition_scheme: Dmipy AcquisitionScheme instance,
+        acquisition scheme containing all the information of the ivim
+        acquisition.
+    data: ND-array of shape (Nx, ..., N_DWI),
+        measured data corresponding to the acquisition scheme.
+    mask : (N-1)-dimensional integer/boolean array of size (N_x, N_y, ...),
+        Optional mask of voxels to be included in the optimization.
+    Dstar_value: float,
+        the fixed Dstar blood diffusivity value. Default: 7e-9 m^2/s [2]_.
+    solver: float,
+        which solver to use for the algorithm. Default: 'brute2fine'.
+    fit_args: other keywords that are passed to the optimizer
+
+    Returns
+    -------
+    ivim_fit: Dmipy FittedMultiCompartmentModel instance,
+        contains the fitted IVIM parameters.
+
+    References
+    ----------
+    .. [1] Gurney-Champion, O. J., Klaassen, R., Froeling, M., Barbieri, S.,
+        Stoker, J., Engelbrecht, M. R., ... & Nederveen, A. J. (2018).
+        Comparison of six fit algorithms for the intra-voxel incoherent motion
+        model of diffusion-weighted magnetic resonance imaging data of
+        pancreatic cancer patients. PloS one, 13(4), e0194590.
+    .. [2] Gurney-Champion OJ, Froeling M, Klaassen R, Runge JH, Bel A, Van
+        Laarhoven HWM, et al. Minimizing the Acquisition Time for Intravoxel
+        Incoherent Motion Magnetic Resonance Imaging Acquisitions in the Liver
+        and Pancreas. Invest Radiol. 2016;51: 211–220.
+    .. [3] Park HJ, Sung YS, Lee SS, Lee Y, Cheong H, Kim YJ, et al. Intravoxel
+        incoherent motion diffusion-weighted MRI of the abdomen: The effect of
+        fitting algorithms on the accuracy and reliability of the parameters.
+        J Magn Reson Imaging. 2017;45: 1637–1647.
+    """
+    start = time()
+
+    if fit_args is None:
+        fit_args = {}
+
+    print('Starting IVIM Dstar-fixed algorithm.')
+    ivim_mod = MultiCompartmentModel([G1Ball(), G1Ball()])
+    ivim_mod.set_fixed_parameter(
+        'G1Ball_2_lambda_iso', Dstar_value)  # following [2]
+    ivim_mod.set_parameter_optimization_bounds(
+        'G1Ball_1_lambda_iso', [.5e-9, 6e-9])  # following [3]
+    ivim_fit = ivim_mod.fit(
+        acquisition_scheme=acquisition_scheme,
+        data=data,
+        mask=mask,
+        solver=solver,
+        **fit_args)
+    computation_time = time() - start
+    N_voxels = np.sum(ivim_fit.mask)
+    msg = 'IVIM Dstar-fixed optimization of {0:d} voxels'.format(N_voxels)
+    msg += ' complete in {0:.3f} seconds'.format(computation_time)
+    print(msg)
+    return ivim_fit