{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# User Guide\n",
    "\n",
    "## Accessing the colormaps\n",
    "\n",
    "After importing `colorcet` as `cc`, all the colormaps shown in this notebook will be available for use in different forms. It's a bit difficult to describe, but the idea is that colorcet should have at least one such form convenient for any particular application.  There are three distinct versions for each colormap, each of which consists of 256 distinct colors: \n",
    "\n",
    "1. An ordered list of normalized RGB triples of numerical magnitudes. I.e., each color is represented as a tuple of three numbers, each between 0 and 1.0, such as `[1, 0.54028, 0.0002582]`\n",
    "2. A Bokeh-style palette, i.e., a Python list of RGB colors as hex strings, like ``['#000000', ..., '#ffffff']``\n",
    "3. If matplotlib is installed and importable, a Matplotlib ``LinearSegmentedColormap`` (for continuous maps) or ``ListedColormap`` (for categorical maps), using normalized magnitudes, like ``LinearSegmentedColormap.from_list(\"fire\",[ [0.0,0.0,0.0], ..., [1.0,1.0,1.0] ], 256)``\n",
    "\n",
    "The numerical lists are the original format, useful if you want to access the underlying numerical values. These are available as attributes in the ``colorcet`` namespace as full names with no prefix, e.g. ``cc.linear_kryw_0_100_c71`` or ``cc.glasbey_bw``.\n",
    "\n",
    "The Bokeh-compatible hex-string palettes are provided as attributes in the ``colorcet`` namespace as long names prefixed with ``b_``.  E.g. ``linear_kryw_0_100_c71`` can be accessed as ``cc.b_linear_kryw_0_100_c71``. The same Bokeh palette is also sometimes available with a shorter name like ``cc.fire``, which is the same object as ``cc.b_linear_kryw_0_100_c71``. These names should tab complete once ``cc`` has been imported. Because Bokeh palettes are just Python lists, you can always reverse them using normal Python syntax, e.g. ``list(reversed(cc.fire))``, or use subsets of them with slice notation, e.g. ``cc.fire[25:]``.  If you want to access the Bokeh palettes by string name, they are also collected into a dictionary named ``palette``, so you can use ``cc.palette[\"linear_kryw_0_100_c71\"]`` or ``cc.palette[\"fire\"]`` or ``cc.palette.fire``; whichever is more convenient. Finally, the subset of colormaps that have short, readable names are available separately, accessible as ``cc.palette_n.fire`` or  ``cc.palette_n[\"fire\"]``, e.g. for use in GUI widgets selecting a colormap by readable name.\n",
    "\n",
    "The Matplotlib colormaps are also provided as tab-completable attributes, but consistently with a prefix ``m_``, e.g. ``cc.m_linear_kryw_0_100_c71`` or ``cc.m_fire``.  Already reversed versions are also available, as ``cc.m_linear_kryw_0_100_c71_r`` or ``cc.m_fire_r``.  The same colormaps are also registered with matplotlib's string-based dictionary with the prefix ``cet_``, making them available by name within various matplotlib functions (e.g. ``cet_linear_kryw_0_100_c71``, ``cet_linear_kryw_0_100_c71_r``, ``cet_fire``, or  ``cet_fire_r``).  Finally, if you want to access the Matplotlib colormaps by string name without using Matplotlib's registry, they are also stored in the ``cc.cm`` dictionary, e.g. ``cc.cm[\"linear_kryw_0_100_c71\"]``, ``cc.cm[\"linear_kryw_0_100_c71_r\"]``, ``cc.cm[\"fire\"]``, ``cc.cm.fire``, ``cc.cm[\"fire_r\"]``, or ``cc.cm.fire_r``.\n",
    "\n",
    "In each case, the colormap names used are the shortest ones that are expected to be unique in that context, and in practice you are only likely to need one of these forms for any particular application."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Example\n",
    "\n",
    "Here we show importing fire and printing the first 5 colors in the set. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import colorcet as cc\n",
    "\n",
    "cc.fire[:5]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plotting\n",
    "\n",
    "For ease of use, we also provide minimal plotting commands for use with colorcet. These depend on holoviews, which needs to be installed before they can be used. Once set up, these commands provide easy viewing capability of the colormaps."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Example\n",
    "\n",
    "Import `swatch` or `swatches` from `colorcet.plotting` and load your desired backend into holoviews. Then call `swatch` with the name of a colormap. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from colorcet.plotting import swatch, swatches\n",
    "import holoviews as hv\n",
    "hv.extension('matplotlib')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "swatch('fire')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Using `colorcet` via `matplotlib.cm.get_cmap`\n",
    "\n",
    "The `colorcet` colormaps are all available through `matplotlip.cm.get_cmap` by prepending `cet_`to the colormap name. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from matplotlib.cm import get_cmap\n",
    "\n",
    "get_cmap(\"cet_fire\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Using `colorcet` to visualize custom colormaps using `swatch`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "color_list = ['#000000', '#380000', '#560000', '#760100', '#980300', '#bb0600', '#df0d00', '#f93500', '#fe6800', '#ff9100', '#ffb402', '#ffd407', '#fff324']\n",
    "\n",
    "swatch(name='custom', cmap=color_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Complete list\n",
    "\n",
    "The `swatches` command accepts the optional key word argument `group` to show just the colormaps whose names match the given string - try 'glasbey', 'cyclic', or 'diverging'. When no arguments are provided, `swatches` returns all of the colorcet colormaps."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "swatches()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more explanation of the various options see [categorical](Categorical.ipynb) and [continuous](Continuous.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```{toctree}\n",
    ":titlesonly:\n",
    ":hidden:\n",
    ":maxdepth: 2\n",
    "\n",
    "Accessing the colormaps <self>\n",
    "Continuous <Continuous>\n",
    "Categorical <Categorical>\n",
    "```"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}