Merge pull request #13 from biosustain/options_docs

Describes how to modify options through the INCAWrapper in the docs.

docs/index.rst

@@ -38,6 +38,7 @@ Overview of the documentation
    multiple_experiments
    monte_carlo_sampling
    incawrapper_and_the_incagui
+   options
    Low_level_api
    examples/index
    developer/index

docs/options.ipynb

@@ -0,0 +1,123 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Controlling INCA option/settings\n",
+    "INCA enables control over some parameters when running analysis, such as the number of restarts during flux estimation or turning on/off INCAs natural abundance adjustment. In the GUI these are adjusted in the \"Options\" menu. Each parameter is described in depth in the INCA manual (See section 4.1 Menu functions in the [INCA manual](https://mfa.vueinnovations.com/sites/default/files/public/d23/n3969/INCAhelp.pdf)).\n",
+    "\n",
+    "The INCAWrapper also allow users to modify the options. This can be done through the `define_options()` function. This function takes any number of keyword arguments, where the keyword has to match a valid INCA option variable. The exact names of the option variables and their default values can be found in the INCA documentation, which is located in your INCA distribution. You can find this in `<your-inca-folder>/doc/inca/class/@option/option.html` on your local computer if you have INCA installed. A few examples of commonly used options are:\n",
+    "- `fit_starts` the number of restarts of the flux estimation algorithm, default 1.\n",
+    "- `sim_na` adjust for natural abundance in labelled atoms, default true.\n",
+    "- `sim_more` adjust for natural abundance in unlabelled atoms, default true \n",
+    "- `sim_ss` simulate only steady state isotopomer distributions (i.e. NOT INST-MFA), default true.\n",
+    "\n",
+    "The INCAWrapper leaves all options that are not modified at their default value. \n",
+    "\n",
+    "\n",
+    "In most of the tutorials in this documentation we will modify one or more option(s), please refer to the other tutorials for how to use the `define_options()` function in a realistic setting. However, here we will do a very quick demonstration.\n",
+    "\n",
+    "First, we load the incawrapper package."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import incawrapper"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now, we create a new `INCAScript`, change all the options described above and add the changes to the options block in the `INCAScript`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "clear functions\n",
+      "\n",
+      "% REACTION BLOCK\n",
+      "\n",
+      "\n",
+      "% TRACERS BLOCK\n",
+      "\n",
+      "\n",
+      "% FLUXES BLOCK\n",
+      "\n",
+      "\n",
+      "% MS_FRAGMENTS BLOCK\n",
+      "\n",
+      "\n",
+      "% POOL_SIZES BLOCK\n",
+      "\n",
+      "\n",
+      "% EXPERIMENTAL_DATA BLOCK\n",
+      "\n",
+      "\n",
+      "% MODEL BLOCK\n",
+      "\n",
+      "\n",
+      "% MODEL MODIFICATIONS BLOCK\n",
+      "\n",
+      "\n",
+      "% OPTIONS BLOCK\n",
+      "m.options = option('fits_starts', 100, 'sim_na', false, 'sim_more', false, 'sim_ss', false)\n",
+      "\n",
+      "mod2stoich(m); % make sure the fluxes are feasible\n",
+      "\n",
+      "% RUNNER BLOCK\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "script = incawrapper.INCAScript() # Create a new script\n",
+    "script.add_to_block(\n",
+    "    \"options\",\n",
+    "    incawrapper.define_options(fits_starts=100, sim_na=False, sim_more=False, sim_ss=False)\n",
+    ")\n",
+    "print(script)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The above `INCAScript` cannot run because it does not hold any model, but we can see how the options are modified in the script."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "incawrapper-dev",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}