Added the Overlay container notebook

examples/reference/containers/matplotlib/Overlay.ipynb

@@ -0,0 +1,234 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<div class=\"contentcontainer med left\" style=\"margin-left: -50px;\">\n",
+    "<dl class=\"dl-horizontal\">\n",
+    "  <dt>Title</dt> <dd>Overlay Container</dd>\n",
+    "  <dt>Dependencies</dt> <dd>Matplotlib</dd>\n",
+    "  <dt>Backends</dt> <dd>[Matplotlib](./Overlay.ipynb)</dd> <dd>[Bokeh](../bokeh/Overlay.ipynb)</dd>\n",
+    "</dl>\n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import holoviews as hv\n",
+    "hv.extension('matplotlib')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "A Overlay is a collection of HoloViews objects that are related in some way, to be displayed simultanously, overlaid in the space space. Like ``Layout`` and unlike other containers such as [``HoloMap``](./HoloMap.ipynb) , [``GridSpace``](./GridSpace.ipynb) and [``NdOverlay``](./NdOverlay.ipynb) a ``Overlay`` is *not* dictionary like: it holds potentially heterogeneous types without any dimensioned keys.\n",
+    "\n",
+    "\n",
+    "A ``Overlay`` cannot contain any other container type other than ``NdOverlay`` but can contain any HoloViews elements. See [Building Composite Objects](05-Building_Composite_Objects.ipynb) for more details on how to compose containers. It is best to learn about ``Overlay`` and [``Layout``](./Layout.ipynb) together as they are very closely related objects that share many core concepts."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### ``Overlay`` is a heterogeneous collection"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can build a ``Overlay`` between any two HoloViews objects (which can have different types) using the ``*`` operator:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "xvals = [0.1* i for i in range(100)]\n",
+    "curve =  hv.Curve((xvals, [np.sin(x) for x in xvals]))\n",
+    "scatter =  hv.Scatter((xvals[::5], np.linspace(0,1,20)))\n",
+    "curve * scatter"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In this example, we have a ``Overlay`` composed of a ``Curve`` element and a ``Scatter`` element."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Building ``Overlay`` from a list"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can build Overlay's of any size by passing a list of objects to the ``Overlay`` constructor as shown below:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "curve_list = [ hv.Curve((xvals, [np.sin(f*x) for x in xvals])) for f in [0.5, 0.75]]\n",
+    "scatter_list = [hv.Scatter((xvals[::5], f*np.linspace(0,1,20))) for f in [-0.5, 0.5]]\n",
+    "overlay = hv.Overlay(curve_list + scatter_list)\n",
+    "overlay"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note that these curve and scatter elements are using the default color cycle when overlaid; see [Customizing Plots](../../../user_guide/03-Customizing_Plots.ipynb) for more information on cycles."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## A ``Overlay`` has two-level attribute access"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "``Overlay`` and ``Layout`` are fundamentally tree-structures holding arbitrary heterogenous HoloViews objects and are quite different from the dictionary-like dimensioned containers such as [``HoloMap``](./HoloMap.ipynb) , [``GridSpace``](./GridSpace.ipynb) and [``NdOverlay``](./NdOverlay.ipynb).\n",
+    "\n",
+    "All HoloViews objects have string ``group`` and ``label`` parameters, resulting in a 2-level attribute access on ``Overlay`` objects. First let us see how to index the above example where ``group`` and ``label`` was not specified for any of the elements:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "overlay2 = overlay.Curve.I * overlay.Scatter.II\n",
+    "overlay2"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here we create a second ``Overlay`` by indexing two elements from our earlier ``overlay`` object. We see that the first level is the ``group`` string (which defaults to the element class name) followed by the label, which wasn't set and is therefore mapped to a roman numeral (I,II,III etc).\n",
+    "\n",
+    "As no group and label was specified, our new ``Overlay`` will once again have ``Curve.I`` for the curve but as there is only one scatter element, it will have ``Scatter.II`` to index the scatter."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Tab-completion"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "``Overlay`` and ``Layout`` are designed to be easy to explore and inspect with tab completion. Try running:\n",
+    "\n",
+    "```python\n",
+    "overlay.[tab]\n",
+    "```\n",
+    "\n",
+    "And you should see the first levels of indexing (``Curve`` and ``Scatter``) conveniently listed at the top. If this is not the case, you may need to enable improved tab-completion as described in [Configuring HoloViews](../../../user_guide/Configuring_HoloViews.ipynb)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Using ``group`` and ``label``"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": true
+   },
+   "source": [
+    "Now let's return to the first simple example, although this time we will set a ``group`` and ``label``; see the [Annotating Data](../../../user_guide/01-Annotating_Data.ipynb) for more information:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "xvals = [0.1* i for i in range(100)]\n",
+    "curve1 =  hv.Curve((xvals, [np.sin(x) for x in xvals]), group='Sinusoid', label='Low Frequency')\n",
+    "curve2 =  hv.Curve((xvals, [np.sin(2*x) for x in xvals]), group='Sinusoid', label='High Frequency')\n",
+    "scatter =  hv.Scatter((xvals[::5], np.linspace(0,1,20)), group='Linear Points', label='Demo')\n",
+    "overlay3 = curve1 * curve2 * scatter\n",
+    "overlay3"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can now see how group and label affect access, in addition to being used for setting the legend shown above and for allowing plot customization (see \n",
+    "[Customizing Plots](../../../user_guide/03-Customizing_Plots.ipynb) for more information):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "overlay3.Linear_Points.Demo * overlay3.Sinusoid.High_Frequency * overlay3.Sinusoid.Low_Frequency"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We have used the semantic group and label names to access the elements and build a new re-ordered ``Overlay`` which we can observe by the switched z-ordering and legend colors used for the two sinusoidal curves."
+   ]
+  }
+ ],
+ "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.1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}