new-api.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Emperor's Python API\n",
    "\n",
    "**This notebook demonstrate Emperor's new Python API, which can and will change as we continue to exercise this interface, for more information, have a look at the [pull request here](https://github.com/biocore/emperor/pull/453).**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import pandas as pd, numpy as np\n",
    "from emperor import Emperor\n",
    "from skbio.stats.ordination import OrdinationResults\n",
    "\n",
    "\n",
    "from emperor.util import nbinstall"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "nbinstall()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ordination plots are almost invariantly associated with a set of data, that\n",
    "    relates each sample to its scientific context, we refer to this as the\n",
    "    *sample metadata*, and represent it using Pandas `DataFrame`s. For this\n",
    "    example we will need some metadata, we start by creating our metadata\n",
    "    object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "data = [['PC.354', 'Control', '20061218', 'Control_mouse_I.D._354'],\n",
    "['PC.355', 'Control', '20061218', 'Control_mouse_I.D._355'],\n",
    "['PC.356', 'Control', '20061126', 'Control_mouse_I.D._356'],\n",
    "['PC.481', 'Control', '20070314', 'Control_mouse_I.D._481'],\n",
    "['PC.593', 'Control', '20071210', 'Control_mouse_I.D._593'],\n",
    "['PC.607', 'Fast', '20071112', 'Fasting_mouse_I.D._607'],\n",
    "['PC.634', 'Fast', '20080116', 'Fasting_mouse_I.D._634'],\n",
    "['PC.635', 'Fast', '20080116', 'Fasting_mouse_I.D._635'],\n",
    "['PC.636', 'Fast', '20080116', 'Fasting_mouse_I.D._636']]\n",
    "columns = ['SampleID', 'Treatment', 'DOB', 'Description']\n",
    "mf = pd.DataFrame(columns=columns, data=data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before we can use this mapping file in Emperor, we should set the index\n",
    "    to be `SampleID`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "mf.set_index('SampleID', inplace=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then let's create some artificial ordination data, and encapsulate it in an `OrdinationResults` object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "eigvals = np.array([0.47941212, 0.29201496, 0.24744925,\n",
    "                    0.20149607, 0.18007613, 0.14780677,\n",
    "                    0.13579593, 0.1122597, 0.])\n",
    "n = eigvals.shape[0]\n",
    "site = np.random.randn(n, n)\n",
    "site_ids = ('PC.636', 'PC.635', 'PC.356', 'PC.481', 'PC.354', 'PC.593',\n",
    "            'PC.355', 'PC.607', 'PC.634')\n",
    "p_explained = np.array([0.26688705, 0.1625637, 0.13775413, 0.11217216,\n",
    "                     0.10024775, 0.08228351, 0.07559712, 0.06249458,\n",
    "                     0.])\n",
    "ores = OrdinationResults(eigvals, site=site, site_ids=site_ids,\n",
    "                         proportion_explained=p_explained)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally import the Emperor object and display it using Jupyter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# change the remote parameter to False/True depending on what you want to do\n",
    "x = Emperor(ores, mf, remote=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "x"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}