From b40590d199dda4b993db94332fd22478ceccf856 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Sat, 23 Dec 2023 19:48:38 +0100 Subject: [PATCH 1/5] Docs: Add section on displaying Altair charts in dashboards --- doc/user_guide/display_frontends.rst | 33 ++++++++++++++++++---------- 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/doc/user_guide/display_frontends.rst b/doc/user_guide/display_frontends.rst index ad418bea8..64f2d589e 100644 --- a/doc/user_guide/display_frontends.rst +++ b/doc/user_guide/display_frontends.rst @@ -137,8 +137,27 @@ Optionally, for offline rendering, you can use the mimetype renderer:: .. _display-general: -Working in non-Notebook Environments ------------------------------------- +Dashboards +---------- +Altair is compatible with common Python dashboarding packages. Some of them even provide support for reading out :ref:`parameters ` from the chart. +This allows you to e.g. select data points and update another part of the dashboard such as a table based on that selection: + +=================================================================================================================================== =================================== ============================= +Package Displays interactive Altair charts Supports reading out parameters +=================================================================================================================================== =================================== ============================= +`Panel `_ ✔ ✔ +`Plotly Dash `_ using `dash_vega_components `_ ✔ ✔ +`Jupyter Voila `_ using :ref:`JupyterChart ` ✔ ✔ +`Shiny `_ using :ref:`JupyterChart ` ✔ ✔ +`Solara `_ ✔ ✔ +`Streamlit `_ ✔ +=================================================================================================================================== =================================== ============================= + +If you are using a dashboarding package that is not listed here, please `open an issue `_ on GitHub so that we can add it. + + +Working in environments without a JavaScript frontend +----------------------------------------------------- The Vega-Lite specifications produced by Altair can be produced in any Python environment, but to render these specifications currently requires a javascript engine. For this reason, Altair works most seamlessly with the browser-based @@ -150,16 +169,6 @@ to a second tool that can execute javascript. There are a few options available for this: -Vega-enabled IDEs -~~~~~~~~~~~~~~~~~ -Some IDEs have extensions that natively recognize and display Altair charts. -Examples are: - -- The `VSCode-Python`_ extension, which supports native Altair and Vega-Lite - chart display as of November 2019. -- The Hydrogen_ project, which is built on nteract_ and renders Altair charts - via the ``mimetype`` renderer. - Altair Viewer ~~~~~~~~~~~~~ .. note:: From 31cada786c565e93f2c4b198e4ff336fc3ba22c1 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Sat, 23 Dec 2023 19:51:01 +0100 Subject: [PATCH 2/5] Fix title line length --- doc/user_guide/display_frontends.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/display_frontends.rst b/doc/user_guide/display_frontends.rst index 64f2d589e..2397a62b2 100644 --- a/doc/user_guide/display_frontends.rst +++ b/doc/user_guide/display_frontends.rst @@ -157,7 +157,7 @@ If you are using a dashboarding package that is not listed here, please `open an Working in environments without a JavaScript frontend ------------------------------------------------------ +----------------------------------------------------- The Vega-Lite specifications produced by Altair can be produced in any Python environment, but to render these specifications currently requires a javascript engine. For this reason, Altair works most seamlessly with the browser-based From ab7906cf9f9f58e3c5d05b2a555f4337f3105cbb Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Sat, 23 Dec 2023 20:09:09 +0100 Subject: [PATCH 3/5] Add note to changelog --- doc/releases/changes.rst | 2 ++ doc/user_guide/display_frontends.rst | 3 ++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/releases/changes.rst b/doc/releases/changes.rst index 206e7f8c3..ff7dacb6f 100644 --- a/doc/releases/changes.rst +++ b/doc/releases/changes.rst @@ -8,6 +8,8 @@ Version 5.3.0 (unreleased month day, year) Enhancements ~~~~~~~~~~~~ +- Docs: Add :ref:`section on dashboards ` which have support for Altair (#3299) + Bug Fixes ~~~~~~~~~ Backward-Incompatible Changes diff --git a/doc/user_guide/display_frontends.rst b/doc/user_guide/display_frontends.rst index 2397a62b2..9e09d5f20 100644 --- a/doc/user_guide/display_frontends.rst +++ b/doc/user_guide/display_frontends.rst @@ -135,7 +135,7 @@ Optionally, for offline rendering, you can use the mimetype renderer:: # Optional in VS Code alt.renderers.enable('mimetype') -.. _display-general: +.. _display_dashboards: Dashboards ---------- @@ -155,6 +155,7 @@ Package If you are using a dashboarding package that is not listed here, please `open an issue `_ on GitHub so that we can add it. +.. _display-general: Working in environments without a JavaScript frontend ----------------------------------------------------- From 2ca0dafe2b482126ccea218d330968676558a432 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Mon, 25 Dec 2023 10:29:45 +0100 Subject: [PATCH 4/5] Add note about Quarto and Jupyter Book --- doc/user_guide/display_frontends.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/user_guide/display_frontends.rst b/doc/user_guide/display_frontends.rst index 9e09d5f20..c440b7155 100644 --- a/doc/user_guide/display_frontends.rst +++ b/doc/user_guide/display_frontends.rst @@ -153,6 +153,9 @@ Package `Streamlit `_ ✔ =================================================================================================================================== =================================== ============================= +The above mentioned frameworks all require you to run a web application on a server if you want to share your work with others. A web application gives you a lot of flexibility, you can for example fetch data from a database based on the value of a dropdown menu in the dashboard. However, it comes with some complexity as well. +For use cases where the interactivity provided by Altair itself is enough, you can also use tools which generate HTML pages which do not require a web server such as `Quarto `_ or `Jupyter Book `_. + If you are using a dashboarding package that is not listed here, please `open an issue `_ on GitHub so that we can add it. .. _display-general: From 1769a238c91f0e74b3825351b6149f023d0d4cd7 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Wed, 27 Dec 2023 17:56:38 +0100 Subject: [PATCH 5/5] Change 'Some' to 'Many' --- doc/user_guide/display_frontends.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/display_frontends.rst b/doc/user_guide/display_frontends.rst index c440b7155..2d4d78b7e 100644 --- a/doc/user_guide/display_frontends.rst +++ b/doc/user_guide/display_frontends.rst @@ -139,7 +139,7 @@ Optionally, for offline rendering, you can use the mimetype renderer:: Dashboards ---------- -Altair is compatible with common Python dashboarding packages. Some of them even provide support for reading out :ref:`parameters ` from the chart. +Altair is compatible with common Python dashboarding packages. Many of them even provide support for reading out :ref:`parameters ` from the chart. This allows you to e.g. select data points and update another part of the dashboard such as a table based on that selection: =================================================================================================================================== =================================== =============================