added contribution guidelines

contribution_guidelines.ipynb

@@ -0,0 +1,192 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Dmipy Contribution Guidelines"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The idea behind dmipy is that it's modular and easily extendable with new models and optimizers.\n",
+    "\n",
+    "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.\n",
+    "\n",
+    "If you want contribute, just contact us or open a pull request."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Blueprint Compartment Models"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "class NewCompartmentModel:\n",
+    "    \n",
+    "    # some default optimization ranges (min and max allowed value), and their scale.\n",
+    "    self._parameter_scales = {'parameter1': value1, 'parameter2': value2}\n",
+    "    self._parameter_ranges = {'parameter1': [start1, end1], 'parameter2': [start2, end2]}\n",
+    "    \n",
+    "    def __init__(self, parameter1=None, parameter2=None):\n",
+    "        \"instantiate your model\"\n",
+    "        self.parameter1 = parameter1\n",
+    "        self.parameter2 = parameter2\n",
+    "    \n",
+    "    def __call__(self, acquisition_scheme, **kwargs):\n",
+    "        \"your function call that returns signal attenuation for the given acquisition scheme\"\n",
+    "        \n",
+    "        parameter1 = kwargs.get('parameter1', self.parameter1)\n",
+    "        parameter2 = kwargs.get('parameter2', self.parameter2)\n",
+    "\n",
+    "        return signal_attenuation\n",
+    "\n",
+    "    def optional_helper_functions(self, params)\n",
+    "        ..."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Blueprint Spherical Distributions"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "class NewSphericalDistribution:\n",
+    "    \n",
+    "    # some default optimization ranges (min and max allowed value), and their scale.\n",
+    "    self._parameter_scales = {'parameter1': value1, 'parameter2': value2}\n",
+    "    self._parameter_ranges = {'parameter1': [start1, end1], 'parameter2': [start2, end2]}\n",
+    "    \n",
+    "    def __init__(self, parameter1=None, parameter2=None):\n",
+    "        \"instantiate your model\"\n",
+    "        self.parameter1 = parameter1\n",
+    "        self.parameter2 = parameter2\n",
+    "    \n",
+    "    def __call__(self, sphere_orientations, **kwargs):\n",
+    "        \"your function call that returns probability density at the given sphere orientations\"\n",
+    "        \n",
+    "        parameter1 = kwargs.get('parameter1', self.parameter1)\n",
+    "        parameter2 = kwargs.get('parameter2', self.parameter2)\n",
+    "\n",
+    "        return probability_density\n",
+    "\n",
+    "    def spherical_harmonics_representation(self, sh_order=some_default, **kwargs):\n",
+    "        \"returns the spherical harmonics representation of the spherical distribution\"\n",
+    "        return distribution_sh_coefficients\n",
+    "        \n",
+    "    def optional_helper_functions(self, params)\n",
+    "        ..."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Blueprint Spatial Distributions"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "class NewSpatialDistribution:\n",
+    "    \n",
+    "    # some default optimization ranges (min and max allowed value), and their scale.\n",
+    "    self._parameter_scales = {'parameter1': value1, 'parameter2': value2}\n",
+    "    self._parameter_ranges = {'parameter1': [start1, end1], 'parameter2': [start2, end2]}\n",
+    "    \n",
+    "    def __init__(self, parameter1=None, parameter2=None):\n",
+    "        \"instantiate your model\"\n",
+    "        self.parameter1 = parameter1\n",
+    "        self.parameter2 = parameter2\n",
+    "    \n",
+    "    def __call__(self, **kwargs):\n",
+    "        \"your function call that returns probability density for some sampling range.\"\n",
+    "        \"Ideally this sampling range is automatically dependent on the input parameters.\"\n",
+    "        \n",
+    "        parameter1 = kwargs.get('parameter1', self.parameter1)\n",
+    "        parameter2 = kwargs.get('parameter2', self.parameter2)\n",
+    "\n",
+    "        return sampled_parameter_points, probability_density_at_those_points\n",
+    "        \n",
+    "    def optional_helper_functions(self, params)\n",
+    "        ..."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Blueprint Optimizers"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "class NewOptimizer:\n",
+    "    # the optimizer should be instantiated using the model, acquisition scheme and possible solver options.\n",
+    "    def __init__(self, model, acquisition_scheme, possible_solver_options):\n",
+    "        self.model = model\n",
+    "        self.acquisition_scheme = acquisition_scheme\n",
+    "        self.possible_solver_options = possible_solver_options\n",
+    "    \n",
+    "    def __call__(self, data, possible_x0_vector):\n",
+    "        \"function call that returns the fitted model parameters.\"\n",
+    "        return fitted_parameter_array\n",
+    "    \n",
+    "    def optional_helper_functions(self, params)\n",
+    "        ..."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 2",
+   "language": "python",
+   "name": "python2"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.14"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}