bqnt_first_app.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### nbappinator - first bqnt app\n",
    "\n",
    "This app runs a BQL query that takes a single parameter, displays the result as an interactive table, and provides a simple charting interface that draws an interactive Plotly chart of the results."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Before Running in BQuant Enterprise\n",
    "\n",
    "In BQuant Enterprise, certain packages\\* must be loaded *before* starting your project. This is accomplished through Custom Environments.\n",
    "\n",
    "To run examples using `nbappinator`:\n",
    "\n",
    "1. Create a Custom Environment\n",
    "2. Change the Name of the Custom Environment\n",
    "3. Add `nbappinator` to it\n",
    "4. Click `solve`\n",
    "5. Save the Custom Environment\n",
    "6. Launch/Relaunch a Project using the Custom Environment\n",
    "\n",
    "The first time you launch a Custom Environment will take a few minutes to load. Subsequent launches will be much faster, but the environment will rebuild everytime you make a change to the packages or versions. I usually put the minimum required packages into the Custom Environment, and install the rest at runtime.\n",
    "\n",
    "\\* Jupyter extensions, primarily UI widget extensions that register Javascript models, must be loaded at Jupyter startup time. \n",
    "\\*\\* Other packages that *don't* require extensions may be installed at runtime, using `%package install <xyz>` or `%pip install <xyz>`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Import your packages"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import nbappinator as nbapp\n",
    "import jinja2\n",
    "import logging\n",
    "import bql\n",
    "import pandas as pd\n",
    "import plotly.express as px"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Setup any globals\n",
    "\n",
    "Setup static variables used in the global scope (outside a function) that will be used without the function.\n",
    "\n",
    "Try to only use static globals: global variables that don't change / aren't mutated."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "logging.basicConfig(encoding=\"utf-8\", level=logging.INFO)\n",
    "\n",
    "logger = logging.getLogger(__name__)\n",
    "\n",
    "bq = bql.Service()\n",
    "\n",
    "INITIAL_QUERY = \"\"\"get(\n",
    "      px_last\n",
    "    ) for(\n",
    "      {{SECURITY}}\n",
    "    ) with(\n",
    "      dates=range(-29d, 0d),\n",
    "      fill=prev,\n",
    "      currency=USD\n",
    "    )\"\"\"\n",
    "\n",
    "PAGES = [\"Data\", \"Chart\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Define functions\n",
    "\n",
    "Functions to execute the BQL query, apply the template, and draw a chart."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "def _exec_bql(query: str) -> pd.DataFrame:\n",
    "    r = bq.execute(query)\n",
    "    df = bql.combined_df(r).reset_index()\n",
    "    return df\n",
    "\n",
    "\n",
    "def execute_query(\n",
    "    component: str, action: str, args: str, app: nbapp.UiModel, caller: str\n",
    "):\n",
    "    app.clear_messages()\n",
    "    with app.messages:\n",
    "        try:\n",
    "            app.update_status(name=caller, message=\"Running Query\", running=True)\n",
    "            data_page = app.get_page(PAGES[0])\n",
    "            data_page.clear()\n",
    "            chart_page = app.get_page(PAGES[1])\n",
    "            chart_page.clear()\n",
    "\n",
    "            # Create query from a template\n",
    "            security: str = app.get_valuestr(\"security\")\n",
    "            base_query: str = app.get_valuestr(\"query\")\n",
    "            query = jinja2.Template(base_query).render(SECURITY=security)\n",
    "            print(query)\n",
    "\n",
    "            # Execute the query\n",
    "            df = _exec_bql(query)\n",
    "\n",
    "            # Display the dataframe in a grid\n",
    "            data_page.clear()\n",
    "            data_page.add_df(name=\"df1\", df=df)\n",
    "            df.columns = [col.lower() for col in df.columns]\n",
    "\n",
    "            # Create a menu on the chart_page that lets the user pick columns from the chart.\n",
    "            cols = list(df.columns)\n",
    "            options_container = chart_page.add_box(name=\"options\", horiz=True)\n",
    "            options_container.add_select(\n",
    "                name=\"x_axis\", label=\"X Axis\", options=cols, value=\"date\"\n",
    "            )\n",
    "            options_container.add_select(\n",
    "                name=\"y_axis\", label=\"Y Axis\", options=cols, value=cols[-1]\n",
    "            )\n",
    "            options_container.add_select(\n",
    "                name=\"z_axis\", label=\"Series\", options=cols, value=\"id\"\n",
    "            )\n",
    "            chart_page.add_button(\n",
    "                name=\"drawchart\", label=\"Draw Chart\", action=draw_chart, status=False\n",
    "            )\n",
    "            chart_page.add_container(name=\"chartcontainer\")\n",
    "            app.update_status(name=caller, message=\"Query Complete\", running=False)\n",
    "        except Exception as e:\n",
    "            app.update_status(\n",
    "                name=caller,\n",
    "                message=f\"Error {e} running query, see Messages for details\",\n",
    "                running=False,\n",
    "            )\n",
    "\n",
    "\n",
    "def draw_chart(component: str, action: str, args: str, app: nbapp.UiModel, caller: str):\n",
    "    with app.messages:\n",
    "        df = app.widgets[\"df1\"].w.df\n",
    "        display(df.columns)\n",
    "\n",
    "        x = app.get_values(\"x_axis\")\n",
    "\n",
    "        y = app.get_values(\"y_axis\")\n",
    "        color = app.get_values(\"z_axis\")\n",
    "\n",
    "        # Sort by X and Color, so chart doesn't \"zig-zag\" along the X.\n",
    "        if color is not None:\n",
    "            sorting_fields = [x, color]\n",
    "        else:\n",
    "            sorting_fields = [x]\n",
    "        df_sorted = df.sort_values(by=sorting_fields)\n",
    "\n",
    "        fig = px.line(df_sorted, x=x, y=y, color=color)\n",
    "\n",
    "        app.clear_container(\"chartcontainer\")\n",
    "        chartcontainer = app.get_container(\"chartcontainer\")\n",
    "        chartcontainer.add_plotly_fig(name=\"f1\", fig=fig)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Setup and Display the nbappinator Application\n",
    "\n",
    "The example below is not functional, but shows what it would look like in BQuant."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<script>\n",
       "                    if (window.location.href.indexOf('voila') >= 0){\n",
       "                        const l=document.createElement('link');\n",
       "                        l.setAttribute('rel','stylesheet');  \n",
       "                        l.setAttribute('type','text/css');\n",
       "                        l.setAttribute('href',`${window.location.href.split('/').slice(0,7).join('/')}/static/theme-light.css`);\n",
       "                        document.body.appendChild(l);\n",
       "                        document.body.classList.remove('theme-dark')\n",
       "                        document.body.classList.add('theme-light')\n",
       "                    }\n",
       "                </script>\n",
       "                "
      ],
      "text/plain": [
       "<nbappinator.appinator.ThemeFixer at 0x19eff311790>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "bd11219738c6415ebde5badc341f4dbb",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "Html(children=[Html(children=['\\n    .vuetify-styles code, .vuetify-styles kbd, .vuetify-styles samp{\\n       …"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "myapp = nbapp.TabbedUiModel(pages=PAGES, log_footer=\"Messages\", headers=[\"Config\"])\n",
    "\n",
    "config_page = myapp.get_page(\"Config\")\n",
    "config_page.add_textfield(\n",
    "    name=\"security\",\n",
    "    label=\"Enter Security: ['Security1', 'Security2']\",\n",
    "    value=\"['IBM US Equity']\",\n",
    ")\n",
    "config_page.add_textarea(\n",
    "    name=\"query\",\n",
    "    label=\"Enter BQL, with {{SECURITY}} for the Universe\",\n",
    "    value=INITIAL_QUERY,\n",
    ")\n",
    "\n",
    "config_page.add_button(\n",
    "    name=\"update\", label=\"Run Query\", action=execute_query, status=True\n",
    ")\n",
    "\n",
    "myapp.display()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Publish the Notebook\n",
    "\n",
    "You can then Publish this application to another user. They'll receive a *Message* in Bloomberg with a link to the application."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.11.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}