{
 "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>HoloMap Container</dd>\n",
    "  <dt>Dependencies</dt> <dd>Plotly</dd>\n",
    "  <dt>Backends</dt> <dd><a href='./HoloMap.ipynb'>Matplotlib</a></dd> <dd><a href='../bokeh/HoloMap.ipynb'>Bokeh</a></dd> <dd><a href='../plotly/HoloMap.ipynb'>Plotly</a></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 HoloMap is an explorable multi-dimensional dictionary of HoloViews objects. A ``HoloMap`` cannot contain ``Layouts``, ``NdLayouts``, ``GridSpaces`` or other ``HoloMaps`` or ``DyamicMap`` but can contain any other HoloViews object. See the [Building Composite Objects](../../../user_guide/06-Building_Composite_Objects.ipynb) user guide for details on how to compose containers."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### ``HoloMap`` holds dictionaries"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As a ``HoloMap`` is a dictionary of elements, let us now create a dictionary of sine curves:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "frequencies = [0.5, 0.75, 1.0, 1.25]\n",
    "\n",
    "def sine_curve(phase, freq):\n",
    "    xvals = [0.1* i for i in range(100)]\n",
    "    return hv.Curve((xvals, [np.sin(phase+freq*x) for x in xvals]))\n",
    "\n",
    "curve_dict = {f:sine_curve(0,f) for f in frequencies}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now have a dictionary where the frequency is the key and the corresponding curve element is the value. We can now turn this dictionary into a ``HoloMap`` by declaring the keys as corresponding to the frequency key dimension:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hmap = hv.HoloMap(curve_dict, kdims='frequency')\n",
    "hmap"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### ``HoloMap`` is multi-dimensional"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By using tuple keys and making sure each position in the tuple is assigned a corresponding ``kdim``, ``HoloMaps`` allow exploration of a multi-dimensional space:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "phases      = [0, np.pi/2, np.pi, 3*np.pi/2]\n",
    "curve_dict_2D = {(p,f):sine_curve(p,f) for p in phases for f in frequencies}\n",
    "hmap = hv.HoloMap(curve_dict_2D, kdims=['phase', 'frequency'])\n",
    "hmap"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### ``HoloMap`` supports dictionary-like behavior"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "HoloMaps support a number of features similar to regular dictionaries, including **assignment**:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hmap = hv.HoloMap(kdims=['phase', 'frequency'])\n",
    "for (phase, freq) in [(0,0.5), (0.5,0.5), (0.5,1), (0,1)]:\n",
    "    hmap[(phase, freq)] = sine_curve(phase,freq)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Key membership predicate**:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "(0, 0.5) in hmap"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**The ``get`` method:**:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hmap.get((0,0.5))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### ``HoloMap`` supports multi-dimensional indexing and slicing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One difference with regular dictionaries, is that ``HoloMaps`` support multi-dimensional indexing:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hmap[0,1] + hmap[0,:]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See the [User Guide] for more information on selecting, slicing and indexing."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### ``HoloMap`` is ordered"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One difference with regular Python dictionaries is that they are *ordered*, which can be observed by inspecting the ``.data`` attribute:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hmap.data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We see that internally, ``HoloMaps`` uses [``OrderedDict``](https://docs.python.org/3.6/library/collections.html#collections.OrderedDict) where the keys are sorted by default. You can set ``sort=False`` and then either supply an ordered list of (key, value) tuples, an ``OrderedDict`` or insert items in a chosen order.\n",
    "\n",
    "That said, there is generally very-little reason to ever use ``sort=False`` as regular Python dictionaries do not have a well-defined key ordering and ``HoloViews`` sliders work regardless of the ordering used. The only reason to set the ordering is if you wish to iterate over a ``HoloMap`` using the ``items``, ``keys``, ``values`` methods or use the iterator interface."
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}