From 900a90175dc4a8db9a9c577f0163ce533b343d06 Mon Sep 17 00:00:00 2001
From: Philipp Rudiger <P.Rudiger@ed.ac.uk>
Date: Tue, 10 May 2016 12:17:25 +0100
Subject: [PATCH] Added Tutorial section to explain DynamicMap groupby methods

---
 doc/Tutorials/Dynamic_Map.ipynb | 100 ++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)

diff --git a/doc/Tutorials/Dynamic_Map.ipynb b/doc/Tutorials/Dynamic_Map.ipynb
index e9d0e91626..82174d1002 100644
--- a/doc/Tutorials/Dynamic_Map.ipynb
+++ b/doc/Tutorials/Dynamic_Map.ipynb
@@ -597,6 +597,106 @@
     "* There cannot be more dimensions declared in the sampled ``DynamicMap`` than across the rest of the layout. We hope to relax this restriction in future."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Using groupby to discretize a DynamicMap\n",
+    "\n",
+    "A DynamicMap also makes it easy to partially or completely discretize a function to evaluate in a complex plot. By grouping over specific dimensions dimensions which define a fixed sampling via the Dimension values parameter can be viewed as a ``GridSpace``, ``NdLayout`` or ``NdOverlay``. If a dimension specifies only a continuous range it can't be grouped over but it may still be explored using the widgets. This means we can plot partial or completely discretized views of a parameter space easily.\n",
+    "\n",
+    "#### Partially discretize\n",
+    "\n",
+    "Fundamentally all the groupby operations use the ``groupby`` method, however there are three convenience functions to group dimensions into an ``NdOverlay`` (``.overlay``), ``GridSpace`` (``.grid``) and ``NdLayout`` (``.layout``).\n",
+    "\n",
+    "Here we will evaluate a simple sine function with three dimensions, the phase, frequency and amplitude. We assign the frequency and amplitude discrete samples and define a continuous range for the phase."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "xs = np.linspace(0, 2*np.pi)\n",
+    "\n",
+    "def sin(ph, f, amp):\n",
+    "    return hv.Curve((xs, np.sin(xs*f+ph)*amp))\n",
+    "\n",
+    "kdims=[hv.Dimension('phase', range=(0, np.pi)),\n",
+    "       hv.Dimension('frequency', values=[0.1, 1, 2, 5, 10]),\n",
+    "       hv.Dimension('amplitude', values=[0.5, 5, 10])]\n",
+    "\n",
+    "sine_dmap = hv.DynamicMap(sin, kdims=kdims)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now we define the amplitude dimension to be overlaid and the amplitude dimension to be gridded."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "%%opts GridSpace [show_legend=True]\n",
+    "sine_dmap.overlay('amplitude').grid('frequency')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Fully discretize\n",
+    "\n",
+    "Now we define a function to evaluate over a space, instead of sampling it manually we can evaluate it using the groupby method. The function is a spiral with a frequency and a first and second order phase term. Then we define the dimension values for all the parameters and declare the DynamicMap."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%opts Path (linewidth=1 color=Palette('Blues'))\n",
+    "\n",
+    "def spiral_equation(f, ph, ph2):\n",
+    "    r = np.arange(0, 1, 0.005)\n",
+    "    xs, ys = (r * fn(f*np.pi*np.sin(r+ph)+ph2) for fn in (np.cos, np.sin))\n",
+    "    return hv.Path((xs, ys))\n",
+    "\n",
+    "kdims=[hv.Dimension('f', values=list(np.linspace(1, 10, 10))),\n",
+    "       hv.Dimension('ph', values=list(np.linspace(0, np.pi, 10))),\n",
+    "       hv.Dimension('ph2', values=list(np.linspace(0, np.pi, 4)))]\n",
+    "\n",
+    "spiral_dmap = hv.DynamicMap(spiral_equation, kdims=kdims)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now we can make use of the groupby method directly to group over the frequency and phase dimensions, which we will display as part of a GridSpace by setting the ``container_type``. This leaves second phase variable, which we assign to an NdOverlay by setting the ``group_type``:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "%%opts GridSpace [xaxis=None yaxis=None] Path [bgcolor='w' xaxis=None yaxis=None]\n",
+    "spiral_dmap.groupby(['f', 'ph'], group_type=hv.NdOverlay, container_type=hv.GridSpace)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},