{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "Jupyter-flex allows you to create interactive dashboards based on Jupyter Notebooks based on two simple concepts:\n", "\n", "1. Control the layout of the dashboard using markdown headers\n", "2. Define the dashboard components using Jupyter Notebook cell tags\n", "\n", "## Your first dashboard\n", "\n", "Let's take a very simple Jupyter Notebook with 3 cells and one plot and convert it to a dashboard." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import plotly.express as px" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "df = px.data.iris()" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "fig = px.scatter(df, x=\"sepal_width\", y=\"sepal_length\")\n", "fig.show()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "All you need to do to convert this to a dashboard is to add tag with the value `body` to the that outs the plot.\n", "\n", "
\n", "

How to view and add tags to cells in Jupyter Notebook

\n", "
    \n", "
  1. In the top navigation go to View > Cell Toolbar > Tags
    2. \n", "
  2. Then type \"body\" in the new input of target cell and click on \"Add tag\" or press enter
    3. \n", "
\n", "
" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [ "body" ] }, "outputs": [], "source": [ "fig = px.scatter(df, x=\"sepal_width\", y=\"sepal_length\")\n", "fig.show()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Converting the Notebook to a dashboard \n", "\n", "From here there is a couple of options to convert the notebook to a html dashboard.\n", "\n", "1. You can execute the notebook as you normaly do in the Jupyter Notebook UI and then select: `File > Download as > Flex Dashboard (.html)`:\n", "![Jupyter-flex Download As](/assets/img/getting-started/download-as.png)\n", "2. You can go in a terminal and run `nbconvert`:\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 it so the outputs are shown in the dashboard.\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", "[![Jupyter-flex one plot](/assets/img/screenshots/getting-started/one-plot.png)](/examples/one-plot.html)\n", "\n", "

Click on the image to open the rendered dashboard

\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).\n", "\n", "This is a very simple example, now let's look at the card concept of Jupyter-flex." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Cards: Multiple outputs\n", "\n", "A Card is an object that holds one or more components of the dashboard such as markdown or any output generated from the execution of a Cell such as plots, text and widgets.\n", "\n", "To learn more about cards and its options go to [Layout > Cards](/layouts/#cards).\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": [ "fig = px.scatter(df, x=\"petal_width\", y=\"petal_length\")\n", "fig.show()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "[![Jupyter-flex two plots](/assets/img/screenshots/getting-started/two-plots.png)](/examples/two-plots.html)\n", "\n", "

Click on the image to open the rendered dashboard

\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 to the Card header" ] }, { "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 (since the default theme doesn't show it), it 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": [ "fig = px.scatter(df, x=\"sepal_length\", y=\"petal_length\")\n", "fig.show()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In this case the result would be:\n", "\n", "[![Jupyter-flex two columns](/assets/img/screenshots/getting-started/two-columns.png)](/examples/two-columns.html)\n", "\n", "

Click on the image to open the rendered dashboard

\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 and orientation to be based of rows instead on columns\n", "by tagging a code cell with `parameters`.\n", "\n", "Let's change the orientation of the plot to `rows` and add a title of `A Flex dashboard`." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [ "parameters" ] }, "outputs": [], "source": [ "flex_title = \"A flex dashboard\"\n", "flex_orientation = \"rows\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "[![Jupyter-flex two rows](/assets/img/screenshots/getting-started/two-rows.png)](/examples/two-rows.html)\n", "\n", "

Click on the image to open the rendered dashboard

\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Learning more\n", "\n", "Well done! 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 different plotting libraries in Jupyter-flex dashboards.\n", "\n", "The [Voila and IPywidgets](/voila-ipywidgets/) page describes how to leverage Voila to create dashboards that use a live Jupyter kernel that enable viewers to change underlying parameters and see the results immediately using [ipywidgets](https://ipywidgets.readthedocs.io/)." ] } ], "metadata": { "celltoolbar": "Tags", "kernelspec": { "display_name": "Python 3", "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.7.6" } }, "nbformat": 4, "nbformat_minor": 4 }