{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### **Title**: Waterfall Element\n",
    "\n",
    "**Dependencies**: Bokeh\n",
    "\n",
    "**Backends**: [Bokeh](./Waterfall.ipynb), [Matplotlib](../matplotlib/Waterfall.ipynb)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import polars as pl\n",
    "\n",
    "import holoviews as hv\n",
    "\n",
    "hv.extension('bokeh')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``Waterfall`` Element is a type of bar chart that is used to show how an initial value is affected by a series of intermediate positive or negative values, leading to a final value. It is often used in financial analysis to visualize the cumulative effect of sequentially introduced positive or negative values.\n",
    "\n",
    "The `Waterfall` Element can be created using the `hv.Waterfall` function, which takes a list of tuples where each tuple contains a category and its corresponding value. The categories are typically displayed on the x-axis, while the values are represented as bars on the y-axis. Positive values will extend upwards from the baseline, while negative values will extend downwards."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data = [('Revenue', 100), ('COGS', 50), ('Opex', -30), ('Tax', -10)]\n",
    "w = hv.Waterfall(data)\n",
    "w"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can achieve the same plot using a Pandas DataFrame.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = pl.DataFrame({\n",
    "    'Category': ['Revenue', 'COGS', 'Opex', 'Tax'],\n",
    "    'Amount': [100, 50, -30, -10]\n",
    "})\n",
    "\n",
    "w = hv.Waterfall(df, kdims='Category', vdims='Amount')\n",
    "w"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If your dataframe contains the final values (after totals), you can pre-process it to get the intermediate values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = pl.DataFrame({\n",
    "    \"Category\": [\"Revenue\", \"COGS\", \"Opex\", \"Tax\"],\n",
    "    \"Final\": [100, 150, 120, 110],\n",
    "})\n",
    "\n",
    "df = df.with_columns(\n",
    "    pl.col(\"Final\").diff().fill_null(pl.col(\"Final\")).alias(\"Amount\")\n",
    ")\n",
    "\n",
    "w = hv.Waterfall(df.to_pandas(), kdims=\"Category\", vdims=\"Amount\")\n",
    "w"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Waterfall charts also support numeric values, like years."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = pl.DataFrame({\n",
    "    'Year': [2017, 2018, 2019, 2020],\n",
    "    'Amount': [100, 25, -75, 25]\n",
    "})\n",
    "w = hv.Waterfall(df, kdims='Year', vdims='Amount')\n",
    "w"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The color of the start and end bars can be customized using the `start_color` and `total_color` options. The `positive_color` and `negative_color` options can be used to customize the colors of the positive and negative bars too."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "w.opts(start_color='white', total_color='gray', positive_color=\"#c0ffc0\", negative_color=\"#B52626\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the `total_color` is not specified, the last bar will be mirrored to the `start_color` by default, and vice versa."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "w = hv.Waterfall(df, kdims='Year', vdims='Amount')\n",
    "w.opts(start_color=\"gold\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`total_label` can be used to customize the label of the total bar."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "w.opts(total_label=\"Result\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, the total bar can be hidden by setting `show_total=False`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "w.opts(show_total=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The connectors can also be customized using the `connector_line_color` and `connector_width` options."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "w.opts(connector_line_color=\"black\", connector_line_width=1.5, connector_line_dash='solid')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The connectors can also be turned off with `show_connectors=False`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "w.opts(show_connectors=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For full documentation and the available style and plot options, use ``hv.help(hv.Waterfall)``."
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}