doc build for commit f0b691e828f1d84133457eb6bb58fcaf54458a06

altair-viz · Aug 11, 2024 · 62be3ba · 62be3ba
1 parent 267b1ac
commit 62be3ba
Show file tree

Hide file tree

Showing 1,101 changed files with 289,944 additions and 121,836 deletions.
diff --git a/.buildinfo b/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 4ebfb4c88516a1cb411d779ec98bfe19
+config: 56bd5ddc37135c9ead960d45913e4da3
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/_sources/about/roadmap.rst.txt b/_sources/about/roadmap.rst.txt
@@ -1,158 +1,8 @@
-.. _roadmap:
-
 Roadmap
 =======
 
-This page contains the current roadmap for the Vega-Altair project. The roadmap is
-informed by the needs of the Vega-Altair community, and the priorities of the active
-project contributors. It's designed to communicate the direction of the project,
-but it's not a commitment that these items will be completed in a particular timeframe.
-If you would like to help contribute to any of these areas, or suggest new ones,
-please `start a discussion <https://github.com/altair-viz/altair/discussions>`_.
-
-Vega-Altair is deeply integrated with other components in the Vega ecosystem,
-and as such many items on the roadmap will require work in other projects.
-Abbreviations for these projects are included at the end of project descriptions
-where relevant:
-
-* *(VL)* — `Vega-Lite <https://vega.github.io/vega-lite/>`_
-* *(VG)* — `Vega <https://vega.github.io/vega/>`_
-* *(VF)* — `VegaFusion <https://vegafusion.io/>`_
-* *(VC)* — `VlConvert <https://github.com/vega/vl-convert>`_
-
-API Ergonomics
---------------
-The primary job of the Vega-Altair library is to provide an ergonomic Python
-API for generating Vega-Lite JSON specifications, and there are several improvements
-here that we would like to investigate.
-
-Areas of focus:
-
-* Improve the syntax for creating condition expressions with two or more
-  predicates.
-
-* Explore the possibility of a new operator, ``*``, for modular compositing of sub components.
-  See also `Deneb.jl <https://brucala.github.io/Deneb.jl/dev>`_ by @brucala.
-
-* Standardize the API of methods that convert charts into other formats (``alt.Chart().to_<format>``).
-
-* **Released in 5.2:** *Add type hints to the public API and most of the internals so that users can type check their Altair
-  code with a static type  checker such as mypy. This will also make it easier for other packages to
-  integrate with Altair.*
-
-Documentation
--------------
-We want to continue to improve Vega-Altair's official documentation to be more
-useful for both beginning and experienced users.
-
-Areas of focus:
-
-* Incorporate a conceptual guide that includes best practices of effective
-  data communication.
-
-* Update and extend the tutorial section and replace outdated materials.
-
-* Add usage guide with best practices for publishing Vega-Altair charts in various
-  contexts including websites, research papers, embedded dashboards, and interactive
-  platforms.
-
-* Add guide on building domain specific visualization packages on top of Vega-Altair.
-  For example, Vega-Altair for soccer analytics.
-
-* Add documentation for the expression language that is available throughout the API.
-
-Ecosystem Integration
----------------------
-We want Vega-Altair to be well integrated with the PyData ecosystem. It should
-work well with popular libraries and ecosystem standards.
-
-Areas of focus:
-
-* Provide integration with the broader Python DataFrame ecosystem (beyond pandas). Ensure
-  that all of Vega-Altair's features are available to any DataFrame library that implements the
-  `DataFrame Interchange Protocol <https://data-apis.org/dataframe-protocol/latest/index.html>`_.
-
-* Work with dashboard toolkit maintainers to ensure that Vega-Altair is well supported.
-  Write documentation for best practices for making Vega-Altair's interactive features
-  available in Python.
-
-Gridded Data Support
---------------------
-Vega-Altair currently requires tidy tabular data as input, so it is not currently a natural
-choice for working with gridded data. We would like to extend the project to include native
-support for gridded datasets.
-
-Areas of focus:
-
-* Add support for Python array/tensor interchange protocol (through the ``__dlpack__`` interface)
-
-* Add support for creating charts from Xarray
-  `DataArray <https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html>`_
-  objects (rendering large arrays may require the performance work described elsewhere).
-
-Increased Coverage of Statistical Charts
-----------------------------------------
-While Vega-Altair includes support for many types of statistical visualizations,
-there are a few important types that are not yet possible.
-
-Areas of focus:
-
-* Add support for 2D density visualizations
-  (`vega-lite#6043 <https://github.com/vega/vega-lite/issues/6043>`_) *(VL)*
-
-* Add Violin chart support
-  (`vega-lite#3442 <https://github.com/vega/vega-lite/issues/3442>`_) *(VL)*
-
-Map Tile Support
-----------------
-We want Vega-Altair to provide first-class support for displaying map tiles from
-xyz tile providers like OpenStreetMap. We've released a first version of
-`altair_tiles <https://github.com/altair-viz/altair_tiles>`_ to accomplish this. Feedback is very welcome!
-
-Scale/Performance Improvements
-------------------------------
-In the traditional Vega-Altair architecture, a chart's entire input dataset is serialized
-to JSON and transferred to the browser for data transformation and rendering. Rendering
-itself is then performed by The Vega JavaScript library using the Canvas API (which is
-not GPU accelerated). This architecture has many advantages (e.g. chart specifications
-are fully self-contained and portable to Python-free rendering environments), but it
-is not well suited for creating charts of large datasets.
-
-Through a variety of enhancements, our goal is to allow all Vega-Altair charts to
-scale comfortably to over 1 million rows.
-
-Areas of focus:
-
-* Provide optional integration with VegaFusion to automatically
-  move data transformation steps from the browser to efficient multi-threaded implementations
-  in the Python kernel.
-
-* Utilize binary serialization of datasets in Apache Arrow IPC format between the Python kernel
-  and the browser. This will significant reduce serialization time for large unaggregated
-  visualizations such as scatter plots.
-
-* Support creating Vega-Altair charts that reference tables in external database systems, and convert
-  data transformation steps to SQL that can be evaluated by the database before the results are
-  transferred to the Python kernel *(VF)*.
-
-* Add support for GPU accelerated rendering. This will enable rendering of large unnagregated
-  visualizations at interactive speeds. For example, pan and zoom interactions on a large scatter
-  plot *(VG)*.
-
-Static Image Export
--------------------
-Even though Vega-Altair charts are rendered by the Vega JavaScript library, it's important to
-provide reliable (and easy to install) support for exporting charts to static images. Image
-export was dramatically simplified in Vega-Altair 5.0 with the adoption of VlConvert,
-which has no external dependencies on a system web-browser or Node.js installation. Now that
-image export is easy to install and easy to use, we want to improve support for publication
-workflows.
-
-Areas of focus:
-
-* **Released in 5.1:** *Support configurable pixel density in PNG image export* *(VC)*.
-
-* **Released in 5.2:** *Support exporting charts to vector PDF files with embedded text* *(VC)*.
+The roadmap for Vega-Altair and related projects can be found in
+`this project board <https://github.com/orgs/vega/projects/9/views/3?pane=info>`_.
 
 .. toctree::
    :maxdepth: 1
@@ -163,3 +13,4 @@ Areas of focus:
    code_of_conduct
    governance
    citing
+   versioning
diff --git a/_sources/about/versioning.rst.txt b/_sources/about/versioning.rst.txt
@@ -0,0 +1,46 @@
+Versioning
+==========
+Vega-Altair has historically released major versions that coincide with those of Vega-Lite_.
+
+As the projects have matured, and major versions become less frequent, there has been a growing need to introduce breaking changes between these major versions.
+Such changes would allow Vega-Altair to address technical debt and improve upon API ergonomics.
+
+To ensure future releases clearly communicate changes, Vega-Altair will be working towards adopting SemVer_.
+
+Public API
+----------
+Functionality documented in :ref:`api` defines the Vega-Altair public API.
+
+Version numbers
+---------------
+
+A Vega-Altair release number is composed of ``MAJOR.MINOR.PATCH``.
+
+* Backward incompatible API changes increment **MAJOR** version (``4.2.2`` - ``5.0.0``)
+* New backward compatible functionality increment **MINOR** version (``5.2.0`` - ``5.3.0``)
+* Backward compatible bug fixes increment **PATCH** version (``5.1.1`` - ``5.1.2``)
+
+**MAJOR** versions will *likely* continue to increase with a **MAJOR** increment to Vega-Lite_.
+
+Deprecation
+-----------
+Deprecation warnings may be introduced in **MAJOR** and **MINOR** versions, 
+but the removal of deprecated functionality will not occur until *at least* the next **MAJOR** version.
+
+For upstream breaking changes that trigger a **MAJOR** version, 
+we *may* provide a deprecation warning if we consider the change especially disruptive.
+
+Starting in version ``5.4.0``, all deprecation warnings *must* specify:
+
+* the version number they were introduced
+
+Where possible, deprecation warnings *may* specify:
+
+* an alternative function/method/parameter/class to use instead
+* an explanation for why this change had to be made
+
+Deprecated functionality *may* be removed from the Vega-Altair documentation, if there is a 
+suitable replacement and we believe inclusion of both could confuse new users.
+
+.. _Vega-Lite: https://github.com/vega/vega-lite
+.. _SemVer: https://semver.org/
diff --git a/_sources/gallery/bump_chart.rst.txt b/_sources/gallery/bump_chart.rst.txt
@@ -25,7 +25,7 @@ window transform.
     import pandas as pd
 
     stocks = data.stocks()
-    source = stocks.groupby([pd.Grouper(key="date", freq="6M"),"symbol"]).mean().reset_index()
+    source = stocks.groupby([pd.Grouper(key="date", freq="6MS"),"symbol"]).mean().reset_index()
 
     alt.Chart(source).mark_line(point = True).encode(
         x = alt.X("date:O", timeUnit="yearmonth", title="date"),
@@ -55,7 +55,7 @@ window transform.
             import pandas as pd
 
             stocks = data.stocks()
-            source = stocks.groupby([pd.Grouper(key="date", freq="6M"),"symbol"]).mean().reset_index()
+            source = stocks.groupby([pd.Grouper(key="date", freq="6MS"),"symbol"]).mean().reset_index()
 
             alt.Chart(source).mark_line(point=True).encode(
                 x=alt.X("date:O").timeUnit("yearmonth").title("date"),
@@ -84,7 +84,7 @@ window transform.
             import pandas as pd
 
             stocks = data.stocks()
-            source = stocks.groupby([pd.Grouper(key="date", freq="6M"),"symbol"]).mean().reset_index()
+            source = stocks.groupby([pd.Grouper(key="date", freq="6MS"),"symbol"]).mean().reset_index()
 
             alt.Chart(source).mark_line(point = True).encode(
                 x = alt.X("date:O", timeUnit="yearmonth", title="date"),

diff --git a/_sources/gallery/hexbins.rst.txt b/_sources/gallery/hexbins.rst.txt
@@ -43,7 +43,7 @@ This example shows a hexbin chart.
                                                        labelPadding=20, tickOpacity=0, domainOpacity=0)),
         stroke=alt.value('black'),
         strokeWidth=alt.value(0.2),
-        fill=alt.Color('mean(temp_max):Q', scale=alt.Scale(scheme='darkblue')),
+        fill=alt.Fill('mean(temp_max):Q', scale=alt.Scale(scheme='darkblue')),
         tooltip=['month(' + xField + '):O', 'day(' + yField + '):O', 'mean(temp_max):Q']
     ).transform_calculate(
         # This field is required for the hexagonal X-Offset
@@ -93,7 +93,7 @@ This example shows a hexbin chart.
                     .axis(labelPadding=20, tickOpacity=0, domainOpacity=0),
                 stroke=alt.value('black'),
                 strokeWidth=alt.value(0.2),
-                fill=alt.Color('mean(temp_max):Q').scale(scheme='darkblue'),
+                fill=alt.Fill('mean(temp_max):Q').scale(scheme='darkblue'),
                 tooltip=['month(' + xField + '):O', 'day(' + yField + '):O', 'mean(temp_max):Q']
             ).transform_calculate(
                 # This field is required for the hexagonal X-Offset
@@ -139,7 +139,7 @@ This example shows a hexbin chart.
                                                                labelPadding=20, tickOpacity=0, domainOpacity=0)),
                 stroke=alt.value('black'),
                 strokeWidth=alt.value(0.2),
-                fill=alt.Color('mean(temp_max):Q', scale=alt.Scale(scheme='darkblue')),
+                fill=alt.Fill('mean(temp_max):Q', scale=alt.Scale(scheme='darkblue')),
                 tooltip=['month(' + xField + '):O', 'day(' + yField + '):O', 'mean(temp_max):Q']
             ).transform_calculate(
                 # This field is required for the hexagonal X-Offset

diff --git a/_sources/gallery/index.rst.txt b/_sources/gallery/index.rst.txt
@@ -813,6 +813,17 @@ Circular Plots
      <span class="image-title">Pie Chart with Labels</span>
    </a>
 
+   <a class="imagegroup" href="polar_bar_chart.html">
+   <span
+        class="image" alt="Polar Bar Chart"
+
+        style="background-image: url(../_static/polar_bar_chart-thumb.png);"
+
+    ></span>
+
+     <span class="image-title">Polar Bar Chart</span>
+   </a>
+
    <a class="imagegroup" href="radial_chart.html">
    <span
         class="image" alt="Radial Chart"
@@ -1464,6 +1475,17 @@ Interactive Charts
 
    <span class="gallery">
 
+   <a class="imagegroup" href="interactive_bar_select_highlight.html">
+   <span
+        class="image" alt="Bar Chart with Highlighting on Hover and Selection on Click"
+
+        style="background-image: url(../_static/interactive_bar_select_highlight-thumb.png);"
+
+    ></span>
+
+     <span class="image-title">Bar Chart with Highlighting on Hover and Selection on Click</span>
+   </a>
+
    <a class="imagegroup" href="selection_layer_bar_month.html">
    <span
         class="image" alt="Interactive Average"
@@ -1618,6 +1640,17 @@ Interactive Charts
      <span class="image-title">Multiple Interactions</span>
    </a>
 
+   <a class="imagegroup" href="interactive_reorder_stacked_bars.html">
+   <span
+        class="image" alt="Reorder stacked bar segments"
+
+        style="background-image: url(../_static/interactive_reorder_stacked_bars-thumb.png);"
+
+    ></span>
+
+     <span class="image-title">Reorder stacked bar segments</span>
+   </a>
+
    <a class="imagegroup" href="scatter_with_histogram.html">
    <span
         class="image" alt="Scatter Plot and Histogram with Interval Selection"
@@ -1629,6 +1662,17 @@ Interactive Charts
      <span class="image-title">Scatter Plot and Histogram with Interval Selection</span>
    </a>
 
+   <a class="imagegroup" href="scatter_point_paths_hover.html">
+   <span
+        class="image" alt="Scatter plot with point paths on hover with search box"
+
+        style="background-image: url(../_static/scatter_point_paths_hover-thumb.png);"
+
+    ></span>
+
+     <span class="image-title">Scatter plot with point paths on hover with search box</span>
+   </a>
+
    <a class="imagegroup" href="select_detail.html">
    <span
         class="image" alt="Selection Detail"
@@ -1732,6 +1776,17 @@ Advanced Calculations
      <span class="image-title">Comet Chart</span>
    </a>
 
+   <a class="imagegroup" href="line_chart_with_cumsum_faceted.html">
+   <span
+        class="image" alt="Faceted Line Chart with Cumulative Sum"
+
+        style="background-image: url(../_static/line_chart_with_cumsum_faceted-thumb.png);"
+
+    ></span>
+
+     <span class="image-title">Faceted Line Chart with Cumulative Sum</span>
+   </a>
+
    <a class="imagegroup" href="gantt_chart.html">
    <span
         class="image" alt="Gantt Chart"