Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Be clearer about how vegafusion works #3052

Merged
merged 1 commit into from
May 11, 2023
Merged

Be clearer about how vegafusion works #3052

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 19 additions & 14 deletions doc/user_guide/large_datasets.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ If you try to create a plot that will directly embed a dataset with more than
import pandas as pd

data = pd.DataFrame({"x": range(10000)})
alt.Chart(data).mark_line()
alt.Chart(data).mark_point()

.. code-block:: none

Expand Down Expand Up @@ -336,15 +336,15 @@ summary statistics to Altair instead of the full dataset.
VegaFusion
~~~~~~~~~~
`VegaFusion`_ is a third-party package that re-implements most Vega-Lite transforms for evaluation
in the Python kernel. This makes it possible to scale many Altair charts to millions of rows as long as
they include some form of aggregation.

VegaFusion 1.0 provides two rendering modes that are useful in different situations.
in the Python kernel, which makes it possible to scale Altair charts to millions of rows of data.
VegaFusion provides two rendering modes that are useful in different situations.

Mime Renderer
^^^^^^^^^^^^^
The `VegaFusion mime renderer`_ is a good choice for charts that do not re-aggregate or re-filter data in response
to selections. It is enabled with:
The `VegaFusion mime renderer`_ is a good choice for charts that contain aggregations
and that do not re-aggregate or re-filter data in response to selections
(so it offers similar but more advanced functionality as the ``altair-transform`` package).
It is enabled with:

.. code-block:: python

Expand All @@ -357,23 +357,28 @@ Python kernel. It then removes any unused columns and inlines the transformed da
for rendering.

Charts rendered this way are self-contained and do not require the Python kernel or a custom
notebook extension to display. They are rendered with the same frontend functionality that
notebook extension to display. They are rendered with the same frontend functionality that
is already used to display regular Altair charts.

Widget Renderer
^^^^^^^^^^^^^^^
The `VegaFusion widget renderer`_ is a good choice for charts that re-aggregate or re-filter data in response
to selections. It is enabled with:
The `VegaFusion widget renderer`_ is a good choice for displaying unaggregated data
and for aggregated charts that re-aggregate or re-filter data in response to selections
(so it offers similar but more advanced functionality as the ``altair-data-server`` package).
It is enabled with:

.. code-block:: python

import vegafusion as vf
vf.enable_widget()

The widget renderer uses a Jupyter Widget extension to maintain a live connection between the displayed
chart and the Python kernel. This makes it possible for transforms to be evaluated interactively in response to
changes in selections. Charts rendered this way require a running Python kernel and Jupyter Widget extension to
display.
The widget renderer uses a Jupyter Widget extension to maintain a live connection between the displayed chart and the Python kernel.
This makes it possible for transforms to be evaluated interactively in response to changes in selections,
and to send the datasets to the client in arrow format separately instead of inlining them in the chart json spec.

Charts rendered this way require a running Python kernel and Jupyter Widget extension to
display, which works in many frontends including locally in the classic notebook, JupyterLab, and VSCode,
as well as remotely in Colab and Binder.

.. _VegaFusion: https://vegafusion.io
.. _VegaFusion mime renderer: https://vegafusion.io/mime_renderer.html
Expand Down