diff --git a/examples/reference/containers/matplotlib/Overlay.ipynb b/examples/reference/containers/matplotlib/Overlay.ipynb
new file mode 100644
index 0000000000..baf44258aa
--- /dev/null
+++ b/examples/reference/containers/matplotlib/Overlay.ipynb
@@ -0,0 +1,234 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "
\n",
+ "
\n",
+ " - Title
- Overlay Container
\n",
+ " - Dependencies
- Matplotlib
\n",
+ " - Backends
- [Matplotlib](./Overlay.ipynb)
- [Bokeh](../bokeh/Overlay.ipynb)
\n",
+ "
\n",
+ "
"
+ ]
+ },
+ {
+ "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
+}