Merge branch 'master' of github.com:AthenaEPI/mipy

README.md

@@ -46,7 +46,7 @@ To get a feeling for how to use dmipy, we provide a few tutorial notebooks:
 - [Spherical Mean Models](https://github.com/AthenaEPI/mipy/blob/master/examples/example_spherical_mean_models.ipynb)
 ### Global Optimizers
 - [Brute Force (Brute2Fine)](https://github.com/AthenaEPI/dmipy/blob/master/examples/example_brute_force_optimization.ipynb)
-- Stochastic (MIX) [Farooq et al. 2016]
+- [Stochastic (MIX) [Farooq et al. 2016]](https://github.com/AthenaEPI/dmipy/blob/master/examples/example_stochastic_mix_optimization.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](https://github.com/AthenaEPI/mipy/blob/master/examples/tutorial_human_connectome_project_aws.ipynb).
 ### Single Bundle Microstructure Models
@@ -63,7 +63,7 @@ dmipy uses HCP data to illustrate microstructure model examples. To reproduce th
 - [Multi-Compartment Microscopic Diffusion Imaging [Kaden et al. 2016]](https://github.com/AthenaEPI/mipy/blob/master/examples/example_multi_compartment_spherical_mean_technique.ipynb)
 
 ## How to contribute to dmipy
-dmipy's design is completely modular and can easily be extended with new models, distributions or optimizers. To contribute, view our [contribution guidelines](https://github.com/AthenaEPI/dmipy/blob/master/contribution_guidelines.ipynb).
+dmipy's design is completely modular and can easily be extended with new models, distributions or optimizers. To contribute, view our [contribution guidelines](https://github.com/AthenaEPI/dmipy/blob/master/contribution_guidelines.rst).
 ## How to cite dmipy
 Fick, Rutger. *Advanced dMRI signal modeling for tissue microstructure characterization*. Diss. Université Côte d'Azur; Inria Sophia Antipolis, 2017.
 

contribution_guidelines.rst

@@ -0,0 +1,118 @@
+
+Dmipy Contribution Guidelines
+=============================
+
+The idea behind dmipy is that it's modular and easily extendable with
+new models and optimizers.
+
+To contribute your work to dmipy, we just ask that you adhere to some
+guidelines as to how to structure the functions. You can contribute
+CompartmentModel, Spherical Distributions, Spatial Distributions and
+Optimizers. Their blueprints are given below.
+
+If you want contribute, just contact us or open a pull request.
+
+Blueprint Compartment Models
+----------------------------
+
+.. code:: ipython2
+
+    class NewCompartmentModel:
+        
+        # some default optimization ranges (min and max allowed value), and their scale.
+        self._parameter_scales = {'parameter1': value1, 'parameter2': value2}
+        self._parameter_ranges = {'parameter1': [start1, end1], 'parameter2': [start2, end2]}
+        
+        def __init__(self, parameter1=None, parameter2=None):
+            "instantiate your model"
+            self.parameter1 = parameter1
+            self.parameter2 = parameter2
+        
+        def __call__(self, acquisition_scheme, **kwargs):
+            "your function call that returns signal attenuation for the given acquisition scheme"
+            
+            parameter1 = kwargs.get('parameter1', self.parameter1)
+            parameter2 = kwargs.get('parameter2', self.parameter2)
+    
+            return signal_attenuation
+    
+        def optional_helper_functions(self, params)
+            ...
+
+Blueprint Spherical Distributions
+---------------------------------
+
+.. code:: ipython2
+
+    class NewSphericalDistribution:
+        
+        # some default optimization ranges (min and max allowed value), and their scale.
+        self._parameter_scales = {'parameter1': value1, 'parameter2': value2}
+        self._parameter_ranges = {'parameter1': [start1, end1], 'parameter2': [start2, end2]}
+        
+        def __init__(self, parameter1=None, parameter2=None):
+            "instantiate your model"
+            self.parameter1 = parameter1
+            self.parameter2 = parameter2
+        
+        def __call__(self, sphere_orientations, **kwargs):
+            "your function call that returns probability density at the given sphere orientations"
+            
+            parameter1 = kwargs.get('parameter1', self.parameter1)
+            parameter2 = kwargs.get('parameter2', self.parameter2)
+    
+            return probability_density
+    
+        def spherical_harmonics_representation(self, sh_order=some_default, **kwargs):
+            "returns the spherical harmonics representation of the spherical distribution"
+            return distribution_sh_coefficients
+            
+        def optional_helper_functions(self, params)
+            ...
+
+Blueprint Spatial Distributions
+-------------------------------
+
+.. code:: ipython2
+
+    class NewSpatialDistribution:
+        
+        # some default optimization ranges (min and max allowed value), and their scale.
+        self._parameter_scales = {'parameter1': value1, 'parameter2': value2}
+        self._parameter_ranges = {'parameter1': [start1, end1], 'parameter2': [start2, end2]}
+        
+        def __init__(self, parameter1=None, parameter2=None):
+            "instantiate your model"
+            self.parameter1 = parameter1
+            self.parameter2 = parameter2
+        
+        def __call__(self, **kwargs):
+            "your function call that returns probability density for some sampling range."
+            "Ideally this sampling range is automatically dependent on the input parameters."
+            
+            parameter1 = kwargs.get('parameter1', self.parameter1)
+            parameter2 = kwargs.get('parameter2', self.parameter2)
+    
+            return sampled_parameter_points, probability_density_at_those_points
+            
+        def optional_helper_functions(self, params)
+            ...
+
+Blueprint Optimizers
+--------------------
+
+.. code:: ipython2
+
+    class NewOptimizer:
+        # the optimizer should be instantiated using the model, acquisition scheme and possible solver options.
+        def __init__(self, model, acquisition_scheme, possible_solver_options):
+            self.model = model
+            self.acquisition_scheme = acquisition_scheme
+            self.possible_solver_options = possible_solver_options
+        
+        def __call__(self, data, possible_x0_vector):
+            "function call that returns the fitted model parameters."
+            return fitted_parameter_array
+        
+        def optional_helper_functions(self, params)
+            ...

dmipy/optimizers/mix.py

@@ -56,7 +56,7 @@ def __init__(self, model, acquisition_scheme, maxiter=150):
         self.maxiter = maxiter
         self.Nmodels = len(self.model.models)
 
-    def __call__(self, data, x0_vector):
+    def __call__(self, data, x0_vector=None):
         """ The fitting function of the MIX algorithm. Fits the data in three
         distinct steps, first fitting non-linear parameters using
         differential_evolution, then linear parameters using COBYLA, and
@@ -75,11 +75,14 @@ def __call__(self, data, x0_vector):
             The fitted MC model parameters using MIX.
 
         """
-        bounds = list(self.model.bounds_for_optimization)
-        for i, x0_ in enumerate(x0_vector):
-            if (x0_ is not None and
-                    self.model.opt_params_for_optimization[i] is False):
-                bounds[i] = np.r_[x0_, x0_ + 1e-6]
+        if x0_vector is not None:
+            bounds = list(self.model.bounds_for_optimization)
+            for i, x0_ in enumerate(x0_vector):
+                if (not np.isnan(x0_) and
+                        self.model.opt_params_for_optimization[i] is False):
+                    bounds[i] = np.r_[x0_, x0_ + 1e-6]
+        else:
+            bounds = list(self.model.bounds_for_optimization)
 
         # step 1: Variable separation using differential evolution algorithm
         bounds_de = list(bounds)