{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using IPCC Color Palettes\n",
    "\n",
    "**pyam** supports the use of explicit IPCC [AR5](https://tdaviesbarnard.co.uk/1202/ipcc-official-colors-rcp/) and [AR6](https://github.com/IPCC-WG1/colormaps) color palettes by providing the RCP and/or SSP of interest via the `pyam.run_control()` feature."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The full list of the IPCC color palette colors available in **pyam** can be retrieved by the following code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "import pyam\n",
    "\n",
    "colors = pyam.plotting.PYAM_COLORS\n",
    "pd.DataFrame({\"name\": list(colors.keys()), \"color\": list(colors.values())})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Display scenario data with default colours\n",
    "\n",
    "We use the scenario ensemble from the **first-steps tutorial** (here on\n",
    "[GitHub](https://github.com/IAMconsortium/pyam/blob/master/doc/source/tutorials/pyam_first_steps.ipynb)\n",
    "and on [read the docs](https://pyam-iamc.readthedocs.io/en/stable/tutorials/pyam_first_steps.html)).\n",
    "Let's pull out two example scenarios (implemented by multiple modelling frameworks each) and plot them with the default color scheme."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scenarios = [\"CD-LINKS_NoPolicy\", \"CD-LINKS_NPi2020_400\"]\n",
    "\n",
    "df = pyam.IamDataFrame(data=\"tutorial_data.csv\").filter(\n",
    "    variable=\"Emissions|CO2\", region=\"World\", scenario=scenarios\n",
    ")\n",
    "\n",
    "df.plot(color=\"scenario\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As an example, we assume that each of these two sets of scenarios correspond to categorizations in the AR6 context. We can utilize the specific colors by following two steps:\n",
    "\n",
    "1. Update `pyam.run_control()` telling it which scenario name maps to which AR6 color\n",
    "2. Call `line_plot` using that color mapping"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Updating the run control\n",
    "\n",
    "We need to tell **pyam** that whenever it sees a certain scenario name, it should use a specific color from the IPCC palette."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "color_map = {\n",
    "    \"CD-LINKS_NPi2020_400\": \"AR6-SSP2-4.5\",\n",
    "    \"CD-LINKS_NoPolicy\": \"AR6-SSP5-8.5\",\n",
    "}\n",
    "\n",
    "pyam.run_control().update({\"color\": {\"scenario\": color_map}})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The illustration above is implemented directly in Python code, but it also works by specifying the desired mapping in a `yaml` configuration file and loading that file into `run_control()`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Use the new colors\n",
    "\n",
    "Now, it's as simple as calling the plot function again!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.plot(color=\"scenario\")"
   ]
  }
 ],
 "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.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}