{ "cells": [ { "cell_type": "markdown", "metadata": { "tags": [] }, "source": [ "Jupyter-flex allows you to create dashboards based on Jupyter Notebooks based on two simple concepts:\n", "\n", "1. Control the layout of the dashboard using markdown headers (`#`, `##` and `###)\n", "2. Define the dashboard components using Jupyter Notebook cell tags (`body` and others)\n", "\n", "## Your first dashboard\n", "\n", "Let's take a very simple Jupyter Notebook with one plot and make a dashboard.\n", "\n", "The notebook is:" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [] }, "outputs": [], "source": [ "import numpy as np\n", "import pandas as pd\n", "import altair as alt\n", "from vega_datasets import data" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [] }, "outputs": [], "source": [ "alt.renderers.set_embed_options(actions=False)" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [] }, "outputs": [], "source": [ "np.random.seed(42)" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [ "body" ] }, "outputs": [], "source": [ "source = data.cars()\n", "\n", "plot = alt.Chart(source).mark_circle(size=60).encode(\n", " x='Horsepower',\n", " y='Miles_per_Gallon',\n", " color='Origin',\n", " tooltip=['Name', 'Origin', 'Horsepower', 'Miles_per_Gallon']\n", ")\n", "plot" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "All you need to do to convert this to a dashboard is to add a `body` tag to the that cell that has the plot as the output.\n", "\n", "
How to view and add tags to cells in Jupyter Lab
\n", "You can find a tag editor by clicking the gears icon on the top right icon on the right sidebar\n", "
\n", "How to view and add tags to cells in Jupyter Classic Notebook
\n", "Responsive plots
\n", "\n", " Depending on the plotting library you use you might need to add a bit of code to make the plot occupy all the space of the card. See the plotting page for more info.\n", "
\n", "Terminal
\n", "\n", "```\n", "$ jupyter nbconvert --to flex notebook.ipynb\n", "```\n", "\n", "Optionally add the `--execute` flag to execute the notebook before converting them to a dashbaord.\n", "\n", "Terminal
\n", "\n", "```\n", "$ jupyter nbconvert --to flex notebook.ipynb --execute\n", "```\n", "\n", "Open the resulting `.html` file in a browser and the result will be:\n", "\n", "[![](/assets/img/screenshots/jupyter_flex.tests.test_examples/docs_1-one-plot-reference.png)](/examples/1-one-plot.html)\n", "\n", " \n", "\n", "You might notice that the default title of the dashboard is the name of the notebook file, you can customize these using [parameters](#parameters-orientation-and-title)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Cards: Multiple outputs\n", "\n", "A Card is an object that holds one or more Cells. Cells can be markdown or code cells with outputs such as plots, text and widgets.\n", "\n", "You define a new Card by adding a level-3 markdown header (`###`).\n", "\n", "Any output from a tagged Cell will be added to the current Card until a new Card, Section or Page is defined.\n", "\n", "Going back to the notebook example we can add a new plot to the by adding two new cells:\n", "\n", "1. One markdown cell with a level-3 markdown header (`###`)\n", "2. One code cell with the `body` tag" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "### Second plot" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [ "body" ] }, "outputs": [], "source": [ "source = data.stocks()\n", "\n", "plot = alt.Chart(source).mark_area(\n", " color=\"lightblue\",\n", " interpolate='step-after',\n", " line=True\n", ").encode(\n", " x='date',\n", " y='price'\n", ").transform_filter(alt.datum.symbol == 'GOOG')\n", "\n", "plot" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "[![](/assets/img/screenshots/jupyter_flex.tests.test_examples/docs_2-two-plots-reference.png)](/examples/2-two-plots.html)\n", "\n", " \n", "\n", "You will notice two things:\n", "\n", "1. The default layout is a single column with cards stacked vertically and sized to fill available browser height.\n", "2. The value of the level-3 markdown header is added as the Card title" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Sections: Multiple columns\n", "\n", "To add another column to the dashboard define a new Section using a level 2 markdown header (`##`)\n", "\n", "In this case, the value of the header is irrelevant (it wont be shown on the dashboard) it just acts as an indicator to create a new Section." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "## Column" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [ "body" ] }, "outputs": [], "source": [ "source = data.iris()\n", "\n", "plot = alt.Chart(source).mark_circle().encode(\n", " alt.X('sepalLength', scale=alt.Scale(zero=False)),\n", " alt.Y('sepalWidth', scale=alt.Scale(zero=False, padding=1)),\n", " color='species',\n", " size='petalWidth'\n", ")\n", "\n", "plot" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In this case the result would be:\n", "\n", "[![](/assets/img/screenshots/jupyter_flex.tests.test_examples/docs_3-two-columns-reference.png)](/examples/3-two-columns.html)\n", "\n", " \n", "\n", "You will notice another default orientation: to have multiple Sections as columns." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Parameters: Orientation and title\n", "\n", "You can control the parameters of the dashboard such as title, orientation and more by adding a `parameters` tag to a code.\n", "\n", "Let's add a title of `My first Flex dashboard` and change the orientation of the sections to `rows` " ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [ "parameters" ] }, "outputs": [], "source": [ "flex_title = \"My first Flex dashboard\"\n", "flex_orientation = \"rows\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "[![](/assets/img/screenshots/jupyter_flex.tests.test_examples/docs_4-two-rows-reference.png)](/examples/4-two-rows.html)\n", "\n", " \n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Learn more\n", "\n", "Great job! You have created you first Flex dashboard.\n", "\n", "The [Layouts](/layouts) page goes in depth about all the options to control the content of Jupyter-flex dashboards.\n", "\n", "The [Plotting](/plotting) page goes through some considerations around using different plotting libraries in Jupyter-flex dashboards.\n", "\n", "The [Voila and Jupyter Widgets](/voila-widgets/) page describes how to leverage Voila to create dashboards that use a live Jupyter kernel and [Jupyter widgets](https://ipywidgets.readthedocs.io/)." ] } ], "metadata": { "celltoolbar": "Tags", "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.8.12" } }, "nbformat": 4, "nbformat_minor": 4 }