Create wrapper_usage_example.ipynb

doc/wrapper_usage_example.ipynb

@@ -0,0 +1,165 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "# Organisation of code submissions and standardisation to a common interface\n",
+    "\n",
+    "## General structure\n",
+    "Code submissions are located in the src/original folder, where submissions are named as `<initials>_<institution>`. Due to code submissions having different authors, it is expected that they all vary in their usage, inputs, and outputs. In order to facilitate testing in a larger scale, a common interface has been created in the form of the `OsipiBase` class (src/wrappers). This class acts as a parent class for standardised versions of the different code submissions. Together, they create the common interface of function calls and function outputs that allows us to perform mass testing, but also creates easy usage.\n",
+    "\n",
+    "The src/standardized folder contains the standardised version of each code submission. Here, a class is created following a naming convention (`<initials>_<institution>_<algorithm name>`), with `__init__()` and `ivim_fit()` methods that integrate well with the OsipiBase class. The idea is that every submitted fitting algorithm should be initialised in the same way, and executed in the same way.\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "## The standardized versions\n",
+    "The standardised versions of each submission is a class that contains two methods. These classes inherit the functionalities of `OsipiBase`.\n",
+    "\n",
+    "### `__init__()`\n",
+    "The `__init__()` method ensures that the algorithm is initiated correctly in accordance with OsipiBase. Custom code is to be inserted below the `super()` call. This method should contain any of the neccessary steps for the following `ivim_fit()` method to only require signals and b-values as input.\n",
+    "\n",
+    "Below is an example from src/standardized/IAR_LU_biexp.py"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "def __init__(self, bvalues=None, thresholds=None, bounds=None, initial_guess=None, weighting=None, stats=False):\n",
+    "    \"\"\"\n",
+    "        Everything this algorithm requires should be implemented here.\n",
+    "        Number of segmentation thresholds, bounds, etc.\n",
+    "            \n",
+    "        Our OsipiBase object could contain functions that compare the inputs with\n",
+    "        the requirements.\n",
+    "    \"\"\"\n",
+    "    super(IAR_LU_biexp, self).__init__(bvalues, thresholds, bounds, initial_guess) ######## On this line, change \"IAR_LU_biexp\" to the name of the class\n",
+    "\n",
+    "    ######## Your code below #########\n",
+    "        \n",
+    "    # Check the inputs\n",
+    "        \n",
+    "    # Initialize the algorithm\n",
+    "    if self.bvalues is not None:\n",
+    "        bvec = np.zeros((self.bvalues.size, 3))\n",
+    "        bvec[:,2] = 1\n",
+    "        gtab = gradient_table(self.bvalues, bvec, b0_threshold=0)\n",
+    "            \n",
+    "        self.IAR_algorithm = IvimModelBiExp(gtab)\n",
+    "    else:\n",
+    "        self.IAR_algorithm = None"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "### `ivim_fit()`\n",
+    "The purpose of this method is to take a singe voxel signal and b-values as input, and return IVIM parameters as output. This is where most of the custom code will go that is related to each individual code submission. The idea here is to have calls to submitted functions in the src/originals folder. This ensures that the original code is not tampered with. However if required, the original code could be just pasted in here as well.\n",
+    "\n",
+    "Below is an example from src/standardized/IAR_LU_biexp.py"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "\n",
+    "def ivim_fit(self, signals, bvalues, **kwargs):\n",
+    "    \"\"\"Perform the IVIM fit\n",
+    "\n",
+    "    Args:\n",
+    "        signals (array-like)\n",
+    "        bvalues (array-like, optional): b-values for the signals. If None, self.bvalues will be used. Default is None.\n",
+    "\n",
+    "    Returns:\n",
+    "        _type_: _description_\n",
+    "    \"\"\"\n",
+    "        \n",
+    "    if self.IAR_algorithm is None:\n",
+    "        if bvalues is None:\n",
+    "            bvalues = self.bvalues\n",
+    "        else:\n",
+    "            bvalues = np.asarray(bvalues)\n",
+    "            \n",
+    "        bvec = np.zeros((bvalues.size, 3))\n",
+    "        bvec[:,2] = 1\n",
+    "        gtab = gradient_table(bvalues, bvec, b0_threshold=0)\n",
+    "            \n",
+    "        self.IAR_algorithm = IvimModelBiExp(gtab)\n",
+    "            \n",
+    "    fit_results = self.IAR_algorithm.fit(signals)\n",
+    "        \n",
+    "    results = {}\n",
+    "    results[\"f\"] = fit_results.model_params[1]\n",
+    "    results[\"D*\"] = fit_results.model_params[2]\n",
+    "    results[\"D\"] = fit_results.model_params[3]\n",
+    "        \n",
+    "    return results"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "## The `OsipiBase` class\n",
+    "The usage of the OsipiBase class mainly consists of running the osipi_fit() method. In this method, the inputs from `__init__()` of the standardised version of a code submission, and the signals and b-values input to `osipi_fit()` is processed and fed into the `ivim_fit()` function.\n",
+    "\n",
+    "It is the `osipi_fit()` method that provides the common interface for model fitting. As one may note, `ivim_fit()` takes a single voxel as input. `OsipiBase.osipi_fit()` supports multidimensional inputs, which is then iteratively fed into `ivim_fit()`, and returns a corresponding output. Support for future types of input will be implemented here. This ensures that the `ivim_fit()` method can be written as simply as possible, which simplifies the inclusion of new code submissions into the standard interface.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "## Example usage of standardized version of an algorithm\n",
+    "### Using the standardized version directly\n",
+    "The standardised versions can be used directly by\n",
+    "1. Importing the class\n",
+    "2. Initialising the object with the required parameters, e.g. `IAR_LU_biexp(bounds=[(0, 1), (0.005, 0.1), (0, 0.004)])`\n",
+    "3. Call `osipi_fit(signals, bvalues)` for model fitting\n",
+    "\n",
+    "### Using the `OsipiBase` class with algorithm names\n",
+    "Standardised versions can also be initiated using the OsipiBase.osipi_initiate_algorithm() method.\n",
+    "\n",
+    "1. Import `OsipiBase`\n",
+    "2. Initiate `OsipiBase` with the algorithm keyword set to the standardised name of the desired algorithm e.g., `OsipiBase(algorithm=IAR_LU_biexp)`\n",
+    "3. Call `osipi_fit()` for model fitting"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}