{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### **Title**: Labels Element\n",
    "\n",
    "**Dependencies** Matplotlib\n",
    "\n",
    "**Backends** [Matplotlib](./Labels.ipynb), [Bokeh]('../bokeh/Labels.ipynb')"
   ]
  },
  {
   "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": [
    "The ``Labels`` element may be used to annotate a plot with a number of labels. Unlike the ``Text`` element, ``Labels`` is vectorized and allows plotting many labels at once. It also supports any [tabular](../../../user_guide/07-Tabular_Datasets.ipynb) or [gridded](../../../user_guide/08-Gridded_Datasets.ipynb) data format. This also means that most other elements may be cast to a ``Labels`` element to annotate or label the values.\n",
    "\n",
    "``Labels`` also support various options that make it convenient to use as an annotation, e.g. ``xoffset`` and ``yoffset`` options allow adjusting the position of the labels relative to an existing data point and the ``color_index`` option allows us to colormap the data by a certain dimension."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.random.seed(9)\n",
    "data = np.random.rand(10, 2)\n",
    "points = hv.Points(data)\n",
    "labels = hv.Labels({('x', 'y'): data, 'text': [chr(65+i) for i in range(10)]}, ['x', 'y'], 'text').options(\n",
    "    color_index='text', cmap='Category20', xoffset=0.05, yoffset=0.05, size=14\n",
    ")\n",
    "\n",
    "(points.options(color='black', s=25) * labels).redim.range(x=(-0.2, 1.2), y=(-.2, 1.2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the value dimension of the data is not already of string type it will be formatted using the applicable entry in ``Dimension.type_formatters`` or an explicit ``value_format`` defined on the Dimension. Additionally the ``color_index`` option allows us to colormap the text by a dimension.\n",
    "\n",
    "Here we will create a 2D array of values, define a Dimension with a formatter and then colormap the text:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "value_dimension = hv.Dimension('Values', value_format=lambda x: '%.1f' % x)\n",
    "xs = ys = np.linspace(-2.5, 2.5, 25)\n",
    "zs = np.sin(xs**2)*np.sin(ys**2)[:, np.newaxis]\n",
    "\n",
    "hv.Labels((xs, ys, zs), vdims=value_dimension).options(\n",
    "    bgcolor='black', cmap='viridis', color_index='Values', fig_size=200, size=8\n",
    ").redim.range(x=(-2.6, 2.6), y=(-2.6, 2.6))"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}