index.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#hide\n",
    "from dash_oop_components.core import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# dash_oop_components\n",
    "\n",
    "> `dash_oop_components` is a small helper library with object-oriented dashboard building blocks for the plotly dash library"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Install"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`pip install dash_oop_components`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Documentation\n",
    "\n",
    "Documentation can be found at: [https://oegedijk.github.io/dash_oop_components/](https://oegedijk.github.io/dash_oop_components/)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example\n",
    "\n",
    "An example covid tracking dashboard has been deployed to [dash-oop-demo.herokuapp.com](http://dash-oop-demo.herokuapp.com) (code at [github.com/oegedijk/dash_oop_demo](https://github.com/oegedijk/dash_oop_demo)), showcasing:\n",
    "\n",
    "- The use of re-usable, nestable components\n",
    "- Keeping track of state in the querystring\n",
    "- Seperating data from dashboard logic\n",
    "- Loading the dashboard from a config yaml file\n",
    "\n",
    "![](dash_oop_demo.gif)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Purpose"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Plotly's [dash](dash.plotly.com) is an awesome library that allows you to build rich interactive data driven web apps with pure python code. However the default style of dash apps is quite declarative, which for large projects can lead to code that becomes unwieldy, hard to maintain, and hard to collaborate on:\n",
    "- Data wrangling and plot generating logic is mixed up with dashboard interactivity logic \n",
    "    and is spread all over the layout and callback functions.\n",
    "- Configuration of the dashboard is hardcoded somewhere deep in the layout or callbacks, \n",
    "    instead of with tunable hyperparameters.\n",
    "- Callbacks definitions are all mixed up, often far from the relevant layout, instead of being grouped together\n",
    "- To reuse similar components multiple time in your dashboard you need to copy-paste layout and callbacks, violating the DRY principle.\n",
    "- You need to be able to read and edit python in order to reconfigure and restart the dashboard\n",
    "\n",
    "This library provides a number object-oriented wrappers for organizing your dash code that allow you to write clean, modular, composable, re-usable and fully configurable dash code.\n",
    "\n",
    "It includes:\n",
    "- `DashFigureFactory`: a wrapper for your data/plotting functionality, keeping data/plotting logic \n",
    "    seperate from your dashboard interaction logic.\n",
    "- `DashComponent`: a self-contained, modular, configurable unit that combines a dash layout with dash callbacks.\n",
    "    - Keeps layout and callbacks in one place, grouped together.\n",
    "    - Makes use of a `DashFigureFactory` for plots or other data output\n",
    "    - `DashComponents` are composable, meaning that you can nest them into new composite components.\n",
    "    - You can store component configuration to yaml, and then rebuild from yaml.\n",
    "    - You can use `DashConnectors` to connect callbacks between components\n",
    "- `DashApp`: Build a dashboard out of a `DashComponent` and run it.\n",
    "    - Includes the possibility of tracking dashboard state in the querystring url, \n",
    "        allowing for shareable stateful urls.\n",
    "        - Using `DashComponentTabs` you can also track state for current tab only \n",
    "    - You can launch a dashboard from the commandline from a dashboard.yaml file,\n",
    "        meaning that anyone can reconfigure the dashboard and relaunch it, even\n",
    "        without coding experience.\n",
    "\n",
    "All wrappers:\n",
    "\n",
    "\n",
    "Cool extras:\n",
    "- All wrappers automagically store all params to attributes\n",
    "- Component and dashboard configuration can be exported to `.yaml` file, \n",
    "    including import details, and be fully reloaded from this config file.\n",
    "- You can track the state of your dashboard with querystrings and reload the state from url!\n",
    "- Launch from the commandline with the `dashapp` CLI!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example Code\n",
    "\n",
    "A full example dashboard can be found at [github.com/oegedijk/dash_oop_demo](https://github.com/oegedijk/dash_oop_demo) and has been deployed to [https://dash-oop-demo.herokuapp.com/](https://dash-oop-demo.herokuapp.com/)\n",
    "\n",
    "Below is the code for similar but slightly simpler example. Full explanation for the `dash_oop_demo` dashboard can be found [in the example documentation](https://oegedijk.github.io/dash_oop_components/Example.html).\n",
    "\n",
    "The example is a rewrite of this [Charming Data dash instruction video](https://www.youtube.com/watch?v=dgV3GGFMcTc) (go check out his other vids, they're awesome!)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Requirement already satisfied: pandas in /Users/oege/projects/venv/lib/python3.8/site-packages (1.1.3)\n",
      "Requirement already satisfied: plotly-express in /Users/oege/projects/venv/lib/python3.8/site-packages (0.4.1)\n",
      "Requirement already satisfied: numpy>=1.15.4 in /Users/oege/projects/venv/lib/python3.8/site-packages (from pandas) (1.19.2)\n",
      "Requirement already satisfied: python-dateutil>=2.7.3 in /Users/oege/projects/venv/lib/python3.8/site-packages (from pandas) (2.8.1)\n",
      "Requirement already satisfied: pytz>=2017.2 in /Users/oege/projects/venv/lib/python3.8/site-packages (from pandas) (2020.1)\n",
      "Requirement already satisfied: scipy>=0.18 in /Users/oege/projects/venv/lib/python3.8/site-packages (from plotly-express) (1.5.3)\n",
      "Requirement already satisfied: patsy>=0.5 in /Users/oege/projects/venv/lib/python3.8/site-packages (from plotly-express) (0.5.1)\n",
      "Requirement already satisfied: statsmodels>=0.9.0 in /Users/oege/projects/venv/lib/python3.8/site-packages (from plotly-express) (0.12.0)\n",
      "Requirement already satisfied: plotly>=4.1.0 in /Users/oege/projects/venv/lib/python3.8/site-packages (from plotly-express) (4.12.0)\n",
      "Requirement already satisfied: six>=1.5 in /Users/oege/projects/venv/lib/python3.8/site-packages (from python-dateutil>=2.7.3->pandas) (1.15.0)\n",
      "Requirement already satisfied: retrying>=1.3.3 in /Users/oege/projects/venv/lib/python3.8/site-packages (from plotly>=4.1.0->plotly-express) (1.3.3)\n",
      "\u001b[33mWARNING: You are using pip version 20.1.1; however, version 20.2.4 is available.\n",
      "You should consider upgrading via the '/Users/oege/projects/venv/bin/python -m pip install --upgrade pip' command.\u001b[0m\n"
     ]
    }
   ],
   "source": [
    "#hide\n",
    "\n",
    "!pip install pandas plotly-express"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#hide\n",
    "import dash_html_components as html\n",
    "import dash_core_components as dcc\n",
    "import dash_bootstrap_components as dbc\n",
    "\n",
    "from dash.dependencies import Input, Output, State\n",
    "from dash.exceptions import PreventUpdate\n",
    "\n",
    "from dash_oop_components import DashFigureFactory, DashComponent, DashApp\n",
    "\n",
    "import pandas as pd\n",
    "import plotly.express as px"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### CovidPlots: a DashFigureFactory"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First we define a basic `DashFigureFactory` that loads a covid dataset, and provides a single plotting functionality, namely `plot_time_series(countries, metric)`. Make sure to call `super().__init__()` in order to store params to attributes (that's how the datafile parameters gets automatically assigned to self.datafile for example), and store them to a `._stored_params` dict so that they can later be exported to a config file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dash_figure_factory:\n",
      "  class_name: CovidPlots\n",
      "  module: __main__\n",
      "  params:\n",
      "    datafile: covid.csv\n",
      "\n"
     ]
    }
   ],
   "source": [
    "class CovidPlots(DashFigureFactory):\n",
    "    def __init__(self, datafile=\"covid.csv\"):\n",
    "        super().__init__()\n",
    "        self.df = pd.read_csv(self.datafile)\n",
    "        \n",
    "        self.countries = self.df.countriesAndTerritories.unique().tolist()\n",
    "        self.metrics = ['cases', 'deaths']\n",
    "        \n",
    "    def plot_time_series(self, countries, metric):\n",
    "        return px.line(\n",
    "            data_frame=self.df[self.df.countriesAndTerritories.isin(countries)],\n",
    "            x='dateRep',\n",
    "            y=metric,\n",
    "            color='countriesAndTerritories',\n",
    "            labels={'countriesAndTerritories':'Countries', 'dateRep':'date'},\n",
    "            )\n",
    "    \n",
    "figure_factory = CovidPlots(\"covid.csv\")\n",
    "print(figure_factory.to_yaml())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### CovidTimeSeries: a DashComponent"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then we define a `DashComponent` that takes a plot_factory and build a layout with two dropdowns and a graph.\n",
    "\n",
    "- The layout is defined in the `layout(self, params=None)` method\n",
    "- Callbacks are defined in the `component_callbacks(self, app)` method \n",
    "\n",
    "\n",
    "- By calling `super().__init__()` all parameters are automatically stored to attributes (so that we can access \n",
    "    e.g. `self.hide_country_dropdown`), and to a `._stored_params` dict (which can then be exported to `.yaml`)\n",
    "- This layout makes use of the `make_hideable()` staticmethod, to conditionally \n",
    "    wrap certain layout elements in a hidden div.\n",
    "- We track the state of the dropdowns `'value'` attribute by wrapping it in \n",
    "    `self.querystring(params)(dcc.Dropdown)(..)`, and passing the urls's querystring params \n",
    "    down to the layout function upon pageload.\n",
    "- You can make sure that all `component_id`'s are unique by adding `+self.name`. However if you use \n",
    "    `self.id(component_id)`, then `self.name` gets automatically tagged on, and you can use \n",
    "    `self.Input()`, `self.Output()` and `self.State()` instead of the regular `dash` `Input()`, \n",
    "    `Output()` and `State()` functions.\n",
    "    - If you don't explicitly pass a `name`,  gets a random uuid string automatically gets assigned.\n",
    "- Note that the callbacks are registered using `component_callbacks(self, app)` method\n",
    "- Note that the callback uses the `plot_factory` for the plotting logic."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class CovidTimeSeries(DashComponent):\n",
    "    def __init__(self, plot_factory, \n",
    "                 hide_country_dropdown=False, countries=None, \n",
    "                 hide_metric_dropdown=False, metric='cases', name=None):\n",
    "        super().__init__()\n",
    "        \n",
    "        if not self.countries:\n",
    "            self.countries = self.plot_factory.countries\n",
    "        \n",
    "    def layout(self, params=None):\n",
    "        return dbc.Container([\n",
    "            dbc.Row([\n",
    "                dbc.Col([\n",
    "                    html.H3(\"Covid Time Series\"),\n",
    "                    self.make_hideable(\n",
    "                        self.querystring(params)(dcc.Dropdown)(\n",
    "                            id=self.id('timeseries-metric-dropdown'),\n",
    "                            options=[{'label': metric, 'value': metric} for metric in ['cases', 'deaths']],\n",
    "                            value=self.metric,\n",
    "                        ), hide=self.hide_metric_dropdown),\n",
    "                    self.make_hideable(\n",
    "                        self.querystring(params)(dcc.Dropdown)(\n",
    "                            id=self.id('timeseries-country-dropdown'),\n",
    "                            options=[{'label': country, 'value': country} for country in self.plot_factory.countries],\n",
    "                            value=self.countries,\n",
    "                            multi=True,\n",
    "                        ), hide=self.hide_country_dropdown),\n",
    "                    dcc.Graph(id=self.id('timeseries-figure'))\n",
    "                ]),\n",
    "            ])\n",
    "        ])\n",
    "    \n",
    "    def component_callbacks(self, app):\n",
    "        @app.callback(\n",
    "            self.Output('timeseries-figure', 'figure'),\n",
    "            self.Input('timeseries-country-dropdown', 'value'),\n",
    "            self.Input('timeseries-metric-dropdown', 'value')\n",
    "        )\n",
    "        def update_timeseries_plot(countries, metric):\n",
    "            if countries and metric is not None:\n",
    "                return self.plot_factory.plot_time_series(countries, metric)\n",
    "            raise PreventUpdate"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### DuoPlots: a composition of two subcomponents\n",
    "A composite `DashComponent` that combines two `CovidTimeSeries` into a single layout. \n",
    "Both subcomponents are passed the same `plot_factory` but assigned different initial values.\n",
    "\n",
    "- The layouts of subcomponents can be included in the composite layout with \n",
    "    `self.plot_left.layout(params)` and `self.plot_right.layout(params)`\n",
    "- Composite callbacks should again be defined under `self.component_callbacks(app)`\n",
    "    - calling `.register_callbacks(app)` first registers all callbacks of subcomponents, \n",
    "        and then calls `component_callbacks(app)`.\n",
    "    - composite callbacks can access elements of subcomponents by using the `subcomponent.name` fields in the ids.\n",
    "- When tracking the state of the dashboard in the querystring it is important to name your components, so that \n",
    "    the next time you start the dashboard the elements will have the same id's. In this case we \n",
    "    pass `name=\"left\"` and `name=\"right\"`.\n",
    "- Make sure to pass the params parameter of the layout down to the subcomponent layouts!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dash_component:\n",
      "  class_name: DuoPlots\n",
      "  module: __main__\n",
      "  params:\n",
      "    plot_factory:\n",
      "      dash_figure_factory:\n",
      "        class_name: CovidPlots\n",
      "        module: __main__\n",
      "        params:\n",
      "          datafile: covid.csv\n",
      "    name: DAtVxQgozo\n",
      "\n"
     ]
    }
   ],
   "source": [
    "class DuoPlots(DashComponent):\n",
    "    def __init__(self, plot_factory):\n",
    "        super().__init__()\n",
    "        self.plot_left = CovidTimeSeries(plot_factory, \n",
    "                                         countries=['China', 'Vietnam', 'Taiwan'], \n",
    "                                         metric='cases', name='left')\n",
    "        self.plot_right = CovidTimeSeries(plot_factory, \n",
    "                                          countries=['Italy', 'Germany', 'Sweden'], \n",
    "                                          metric='deaths', name='right')\n",
    "        \n",
    "    def layout(self, params=None):\n",
    "        return dbc.Container([\n",
    "            html.H1(\"Covid Dashboard\"),\n",
    "            dbc.Row([\n",
    "                dbc.Col([\n",
    "                    self.plot_left.layout(params)\n",
    "                ]),\n",
    "                dbc.Col([\n",
    "                    self.plot_right.layout(params)\n",
    "                ])\n",
    "            ])\n",
    "        ], fluid=True)\n",
    "    \n",
    "dashboard = DuoPlots(figure_factory)\n",
    "print(dashboard.to_yaml())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Build and start `DashApp`:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Pass the `dashboard` to the `DashApp` to create a dash flask application.\n",
    "\n",
    "- You can pass `mode='inline'`, `'external'` or `'jupyterlab'` when you are working in a notebook in order to keep\n",
    "    the notebook interactive while the app is running\n",
    "- By passing `querystrings=True` you automatically keep track of the state of the dashboard int the url querystring\n",
    "- By passing `bootstrap=True` the default bootstrap css gets automatically included. You can also choose particular themes, e.g. `bootstrap=dbc.themes.FLATLY`\n",
    "- You can pass other dash parameters in the `**kwargs`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dash_app:\n",
      "  class_name: DashApp\n",
      "  module: dash_oop_components.core\n",
      "  params:\n",
      "    dashboard_component:\n",
      "      dash_component:\n",
      "        class_name: DuoPlots\n",
      "        module: __main__\n",
      "        params:\n",
      "          plot_factory:\n",
      "            dash_figure_factory:\n",
      "              class_name: CovidPlots\n",
      "              module: __main__\n",
      "              params:\n",
      "                datafile: covid.csv\n",
      "          name: DAtVxQgozo\n",
      "    port: 8050\n",
      "    mode: dash\n",
      "    querystrings: true\n",
      "    bootstrap: true\n",
      "    kwargs:\n",
      "      external_stylesheets:\n",
      "      - https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css\n",
      "      suppress_callback_exceptions: true\n",
      "\n"
     ]
    }
   ],
   "source": [
    "app = DashApp(dashboard, querystrings=True, bootstrap=True)\n",
    "print(app.to_yaml())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#hide\n",
    "run_app = False # set to False to avoid hanging the tests"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if run_app:\n",
    "    app.run(9051)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "app.to_yaml(\"covid_dashboard.yaml\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### launch from the commandline with `dashapp` CLI\n",
    "\n",
    "Now we could launch the dashboard from the command line with the `dashapp` CLI tool:\n",
    "\n",
    "```sh\n",
    "$ dashapp covid_dashboard.yaml\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### reload dashboard from config:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "app2 = DashApp.from_yaml(\"covid_dashboard.yaml\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can check that the configuration of this new `app2` is indeed the same as `app`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dash_app:\n",
      "  class_name: DashApp\n",
      "  module: dash_oop_components.core\n",
      "  params:\n",
      "    dashboard_component:\n",
      "      dash_component:\n",
      "        class_name: DuoPlots\n",
      "        module: __main__\n",
      "        params:\n",
      "          plot_factory:\n",
      "            dash_figure_factory:\n",
      "              class_name: CovidPlots\n",
      "              module: __main__\n",
      "              params:\n",
      "                datafile: covid.csv\n",
      "          name: 95vGiZRAt2\n",
      "    port: 8050\n",
      "    mode: dash\n",
      "    querystrings: true\n",
      "    bootstrap: true\n",
      "    kwargs:\n",
      "      external_stylesheets:\n",
      "      - https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css\n",
      "      - https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css\n",
      "      suppress_callback_exceptions: true\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(app2.to_yaml())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And if we run it it still works!\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if run_app: \n",
    "    app2.run()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}