From 6f6b9f7a9891af70c4e28c8d3ac8636d13e8de78 Mon Sep 17 00:00:00 2001 From: Jon Mease Date: Tue, 26 Mar 2024 11:42:27 -0400 Subject: [PATCH] Update docs --- doc/user_guide/display_frontends.rst | 107 ++++++++++++++++++--------- 1 file changed, 71 insertions(+), 36 deletions(-) diff --git a/doc/user_guide/display_frontends.rst b/doc/user_guide/display_frontends.rst index 132001a78..e44acd48e 100644 --- a/doc/user_guide/display_frontends.rst +++ b/doc/user_guide/display_frontends.rst @@ -55,6 +55,11 @@ The most used built-in renderers are: dependencies from the ``vl-convert-python`` package (rather than from an online CDN) so that an internet connection is not required. +``alt.renderers.enable("browser")`` + *(added in version 5.3):* Display charts in an external web browser. This renderer is + particularly useful when using Vega-Altair in a local non-Jupyter environment, such as + in `IPython`_ or `Spyder`_. See :ref:`display-browser` for more information. + In addition, Altair includes the following renderers: - ``"default"``, ``"colab"``, ``"kaggle"``, ``"zeppelin"``: identical to ``"html"`` @@ -179,57 +184,83 @@ 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 +environment, but to render these specifications currently requires a JavaScript engine. For this reason, Altair works most seamlessly with the browser-based -environments mentioned above. +environments mentioned above. Even so, Altair can be used effectively in non-browser +based environments using the approaches described below. -If you would like to render plots from another Python interface that does not -have a built-in javascript engine, you'll need to somehow connect your charts -to a second tool that can execute javascript. +Static Image Renderers +~~~~~~~~~~~~~~~~~~~~~~ +The ``"png"`` and ``"svg"`` renderers rely on the JavaScript engine embedded in +the vl-convert optional dependency to generate static images from Vega-Lite chart +specifications. These static images are then displayed in IPython-based environments +using the Mime Renderer Extensions system. This approach may be used to display static +versions of Altair charts inline in the `IPython QtConsole`_ and `Spyder`_, as well as +in browser-based environments like JupyterLab. -There are a few options available for this: +The ``"svg"`` renderer is enabled like this:: -Altair Viewer -~~~~~~~~~~~~~ -.. note:: - - altair_viewer does not yet support Altair 5. + alt.renderers.enable("svg") -For non-notebook IDEs, a useful companion is the `Altair Viewer`_ package, -which provides an Altair renderer that works directly from any Python terminal. -Start by installing the package:: - $ pip install altair_viewer +The ``"png"`` renderer is enabled like this:: -When enabled, this will serve charts via a local HTTP server and automatically open -a browser window in which to view them, with subsequent charts displayed in the -same window. + alt.renderers.enable("png") -If you are using an IPython-compatible terminal ``altair_viewer`` can be enabled via -Altair's standard renderer framework:: - import altair as alt - alt.renderers.enable('altair_viewer') +The ``"png"`` renderer supports the following keyword argument configuration options: -If you prefer to manually trigger chart display, you can use the built-in :meth:`Chart.show` -method to manually trigger chart display:: +- The ``scale_factor`` argument may be used to increase the chart size by the specified + scale factor (Default 1.0). +- The ``ppi`` argument controls the pixels-per-inch resolution of the displayed image (Default 72). - import altair as alt +Example usage:: - # load a simple dataset as a pandas DataFrame - from vega_datasets import data - cars = data.cars() + alt.renderers.enable("png", scale_factor=2, ppi=144) - chart = alt.Chart(cars).mark_point().encode( - x='Horsepower', - y='Miles_per_Gallon', - color='Origin', - ).interactive() - chart.show() +.. _display-browser: + +Browser Renderer +~~~~~~~~~~~~~~~~ +To support displaying charts with interactive features in non-browser based environments, +the ``"browser"`` renderer automatically opens charts in browser tabs of a system web browser. + +The ``"browser"`` renderer is enabled like this:: + + alt.renderers.enable("browser") + + +The ``"browser"`` renderer supports the following keyword argument configuration options: + +- The ``using`` argument may be used to specify which system web browser to use. This + may be set to a string to indicate the single browser that must be used (e.g. ``"safari"``), + or it may be set to a list of browser names where the first available browser is used. See the + documentation for the `webbrowser module`_ for the list of supported browser names. If not + specified, the system default browser is used. +- The ``offline`` argument may be used to specify whether JavaScript dependencies should + be loaded from an online CDN or embedded alongside the chart specification. When ``offline`` + is ``False`` (The default), JavaScript dependencies are loaded from an online CDN, and so + an internet connection is required. When ``offline`` is ``True``, JavaScript dependencies + are embedded alongside chart specification and so no internet connection is required. Setting + ``offline`` to ``True`` requires the optional ``vl-convert-python`` dependency. +- The ``port`` argument may be used to configure the system port that the chart HTML is served + on. Defaults to a random open port. + +Limitations: + +- The ``"browser"`` renderer sets up a temporary web server that serves the chart exactly once, + then opens the designated browser pointing to this server's URL. This approach does not require + the creation of temporary HTML files on disk, and it's memory efficient as there are no long-lived + web server processes required. A limitation of this approach is that the chart will be lost if the + browser is refreshed, and it's not possible to copy the chart URL and paste it in another browser + tab. +- When used in IPython-based environments, the ``"browser"`` renderer will automatically open the + chart in the browser when the chart is the final value of the cell or command. This behavior is not + available in the standard ``python`` REPL. In this case, the ``chart.show()`` method may be used to + manually invoke the active renderer and open the chart in the browser. +- This renderer is not compatible with remote environments like Binder or Colab. -This command will block the Python interpreter until the browser window containing -the chart is closed. Manual ``save()`` and display ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -678,3 +709,7 @@ see :ref:`display-general`. .. _Vega: https://vega.github.io/vega/ .. _VSCode-Python: https://code.visualstudio.com/docs/python/python-tutorial .. _Zeppelin: https://zeppelin.apache.org/ +.. _IPython: https://ipython.org/ +.. _Spyder: https://www.spyder-ide.org/ +.. _IPython QtConsole: https://qtconsole.readthedocs.io/en/stable/ +.. _webbrowser module: https://docs.python.org/3/library/webbrowser.html#webbrowser.register