{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Basic Barplot with plotnine\n",
    "\n",
    "This vignette shows how to create a basic\n",
    "[barplot](https://www.data-to-viz.com/graph/barplot.html) using\n",
    "[plotnine](https://plotnine.org).\n",
    "A barplot displays the relationship between a **numeric** variable and\n",
    "a **categorical** variable.\n",
    "\n",
    "This example is a plotnine port of the\n",
    "[Basic Barplot](https://python-graph-gallery.com/1-basic-barplot/)\n",
    "tutorial from the\n",
    "[Python Graph Gallery](https://python-graph-gallery.com), which\n",
    "originally uses matplotlib."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Libraries & Dataset\n",
    "\n",
    "We use **pandas** to hold the data and **plotnine_extra** (which\n",
    "re-exports the full plotnine API) for plotting."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "from plotnine import (\n",
    "    ggplot,\n",
    "    aes,\n",
    "    geom_col,\n",
    "    labs,\n",
    "    theme_minimal,\n",
    ")\n",
    "\n",
    "# Create the dataset (same data as the original matplotlib example)\n",
    "df = pd.DataFrame({\n",
    "    \"category\": [\"A\", \"B\", \"C\", \"D\", \"E\"],\n",
    "    \"height\": [3, 12, 5, 18, 45],\n",
    "})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic Barplot\n",
    "\n",
    "With plotnine we build plots using the *grammar of graphics*:\n",
    "\n",
    "1. **`ggplot(df, aes(...))`** – bind the data and map columns to\n",
    "   aesthetics.\n",
    "2. **`geom_col()`** – draw a bar whose height equals the value in the\n",
    "   data (use `geom_bar()` when you want plotnine to count rows for\n",
    "   you)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "(\n",
    "    ggplot(df, aes(x=\"category\", y=\"height\"))\n",
    "    + geom_col()\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Customising the plot\n",
    "\n",
    "plotnine makes it easy to polish the appearance.  Below we add a\n",
    "colour fill, labels, and a cleaner theme."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "(\n",
    "    ggplot(df, aes(x=\"category\", y=\"height\"))\n",
    "    + geom_col(fill=\"#69b3a2\")\n",
    "    + labs(\n",
    "        title=\"Basic Barplot with plotnine\",\n",
    "        x=\"Category\",\n",
    "        y=\"Value\",\n",
    "    )\n",
    "    + theme_minimal()\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Going further\n",
    "\n",
    "Because plotnine implements the grammar of graphics, extending this\n",
    "basic example is straightforward:\n",
    "\n",
    "* Map `fill` to a column to get grouped / stacked bars.\n",
    "* Use `coord_flip()` for horizontal bars.\n",
    "* Add error bars with `geom_errorbar()`.\n",
    "* Facet with `facet_wrap()` or `facet_grid()`.\n",
    "\n",
    "See the [plotnine documentation](https://plotnine.org) and the\n",
    "[plotnine-extra API reference](../api/index.rst) for more details."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}