{
 "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> Violin Element</dd>\n",
    "  <dt>Dependencies</dt> <dd>Bokeh</dd>\n",
    "  <dt>Backends</dt>\n",
    "    <dd><a href='./Violin.ipynb'>Bokeh</a></dd>\n",
    "    <dd><a href='../matplotlib/Violin.ipynb'>Matplotlib</a></dd>\n",
    "    '<dd><a href='../plotly/Violin.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",
    "hv.extension('bokeh')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A ``Violin`` element is used to visualise the distribution of a dataset by displaying its probability density. It is very similar to the ``BoxWhisker`` element but provides a more faithful representation even for bi- or multimodal data. The probability density is shown by the area akin to a vertical and mirrored ``Distribution`` element.  The thick black bar in the centre represents the interquartile range, the thin black line extended from it represents the 95% confidence intervals, and the white dot is the median.\n",
    "\n",
    "The data of a ``Violin`` Element may have any number of key dimensions representing the grouping of the value dimension and a single value dimensions representing the distribution of values within each group. See the [Tabular Datasets](../../../user_guide/08-Tabular_Datasets.ipynb) user guide for supported data formats, which include arrays, pandas dataframes and dictionaries of arrays.\n",
    "\n",
    "In the simplest case a ``Violin`` can be used to display a single distribution of values, such as a NumPy array of normally distributed values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.random.seed(37)\n",
    "violin = hv.Violin(np.random.randn(100), vdims='Value')\n",
    "violin"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Violin element supports multiple options for indicating the distribution values in addition to the default ``inner`` value of 'box'. The 'stick' option visualizes each sample as a single line while 'quartiles' highlights the first, second and third quartiles. Additionally the ``bandwidth`` and ``cut`` options may be used to control the kernel density estimate:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "stick = violin.relabel(group='Stick').opts(opts.Violin(inner='stick', cut=0.1, bandwidth=0.1))\n",
    "quartiles = violin.relabel(group='Quartiles').opts(opts.Violin(inner='quartiles', cut=1., bandwidth=1))\n",
    "stick + quartiles"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``Violin`` element is particularly useful to compare multiple distribution across different categories. As a simple example we can create a dataset of values with randomly assigned Group and Category values and compare the distributions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "groups = [chr(65+g) for g in np.random.randint(0, 3, 200)]\n",
    "violin = hv.Violin((groups, np.random.randint(0, 5, 200), np.random.randn(200)),\n",
    "                    ['Group', 'Category'], 'Value')\n",
    "violin.opts(opts.Violin(height=400, show_legend=False, width=600, violin_color=hv.dim('Category').str()), clone=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively we can also use the `split` keyword to split compare two conditions for each `Violin` (in this example we use a style mapping to create a True/False conditions for 'Category' values above and below 2):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "violin.opts(opts.Violin(height=400, show_legend=True, width=600, split=hv.dim('Category')>2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For full documentation and the available style and plot options, use ``hv.help(hv.Violin).``"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}