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 +}