escher-01.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# What is Escher?\n",
    "\n",
    "Escher is a web-based tool for building, viewing, and sharing visualizations of biological pathways. These 'pathway maps' are a great way to contextualize data about metabolism, including the predictions made with COBRA and Cameo.\n",
    "\n",
    "### Links\n",
    "\n",
    "- Homepage: http://escher.github.io\n",
    "- Documentation: https://escher.readthedocs.org\n",
    "- Publication: https://doi.org/10.1371/journal.pcbi.1004321\n",
    "\n",
    "# Try the Escher application (10 min)\n",
    "\n",
    "Escher is a web application, and you can use it by visiting the [homepage](http://escher.github.io) from any browser.\n",
    "\n",
    "Try it now. Visit the homepage and click Load Map to see an example of an interactive Escher map. Try:\n",
    "\n",
    "- Load the map called \"Central metabolism (iJO1366)\" for _Escherichia coli_\n",
    "- Zoom and pan on the map. Drag the map to pan. Use the + and - buttons on the left to zoom (or the + and - keys).\n",
    "- Search by selecting **Find** from the **View** menu at the top. You can search by reaction, metabolite, or gene.\n",
    "- Save the map as a JSON file in the **Map** menu. This file represents the current Escher map, and you can load it in later.\n",
    "- Save the map as SVG in the **Map** menu. This saves an image of the map that is great for generating figures with application like Adobe Illustrator and Inkscape.\n",
    "\n",
    "In Escher, you can also edit existing pathways, draw new pathways, and save the map in a number of formats. You will find more detail in the [docs](https://escher.readthedocs.org). Try some of these features out if you have time."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Escher for Python (20 min)\n",
    "\n",
    "We also provide a Python package to create Escher visualizations from Python code and embed them in Jupyter notebooks. This is especially useful if you are making predictions or analyzing data in Python, and you want a quick visualization.\n",
    "\n",
    "In this notebook, we'll go through the key features of Escher that can be used to visualize predicted fluxes from COBRA.\n",
    "\n",
    "To get started, import escher, cobra, and cameo."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import escher\n",
    "import cobra\n",
    "import cameo"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Finding maps\n",
    "\n",
    "The maps on the Escher website are also available from Python. You can list them like this."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "escher.list_available_maps()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Launch the builder\n",
    "\n",
    "Use the `Builder` class to create a new Escher map. You can pass a `map_name` from `list_available_maps` for a pre-built map. Then display it in the notebook.\n",
    "\n",
    "This map will let you pan and zoom, but editing features are not enabled."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "b = escher.Builder(map_name='e_coli_core.Core metabolism')\n",
    "b.display_in_notebook()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plot FBA solutions in Escher\n",
    "\n",
    "Flux predictions are easy to plot on the map. Let's first generate a flux vector in COBRApy."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "model = cobra.io.read_sbml_model('data/e_coli_core.xml.gz')\n",
    "solution = model.optimize()\n",
    "print('Growth rate: %.2f' % solution.objective_value)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now these we have a solution, let's visualize it on the map. To improve the visual style, you can adjust many options of the Builder. Some of the most useful ones are:\n",
    "\n",
    "- reaction_scale: Pass a color & size scale as a list of points. You can set points for 'min', 'mean', 'max', 'median', 'Q1', 'Q3', and 'value'. These are the same options available in the Settings menu on the Escher website.\n",
    "- hide_secondary_metabolite: Simplify the map by hiding cofactors.\n",
    "- reaction_styles: Pass an array with any or 'size' to size reactions, 'color' to color them, 'text' to include data in their text labels, and 'abs' to visualize the absolute value of your data\n",
    "\n",
    "Similar settings are available for metabolite data, and they are all described in the [docs](https://escher.readthedocs.io/en/stable/python_api.html)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "b = escher.Builder(map_name='e_coli_core.Core metabolism',\n",
    "                   reaction_data=dict(solution.fluxes),\n",
    "                   # change the default colors\n",
    "                   reaction_scale=[{'type': 'min', 'color': '#cccccc', 'size': 4},\n",
    "                                   {'type': 'value', 'value': 0.1, 'color': '#cccccc', 'size': 8},\n",
    "                                   {'type': 'mean', 'color': '#0000dd', 'size': 20},\n",
    "                                   {'type': 'max', 'color': '#ff0000', 'size': 40}],\n",
    "                   # absolute value and no text for data\n",
    "                   reaction_styles=['size', 'color', 'abs'],\n",
    "                   # only show the primary metabolites\n",
    "                   hide_secondary_metabolites=True)\n",
    "b.display_in_notebook()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "heading_collapsed": true
   },
   "source": [
    "# Escher for experimental data (20min)\n",
    "\n",
    "Escher can be used to visualize any experimental data associated with reactions, metabolites, or genes.\n",
    "\n",
    "Reaction-associated data is loaded just like fluxes. Each data point should have a key that is a reaction ID on the map and a floating point value.\n",
    "\n",
    "## Metabolite data\n",
    "\n",
    "For metabolite data, each point should have a key that is a metabolite ID on the map. Let's look at an existing CSV file of metabolomics data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "hidden": true
   },
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "metabolomics = pd.read_table('data/S4_McCloskey2013_aerobic_metabolomics.csv', sep=',', header=None)\n",
    "metabolomics.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "hidden": true
   },
   "source": [
    "Escher expects a dictionary, so let's make a dictionary out of this data and pass it into a Builder as `metabolite_data`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "hidden": true
   },
   "outputs": [],
   "source": [
    "metabolomics_dict = dict(metabolomics.values)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "hidden": true
   },
   "outputs": [],
   "source": [
    "b = escher.Builder(map_name='e_coli_core.Core metabolism',\n",
    "                   metabolite_data=metabolomics_dict,\n",
    "                   metabolite_scale=[\n",
    "                       {'type': 'min', 'color': 'white', 'size': 10},\n",
    "                       {'type': 'median', 'color': 'green', 'size': 20},\n",
    "                       {'type': 'max', 'color': 'red', 'size': 40},\n",
    "                   ],\n",
    "                   enable_tooltips=False, \n",
    "                  )\n",
    "b.display_in_notebook()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "hidden": true
   },
   "source": [
    "## Gene data & dataset comparison with Escher\n",
    "\n",
    "For metabolite data, each point should have a key that is a gene ID on the map. To see the genes, first load a map with the option `show_gene_reaction_rules=True`.\n",
    "\n",
    "Escher also allows you to load two datasets and visualize a comparison, so we will try that with gene data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "hidden": true
   },
   "outputs": [],
   "source": [
    "b = escher.Builder(map_name='e_coli_core.Core metabolism',\n",
    "                   show_gene_reaction_rules=True,\n",
    "                  )\n",
    "b.display_in_notebook()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "hidden": true
   },
   "source": [
    "You can provide genes by ID (the locus tags show on the map) or by name (you can see these when you hover over a gene).\n",
    "\n",
    "Let's load some example RNA-seq data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "hidden": true
   },
   "outputs": [],
   "source": [
    "rnaseq = pd.read_table('data/S6_RNA-seq_aerobic_to_anaerobic.csv', sep=',', header=0, index_col=0)\n",
    "rnaseq.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "hidden": true
   },
   "source": [
    "Notice that we have two datasets here. For multiple datasets, Escher expects an array of data dictionaries. E.g.:\n",
    "\n",
    "`[ { 'b0001': 4895.5133 ... }, { 'b0001':  8567.3833 ...} ]`\n",
    "\n",
    "We can make that array like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "hidden": true
   },
   "outputs": [],
   "source": [
    "rnaseq_array = [dict(zip(rnaseq.index, x)) for x in rnaseq.values.T]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "hidden": true
   },
   "source": [
    "Let's plot it on the map! Genes are visualized on reactions, so the `reaction_scale` and `reaction_styles` options still work here. We also have new options for `reaction_compare_style` which can be 'fold', 'log2_fold', or 'diff' and define how the two datasets are compared on the map."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "hidden": true
   },
   "outputs": [],
   "source": [
    "b = escher.Builder(map_name='e_coli_core.Core metabolism',\n",
    "                   gene_data=rnaseq_array,\n",
    "                   reaction_compare_style='log2_fold',\n",
    "                   # change the default colors\n",
    "                   reaction_scale=[{'type': 'min', 'color': 'green', 'size': 25},\n",
    "                                   {'type': 'value', 'value': 0, 'color': '#cccccc', 'size': 8},\n",
    "                                   {'type': 'max', 'color': 'red', 'size': 25}],\n",
    "                   # absolute value and no text for data\n",
    "                   reaction_styles=['size', 'color', 'text'],\n",
    "                   # only show the primary metabolites\n",
    "                   hide_secondary_metabolites=True)\n",
    "b.display_in_notebook()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "hidden": true
   },
   "source": [
    "Right away, we can see that genes activated in anaerobic conditions (e.g. fermentation pathways) are red, and genes activated in aerobic conditions (e.g. TCA cycle) are green."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Editing maps and loading custom maps in Escher (10min)\n",
    "\n",
    "Escher lets you build your own maps for any model. The Jupyter notebook is not a great environment for interactiving heavily with the maps, so editing is easier on the website. All you need is a JSON file for your COBRA model to serve as the source of content for your new map. You can also build new maps with the models already available on the Escher website, or you can edit existing maps to fit your needs.\n",
    "\n",
    "There are some more tips on this page in the documentation: \n",
    "\n",
    "https://escher.readthedocs.io/en/stable/contribute_maps.html\n",
    "\n",
    "\n",
    "Once you have a custom map, you can visualized it in the Escher Python package by passing a filename to `map_json`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# pass the model to a new builder\n",
    "b = escher.Builder(map_json='data/custom_map.json')\n",
    "b.display_in_notebook()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To make the file accessible to Escher, go to the Jupyter file manager and use the Upload button to add your custom map to the data folder. Then try visualizing it here in Escher:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "b = escher.Builder(map_json='data/CHANGE_ME.json')\n",
    "b.display_in_notebook()"
   ]
  }
 ],
 "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.6.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}