doc/source/user_guide/style.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Table Visualization\n",
    "\n",
    "This section demonstrates visualization of tabular data using the [Styler][styler]\n",
    "class. For information on visualization with charting please see [Chart Visualization][viz]. This document is written as a Jupyter Notebook, and can be viewed or downloaded [here][download].\n",
    "\n",
    "[styler]: ../reference/api/pandas.io.formats.style.Styler.rst\n",
    "[viz]: visualization.rst\n",
    "[download]: https://nbviewer.ipython.org/github/pandas-dev/pandas/blob/master/doc/source/user_guide/style.ipynb"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Styler Object and HTML \n",
    "\n",
    "Styling should be performed after the data in a DataFrame has been processed. The [Styler][styler] creates an HTML `<table>` and leverages CSS styling language to manipulate many parameters including colors, fonts, borders, background, etc. See [here][w3schools] for more information on styling HTML tables. This allows a lot of flexibility out of the box, and even enables web developers to integrate DataFrames into their exiting user interface designs.\n",
    "    \n",
    "The `DataFrame.style` attribute is a property that returns a [Styler][styler] object. It has a `_repr_html_` method defined on it so they are rendered automatically in Jupyter Notebook.\n",
    "\n",
    "[styler]: ../reference/api/pandas.io.formats.style.Styler.rst\n",
    "[w3schools]: https://www.w3schools.com/html/html_tables.asp"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "import matplotlib.pyplot\n",
    "# We have this here to trigger matplotlib's font cache stuff.\n",
    "# This cell is hidden from the output"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import numpy as np\n",
    "\n",
    "df = pd.DataFrame([[38.0, 2.0, 18.0, 22.0, 21, np.nan],[19, 439, 6, 452, 226,232]], \n",
    "                  index=pd.Index(['Tumour (Positive)', 'Non-Tumour (Negative)'], name='Actual Label:'), \n",
    "                  columns=pd.MultiIndex.from_product([['Decision Tree', 'Regression', 'Random'],['Tumour', 'Non-Tumour']], names=['Model:', 'Predicted:']))\n",
    "df.style"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above output looks very similar to the standard DataFrame HTML representation. But the HTML here has already attached some CSS classes to each cell, even if we haven't yet created any styles. We can view these by calling the  [.render()][render] method, which returns the raw HTML as string, which is useful for further processing or adding to a file - read on in [More about CSS and HTML](#More-About-CSS-and-HTML). Below we will show how we can use these to format the DataFrame to be more communicative. For example how we can build `s`:\n",
    "\n",
    "[render]: ../reference/api/pandas.io.formats.style.Styler.render.rst"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Hidden cell to just create the below example: code is covered throughout the guide.\n",
    "s = df.style\\\n",
    "      .hide_columns([('Random', 'Tumour'), ('Random', 'Non-Tumour')])\\\n",
    "      .format('{:.0f}')\\\n",
    "      .set_table_styles([{\n",
    "        'selector': '',\n",
    "        'props':  'border-collapse: separate;'\n",
    "      },{\n",
    "        'selector': 'caption',\n",
    "        'props': 'caption-side: bottom; font-size:1.3em;'\n",
    "      },{\n",
    "        'selector': '.index_name',\n",
    "        'props': 'font-style: italic; color: darkgrey; font-weight:normal;'\n",
    "      },{\n",
    "        'selector': 'th:not(.index_name)',\n",
    "        'props': 'background-color: #000066; color: white;'\n",
    "      },{\n",
    "        'selector': 'th.col_heading',\n",
    "        'props': 'text-align: center;'\n",
    "      },{\n",
    "        'selector': 'th.col_heading.level0',\n",
    "        'props': 'font-size: 1.5em;'\n",
    "      },{\n",
    "        'selector': 'th.col2',\n",
    "        'props': 'border-left: 1px solid white;'\n",
    "      },{\n",
    "        'selector': '.col2',\n",
    "        'props': 'border-left: 1px solid #000066;'\n",
    "      },{\n",
    "        'selector': 'td',\n",
    "        'props': 'text-align: center; font-weight:bold;'\n",
    "      },{\n",
    "        'selector': '.true',\n",
    "        'props': 'background-color: #e6ffe6;'\n",
    "      },{\n",
    "        'selector': '.false',\n",
    "        'props': 'background-color: #ffe6e6;'\n",
    "      },{\n",
    "        'selector': '.border-red',\n",
    "        'props': 'border: 2px dashed red;'\n",
    "      },{\n",
    "        'selector': '.border-green',\n",
    "        'props': 'border: 2px dashed green;'\n",
    "      },{\n",
    "        'selector': 'td:hover',\n",
    "        'props': 'background-color: #ffffb3;'\n",
    "      }])\\\n",
    "      .set_td_classes(pd.DataFrame([['true border-green', 'false', 'true', 'false border-red', '', ''],\n",
    "                                    ['false', 'true', 'false', 'true', '', '']], \n",
    "                                    index=df.index, columns=df.columns))\\\n",
    "      .set_caption(\"Confusion matrix for multiple cancer prediction models.\")\\\n",
    "      .set_tooltips(pd.DataFrame([['This model has a very strong true positive rate', '', '', \"This model's total number of false negatives is too high\", '', ''],\n",
    "                                    ['', '', '', '', '', '']], \n",
    "                                    index=df.index, columns=df.columns),\n",
    "                   css_class='pd-tt', props=\n",
    "    'visibility: hidden; position: absolute; z-index: 1; border: 1px solid #000066;'\n",
    "    'background-color: white; color: #000066; font-size: 0.8em;' \n",
    "    'transform: translate(0px, -24px); padding: 0.6em; border-radius: 0.5em;')\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Formatting the Display\n",
    "\n",
    "### Formatting Values\n",
    "\n",
    "Before adding styles it is useful to show that the [Styler][styler] can distinguish the *display* value from the *actual* value. To control the display value, the text is printed in each cell, and we can use the [.format()][formatfunc] method to manipulate this according to a [format spec string][format] or a callable that takes a single value and returns a string. It is possible to define this for the whole table or for individual columns. \n",
    "\n",
    "Additionally, the format function has a **precision** argument to specifically help formatting floats, an **na_rep** argument to display missing data, and an **escape** argument to help displaying safe-HTML. The default formatter is configured to adopt pandas' regular `display.precision` option, controllable using `with pd.option_context('display.precision', 2):`\n",
    "\n",
    "Here is an example of using the multiple options to control the formatting generally and with specific column formatters.\n",
    "\n",
    "[styler]: ../reference/api/pandas.io.formats.style.Styler.rst\n",
    "[format]: https://docs.python.org/3/library/string.html#format-specification-mini-language\n",
    "[formatfunc]: ../reference/api/pandas.io.formats.style.Styler.format.rst"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.style.format(precision=0, na_rep='MISSING', \n",
    "                formatter={('Decision Tree', 'Tumour'): \"{:.2f}\",\n",
    "                           ('Regression', 'Non-Tumour'): lambda x: \"$ {:,.1f}\".format(x*-1e3)\n",
    "                          })"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Hiding Data\n",
    "\n",
    "The index can be hidden from rendering by calling [.hide_index()][hideidx], which might be useful if your index is integer based.\n",
    "\n",
    "Columns can be hidden from rendering by calling [.hide_columns()][hidecols] and passing in the name of a column, or a slice of columns.\n",
    "\n",
    "Hiding does not change the integer arrangement of CSS classes, e.g. hiding the first two columns of a DataFrame means the column class indexing will start at `col2`, since `col0` and `col1` are simply ignored.\n",
    "\n",
    "We can update our `Styler` object to hide some data and format the values.\n",
    "\n",
    "[hideidx]: ../reference/api/pandas.io.formats.style.Styler.hide_index.rst\n",
    "[hidecols]: ../reference/api/pandas.io.formats.style.Styler.hide_columns.rst"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s = df.style.format('{:.0f}').hide_columns([('Random', 'Tumour'), ('Random', 'Non-Tumour')])\n",
    "s"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Hidden cell to avoid CSS clashes and latter code upcoding previous formatting \n",
    "s.set_uuid('after_hide')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Methods to Add Styles\n",
    "\n",
    "There are **3 primary methods of adding custom CSS styles** to [Styler][styler]:\n",
    "\n",
    "- Using [.set_table_styles()][table] to control broader areas of the table with specified internal CSS. Although table styles allow the flexibility to add CSS selectors and properties controlling all individual parts of the table, they are unwieldy for individual cell specifications. Also, note that table styles cannot be exported to Excel. \n",
    "- Using [.set_td_classes()][td_class] to directly link either external CSS classes to your data cells or link the internal CSS classes created by [.set_table_styles()][table]. See [here](#Setting-Classes-and-Linking-to-External-CSS). These cannot be used on column header rows or indexes, and also won't export to Excel. \n",
    "- Using the [.apply()][apply] and [.applymap()][applymap] functions to add direct internal CSS to specific data cells. See [here](#Styler-Functions). These cannot be used on column header rows or indexes, but only these methods add styles that will export to Excel. These methods work in a similar way to [DataFrame.apply()][dfapply] and [DataFrame.applymap()][dfapplymap].\n",
    "\n",
    "[table]: ../reference/api/pandas.io.formats.style.Styler.set_table_styles.rst\n",
    "[styler]: ../reference/api/pandas.io.formats.style.Styler.rst\n",
    "[td_class]: ../reference/api/pandas.io.formats.style.Styler.set_td_classes.rst\n",
    "[apply]: ../reference/api/pandas.io.formats.style.Styler.apply.rst\n",
    "[applymap]: ../reference/api/pandas.io.formats.style.Styler.applymap.rst\n",
    "[dfapply]: ../reference/api/pandas.DataFrame.apply.rst\n",
    "[dfapplymap]: ../reference/api/pandas.DataFrame.applymap.rst"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Table Styles\n",
    "\n",
    "Table styles are flexible enough to control all individual parts of the table, including column headers and indexes. \n",
    "However, they can be unwieldy to type for individual data cells or for any kind of conditional formatting, so we recommend that table styles are used for broad styling, such as entire rows or columns at a time.\n",
    "\n",
    "Table styles are also used to control features which can apply to the whole table at once such as creating a generic hover functionality. The `:hover` pseudo-selector, as well as other pseudo-selectors, can only be used this way.\n",
    "\n",
    "To replicate the normal format of CSS selectors and properties (attribute value pairs), e.g. \n",
    "\n",
    "```\n",
    "tr:hover {\n",
    "  background-color: #ffff99;\n",
    "}\n",
    "```\n",
    "\n",
    "the necessary format to pass styles to [.set_table_styles()][table] is as a list of dicts, each with a CSS-selector tag and CSS-properties. Properties can either be a list of 2-tuples, or a regular CSS-string, for example:\n",
    "\n",
    "[table]: ../reference/api/pandas.io.formats.style.Styler.set_table_styles.rst"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cell_hover = {  # for row hover use <tr> instead of <td>\n",
    "    'selector': 'td:hover',\n",
    "    'props': [('background-color', '#ffffb3')]\n",
    "}\n",
    "index_names = {\n",
    "    'selector': '.index_name',\n",
    "    'props': 'font-style: italic; color: darkgrey; font-weight:normal;'\n",
    "}\n",
    "headers = {\n",
    "    'selector': 'th:not(.index_name)',\n",
    "    'props': 'background-color: #000066; color: white;'\n",
    "}\n",
    "s.set_table_styles([cell_hover, index_names, headers])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Hidden cell to avoid CSS clashes and latter code upcoding previous formatting \n",
    "s.set_uuid('after_tab_styles1')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next we just add a couple more styling artifacts targeting specific parts of the table. Be careful here, since we are *chaining methods* we need to explicitly instruct the method **not to** ``overwrite`` the existing styles."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.set_table_styles([\n",
    "    {'selector': 'th.col_heading', 'props': 'text-align: center;'},\n",
    "    {'selector': 'th.col_heading.level0', 'props': 'font-size: 1.5em;'},\n",
    "    {'selector': 'td', 'props': 'text-align: center; font-weight: bold;'},\n",
    "], overwrite=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Hidden cell to avoid CSS clashes and latter code upcoding previous formatting \n",
    "s.set_uuid('after_tab_styles2')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As a convenience method (*since version 1.2.0*) we can also pass a **dict** to [.set_table_styles()][table] which contains row or column keys. Behind the scenes Styler just indexes the keys and adds relevant `.col<m>` or `.row<n>` classes as necessary to the given CSS selectors.\n",
    "\n",
    "[table]: ../reference/api/pandas.io.formats.style.Styler.set_table_styles.rst"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.set_table_styles({\n",
    "    ('Regression', 'Tumour'): [{'selector': 'th', 'props': 'border-left: 1px solid white'},\n",
    "                               {'selector': 'td', 'props': 'border-left: 1px solid #000066'}]\n",
    "}, overwrite=False, axis=0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Hidden cell to avoid CSS clashes and latter code upcoding previous formatting \n",
    "s.set_uuid('xyz01')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setting Classes and Linking to External CSS\n",
    "\n",
    "If you have designed a website then it is likely you will already have an external CSS file that controls the styling of table and cell objects within it. You may want to use these native files rather than duplicate all the CSS in python (and duplicate any maintenance work).\n",
    "\n",
    "### Table Attributes\n",
    "\n",
    "It is very easy to add a `class` to the main `<table>` using [.set_table_attributes()][tableatt]. This method can also attach inline styles - read more in [CSS Hierarchies](#CSS-Hierarchies).\n",
    "\n",
    "[tableatt]: ../reference/api/pandas.io.formats.style.Styler.set_table_attributes.rst"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "out = s.set_table_attributes('class=\"my-table-cls\"').render()\n",
    "print(out[out.find('<table'):][:109])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Data Cell CSS Classes\n",
    "\n",
    "*New in version 1.2.0*\n",
    "\n",
    "The [.set_td_classes()][tdclass] method accepts a DataFrame with matching indices and columns to the underlying [Styler][styler]'s DataFrame. That DataFrame will contain strings as css-classes to add to individual data cells: the `<td>` elements of the `<table>`. Rather than use external CSS we will create our classes internally and add them to table style. We will save adding the borders until the [section on tooltips](#Tooltips).\n",
    "\n",
    "[tdclass]: ../reference/api/pandas.io.formats.style.Styler.set_td_classes.rst\n",
    "[styler]: ../reference/api/pandas.io.formats.style.Styler.rst"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.set_table_styles([  # create internal CSS classes\n",
    "    {'selector': '.true', 'props': 'background-color: #e6ffe6;'},\n",
    "    {'selector': '.false', 'props': 'background-color: #ffe6e6;'},\n",
    "], overwrite=False)\n",
    "cell_color = pd.DataFrame([['true ', 'false ', 'true ', 'false '], \n",
    "                           ['false ', 'true ', 'false ', 'true ']], \n",
    "                          index=df.index, \n",
    "                          columns=df.columns[:4])\n",
    "s.set_td_classes(cell_color)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Hidden cell to avoid CSS clashes and latter code upcoding previous formatting \n",
    "s.set_uuid('after_classes')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Styler Functions\n",
    "\n",
    "We use the following methods to pass your style functions. Both of those methods take a function (and some other keyword arguments) and apply it to the DataFrame in a certain way, rendering CSS styles.\n",
    "\n",
    "- [.applymap()][applymap] (elementwise): accepts a function that takes a single value and returns a string with the CSS attribute-value pair.\n",
    "- [.apply()][apply] (column-/row-/table-wise): accepts a function that takes a Series or DataFrame and returns a Series, DataFrame, or numpy array with an identical shape where each element is a string with a CSS attribute-value pair. This method passes each column or row of your DataFrame one-at-a-time or the entire table at once, depending on the `axis` keyword argument. For columnwise use `axis=0`, rowwise use `axis=1`, and for the entire table at once use `axis=None`.\n",
    "\n",
    "This method is powerful for applying multiple, complex logic to data cells. We create a new DataFrame to demonstrate this.\n",
    "\n",
    "[apply]: ../reference/api/pandas.io.formats.style.Styler.apply.rst\n",
    "[applymap]: ../reference/api/pandas.io.formats.style.Styler.applymap.rst"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.random.seed(0)\n",
    "df2 = pd.DataFrame(np.random.randn(10,4), columns=['A','B','C','D'])\n",
    "df2.style"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example we can build a function that colors text if it is negative, and chain this with a function that partially fades cells of negligible value. Since this looks at each element in turn we use ``applymap``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def style_negative(v, props=''):\n",
    "    return props if v < 0 else None\n",
    "s2 = df2.style.applymap(style_negative, props='color:red;')\\\n",
    "              .applymap(lambda v: 'opacity: 20%;' if (v < 0.3) and (v > -0.3) else None)\n",
    "s2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Hidden cell to avoid CSS clashes and latter code upcoding previous formatting \n",
    "s2.set_uuid('after_applymap')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also build a function that highlights the maximum value across rows, cols, and the DataFrame all at once. In this case we use ``apply``. Below we highlight the maximum in a column."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def highlight_max(s, props=''):\n",
    "    return np.where(s == np.nanmax(s.values), props, '')\n",
    "s2.apply(highlight_max, props='color:white;background-color:darkblue', axis=0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Hidden cell to avoid CSS clashes and latter code upcoding previous formatting \n",
    "s2.set_uuid('after_apply')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can use the same function across the different axes, highlighting here the DataFrame maximum in purple, and row maximums in pink."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s2.apply(highlight_max, props='color:white;background-color:pink;', axis=1)\\\n",
    "  .apply(highlight_max, props='color:white;background-color:purple', axis=None)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This last example shows how some styles have been overwritten by others. In general the most recent style applied is active but you can read more in the [section on CSS hierarchies](#CSS-Hierarchies). You can also apply these styles to more granular parts of the DataFrame - read more in section on [subset slicing](#Finer-Control-with-Slicing).\n",
    "\n",
    "It is possible to replicate some of this functionality using just classes but it can be more cumbersome. See [item 3)  of Optimization](#Optimization)\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "*Debugging Tip*: If you're having trouble writing your style function, try just passing it into ``DataFrame.apply``. Internally, ``Styler.apply`` uses ``DataFrame.apply`` so the result should be the same, and with ``DataFrame.apply`` you will be able to inspect the CSS string output of your intended function in each cell.\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tooltips and Captions\n",
    "\n",
    "Table captions can be added with the [.set_caption()][caption] method. You can use table styles to control the CSS relevant to the caption.\n",
    "\n",
    "[caption]: ../reference/api/pandas.io.formats.style.Styler.set_caption.rst"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.set_caption(\"Confusion matrix for multiple cancer prediction models.\")\\\n",
    " .set_table_styles([{\n",
    "     'selector': 'caption',\n",
    "     'props': 'caption-side: bottom; font-size:1.25em;'\n",
    " }], overwrite=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Hidden cell to avoid CSS clashes and latter code upcoding previous formatting \n",
    "s.set_uuid('after_caption')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Adding tooltips (*since version 1.3.0*) can be done using the [.set_tooltips()][tooltips] method in the same way you can add CSS classes to data cells by providing a string based DataFrame with intersecting indices and columns. You don't have to specify a `css_class` name or any css `props` for the tooltips, since there are standard defaults, but the option is there if you want more visual control. \n",
    "\n",
    "[tooltips]: ../reference/api/pandas.io.formats.style.Styler.set_tooltips.rst"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tt = pd.DataFrame([['This model has a very strong true positive rate', \n",
    "                    \"This model's total number of false negatives is too high\"]], \n",
    "                  index=['Tumour (Positive)'], columns=df.columns[[0,3]])\n",
    "s.set_tooltips(tt, props='visibility: hidden; position: absolute; z-index: 1; border: 1px solid #000066;'\n",
    "                         'background-color: white; color: #000066; font-size: 0.8em;' \n",
    "                         'transform: translate(0px, -24px); padding: 0.6em; border-radius: 0.5em;')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Hidden cell to avoid CSS clashes and latter code upcoding previous formatting \n",
    "s.set_uuid('after_tooltips')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The only thing left to do for our table is to add the highlighting borders to draw the audience attention to the tooltips. We will create internal CSS classes as before using table styles. **Setting classes always overwrites** so we need to make sure we add the previous classes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.set_table_styles([  # create internal CSS classes\n",
    "    {'selector': '.border-red', 'props': 'border: 2px dashed red;'},\n",
    "    {'selector': '.border-green', 'props': 'border: 2px dashed green;'},\n",
    "], overwrite=False)\n",
    "cell_border = pd.DataFrame([['border-green ', ' ', ' ', 'border-red '], \n",
    "                           [' ', ' ', ' ', ' ']], \n",
    "                          index=df.index, \n",
    "                          columns=df.columns[:4])\n",
    "s.set_td_classes(cell_color + cell_border)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Hidden cell to avoid CSS clashes and latter code upcoding previous formatting \n",
    "s.set_uuid('after_borders')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Finer Control with Slicing\n",
    "\n",
    "The examples we have shown so far for the `Styler.apply` and `Styler.applymap` functions have not demonstrated the use of the ``subset`` argument. This is a useful argument which permits a lot of flexibility: it allows you to apply styles to specific rows or columns, without having to code that logic into your `style` function.\n",
    "\n",
    "The value passed to `subset` behaves similar to slicing a DataFrame;\n",
    "\n",
    "- A scalar is treated as a column label\n",
    "- A list (or Series or NumPy array) is treated as multiple column labels\n",
    "- A tuple is treated as `(row_indexer, column_indexer)`\n",
    "\n",
    "Consider using `pd.IndexSlice` to construct the tuple for the last one. We will create a MultiIndexed DataFrame to demonstrate the functionality."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df3 = pd.DataFrame(np.random.randn(4,4), \n",
    "                   pd.MultiIndex.from_product([['A', 'B'], ['r1', 'r2']]),\n",
    "                   columns=['c1','c2','c3','c4'])\n",
    "df3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will use subset to highlight the maximum in the third and fourth columns with red text. We will highlight the subset sliced region in yellow."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "slice_ = ['c3', 'c4']\n",
    "df3.style.apply(highlight_max, props='color:red;', axis=0, subset=slice_)\\\n",
    "         .set_properties(**{'background-color': '#ffffb3'}, subset=slice_)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If combined with the ``IndexSlice`` as suggested then it can index across both dimensions with greater flexibility."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "idx = pd.IndexSlice\n",
    "slice_ = idx[idx[:,'r1'], idx['c2':'c4']]\n",
    "df3.style.apply(highlight_max, props='color:red;', axis=0, subset=slice_)\\\n",
    "         .set_properties(**{'background-color': '#ffffb3'}, subset=slice_)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This also provides the flexibility to sub select rows when used with the `axis=1`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "slice_ = idx[idx[:,'r2'], :]\n",
    "df3.style.apply(highlight_max, props='color:red;', axis=1, subset=slice_)\\\n",
    "         .set_properties(**{'background-color': '#ffffb3'}, subset=slice_)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There is also scope to provide **conditional filtering**. \n",
    "\n",
    "Suppose we want to highlight the maximum across columns 2 and 4 only in the case that the sum of columns 1 and 3 is less than -2.0 *(essentially excluding rows* `(:,'r2')`*)*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "slice_ = idx[idx[(df3['c1'] + df3['c3']) < -2.0], ['c2', 'c4']]\n",
    "df3.style.apply(highlight_max, props='color:red;', axis=1, subset=slice_)\\\n",
    "         .set_properties(**{'background-color': '#ffffb3'}, subset=slice_)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Only label-based slicing is supported right now, not positional, and not callables.\n",
    "\n",
    "If your style function uses a `subset` or `axis` keyword argument, consider wrapping your function in a `functools.partial`, partialing out that keyword.\n",
    "\n",
    "```python\n",
    "my_func2 = functools.partial(my_func, subset=42)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Optimization\n",
    "\n",
    "Generally, for smaller tables and most cases, the rendered HTML does not need to be optimized, and we don't really recommend it. There are two cases where it is worth considering:\n",
    "\n",
    " - If you are rendering and styling a very large HTML table, certain browsers have performance issues.\n",
    " - If you are using ``Styler`` to dynamically create part of online user interfaces and want to improve network performance.\n",
    " \n",
    "Here we recommend the following steps to implement:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1. Remove UUID and cell_ids\n",
    "\n",
    "Ignore the `uuid` and set `cell_ids` to `False`. This will prevent unnecessary HTML."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "<font color=red>This is sub-optimal:</font>\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df4 = pd.DataFrame([[1,2],[3,4]])\n",
    "s4 = df4.style"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "\n",
    "<font color=green>This is better:</font>\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pandas.io.formats.style import Styler\n",
    "s4 = Styler(df4, uuid_len=0, cell_ids=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2. Use table styles\n",
    "\n",
    "Use table styles where possible (e.g. for all cells or rows or columns at a time) since the CSS is nearly always more efficient than other formats."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "<font color=red>This is sub-optimal:</font>\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "props = 'font-family: \"Times New Roman\", Times, serif; color: #e83e8c; font-size:1.3em;'\n",
    "df4.style.applymap(lambda x: props, subset=[1])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "\n",
    "<font color=green>This is better:</font>\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df4.style.set_table_styles([{'selector': 'td.col1', 'props': props}])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3. Set classes instead of using Styler functions\n",
    "\n",
    "For large DataFrames where the same style is applied to many cells it can be more efficient to declare the styles as classes and then apply those classes to data cells, rather than directly applying styles to cells. It is, however, probably still easier to use the Styler function api when you are not concerned about optimization."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "<font color=red>This is sub-optimal:</font>\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df2.style.apply(highlight_max, props='color:white;background-color:darkblue;', axis=0)\\\n",
    "         .apply(highlight_max, props='color:white;background-color:pink;', axis=1)\\\n",
    "         .apply(highlight_max, props='color:white;background-color:purple', axis=None)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "\n",
    "<font color=green>This is better:</font>\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "build = lambda x: pd.DataFrame(x, index=df2.index, columns=df2.columns)\n",
    "cls1 = build(df2.apply(highlight_max, props='cls-1 ', axis=0))\n",
    "cls2 = build(df2.apply(highlight_max, props='cls-2 ', axis=1, result_type='expand').values)\n",
    "cls3 = build(highlight_max(df2, props='cls-3 '))\n",
    "df2.style.set_table_styles([\n",
    "    {'selector': '.cls-1', 'props': 'color:white;background-color:darkblue;'},\n",
    "    {'selector': '.cls-2', 'props': 'color:white;background-color:pink;'},\n",
    "    {'selector': '.cls-3', 'props': 'color:white;background-color:purple;'}\n",
    "]).set_td_classes(cls1 + cls2 + cls3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4. Don't use tooltips\n",
    "\n",
    "Tooltips require `cell_ids` to work and they generate extra HTML elements for *every* data cell."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5. If every byte counts use string replacement\n",
    "\n",
    "You can remove unnecessary HTML, or shorten the default class names with string replace functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "html = Styler(df4, uuid_len=0, cell_ids=False)\\\n",
    "      .set_table_styles([{'selector': 'td', 'props': props},\n",
    "                         {'selector': '.col1', 'props': 'color:green;'},\n",
    "                         {'selector': '.level0', 'props': 'color:blue;'}])\\\n",
    "      .render()\\\n",
    "      .replace('blank', '')\\\n",
    "      .replace('data', '')\\\n",
    "      .replace('level0', 'l0')\\\n",
    "      .replace('col_heading', '')\\\n",
    "      .replace('row_heading', '')\n",
    "\n",
    "import re\n",
    "html = re.sub(r'col[0-9]+', lambda x: x.group().replace('col', 'c'), html)\n",
    "html = re.sub(r'row[0-9]+', lambda x: x.group().replace('row', 'r'), html)\n",
    "print(html)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import HTML\n",
    "HTML(html)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Builtin Styles"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We expect certain styling functions to be common enough that we've included a few \"built-in\" to the `Styler`, so you don't have to write them yourself."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df2.iloc[0,2] = np.nan\n",
    "df2.iloc[4,3] = np.nan\n",
    "df2.loc[:4].style.highlight_null(null_color='red')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can create \"heatmaps\" with the `background_gradient` method. These require matplotlib, and we'll use [Seaborn](https://stanford.edu/~mwaskom/software/seaborn/) to get a nice colormap."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import seaborn as sns\n",
    "cm = sns.light_palette(\"green\", as_cmap=True)\n",
    "\n",
    "df2.style.background_gradient(cmap=cm)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`Styler.background_gradient` takes the keyword arguments `low` and `high`. Roughly speaking these extend the range of your data by `low` and `high` percent so that when we convert the colors, the colormap's entire range isn't used. This is useful so that you can actually read the text still."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Uses the full color range\n",
    "df2.loc[:4].style.background_gradient(cmap='viridis')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Compress the color range\n",
    "df2.loc[:4].style\\\n",
    "   .background_gradient(cmap='viridis', low=.5, high=0)\\\n",
    "   .highlight_null('red')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There's also `.highlight_min` and `.highlight_max`, which is almost identical to the user defined version we created above, and also a `.highlight_null` method. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df2.loc[:4].style.highlight_max(axis=0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use `Styler.set_properties` when the style doesn't actually depend on the values. This is just a simple wrapper for `.applymap` where the function returns the same properties for all cells."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df2.loc[:4].style.set_properties(**{'background-color': 'black',\n",
    "                           'color': 'lawngreen',\n",
    "                           'border-color': 'white'})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Bar charts"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can include \"bar charts\" in your DataFrame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df2.style.bar(subset=['A', 'B'], color='#d65f5f')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In version 0.20.0 the ability to customize the bar chart further was given. You can now have the `df.style.bar` be centered on zero or midpoint value (in addition to the already existing way of having the min value at the left side of the cell), and you can pass a list of `[color_negative, color_positive]`.\n",
    "\n",
    "Here's how you can change the above with the new `align='mid'` option:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df2.style.bar(subset=['A', 'B'], align='mid', color=['#d65f5f', '#5fba7d'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following example aims to give a highlight of the behavior of the new align options:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Hide the construction of the display chart from the user\n",
    "import pandas as pd\n",
    "from IPython.display import HTML\n",
    "\n",
    "# Test series\n",
    "test1 = pd.Series([-100,-60,-30,-20], name='All Negative')\n",
    "test2 = pd.Series([10,20,50,100], name='All Positive')\n",
    "test3 = pd.Series([-10,-5,0,90], name='Both Pos and Neg')\n",
    "\n",
    "head = \"\"\"\n",
    "<table>\n",
    "    <thead>\n",
    "        <th>Align</th>\n",
    "        <th>All Negative</th>\n",
    "        <th>All Positive</th>\n",
    "        <th>Both Neg and Pos</th>\n",
    "    </thead>\n",
    "    </tbody>\n",
    "\n",
    "\"\"\"\n",
    "\n",
    "aligns = ['left','zero','mid']\n",
    "for align in aligns:\n",
    "    row = \"<tr><th>{}</th>\".format(align)\n",
    "    for series in [test1,test2,test3]:\n",
    "        s = series.copy()\n",
    "        s.name=''\n",
    "        row += \"<td>{}</td>\".format(s.to_frame().style.bar(align=align, \n",
    "                                                           color=['#d65f5f', '#5fba7d'], \n",
    "                                                           width=100).render()) #testn['width']\n",
    "    row += '</tr>'\n",
    "    head += row\n",
    "    \n",
    "head+= \"\"\"\n",
    "</tbody>\n",
    "</table>\"\"\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "HTML(head)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sharing styles"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Say you have a lovely style built up for a DataFrame, and now you want to apply the same style to a second DataFrame. Export the style with `df1.style.export`, and import it on the second DataFrame with `df1.style.set`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "style1 = df2.style.applymap(style_negative, props='color:red;')\\\n",
    "         .applymap(lambda v: 'opacity: 20%;' if (v < 0.3) and (v > -0.3) else None)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "style2 = df3.style\n",
    "style2.use(style1.export())\n",
    "style2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that you're able to share the styles even though they're data aware. The styles are re-evaluated on the new DataFrame they've been `use`d upon."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Limitations\n",
    "\n",
    "- DataFrame only `(use Series.to_frame().style)`\n",
    "- The index and columns must be unique\n",
    "- No large repr, and construction performance isn't great; although we have some [HTML optimizations](#Optimization)\n",
    "- You can only style the *values*, not the index or columns (except with `table_styles` above)\n",
    "- You can only apply styles, you can't insert new HTML entities\n",
    "\n",
    "Some of these might be addressed in the future. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other Fun and Useful Stuff\n",
    "\n",
    "Here are a few interesting examples."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Widgets\n",
    "\n",
    "`Styler` interacts pretty well with widgets. If you're viewing this online instead of running the notebook yourself, you're missing out on interactively adjusting the color palette."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ipywidgets import widgets\n",
    "@widgets.interact\n",
    "def f(h_neg=(0, 359, 1), h_pos=(0, 359), s=(0., 99.9), l=(0., 99.9)):\n",
    "    return df2.style.background_gradient(\n",
    "        cmap=sns.palettes.diverging_palette(h_neg=h_neg, h_pos=h_pos, s=s, l=l,\n",
    "                                            as_cmap=True)\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Magnify"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def magnify():\n",
    "    return [dict(selector=\"th\",\n",
    "                 props=[(\"font-size\", \"4pt\")]),\n",
    "            dict(selector=\"td\",\n",
    "                 props=[('padding', \"0em 0em\")]),\n",
    "            dict(selector=\"th:hover\",\n",
    "                 props=[(\"font-size\", \"12pt\")]),\n",
    "            dict(selector=\"tr:hover td:hover\",\n",
    "                 props=[('max-width', '200px'),\n",
    "                        ('font-size', '12pt')])\n",
    "]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.random.seed(25)\n",
    "cmap = cmap=sns.diverging_palette(5, 250, as_cmap=True)\n",
    "bigdf = pd.DataFrame(np.random.randn(20, 25)).cumsum()\n",
    "\n",
    "bigdf.style.background_gradient(cmap, axis=1)\\\n",
    "    .set_properties(**{'max-width': '80px', 'font-size': '1pt'})\\\n",
    "    .set_caption(\"Hover to magnify\")\\\n",
    "    .format(precision=2)\\\n",
    "    .set_table_styles(magnify())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Sticky Headers\n",
    "\n",
    "If you display a large matrix or DataFrame in a notebook, but you want to always see the column and row headers you can use the following CSS to make them stick. We might make this into an API function later."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bigdf = pd.DataFrame(np.random.randn(15, 100))\n",
    "bigdf.style.set_table_styles([\n",
    "    {'selector': 'thead th', 'props': 'position: sticky; top:0; background-color:salmon;'},\n",
    "    {'selector': 'tbody th', 'props': 'position: sticky; left:0; background-color:lightgreen;'}  \n",
    "])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Hiding Headers\n",
    "\n",
    "We don't yet have any API to hide headers so a quick fix is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df3.style.set_table_styles([{'selector': 'thead tr', 'props': 'display: none;'}])  # or 'thead th'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### HTML Escaping\n",
    "\n",
    "Suppose you have to display HTML within HTML, that can be a bit of pain when the renderer can't distinguish. You can use the `escape` formatting option to handle this, and even use it within a formatter that contains HTML itself."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df4 = pd.DataFrame([['<div></div>', '\"&other\"', '<span></span>']])\n",
    "df4.style"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df4.style.format(escape=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df4.style.format('<a href=\"https://pandas.pydata.org\" target=\"_blank\">{}</a>', escape=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Export to Excel\n",
    "\n",
    "Some support (*since version 0.20.0*) is available for exporting styled `DataFrames` to Excel worksheets using the `OpenPyXL` or `XlsxWriter` engines. CSS2.2 properties handled include:\n",
    "\n",
    "- `background-color`\n",
    "- `color`\n",
    "- `font-family`\n",
    "- `font-style`\n",
    "- `font-weight`\n",
    "- `text-align`\n",
    "- `text-decoration`\n",
    "- `vertical-align`\n",
    "- `white-space: nowrap`\n",
    "\n",
    "\n",
    "- Currently broken: `border-style`, `border-width`, `border-color` and their {`top`, `right`, `bottom`, `left` variants}\n",
    "\n",
    "\n",
    "- Only CSS2 named colors and hex colors of the form `#rgb` or `#rrggbb` are currently supported.\n",
    "- The following pseudo CSS properties are also available to set excel specific style properties:\n",
    "    - `number-format`\n",
    "\n",
    "Table level styles, and data cell CSS-classes are not included in the export to Excel: individual cells must have their properties mapped by the `Styler.apply` and/or `Styler.applymap` methods."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df2.style.\\\n",
    "    applymap(style_negative, props='color:red;').\\\n",
    "    highlight_max(axis=0).\\\n",
    "    to_excel('styled.xlsx', engine='openpyxl')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A screenshot of the output:\n",
    "\n",
    "![Excel spreadsheet with styled DataFrame](../_static/style-excel.png)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## More About CSS and HTML\n",
    "\n",
    "Cascading Style Sheet (CSS) language, which is designed to influence how a browser renders HTML elements, has its own peculiarities. It never reports errors: it just silently ignores them and doesn't render your objects how you intend so can sometimes be frustrating. Here is a very brief primer on how ``Styler`` creates HTML and interacts with CSS, with advice on common pitfalls to avoid."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### CSS Classes and Ids\n",
    "\n",
    "The precise structure of the CSS `class` attached to each cell is as follows.\n",
    "\n",
    "- Cells with Index and Column names include `index_name` and `level<k>` where `k` is its level in a MultiIndex\n",
    "- Index label cells include\n",
    "  + `row_heading`\n",
    "  + `level<k>` where `k` is the level in a MultiIndex\n",
    "  + `row<m>` where `m` is the numeric position of the row\n",
    "- Column label cells include\n",
    "  + `col_heading`\n",
    "  + `level<k>` where `k` is the level in a MultiIndex\n",
    "  + `col<n>` where `n` is the numeric position of the column\n",
    "- Data cells include\n",
    "  + `data`\n",
    "  + `row<m>`, where `m` is the numeric position of the cell.\n",
    "  + `col<n>`, where `n` is the numeric position of the cell.\n",
    "- Blank cells include `blank`\n",
    "\n",
    "The structure of the `id` is `T_uuid_level<k>_row<m>_col<n>` where `level<k>` is used only on headings, and headings will only have either `row<m>` or `col<n>` whichever is needed. By default we've also prepended each row/column identifier with a UUID unique to each DataFrame so that the style from one doesn't collide with the styling from another within the same notebook or page. You can read more about the use of UUIDs in [Optimization](#Optimization).\n",
    "\n",
    "We can see example of the HTML by calling the [.render()][render] method.\n",
    "\n",
    "[render]: ../reference/api/pandas.io.formats.style.Styler.render.rst"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(pd.DataFrame([[1,2],[3,4]], index=['i1', 'i2'], columns=['c1', 'c2']).style.render())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### CSS Hierarchies\n",
    "\n",
    "The examples have shown that when CSS styles overlap, the one that comes last in the HTML render, takes precedence. So the following yield different results:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df4 = pd.DataFrame([['text']])\n",
    "df4.style.applymap(lambda x: 'color:green;')\\\n",
    "         .applymap(lambda x: 'color:red;')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df4.style.applymap(lambda x: 'color:red;')\\\n",
    "         .applymap(lambda x: 'color:green;')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is only true for CSS rules that are equivalent in hierarchy, or importance. You can read more about [CSS specificity here](https://www.w3schools.com/css/css_specificity.asp) but for our purposes it suffices to summarize the key points:\n",
    "\n",
    "A CSS importance score for each HTML element is derived by starting at zero and adding:\n",
    "\n",
    " - 1000 for an inline style attribute\n",
    " - 100 for each ID\n",
    " - 10 for each attribute, class or pseudo-class\n",
    " - 1 for each element name or pseudo-element\n",
    " \n",
    "Let's use this to describe the action of the following configurations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df4.style.set_uuid('a_')\\\n",
    "         .set_table_styles([{'selector': 'td', 'props': 'color:red;'}])\\\n",
    "         .applymap(lambda x: 'color:green;')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This text is red because the generated selector `#T_a_ td` is worth 101 (ID plus element), whereas `#T_a_row0_col0` is only worth 100 (ID), so is considered inferior even though in the HTML it comes after the previous."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df4.style.set_uuid('b_')\\\n",
    "         .set_table_styles([{'selector': 'td', 'props': 'color:red;'},\n",
    "                            {'selector': '.cls-1', 'props': 'color:blue;'}])\\\n",
    "         .applymap(lambda x: 'color:green;')\\\n",
    "         .set_td_classes(pd.DataFrame([['cls-1']]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the above case the text is blue because the selector `#T_b_ .cls-1` is worth 110 (ID plus class), which takes precendence."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df4.style.set_uuid('c_')\\\n",
    "         .set_table_styles([{'selector': 'td', 'props': 'color:red;'},\n",
    "                            {'selector': '.cls-1', 'props': 'color:blue;'},\n",
    "                            {'selector': 'td.data', 'props': 'color:yellow;'}])\\\n",
    "         .applymap(lambda x: 'color:green;')\\\n",
    "         .set_td_classes(pd.DataFrame([['cls-1']]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we have created another table style this time the selector `T_c_ td.data` (ID plus element plus class) gets bumped up to 111. \n",
    "\n",
    "If your style fails to be applied, and its really frustrating, try the `!important` trump card."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df4.style.set_uuid('d_')\\\n",
    "         .set_table_styles([{'selector': 'td', 'props': 'color:red;'},\n",
    "                            {'selector': '.cls-1', 'props': 'color:blue;'},\n",
    "                            {'selector': 'td.data', 'props': 'color:yellow;'}])\\\n",
    "         .applymap(lambda x: 'color:green !important;')\\\n",
    "         .set_td_classes(pd.DataFrame([['cls-1']]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally got that green text after all!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Extensibility\n",
    "\n",
    "The core of pandas is, and will remain, its \"high-performance, easy-to-use data structures\".\n",
    "With that in mind, we hope that `DataFrame.style` accomplishes two goals\n",
    "\n",
    "- Provide an API that is pleasing to use interactively and is \"good enough\" for many tasks\n",
    "- Provide the foundations for dedicated libraries to build on\n",
    "\n",
    "If you build a great library on top of this, let us know and we'll [link](https://pandas.pydata.org/pandas-docs/stable/ecosystem.html) to it.\n",
    "\n",
    "### Subclassing\n",
    "\n",
    "If the default template doesn't quite suit your needs, you can subclass Styler and extend or override the template.\n",
    "We'll show an example of extending the default template to insert a custom header before each table."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from jinja2 import Environment, ChoiceLoader, FileSystemLoader\n",
    "from IPython.display import HTML\n",
    "from pandas.io.formats.style import Styler"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We'll use the following template:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with open(\"templates/myhtml.tpl\") as f:\n",
    "    print(f.read())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that we've created a template, we need to set up a subclass of ``Styler`` that\n",
    "knows about it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class MyStyler(Styler):\n",
    "    env = Environment(\n",
    "        loader=ChoiceLoader([\n",
    "            FileSystemLoader(\"templates\"),  # contains ours\n",
    "            Styler.loader,  # the default\n",
    "        ])\n",
    "    )\n",
    "    template_html = env.get_template(\"myhtml.tpl\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that we include the original loader in our environment's loader.\n",
    "That's because we extend the original template, so the Jinja environment needs\n",
    "to be able to find it.\n",
    "\n",
    "Now we can use that custom styler. It's `__init__` takes a DataFrame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "MyStyler(df3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Our custom template accepts a `table_title` keyword. We can provide the value in the `.render` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "HTML(MyStyler(df3).render(table_title=\"Extending Example\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For convenience, we provide the `Styler.from_custom_template` method that does the same as the custom subclass."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "EasyStyler = Styler.from_custom_template(\"templates\", \"myhtml.tpl\")\n",
    "EasyStyler(df3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here's the template structure:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with open(\"templates/template_structure.html\") as f:\n",
    "    structure = f.read()\n",
    "    \n",
    "HTML(structure)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See the template in the [GitHub repo](https://github.com/pandas-dev/pandas) for more details."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# # Hack to get the same style in the notebook as the\n",
    "# # main site. This is hidden in the docs.\n",
    "# from IPython.display import HTML\n",
    "# with open(\"themes/nature_with_gtoc/static/nature.css_t\") as f:\n",
    "#     css = f.read()\n",
    "    \n",
    "# HTML('<style>{}</style>'.format(css))"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}