python/examples/example_petab/petab.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using PEtab\n",
    "\n",
    "This notebook illustrates how to run model simulations based on [PEtab](https://github.com/petab-dev/petab) problems with AMICI.\n",
    "\n",
    "PEtab is a format for specifying parameter estimation problems in systems biology. It is based on [SBML](http://sbml.org/) and [TSV](https://en.wikipedia.org/wiki/Tab-separated_values) files. (AMICI also supports PySB-based PEtab problems, that will be covered by PEtab v2). The Python package [pyPESTO](https://pypesto.readthedocs.io/) provides a convenient interface for parameter estimation with PEtab problems and uses AMICI as a backend. However, AMICI can also be used directly to simulate PEtab problems. This is illustrated in this notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import petab\n",
    "\n",
    "from amici import runAmiciSimulation\n",
    "from amici.petab.petab_import import import_petab_problem\n",
    "from amici.petab.petab_problem import PetabProblem\n",
    "from amici.petab.simulations import simulate_petab\n",
    "from amici.plotting import plot_state_trajectories"
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Importing a PEtab problem"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We use the [Boehm_JProteomeRes2014](https://github.com/Benchmarking-Initiative/Benchmark-Models-PEtab/tree/master/Benchmark-Models/Boehm_JProteomeRes2014) example model from the [benchmark collection](https://github.com/Benchmarking-Initiative/Benchmark-Models-PEtab):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_name = \"Boehm_JProteomeRes2014\"\n",
    "# local path or URL to the yaml file for the PEtab problem\n",
    "petab_yaml = f\"https://github.com/Benchmarking-Initiative/Benchmark-Models-PEtab/master/Benchmark-Models/{model_name}/{model_name}.yaml\"\n",
    "# load the problem using the PEtab library\n",
    "petab_problem = petab.Problem.from_yaml(petab_yaml)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "Next, we import the model to amici using `import_petab_problem`. `import_petab_problem` has many options to choose between faster importer or more flexible or faster model simulations. We import the model with default settings, and we obtain an AMICI model instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "amici_model = import_petab_problem(petab_problem, verbose=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That's it. Now, we can use the model to perform simulations.\n",
    "\n",
    "## Simulating a PEtab problem\n",
    "\n",
    "For simple simulations, a function `simulate_petab` is available. This function will simulate the model for all conditions specified in the PEtab problem and compute the objective value (and if requested, the gradient). `simulate_petab` is mostly useful for running individual simulations. If large numbers of model simulations are required, there are more efficient means. In particular, for parameter estimation, consider using the optimized objective function provided by [pyPESTO](https://github.com/icb-dcm/pypesto).\n",
    "\n",
    "We use the `simulate_petab` function to simulate the model at the nominal parameters (i.e., the parameters specified in the PEtab problem in the `nominalValue` column of the parameter table):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "simulate_petab(petab_problem, amici_model)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " Parameters can also be directly specified, both scaled and unscaled:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "parameters = {\n",
    "    x_id: x_val\n",
    "    for x_id, x_val in zip(petab_problem.x_ids, petab_problem.x_nominal_scaled)\n",
    "    # Fixed parameters cannot be changed in `simulate_petab`, unless we explicitly pass\n",
    "    #  a `parameter_mapping` that was generated with `fill_fixed_parameters=False`\n",
    "    if x_id not in amici_model.getFixedParameterIds()\n",
    "}\n",
    "simulate_petab(\n",
    "    petab_problem,\n",
    "    amici_model,\n",
    "    problem_parameters=parameters,\n",
    "    scaled_parameters=True,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Working with PEtab-defined simulation conditions\n",
    "\n",
    "`simulate_petab` is convenient for quickly simulating PEtab-based problems, but for certain applications it may be too inflexible.\n",
    "For example, it is not easily possible to obtain model outputs for time points other than the measurement timepoints specified in the PEtab problem. In such a case, the `PetabProblem` class can be used to easily generate AMICI `ExpData` objects representing PEtab-defined simulation conditions:"
   ]
  },
  {
   "cell_type": "code",
   "outputs": [],
   "source": [
    "app = PetabProblem(petab_problem)\n",
    "\n",
    "# ExpData for all conditions:\n",
    "app.get_edatas()\n",
    "\n",
    "# ExpData for a single condition:\n",
    "edata = app.get_edata(\"model1_data1\")"
   ],
   "metadata": {
    "collapsed": false
   },
   "execution_count": null
  },
  {
   "cell_type": "code",
   "outputs": [],
   "source": [
    "rdata = runAmiciSimulation(amici_model, solver=amici_model.getSolver(), edata=edata)\n",
    "rdata"
   ],
   "metadata": {
    "collapsed": false
   },
   "execution_count": null
  },
  {
   "cell_type": "code",
   "outputs": [],
   "source": [
    "plot_state_trajectories(rdata)"
   ],
   "metadata": {
    "collapsed": false
   },
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "source": [
    "For further information, check out the [AMICI documentation](https://amici.readthedocs.io/en/latest/)."
   ],
   "metadata": {
    "collapsed": false
   }
  }
 ],
 "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.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}