revbayes_magic_demo.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### jupyter magic commands\n",
    "Jupyter provides a number of magic commands, allowing you to integrate external functions and methods that are not natively found in RevBayes into your RevBayes workflow.\n",
    "\n",
    "To list the magic commands available in Jupyter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Available line magics:\n",
      "%activity  %cd  %connect_info  %conversation  %dot  %download  %edit  %get  %help  %html  %include  %install  %install_magic  %javascript  %jigsaw  %kernel  %kx  %latex  %load  %ls  %lsmagic  %macro  %magic  %matplotlib  %parallel  %plot  %pmap  %px  %python  %reload_magics  %restart  %run  %scheme  %set  %shell\n",
      "\n",
      "Available cell magics:\n",
      "%%activity  %%brain  %%conversation  %%debug  %%dot  %%file  %%help  %%html  %%javascript  %%kx  %%latex  %%macro  %%pipe  %%processing  %%px  %%python  %%scheme  %%shell  %%show  %%time  %%tutor\n"
     ]
    }
   ],
   "source": [
    "%lsmagic"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Simulate a tree in `RevBayes`\n",
    "Suppose we simulate and save a `Tree` object to file using `writeNexus` in RevBayes. We can then open that tree file from within the same Juptyer notebook using the `%python` magic command.\n",
    "\n",
    "First, create and save the `Tree` object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "n_taxa = 10\n",
    "for (i in 1:n_taxa) {\n",
    "    taxa[i] = taxon(\"T\"+i, 0.0)\n",
    "}\n",
    "phy ~ dnBDP(lambda=1, rootAge=1, taxa=taxa)\n",
    "writeNexus(data=phy, filename=\"example/output/magic_test.tre\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Open output in `tracer`\n",
    "Let's view the tree in [FigTree](http://tree.bio.ed.ac.uk/software/figtree/). Launch terminal commands using the magic function `%shell`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%shell figtree example/output/magic_test.tre"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Of course, this example relies on `figtree` existing in the user's environment `PATH` variable."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Executing `python` code\n",
    "Use `%%python` to indicate the next cell conatins python commands"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Dendropy\n",
      "                                                                                               /----------------------- T1 \n",
      "                                                                       /-----------------------+                           \n",
      "                                                                       |                       \\----------------------- T10\n",
      "                                               /-----------------------+                                                   \n",
      "                                               |                       |                       /----------------------- T3 \n",
      "/----------------------------------------------+                       \\-----------------------+                           \n",
      "|                                              |                                               \\----------------------- T9 \n",
      "|                                              |                                                                           \n",
      "|                                              \\----------------------------------------------------------------------- T6 \n",
      "|                                                                                                                          \n",
      "+                                              /----------------------------------------------------------------------- T5 \n",
      "|                                              |                                                                           \n",
      "|                      /-----------------------+                                               /----------------------- T8 \n",
      "|                      |                       |                       /-----------------------+                           \n",
      "|                      |                       \\-----------------------+                       \\----------------------- T7 \n",
      "\\----------------------+                                               |                                                   \n",
      "                       |                                               \\----------------------------------------------- T4 \n",
      "                       |                                                                                                   \n",
      "                       \\----------------------------------------------------------------------------------------------- T2 \n",
      "                                                                                                                           \n",
      "                                                                                                                           \n"
     ]
    }
   ],
   "source": [
    "%%python\n",
    "\n",
    "# python packages\n",
    "import dendropy\n",
    "from Bio import Phylo\n",
    "\n",
    "# the tree's filename\n",
    "phy_fn = 'example/output/magic_test.tre'\n",
    "\n",
    "# visualize a tree in Dendropy\n",
    "dtree = dendropy.Tree.get(path=phy_fn,schema='nexus')\n",
    "print('Dendropy\\n'+dtree.as_ascii_plot())\n",
    "\n",
    "# visualize a tree in Biopython\n",
    "bptree = Phylo.read(phy_fn, 'nexus')\n",
    "Phylo.draw(bptree)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This draws the tree in a pyplot window.\n",
    "Full-featured kernels enable inline figure presentation through the magic command \"`%matplotlib inline`\".\n",
    "Unfortunately, this is not currently supported in metakernel ([link](https://groups.google.com/forum/#!msg/jupyter/A6uw-Pp5fE0/udnhbhS_AgAJ)).\n",
    "I've made no progress so far on a workaround."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Executing `R` code through `rpy2`\n",
    "`R` does not natively support magic commands.\n",
    "However, we can the package `rpy2` to execute `R` commands through the `%%python` environment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ape tree as rpy2 object:\n",
      "\n",
      "Phylogenetic tree with 10 tips and 9 internal nodes.\n",
      "\n",
      "Tip labels:\n",
      "\tT1, T10, T3, T9, T6, T5, ...\n",
      "\n",
      "Rooted; includes branch lengths.\n",
      "\n",
      "Tip labels as rpy2 object:\n",
      " [1] \"T1\"  \"T10\" \"T3\"  \"T9\"  \"T6\"  \"T5\"  \"T8\"  \"T7\"  \"T4\"  \"T2\" \n",
      "\n"
     ]
    }
   ],
   "source": [
    "%%python\n",
    "\n",
    "# python packages\n",
    "from rpy2.robjects import r\n",
    "import dendropy\n",
    "\n",
    "# read tree into dendropy\n",
    "phy_fn = 'example/output/magic_test.tre'\n",
    "dtree = dendropy.Tree.get(path=phy_fn,schema='nexus')\n",
    "\n",
    "# extract Newick string from file\n",
    "phy_str = dtree.as_string(\"newick\")\n",
    "\n",
    "# parse Newick string in R\n",
    "rtree = r(\"\"\"\n",
    "library('ape')\n",
    "phy_r=read.tree(text='%s')\n",
    "\"\"\" % phy_str)\n",
    "\n",
    "# read the R object from the global rpy2 environment\n",
    "rtree=r['phy_r']\n",
    "print(\"ape tree as rpy2 object:\")\n",
    "print(rtree)\n",
    "\n",
    "# store R values into python\n",
    "tip_labels = rtree[ rtree.names.index('tip.label') ]\n",
    "print(\"Tip labels as rpy2 object:\")\n",
    "print(tip_labels)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### Importing `python` objects into `RevBayes`\n",
    "\n",
    "This feature is slated for future development."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "RevBayes",
   "language": "bash",
   "name": "revbayes_kernel"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "r"
   },
   "file_extension": ".Rev",
   "help_links": [
    {
     "text": "RevBayes",
     "url": "https://revbayes.org"
    },
    {
     "text": "RevBayes Kernel",
     "url": "https://github.com/sdwfrost/revbayes_kernel"
    },
    {
     "text": "MetaKernel Magics",
     "url": "https://github.com/calysto/metakernel/blob/master/metakernel/magics/README.md"
    }
   ],
   "mimetype": "text/x-rsrc",
   "name": "RevBayes",
   "pygments_lexer": "R"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}