{
 "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> Histogram Element</dd>\n",
    "  <dt>Dependencies</dt> <dd>Matplotlib</dd>\n",
    "  <dt>Backends</dt>\n",
    "    <dd><a href='./Histogram.ipynb'>Matplotlib</a></dd>\n",
    "    <dd><a href='../bokeh/Histogram.ipynb'>Bokeh</a></dd>\n",
    "    <dd><a href='../plotly/Histogram.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",
    "from holoviews import opts\n",
    "\n",
    "hv.extension('matplotlib')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "``Histogram``s partition the `x` axis into discrete (but not necessarily regular) bins, showing counts in each as a bar. A ``Histogram`` accepts the output of ``np.histogram`` as input, which consists of a tuple of the histogram values with a shape of ``N`` and bin edges with a shape of ``N+1``. As a simple example we will generate a histogram of a normal distribution with 20 bins."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.random.seed(1)\n",
    "data = np.random.randn(10000)\n",
    "frequencies, edges = np.histogram(data, 20)\n",
    "print('Values: %s, Edges: %s' % (frequencies.shape[0], edges.shape[0]))\n",
    "hv.Histogram((edges, frequencies))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``Histogram`` Element will also expand evenly sampled bin centers, therefore we can easily cast between a linearly sampled Curve or Scatter and a Histogram."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "xs = np.linspace(0, np.pi*2)\n",
    "ys = np.sin(xs)\n",
    "curve = hv.Curve((xs, ys))\n",
    "curve + hv.Histogram(curve)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Like most other elements a ``Histogram`` also supports using ``dim`` transforms to map dimensions to visual attributes. To demonstrate this we will use the ``bin`` transform to bin the 'y' values into positive and negative values and map those to a 'blue' and 'red' ``fill_color``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hv.Histogram(curve).opts(color=hv.dim('y').bin(bins=[-1, 0, 1], labels=['red', 'blue']))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``.hist`` method is an easy way to compute a histogram from an existing Element:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "points = hv.Points(np.random.randn(100,2))\n",
    "\n",
    "points.hist(dimension=['x','y'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``.hist`` method is just a convenient wrapper around the ``histogram`` operation that computes a histogram from an Element, and then adjoins the resulting histogram to the main plot. You can also do this process manually; here we create an additional set of ``Points``, compute a ``Histogram`` for the 'x' and 'y' dimension on each, and then overlay them and adjoin to the plot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from holoviews.operation import histogram\n",
    "points2 = hv.Points(np.random.randn(100,2)*2+1).redim.range(x=(-5, 5), y=(-5, 5))\n",
    "\n",
    "xhist, yhist = (histogram(points2, bin_range=(-5, 5), dimension=dim) *\n",
    "                histogram(points,  bin_range=(-5, 5), dimension=dim) \n",
    "                for dim in 'xy')\n",
    "((points2 * points) << yhist << xhist).opts(\n",
    "    opts.Histogram(alpha=0.3))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For full documentation and the available style and plot options, use ``hv.help(hv.Histogram).``"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}