Merge branch 'main' into type_hint_api

.github/workflows/build.yml

@@ -40,8 +40,8 @@ jobs:
         if: ${{ matrix.python-version == '3.8' }}
         run: |
           pip uninstall -y pyarrow vegafusion vegafusion-python-embed
-      - name: Maybe install lowest supported Pandas version
-        # We install the lowest supported Pandas version for one job to test that
+      - name: Maybe install lowest supported pandas version
+        # We install the lowest supported pandas version for one job to test that
         # it still works. Downgrade to the oldest versions of pandas and numpy that include
         # Python 3.8 wheels, so only run this job for Python 3.8
         if: ${{ matrix.python-version == '3.8' }}

CONTRIBUTING.md

@@ -53,6 +53,14 @@ git switch -c <your-branch-name>
 
 With this branch checked-out, make the desired changes to the package.
 
+A large part of Altair's code base is automatically generated.
+After you have made your manual changes,
+make sure to run the following to see if there are any changes
+to the automatically generated files: `python tools/generate_schema_wrapper.py`.
+
+For information on how to update the Vega-Lite version that Altair uses,
+please read [the maintainers' notes](NOTES_FOR_MAINTAINERS.md).
+
 ### Testing your Changes
 
 Before suggesting your contributing your changing to the main Altair repository,

RELEASING.md

@@ -1,6 +1,5 @@
-1. Create a new virtual environment following the instructions in `CONTRIBUTING.md`. 
-   Make sure to also install all dependencies for the documentation including `altair_saver`
-   and uninstall `vl-convert-python` (this is not needed for normal contributions to the repo, see `CONTRIBUTING.md` for details).
+1. Create a new virtual environment following the instructions in `CONTRIBUTING.md`.
+   Make sure to also install all dependencies for the documentation.
 
 2. Make certain your branch is in sync with head:
 
@@ -21,7 +20,7 @@
 5. Update version to, e.g. 5.0.0:
 
    - in ``altair/__init__.py``
-   - in ``doc/conf.py`` (two places)
+   - in ``doc/conf.py``
 
 6. Double-check that all vega-lite/vega/vega-embed versions are up-to-date:
 
@@ -55,19 +54,21 @@
 12. update version to, e.g. 5.1.0dev:
 
     - in ``altair/__init__.py``
-    - in ``doc/conf.py`` (two places)
+    - in ``doc/conf.py``
 
 13. add a new changelog entry for the unreleased version:
 
-       Version 5.1.0 (unreleased)
-       --------------------------
-
-       Enhancements
-       ~~~~~~~~~~~~
-       Bug Fixes
-       ~~~~~~~~~
-       Backward-Incompatible Changes
-       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    ```
+    Version 5.1.0 (unreleased)
+    --------------------------
+
+    Enhancements
+    ~~~~~~~~~~~~
+    Bug Fixes
+    ~~~~~~~~~
+    Backward-Incompatible Changes
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    ```
 
 14. Commit change and push to main:
 

altair/utils/_importers.py

@@ -29,7 +29,7 @@ def import_vegafusion() -> ModuleType:
 
 
 def import_vl_convert() -> ModuleType:
-    min_version = "0.13.0"
+    min_version = "0.14.0"
     try:
         version = importlib_version("vl-convert-python")
         if Version(version) < Version(min_version):

altair/utils/core.py

@@ -343,7 +343,7 @@ def to_list_if_array(val):
         if dtype_name == "category":
             # Work around bug in to_json for categorical types in older versions
             # of pandas as they do not properly convert NaN values to null in to_json.
-            # We can probably remove this part once we require Pandas >= 1.0
+            # We can probably remove this part once we require pandas >= 1.0
             col = df[col_name].astype(object)
             df[col_name] = col.where(col.notnull(), None)
         elif dtype_name == "string":
@@ -588,8 +588,10 @@ def parse_shorthand(
                     column = dfi.get_column_by_name(unescaped_field)
                     try:
                         attrs["type"] = infer_vegalite_type_for_dfi_column(column)
-                    except NotImplementedError:
-                        # Fall back to pandas-based inference
+                    except (NotImplementedError, AttributeError, ValueError):
+                        # Fall back to pandas-based inference.
+                        # Note: The AttributeError catch is a workaround for
+                        # https://github.com/pandas-dev/pandas/issues/55332
                         if isinstance(data, pd.DataFrame):
                             attrs["type"] = infer_vegalite_type(data[unescaped_field])
                         else:

altair/vegalite/v5/api.py

@@ -3009,7 +3009,7 @@ class RepeatChart(TopLevelMixin, core.TopLevelRepeatSpec):
 
     # Because TopLevelRepeatSpec is defined as a union as of Vega-Lite schema 4.9,
     # we set the arguments explicitly here.
-    # TODO: Should we instead use tools/schemapi/codegen._get_args?
+    # TODO: Should we instead use tools/schemapi/codegen.get_args?
     @utils.use_signature(core.TopLevelRepeatSpec)
     def __init__(
         self,

altair/vegalite/v5/schema/__init__.py

@@ -1,5 +1,5 @@
 # ruff: noqa
 from .core import *
 from .channels import *
-SCHEMA_VERSION = 'v5.14.1'
-SCHEMA_URL = 'https://vega.github.io/schema/vega-lite/v5.14.1.json'
+SCHEMA_VERSION = 'v5.15.1'
+SCHEMA_URL = 'https://vega.github.io/schema/vega-lite/v5.15.1.json'

altair/vegalite/v5/schema/core.py

@@ -7054,6 +7054,13 @@ class IntervalSelectionConfig(VegaLiteSchema):
         An array of encoding channels. The corresponding data field values must match for a
         data tuple to fall within the selection.
 
+        **See also:** The `projection with encodings and fields section
+        <https://vega.github.io/vega-lite/docs/selection.html#project>`__ in the
+        documentation.
+    fields : List(:class:`FieldName`)
+        An array of field names whose values must match for a data tuple to fall within the
+        selection.
+
         **See also:** The `projection with encodings and fields section
         <https://vega.github.io/vega-lite/docs/selection.html#project>`__ in the
         documentation.
@@ -7121,10 +7128,11 @@ class IntervalSelectionConfig(VegaLiteSchema):
     """
     _schema = {'$ref': '#/definitions/IntervalSelectionConfig'}
 
-    def __init__(self, type=Undefined, clear=Undefined, encodings=Undefined, mark=Undefined,
-                 on=Undefined, resolve=Undefined, translate=Undefined, zoom=Undefined, **kwds):
+    def __init__(self, type=Undefined, clear=Undefined, encodings=Undefined, fields=Undefined,
+                 mark=Undefined, on=Undefined, resolve=Undefined, translate=Undefined, zoom=Undefined,
+                 **kwds):
         super(IntervalSelectionConfig, self).__init__(type=type, clear=clear, encodings=encodings,
-                                                      mark=mark, on=on, resolve=resolve,
+                                                      fields=fields, mark=mark, on=on, resolve=resolve,
                                                       translate=translate, zoom=zoom, **kwds)
 
 
@@ -7150,6 +7158,13 @@ class IntervalSelectionConfigWithoutType(VegaLiteSchema):
         An array of encoding channels. The corresponding data field values must match for a
         data tuple to fall within the selection.
 
+        **See also:** The `projection with encodings and fields section
+        <https://vega.github.io/vega-lite/docs/selection.html#project>`__ in the
+        documentation.
+    fields : List(:class:`FieldName`)
+        An array of field names whose values must match for a data tuple to fall within the
+        selection.
+
         **See also:** The `projection with encodings and fields section
         <https://vega.github.io/vega-lite/docs/selection.html#project>`__ in the
         documentation.
@@ -7217,11 +7232,12 @@ class IntervalSelectionConfigWithoutType(VegaLiteSchema):
     """
     _schema = {'$ref': '#/definitions/IntervalSelectionConfigWithoutType'}
 
-    def __init__(self, clear=Undefined, encodings=Undefined, mark=Undefined, on=Undefined,
-                 resolve=Undefined, translate=Undefined, zoom=Undefined, **kwds):
+    def __init__(self, clear=Undefined, encodings=Undefined, fields=Undefined, mark=Undefined,
+                 on=Undefined, resolve=Undefined, translate=Undefined, zoom=Undefined, **kwds):
         super(IntervalSelectionConfigWithoutType, self).__init__(clear=clear, encodings=encodings,
-                                                                 mark=mark, on=on, resolve=resolve,
-                                                                 translate=translate, zoom=zoom, **kwds)
+                                                                 fields=fields, mark=mark, on=on,
+                                                                 resolve=resolve, translate=translate,
+                                                                 zoom=zoom, **kwds)
 
 
 class JoinAggregateFieldDef(VegaLiteSchema):
@@ -21862,7 +21878,8 @@ class EventType(WindowEventType):
 
     enum('click', 'dblclick', 'dragenter', 'dragleave', 'dragover', 'keydown', 'keypress',
     'keyup', 'mousedown', 'mousemove', 'mouseout', 'mouseover', 'mouseup', 'mousewheel',
-    'timer', 'touchend', 'touchmove', 'touchstart', 'wheel')
+    'pointerdown', 'pointermove', 'pointerout', 'pointerover', 'pointerup', 'timer', 'touchend',
+    'touchmove', 'touchstart', 'wheel')
     """
     _schema = {'$ref': '#/definitions/EventType'}
 

altair/vegalite/v5/schema/vega-lite-schema.json

@@ -8791,6 +8791,11 @@
         "mouseover",
         "mouseup",
         "mousewheel",
+        "pointerdown",
+        "pointermove",
+        "pointerout",
+        "pointerover",
+        "pointerup",
         "timer",
         "touchend",
         "touchmove",
@@ -12467,6 +12472,13 @@
           },
           "type": "array"
         },
+        "fields": {
+          "description": "An array of field names whose values must match for a data tuple to fall within the selection.\n\n__See also:__ The [projection with `encodings` and `fields` section](https://vega.github.io/vega-lite/docs/selection.html#project) in the documentation.",
+          "items": {
+            "$ref": "#/definitions/FieldName"
+          },
+          "type": "array"
+        },
         "mark": {
           "$ref": "#/definitions/BrushConfig",
           "description": "An interval selection also adds a rectangle mark to depict the extents of the interval. The `mark` property can be used to customize the appearance of the mark.\n\n__See also:__ [`mark` examples](https://vega.github.io/vega-lite/docs/selection.html#mark) in the documentation."
@@ -12535,6 +12547,13 @@
           },
           "type": "array"
         },
+        "fields": {
+          "description": "An array of field names whose values must match for a data tuple to fall within the selection.\n\n__See also:__ The [projection with `encodings` and `fields` section](https://vega.github.io/vega-lite/docs/selection.html#project) in the documentation.",
+          "items": {
+            "$ref": "#/definitions/FieldName"
+          },
+          "type": "array"
+        },
         "mark": {
           "$ref": "#/definitions/BrushConfig",
           "description": "An interval selection also adds a rectangle mark to depict the extents of the interval. The `mark` property can be used to customize the appearance of the mark.\n\n__See also:__ [`mark` examples](https://vega.github.io/vega-lite/docs/selection.html#mark) in the documentation."

doc/_static/custom.css

@@ -70,11 +70,23 @@ properly displayed on mobile devices and not restricted to 20% */
   vertical-align: text-bottom;
   margin-right: 3px;
 }
-  
+
 .full-width-plot {
   width: 100%;
 }
 
+/* This hides the Ctrl + K from the search box on the start page
+ * to make it less distracting on the home page.
+ * The shortcut still shows up when clicking the search box */
+.search-button-field > .search-button__kbd-shortcut {
+    display: none;
+}
+
+/* Use old light blue color for banner since it goes better with the Altair logo */
+.bd-header-announcement {
+    background-color: #daebf1 !important;
+}
+
 /* Configurations for the start page
 ------------------------------------ */
 .lead {
@@ -92,4 +104,4 @@ properly displayed on mobile devices and not restricted to 20% */
   /* Default is bolder which is less */
   font-weight: bold;
 }
-/* ---------------------------------- */
+/* ---------------------------------- */

doc/about/citing.rst

@@ -0,0 +1,41 @@
+Citing
+===============
+
+Vega-Altair
+-----------
+If you use Vega-Altair in academic work, please consider citing
+`Altair: Interactive Statistical Visualizations for Python <https://joss.theoj.org/papers/10.21105/joss.01057>`_ as
+
+.. code-block::
+
+  @article{VanderPlas2018,
+    doi = {10.21105/joss.01057},
+    url = {https://doi.org/10.21105/joss.01057},
+    year = {2018},
+    publisher = {The Open Journal},
+    volume = {3},
+    number = {32},
+    pages = {1057},
+    author = {Jacob VanderPlas and Brian Granger and Jeffrey Heer and Dominik Moritz and Kanit Wongsuphasawat and Arvind Satyanarayan and Eitan Lees and Ilia Timofeev and Ben Welsh and Scott Sievert},
+    title = {Altair: Interactive Statistical Visualizations for Python},
+    journal = {Journal of Open Source Software}
+  }
+
+Vega-Lite
+---------
+Please additionally consider citing the
+`Vega-Lite <https://vega.github.io/vega-lite/>`_ project, which Vega-Altair is based on:
+`Vega-Lite: A Grammar of Interactive Graphics <https://dl.acm.org/doi/10.1109/TVCG.2016.2599030>`_
+
+.. code-block::
+
+  @article{Satyanarayan2017,
+    author={Satyanarayan, Arvind and Moritz, Dominik and Wongsuphasawat, Kanit and Heer, Jeffrey},
+    title={Vega-Lite: A Grammar of Interactive Graphics},
+    journal={IEEE transactions on visualization and computer graphics},
+    year={2017},
+    volume={23},
+    number={1},
+    pages={341-350},
+    publisher={IEEE}
+  }

doc/about/roadmap.rst

@@ -162,3 +162,4 @@ Areas of focus:
    self
    code_of_conduct
    governance
+   citing

doc/case_studies/exploring-weather.rst

@@ -17,7 +17,7 @@ The dataset is a CSV file with columns for the temperature
 wind speed (in meter/second), and weather type.
 We have one row for each day from January 1st, 2012 to December 31st, 2015.
 
-Altair is designed to work with data in the form of Pandas_
+Altair is designed to work with data in the form of pandas_
 dataframes, and contains a loader for this and other built-in datasets:
 
 .. altair-plot::
@@ -28,7 +28,7 @@ dataframes, and contains a loader for this and other built-in datasets:
     df = data.seattle_weather()
     df.head()
 
-The data is loaded from the web and stored in a Pandas DataFrame, and from
+The data is loaded from the web and stored in a pandas DataFrame, and from
 here we can explore it with Altair.
 
 Let’s start by looking at the precipitation, using tick marks to see the
@@ -135,7 +135,7 @@ Note that this calculation doesn't actually do any data manipulation in Python,
 but rather encodes and stores the operations within the plot specification,
 where they will be calculated by the renderer.
 
-Of course, the same calculation could be done by using Pandas manipulations to
+Of course, the same calculation could be done by using pandas manipulations to
 explicitly add a column to the dataframe; the disadvantage there is that the
 derived values would have to be stored in the plot specification
 rather than computed on-demand in the browser.
@@ -265,4 +265,4 @@ You can find more visualizations in the :ref:`example-gallery`.
 If you want to further customize your charts, you can refer to Altair's
 :ref:`api`.
 
-.. _Pandas: http://pandas.pydata.org/
+.. _pandas: http://pandas.pydata.org/

doc/getting_started/project_philosophy.rst

@@ -8,7 +8,7 @@ Many excellent plotting libraries exist in Python, including:
 * `Seaborn <https://seaborn.pydata.org/>`_
 * `Lightning <http://lightning-viz.org>`_
 * `Plotly <https://plot.ly/>`_
-* `Pandas built-in plotting <https://pandas.pydata.org/pandas-docs/stable/visualization.html>`_
+* `pandas built-in plotting <https://pandas.pydata.org/pandas-docs/stable/visualization.html>`_
 * `HoloViews <https://holoviews.org>`_
 * `VisPy <https://vispy.org/>`_
 * `pygg <https://www.github.com/sirrice/pygg>`_

doc/getting_started/starting.rst

@@ -29,10 +29,10 @@ Here is the outline of this basic tutorial:
 The Data
 --------
 
-Data in Altair is built around the Pandas Dataframe. One of the defining
+Data in Altair is built around the pandas Dataframe. One of the defining
 characteristics of statistical visualization is that it begins with
 `tidy <http://vita.had.co.nz/papers/tidy-data.html>`_
-Dataframes. For the purposes of this tutorial, we'll start by importing Pandas
+Dataframes. For the purposes of this tutorial, we'll start by importing pandas
 and creating a simple DataFrame to visualize, with a categorical variable in
 column a and a numerical variable in column b: