examples/reference/elements/matplotlib/Polygons.ipynb

{
 "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> Polygons Element</dd>\n",
    "  <dt>Dependencies</dt> <dd>Matplotlib</dd>\n",
    "  <dt>Backends</dt> <dd><a href='./Polygons.ipynb'>Matplotlib</a></dd> <dd><a href='../bokeh/Polygons.ipynb'>Bokeh</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 ``Polygons`` represents a contiguous filled area in a 2D space as a list of polygon geometries. Just like the ``Contours`` element additional scalar value dimensions maybe may be supplied, which can be used to color the ``Polygons`` with the defined ``cmap``. Like other ``Path`` types it accepts a list of arrays, dataframes, a dictionary of columns (or any of the other literal formats including tuples of columns and lists of tuples), but also supports a special 'holes' key to represent empty interior regions. For a full description of the polygon geometry data model see the [Geometry Data User Guide](../../../user_guide/Geometry_Data.ipynb). \n",
    "\n",
    "In order to efficiently represent the scalar values associated with each path the dictionary format is preferable since it can store the scalar values without expanding them into a whole column. Additionally it allows passing multiple columns as a single array by specifying the dimension names as a tuple.\n",
    "\n",
    "In this example we will create a list of random polygons each with an associated ``level`` value. Polygons will default to using the first value dimension as the ``color`` but for clarity we will define the ``color`` explicitly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def rectangle(x=0, y=0, width=.05, height=.05):\n",
    "    return np.array([(x,y), (x+width, y), (x+width, y+height), (x, y+height)])\n",
    "\n",
    "polys = hv.Polygons([{('x', 'y'): rectangle(x, y), 'level': z}\n",
    "                     for x, y, z in np.random.rand(100, 3)], vdims='level')\n",
    "\n",
    "polys.opts(color='level', linewidth=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "``Polygons`` is a very versatile element which may be used to draw custom annotations, choropleth maps (as can be seen in the [texas_unemploment example](../../../gallery/demos/bokeh/texas_choropleth_example.ipynb)) among many other examples. We can also use some of the other path based annotations to quickly generate polygons, including ``Box``, ``Bounds`` and ``Ellipse`` elements. In the simple case we can simply pass a list of these elements:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hv.Polygons([hv.Box(i, i, i) for i in range(10)])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively we can use the ``array`` method to return the x/y-coordinates of the annotations and define additional z-values by declaring a dictionary:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hv.Polygons([{('x', 'y'): hv.Box(0, 0, i).array(), 'z': i} for i in range(10)[::-1]], vdims='z') +\\\n",
    "hv.Polygons([{('x', 'y'): hv.Ellipse(0, 0, (i, i)).array(), 'z': i} for i in range(10)[::-1]], vdims='z')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For full documentation and the available style and plot options, use ``hv.help(hv.Polygons).``"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}