IntraVoxel Incoherent Motion (IVIM) and S0 optimization

[rutgerfick]

• acquisition scheme without b0 measurements should give warning that S0 must be estimated as parameter.
• adds functionality to estimate S0 from data as extra parameter without b0 measurements.
  • S0 is always introduced as parameter instead of separate field that is passed. Added upon model instantiating with default cardinality 1 for 1 TE.
  • S0 cardinality, parameter ranges and scales are setup at beginning of fit(). cardinality is N for N TE values (1 if it is not given). range e.g. 0.5 of min value to 1.5 of max value. scale is set to mean of b0 (or S0 guess).
  • optimize_S0 boolean to either optimize S0 with parameters or fix it to the mean of b0 measurements.
    • if False, S0 is not even passed to the optimizer, but data is predivided inside optimization call but before actual optimizer.
    • if True, S0 is passed and data is divided by S0 inside each optimizer call (and expanded for multi-TE data).
    • if True and there are b0s, S0 initial guess is made to mean of b0 measurements.
    • if True and there are no b0s, S0 initial guess is made to gaussian fit of DWIs and estrapolated to b=0.
    • if False and there are b0s, S0 is fixed to mean of b0 measurements.
    • if False and there are no b0s, an appropriate error is given that tells to check the acquisition scheme or set optimize_S0=True.
    • if True and there are multiple TEs, NotImplemented error for now.
    • if False and there are multiple TEs, S0 is not a float but an array of cardinality the number of TEs. inside the optimization the S0s are expanded to become the length of the DWIs to divide them.
  • S0 estimation in MultiCompartmentModel
  • S0 estimation in MultiCompartmentSphericalMeanModel
  • S0 estimation in MultiCompartmentSphericalHarmonicsModel (S0 is at least calculated as parameter after the CSD optimization).
• IVIM as custom_optimizer just as ss3t.
• correct IVIM example
• if optimize_S0=False, then S0 (and other fixed parameters) are passed as extra arguments to lbfgs minimizer (so not causing extra computation time).
• update all predict functions in FittedCompartments
• fix slowdown for all fitting
• add tests for S0 estimation
  closes IVIM example #15
  closes Option to estimate S0 during model fitting instead of pre-dividing by mean of b0s #18
  closes Ability to easily set parameter optimization ranges #37

[coveralls]

Pull Request Test Coverage Report for Build 451

• 140 of 189 (74.07%) changed or added relevant lines in 6 files are covered.
• 14 unchanged lines in 5 files lost coverage.
• Overall coverage increased (+0.7%) to 83.721%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
dmipy/core/fitted_modeling_framework.py	9	12	75.0%
dmipy/core/modeling_framework.py	57	103	55.34%

Files with Coverage Reduction	New Missed Lines	%
dmipy/core/modeling_framework.py	1	74.64%
dmipy/core/fitted_modeling_framework.py	1	68.29%
dmipy/data/saved_data.py	2	70.94%
dmipy/data/saved_acquisition_schemes.py	2	83.33%
dmipy/optimizers/mix.py	8	83.5%

Totals
Change from base Build 416:	0.7%
Covered Lines:	4610
Relevant Lines:	5358

---

💛 - Coveralls

[codecov-io]

Codecov Report

Merging #16 into master will increase coverage by 0.58%.
The diff coverage is 66.13%.

@@            Coverage Diff             @@
##           master      #16      +/-   ##
==========================================
+ Coverage   82.35%   82.94%   +0.58%     
==========================================
  Files          61       61              
  Lines        5253     5358     +105     
  Branches      614      638      +24     
==========================================
+ Hits         4326     4444     +118     
+ Misses        763      739      -24     
- Partials      164      175      +11

Impacted Files	Coverage Δ
...ssue_response/tests/test_tissue_response_models.py	100% <ø> (ø)	⬆️
dmipy/optimizers_fod/csd_tournier.py	93.97% <ø> (-0.08%)	⬇️
dmipy/optimizers/mix.py	78.48% <100%> (+22.07%)	⬆️
dmipy/core/tests/test_optimization.py	100% <100%> (ø)	⬆️
dmipy/core/modeling_framework.py	69.49% <44.66%> (-0.23%)	⬇️
dmipy/core/fitted_modeling_framework.py	65.77% <66.66%> (+1.01%)	⬆️
dmipy/core/acquisition_scheme.py	77.91% <81.81%> (-0.18%)	⬇️
dmipy/optimizers/brute2fine.py	83.52% <96%> (+2.04%)	⬆️
dmipy/utils/tests/test_spherical_convolution.py	87.8% <0%> (-12.2%)	⬇️
... and 3 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e1ba0bd...e097e8c. Read the comment docs.

[rutgerfick]

IVIM should be a custom optimizer since the literature typically does a 2-step approach and splits the data. see recent paper http://www.ajnr.org/content/ajnr/early/2017/12/07/ajnr.A5474.full.pdf

[rutgerfick]

add test for acquisition scheme dummy deltas function.