From 3f39c3ad8539de0b8fb9061fec3c2f0d59d8e76e Mon Sep 17 00:00:00 2001
From: jlstevens <jlstevens@ed.ac.uk>
Date: Tue, 9 Feb 2016 03:23:37 +0000
Subject: [PATCH] Added tutorial section on DynamicMap caches and HoloMap
 conversion

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

diff --git a/doc/Tutorials/Dynamic_Map.ipynb b/doc/Tutorials/Dynamic_Map.ipynb
index f2489211c2..9a05b910ee 100644
--- a/doc/Tutorials/Dynamic_Map.ipynb
+++ b/doc/Tutorials/Dynamic_Map.ipynb
@@ -210,7 +210,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If you are running this tutorial in a live notebook, you should now see something that looks like the ``HoloMap`` in the [Containers Tutorial](Containers.ipynb#HoloMap). There are some key differences though:\n",
+    "If you are running this tutorial in a live notebook, you should now see something that looks like the ``HoloMap`` in the [Containers Tutorial](Containers.ipynb#HoloMap). ``DynamicMap`` is in fact a subclass of ``HoloMap`` with some crucial differences:\n",
     "\n",
     "* You can now pick any value of **phase** or **frequency** up to the precision allowed by the slider.\n",
     "* What you see in the cell above will not be exported in any HTML snapshot of the notebook."
@@ -233,6 +233,126 @@
     "* The argument order in the callable signature must match the order of the declared key dimensions.\n",
     "* All key dimensions are defined with a bounded ``range`` or ``values`` parameter (for categorical dimensions)."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### The ``DynamicMap`` cache"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Above we mentioned that ``DynamicMap`` is an instance of ``HoloMap``. Does this means it has a ``.data`` attribute?"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "dmap.data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This is exactly the same sort of ``.data`` as the equivalent ``HoloMap`` except this value will vary according to how much you explored the parameter space of ``dmap`` using the sliders above. In a ``HoloMap``, ``.data`` contains a defined sampling along the different dimensions whereas in a ``DynamicMap``, the ``.data`` is the the *cache*.\n",
+    "\n",
+    "The cache serves two purposes:\n",
+    "\n",
+    "* Avoids recomputation of an element in the event that we revisit a particular point in the parameter space. This is fairly unlikely as sliders can now take any continuous value.\n",
+    "* Keeps a record of the space that has been explored with the ``DynamicMap`` by conversion to a ``HoloMap``.\n",
+    "\n",
+    "We can convert a ``DynamicMap`` directly to a ``HoloMap`` as follows:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "hv.HoloMap(dmap)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This is in fact equivalent to declaring a HoloMap with the same parameters using ``dmap.data`` as input.\n",
+    "\n",
+    "Although creating a HoloMap this way is easy, the result is poorly controlled as the keys in the HoloMap are defined by how you moved the sliders around! This can be easily rectified using the same key selection semantics of ``HoloMap`` to define the elements in the cache:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "hv.HoloMap(dmap[{(0,0.01), (0,0.5), (0.5,0.01), (0.5,0.5)}])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "As this sort of cartesian product is a very common way to sample a ``DynamicMap`` there is another convenient syntax which also works with ``HoloMaps``. Here is an equivalent way of defining the same set of keys:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "hv.HoloMap(dmap[{0,0.5},{0.01,0.5}])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note that you can index a ``DynamicMap`` with a literal key in exactly the same way as a ``HoloMap`` so long as you use an exact key value that exists in the cache:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "dmap[dmap.keys()[-1]]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "###  Slicing bounded ``DynamicMaps``"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Slicing is currently not supported in bounded ``DynamicMaps`` (in future this will set the dimension ranges for continuous dimensions). The only slices that is allowed is a single unbounded slice which creates a clone:"
+   ]
   }
  ],
  "metadata": {