{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "4945095f",
   "metadata": {},
   "source": [
    "## Parameter Scans\n",
    "This notebook demonstrates how to edit / change parameter scan tasks. While most scans can be done using basico, by using simple loops, here we create the scans for the COPASI `Parameter Scan` task. That means, that these scans can be carried out later, using the COPASI graphical user interface, or the command line interface. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "c6259da2",
   "metadata": {},
   "outputs": [],
   "source": [
    "from basico import *"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf2919b6",
   "metadata": {},
   "source": [
    "lets start by using the brusselator example, where a scan task is already set up. Using `get_scan_settings`, we can see all the individual settings: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "5d8f7e9a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'update_model': False,\n",
       " 'scheduled': False,\n",
       " 'subtask': 'Steady-State',\n",
       " 'output_during_subtask': False,\n",
       " 'continue_from_current_state': False,\n",
       " 'continue_on_error': False,\n",
       " 'scan_items': [{'type': 'scan',\n",
       "   'num_steps': 10,\n",
       "   'log': False,\n",
       "   'min': 0.5,\n",
       "   'max': 2.0,\n",
       "   'values': '',\n",
       "   'use_values': False,\n",
       "   'item': '(R1).k1',\n",
       "   'cn': 'CN=Root,Model=The Brusselator,Vector=Reactions[R1],ParameterGroup=Parameters,Parameter=k1,Reference=Value'}]}"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "load_example('brusselator')\n",
    "get_scan_settings()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6aba7859",
   "metadata": {},
   "source": [
    "the dictionary that is returned, contains all the information stored in the COPASI file. Altenatively you could also just retrieve the scan items using `get_scan_items`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "e52a693e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'type': 'scan',\n",
       "  'num_steps': 10,\n",
       "  'log': False,\n",
       "  'min': 0.5,\n",
       "  'max': 2.0,\n",
       "  'values': '',\n",
       "  'use_values': False,\n",
       "  'item': '(R1).k1',\n",
       "  'cn': 'CN=Root,Model=The Brusselator,Vector=Reactions[R1],ParameterGroup=Parameters,Parameter=k1,Reference=Value'}]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_scan_items()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "21011a5e",
   "metadata": {},
   "source": [
    "### Modifying Scan Settings\n",
    "Analogue to retrieving the settings, they can be set as well, using the same keys, as displayed above. Again, you can change all settings using `set_scan_settings`. Or just change the scan_items using `set_scan_items`. If the scan settings dictionary contain a `scan_items` element, or if `set_scan_items` is called, then all scan items are replaced with the ones given. Alternatively `add_scan_item` can be used to add one or more scan items directly. \n",
    "\n",
    "Lets change the scan item from above, so that the `(R1).k1` parameter is changed to the specific values of 0.5, 1.0 and 2.0: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "79ea7c68",
   "metadata": {},
   "outputs": [],
   "source": [
    "set_scan_items([{'item': '(R1).k1', 'values': [0.5, 1.0, 2]}])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "6cff7d48",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'type': 'scan',\n",
       "  'num_steps': 0,\n",
       "  'log': False,\n",
       "  'min': 0.0,\n",
       "  'max': 1.0,\n",
       "  'values': [0.5, 1.0, 2.0],\n",
       "  'use_values': True,\n",
       "  'item': '(R1).k1',\n",
       "  'cn': 'CN=Root,Model=The Brusselator,Vector=Reactions[R1],ParameterGroup=Parameters,Parameter=k1'}]"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_scan_items()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6f7af49b",
   "metadata": {},
   "source": [
    "scan items can be specified, either through their display name by specifying the `item` key, or by specifying the `cn` directly. \n",
    "\n",
    "The scan item can be of one of three types: \n",
    "\n",
    "* `scan`: this is the default (so will be used if not specifie), here a model element is varied either through values, or between a specified  `min` and `max` value\n",
    "* `repeat`: here the subtask is repeated `num_steps` times\n",
    "* `random`: here the value for the specified model element is sampled from the specified `distribution` (which can be `uniform`, `normal`, `poisson` or `gamma`)\n",
    "\n",
    "For example to specify a repeat you'd use: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "1d9ccb81",
   "metadata": {},
   "outputs": [],
   "source": [
    "add_scan_item(type='repeat', num_steps=10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "65a59ad1",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'type': 'scan',\n",
       "  'num_steps': 0,\n",
       "  'log': False,\n",
       "  'min': 0.0,\n",
       "  'max': 1.0,\n",
       "  'values': [0.5, 1.0, 2.0],\n",
       "  'use_values': True,\n",
       "  'item': '(R1).k1',\n",
       "  'cn': 'CN=Root,Model=The Brusselator,Vector=Reactions[R1],ParameterGroup=Parameters,Parameter=k1'},\n",
       " {'type': 'repeat', 'num_steps': 10, 'log': None, 'min': None, 'max': None}]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_scan_items()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fca3dee0",
   "metadata": {},
   "source": [
    "as you can see, by using `add_scan_items`, the repeat item is added at the end of the scan list. In COPASI, when multiple scan items are defined, the semantics of those is that for each value of scan item 1, all values of scan item 2 are processed. \n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3c2e0912",
   "metadata": {},
   "source": [
    "For scan items of type `distribution`, the min/max element take up different meaning: \n",
    "\n",
    "* `uniform`: here the value is between the min and max value\n",
    "* `normal`: min=`mean` and max=`standard deviation`\n",
    "* `poisson`: min=`mean` and max has no meaning\n",
    "* `gamma`: min=`shape` and max=`scale`\n",
    "\n",
    "As a last example, lets change it to sample the initial concentration of species `A` from a normal distribution between around 2, and we want to do that 5 times: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "9105d569",
   "metadata": {},
   "outputs": [],
   "source": [
    "set_scan_items([\n",
    "    {\n",
    "        'type': 'repeat',\n",
    "        'num_steps': 5\n",
    "    }, \n",
    "    {\n",
    "        'item': '[A]_0', \n",
    "        'type':'random', \n",
    "        'distribution': 'normal',\n",
    "        'min': 2, \n",
    "        'max': 0.1\n",
    "    }])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "16f7749f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'type': 'repeat', 'num_steps': 5, 'log': None, 'min': None, 'max': None},\n",
       " {'type': 'random',\n",
       "  'num_steps': 0,\n",
       "  'log': False,\n",
       "  'min': 2.0,\n",
       "  'max': 0.1,\n",
       "  'distribution': 'normal',\n",
       "  'item': '[A]_0',\n",
       "  'cn': 'CN=Root,Model=The Brusselator,Vector=Compartments[compartment],Vector=Metabolites[A],Reference=InitialConcentration'}]"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_scan_items()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c29bdfec",
   "metadata": {},
   "source": [
    "### Running a scan:\n",
    "You can run these scans in basico using the `run_scan` method. Where you can optionally pass along a `settings` parameter to reconfigure the scan, or an `output` selection, to grab some data directly. \n",
    "\n",
    "So lets run the configured scan task, changing it to run a the steady state task, collecting the final concentrations of `X` and `Y`: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "0f65239f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>[A]_0</th>\n",
       "      <th>[X]</th>\n",
       "      <th>[Y]</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>2.041315</td>\n",
       "      <td>2.041315</td>\n",
       "      <td>1.469639</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1.925778</td>\n",
       "      <td>1.925778</td>\n",
       "      <td>1.557810</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>2.116724</td>\n",
       "      <td>2.116724</td>\n",
       "      <td>1.417283</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>2.088708</td>\n",
       "      <td>2.088708</td>\n",
       "      <td>1.436292</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>1.950328</td>\n",
       "      <td>1.950328</td>\n",
       "      <td>1.538201</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "      [A]_0       [X]       [Y]\n",
       "0  2.041315  2.041315  1.469639\n",
       "1  1.925778  1.925778  1.557810\n",
       "2  2.116724  2.116724  1.417283\n",
       "3  2.088708  2.088708  1.436292\n",
       "4  1.950328  1.950328  1.538201"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "run_scan(settings={'subtask': T.STEADY_STATE}, output=['[A]_0', '[X]', '[Y]'])"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}