doc/examples/Lotka_Volterra/Lotka_Volterra_Model_Editor/Lotka_Volterra_Model_Editor.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Model Editor\n",
    "\n",
    "This notebook demonstrates functionality of the `yaml2sbml` model editor using the Lotka Volterra equations as an example. The \"Lotka-Volterra\" equations are given by \n",
    "\n",
    "\\begin{align*}\n",
    "\\frac{d}{dt} x_1 &= \\alpha x_1 - \\beta x_1x_2, \\\\\n",
    "\\frac{d}{dt} x_2 &= \\delta x_1x_2 - \\gamma x_2.\n",
    "\\end{align*}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## ODE model\n",
    "\n",
    "We first generate a basic model, that only contains all necessary information for generating an SBML file for model simulation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from yaml2sbml import YamlModel\n",
    "\n",
    "# generate model\n",
    "model = YamlModel()\n",
    "\n",
    "# add ODEs\n",
    "model.add_ode(state_id='x_1', \n",
    "              right_hand_side='alpha*x_1 - beta*x_1*x_2', \n",
    "              initial_value=2)\n",
    "model.add_ode(state_id='x_2', \n",
    "              right_hand_side='delta*x_1*x_2 - gamma*x_2', \n",
    "              initial_value=2)\n",
    "\n",
    "# add parameters\n",
    "model.add_parameter(parameter_id='alpha', nominal_value=2)\n",
    "model.add_parameter(parameter_id='beta', nominal_value=4)\n",
    "model.add_parameter(parameter_id='gamma', nominal_value=3)\n",
    "model.add_parameter(parameter_id='delta', nominal_value=3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`yaml2sbml` can export the `model` object either to YAML or to SBML directly, via  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# write to YAML\n",
    "model.write_to_yaml('Lotka_Volterra_basic.yaml', overwrite=True)\n",
    "\n",
    "# write to SBML\n",
    "model.write_to_sbml('Lotka_Volterra_basic.xml', overwrite=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are further functions to: \n",
    "* get all `parameter_id`s via `model.get_parameter_ids()` \n",
    "* get a parameter by its id (`model.get_parameter_by_id('alpha')`) \n",
    "* delete a parameter by its id (`model.delete_parameter('alpha')`)\n",
    "\n",
    "Similar functions also exist for the other model components."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Parameter Estimation Problem\n",
    "\n",
    "Now we want to extend the current `model` to include all the necessary information for parameter estimation in PEtab. Therefore we load the model from the `.yaml` file and modify the parameters, such that it also contains all information that is going to be written into the PEtab parameter table."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "model = YamlModel.load_from_yaml('Lotka_Volterra_basic.yaml')\n",
    "\n",
    "# extend parameters \n",
    "model.add_parameter(parameter_id='alpha',\n",
    "                    nominal_value=2,\n",
    "                    parameter_scale='log10',\n",
    "                    lower_bound=0.1,\n",
    "                    upper_bound=10,\n",
    "                    estimate=1, \n",
    "                    overwrite=True)\n",
    "\n",
    "model.add_parameter(parameter_id='beta',\n",
    "                    nominal_value=4,\n",
    "                    parameter_scale='log10',\n",
    "                    lower_bound=0.1,\n",
    "                    upper_bound=10,\n",
    "                    estimate=1, \n",
    "                    overwrite=True)\n",
    "\n",
    "model.add_parameter(parameter_id='gamma',\n",
    "                    nominal_value=3,\n",
    "                    parameter_scale='log10',\n",
    "                    lower_bound=0.1,\n",
    "                    upper_bound=10,\n",
    "                    estimate=1,\n",
    "                    overwrite=True)\n",
    "\n",
    "model.add_parameter(parameter_id='delta',\n",
    "                    nominal_value=3,\n",
    "                    parameter_scale='log10',\n",
    "                    lower_bound=0.1,\n",
    "                    upper_bound=10,\n",
    "                    estimate=1,\n",
    "                    overwrite=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A parameter fitting problem in PEtab allows for the specification of observables and experimental conditions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "# specify an observable:\n",
    "model.add_observable(observable_id='prey_measured', \n",
    "                     observable_formula='log10(x_1)',\n",
    "                     noise_formula='noiseParameter1_prey_measured', \n",
    "                     noise_distribution='normal',\n",
    "                     observable_transformation='lin')\n",
    "\n",
    "# specify trivial condition\n",
    "model.add_condition(condition_id='condition1', \n",
    "                    condition_dict={})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The modified model can either be exported to YAML or PEtab via"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "# write to YAML\n",
    "model.write_to_yaml('Lotka_Volterra_PEtab.yaml', overwrite=True)\n",
    "\n",
    "# write to PEtab\n",
    "model.write_to_petab(output_dir='./Lotka_Volterra_PEtab',\n",
    "                     model_name='Lotka_Volterra',\n",
    "                     petab_yaml_name='Lotka_Volterra_problem', \n",
    "                     measurement_table_name='measurement.tsv')"
   ]
  }
 ],
 "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.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}