{
 "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> Scatter Element</dd>\n",
    "  <dt>Dependencies</dt> <dd>Bokeh</dd>\n",
    "  <dt>Backends</dt> <dd><a href='./Scatter.ipynb'>Bokeh</a></dd> <dd><a href='../matplotlib/Scatter.ipynb'>Matplotlib</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('bokeh')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``Scatter`` element visualizes as markers placed in a space of one independent variable, traditionally denoted as *x*, against a dependent variable, traditonally denoted as *y*. In HoloViews, the name ``'x'`` is the default dimension name used in the ``key_dimensions`` and ``'y'`` is the default dimension name used in the ``value_dimensions``. We can see this from the default axis labels when visualizing a simple ``Scatter`` element:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%opts Scatter (color='k' marker='s' size=10)\n",
    "np.random.seed(42)\n",
    "coords = [(i, np.random.random()) for i in range(20)]\n",
    "hv.Scatter(coords)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here the random *y* values are considered to be the 'data' whereas the x positions express where those values are located (compare this to how [``Points``](./Points.ipynb) elements are defined). In this sense, ``Scatter`` can be thought of as a [``Curve``](./Curve.ipynb) without any lines connecting the samples and you can use slicing to view the *y* values corresponding to a chosen *x* range:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%opts Scatter (color='k' marker='s' size=10)\n",
    "hv.Scatter(coords)[0:12] + hv.Scatter(coords)[12:20]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A ``Scatter`` element must always have at least one value dimension but that doesn't mean additional value dimensions aren't supported. Here is an example with two additional quantities for each point, declared as the ``value_dimension``s *z* and &alpha; visualized as the color and size of the dots, respectively:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%opts Scatter [color_index=2 size_index=3 scaling_factor=50]\n",
    "np.random.seed(10)\n",
    "data = np.random.rand(100,4)\n",
    "\n",
    "scatter = hv.Scatter(data, vdims=['y', 'z', 'size'])\n",
    "scatter + scatter[0.3:0.7, 0.3:0.7].hist()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the right subplot, the ``hist`` method is used to show the distribution of samples along our first value dimension, (*y*)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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](Bokeh_Backend), the matplotlib marker options are supported using a compatibility function in HoloViews."
   ]
  },
  {
   "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: ``Points`` are used to visualize data where the *y* variable is *dependent*. This semantic difference also explains why the histogram generated by ``hist`` call above visualizes the distribution of a different dimension than it does for [``Points``](./Points.ipynb).\n",
    "\n",
    "This difference means that ``Scatter`` naturally combine elements that express dependent variables in two-dimensional space such as the ``Chart`` types, such as [``Curve``](./Curve.ipynb). Similarly, ``Points`` express a independent relationship in two-dimensions and combine naturally with [``Raster``](./Raster.ipynb) types such as [``Image``](./Image.ipynb).\n",
    "\n",
    "For full documentation and the available style and plot options, use ``hv.help(hv.Scatter).``"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}