{
 "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> Points Element</dd>\n",
    "  <dt>Dependencies</dt> <dd>Bokeh</dd>\n",
    "  <dt>Backends</dt>\n",
    "    <dd><a href='./Points.ipynb'>Bokeh</a></dd>\n",
    "    <dd><a href='../matplotlib/Points.ipynb'>Matplotlib</a></dd>\n",
    "    <dd><a href='../plotly/Points.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",
    "import pandas as pd\n",
    "from holoviews import opts, dim\n",
    "hv.extension('bokeh')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``Points`` element visualizes as markers placed in a space of two independent variables, traditionally denoted *x* and *y*. In HoloViews, the names ``'x'`` and ``'y'`` are used as the default key dimensions (``kdims``) of the element.  We can see this from the default axis labels when visualizing a simple ``Points`` element:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.random.seed(12)\n",
    "coords = np.random.rand(50,2)\n",
    "points = hv.Points(coords)\n",
    "\n",
    "points.opts(color='k', marker='+', size=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here the random ``x`` values and random ``y`` values are *both* considered to be the coordinates, with no dependency between them (compare this to the different way that [``Scatter``](./Scatter.ipynb) elements are defined). You can think of ``Points`` as simply marking positions in some two-dimensional space. Such positions can be sliced by specifying a 2D region of interest:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "(points + points[0.6:0.8,0.2:0.5]).opts(\n",
    "   opts.Points(color='k', marker='+', size=10))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Although the simplest ``Points`` element simply marks positions in a two-dimensional space without any associated value, value dimensions (``vdims``) are also supported. Here is an example with two additional quantities for each point, declared as the ``vdims``s ``z`` and ``size`` (visualized as the color and size of the dots, respectively):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.random.seed(10)\n",
    "data = np.random.rand(100,4)\n",
    "popts = opts.Points(color='z', size=dim('size')*20)\n",
    "\n",
    "points = hv.Points(data, vdims=['z', 'size'])\n",
    "(points + points[0.3:0.7, 0.3:0.7].hist()).opts(popts)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the right subplot, the ``hist`` method is used to show the distribution of samples along the first value dimension we added (*z*).\n",
    "\n",
    "\n",
    "The marker shape specified above can be any supported by [matplotlib](http://matplotlib.org/api/markers_api.html), e.g. ``s``, ``d``, or ``o``; the other options select the color and size of the marker.  For convenience with the [bokeh backend](../../../user_guide/Plotting_with_Bokeh.ipynb), the matplotlib marker options are supported using a compatibility function in HoloViews."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the data accepted by Points is specified as a sequence of points, where each point is a set of coordinates. For instance, the five points selected above (one of which is tiny and may be hard to spot!) are a sequence of five (x,y,color,size) coordinates:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pts = points[0.3:0.7, 0.3:0.5].data\n",
    "pts"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If your data stores each coordinate axis separately you can either use a Pandas DataFrame, a Python dictionary, or transpose the data before passing it into Points:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "copts = opts.Points(color='z', size=dim('size')*20, width=250, height=250)\n",
    "\n",
    "xs     = [0.44183317, 0.37764192, 0.30021061, 0.54346504, 0.38412185]\n",
    "ys     = [0.43401399, 0.42874733, 0.39644188, 0.33775465, 0.39611779]\n",
    "colors = [0.61776698, 0.51120865, 0.79327323, 0.89802431, 0.89727994]\n",
    "sizes  = [0.51313824, 0.89176257, 0.41227608, 0.94070704, 0.05882237]\n",
    "\n",
    "dictionary = dict(x=xs, y=ys, z=colors, size=sizes)\n",
    "df = pd.DataFrame(dictionary)\n",
    "array = np.stack([xs,ys,colors,sizes]).T\n",
    "\n",
    "(hv.Points(df) +\n",
    " hv.Points(dictionary, vdims=['z', 'size']) +\n",
    " hv.Points(array, vdims=['z', 'size'])).opts(copts)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note**: Although the  ``Scatter`` element is superficially similar to the [``Points``](./Points.ipynb) element (they can generate plots that look identical), the two element types are semantically quite different. The fundamental difference is that [Scatter](./Scatter.ipynb) is used to visualize data where the *y* variable is *dependent*, unlike ``Points``. This semantic difference also explains why the histogram generated by the ``hist`` call above visualizes the distribution of a different dimension than it does for [``Scatter``](./Scatter.ipynb) (because here *z*, not *y*, is the first ``vdim``).\n",
    "\n",
    "This difference means that ``Points`` elements can most naturally overlay with other elements that express independent variables in two-dimensional space, such as [``Raster``](./Raster.ipynb) types like [``Image``](./Image.ipynb). Conversely, ``Scatter`` expresses a dependent relationship between *x* and *y* and thus most naturally overlay with ``Chart`` types such as [``Curve``](./Curve.ipynb).\n",
    "\n",
    "For full documentation and the available style and plot options, use ``hv.help(hv.Points).``"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}