{
 "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> Distribution Element</dd>\n",
    "  <dt>Dependencies</dt> <dd>Matplotlib, SciPy</dd>\n",
    "  <dt>Backends</dt>\n",
    "    <dd><a href='./Distribution.ipynb'>Matplotlib</a></dd>\n",
    "    <dd><a href='../bokeh/Distribution.ipynb'>Bokeh</a></dd>\n",
    "    <dd><a href='../plotly/Distribution.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": [
    "``Distribution`` provides a convenient way to visualize a 1D distribution of values as a [Kernel density estimate](https://en.wikipedia.org/wiki/Kernel_density_estimation). Kernel density estimation is a non-parametric way to\n",
    "estimate the probability density function of a random variable.\n",
    "\n",
    "The KDE works by placing a Gaussian kernel at each sample with the supplied bandwidth, which are then summed to produce the density estimate. By default the bandwidth is determined using the Scott's method, which usually produces good results, but it may be overridden by an explicit value.\n",
    "\n",
    "To start with we will create a ``Distribution`` with 1,000 normally distributed samples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "normal = np.random.randn(1000)\n",
    "hv.Distribution(normal)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can set explicit values for the ``bandwidth`` to see the effect and also declare whether we want the plot to be filled:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hv.NdOverlay({bw: hv.Distribution(normal).opts(alpha=1, bandwidth=bw, filled=False)\n",
    "              for bw in [0.05, 0.1, 0.5, 1]}, 'Bandwidth')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``Distribution`` element is also useful to visualize the marginal distribution of a set of points. Here we will declare distributions for the x- and y-values of two sets of ``Points`` with slightly different spreads and means and then adjoin these plots:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "points = hv.Points(np.random.randn(100,2))\n",
    "points2 = hv.Points(np.random.randn(100,2)*2+1)\n",
    "\n",
    "xdist, ydist = ((hv.Distribution(points2, kdims=[dim]) *\n",
    "                 hv.Distribution(points, kdims=[dim]))\n",
    "                for dim in 'xy')\n",
    "((points2 * points) << ydist << xdist).redim.range(x=(-5, 5), y=(-5, 5))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Underlying the ``Distribution`` element is the ``univariate_kde`` operation, which computes the KDE for us automatically when we plot the element. We can also use this operation directly and print the output highlighting the fact that the operation simply returns an ``Area`` or ``Curve`` element. It also affords more control over the parameters letting us directly set not only the ``bandwidth`` and ``cut`` values but also a ``bin_range``, ``bw_method`` and the number of samples (``n_samples``) to approximate the KDE with:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from holoviews.operation.stats import univariate_kde\n",
    "dist = hv.Distribution(normal)\n",
    "kde = univariate_kde(dist, bin_range=(-4, 4), bw_method='silverman', n_samples=20)\n",
    "kde"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For full documentation and the available style and plot options, use ``hv.help(hv.Distribution).``"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}