Update to Vega-Lite 4.17.0

.github/workflows/docbuild.yml

@@ -25,4 +25,4 @@ jobs:
       run: |
         cd doc && make ${{ matrix.build-type }}
 
-
+

.gitignore

@@ -69,4 +69,4 @@ Untitled*.ipynb
 *.DS_Store
 
 # VSCode
-.vscode
+.vscode

altair/examples/bar_chart_trellis_compact.py

@@ -0,0 +1,50 @@
+"""
+Compact Trellis Grid of Bar Charts
+==================================
+This example shows a simple grid of bar charts to compare performance data..
+"""
+# category: bar charts
+import altair as alt
+import pandas as pd
+
+source = pd.DataFrame(
+    [
+        {"a": "a1", "b": "b1", "c": "x", "p": "0.14"},
+        {"a": "a1", "b": "b1", "c": "y", "p": "0.60"},
+        {"a": "a1", "b": "b1", "c": "z", "p": "0.03"},
+        {"a": "a1", "b": "b2", "c": "x", "p": "0.80"},
+        {"a": "a1", "b": "b2", "c": "y", "p": "0.38"},
+        {"a": "a1", "b": "b2", "c": "z", "p": "0.55"},
+        {"a": "a1", "b": "b3", "c": "x", "p": "0.11"},
+        {"a": "a1", "b": "b3", "c": "y", "p": "0.58"},
+        {"a": "a1", "b": "b3", "c": "z", "p": "0.79"},
+        {"a": "a2", "b": "b1", "c": "x", "p": "0.83"},
+        {"a": "a2", "b": "b1", "c": "y", "p": "0.87"},
+        {"a": "a2", "b": "b1", "c": "z", "p": "0.67"},
+        {"a": "a2", "b": "b2", "c": "x", "p": "0.97"},
+        {"a": "a2", "b": "b2", "c": "y", "p": "0.84"},
+        {"a": "a2", "b": "b2", "c": "z", "p": "0.90"},
+        {"a": "a2", "b": "b3", "c": "x", "p": "0.74"},
+        {"a": "a2", "b": "b3", "c": "y", "p": "0.64"},
+        {"a": "a2", "b": "b3", "c": "z", "p": "0.19"},
+        {"a": "a3", "b": "b1", "c": "x", "p": "0.57"},
+        {"a": "a3", "b": "b1", "c": "y", "p": "0.35"},
+        {"a": "a3", "b": "b1", "c": "z", "p": "0.49"},
+        {"a": "a3", "b": "b2", "c": "x", "p": "0.91"},
+        {"a": "a3", "b": "b2", "c": "y", "p": "0.38"},
+        {"a": "a3", "b": "b2", "c": "z", "p": "0.91"},
+        {"a": "a3", "b": "b3", "c": "x", "p": "0.99"},
+        {"a": "a3", "b": "b3", "c": "y", "p": "0.80"},
+        {"a": "a3", "b": "b3", "c": "z", "p": "0.37"},
+    ]
+)
+
+alt.Chart(source, width=60, height=alt.Step(8)).mark_bar().encode(
+    y=alt.Y("c:N", axis=None),
+    x=alt.X("p:Q", title=None, axis=alt.Axis(format="%")),
+    color=alt.Color(
+        "c:N", title="settings", legend=alt.Legend(orient="bottom", titleOrient="left")
+    ),
+    row=alt.Row("a:N", title="Factor A", header=alt.Header(labelAngle=0)),
+    column=alt.Column("b:N", title="Factor B"),
+)

altair/examples/donut_chart.py

@@ -0,0 +1,18 @@
+"""
+Donut Chart
+-----------
+This example shows how to make a Donut Chart using ``mark_arc``.
+This is adapted from a corresponding Vega-Lite Example:
+`Donut Chart <https://vega.github.io/vega-lite/examples/arc_donut.html>`_.
+"""
+# category: circular plots
+
+import pandas as pd
+import altair as alt
+
+source = pd.DataFrame({"category": [1, 2, 3, 4, 5, 6], "value": [4, 6, 10, 3, 7, 8]})
+
+alt.Chart(source).mark_arc(innerRadius=50).encode(
+    theta=alt.Theta(field="value", type="quantitative"),
+    color=alt.Color(field="category", type="nominal"),
+)

altair/examples/line_chart_with_color_datum.py

@@ -0,0 +1,21 @@
+"""
+Line Chart with datum for color
+-------------------------------
+An example of using ``datum`` and ``repeat`` to color a multi-series line chart.
+This is adapted from this corresponding Vega-Lite Example:
+`Repeat and Layer to Show Different Movie Measures <https://vega.github.io/vega-lite/examples/repeat_layer.html>`_.
+"""
+# category: line charts
+
+import altair as alt
+from vega_datasets import data
+
+source = data.movies()
+
+alt.Chart(source).mark_line().encode(
+    x=alt.X("IMDB_Rating", bin=True),
+    y=alt.Y(
+        alt.repeat("layer"), aggregate="mean", title="Mean of US and Worldwide Gross"
+    ),
+    color=alt.datum(alt.repeat("layer")),
+).repeat(layer=["US_Gross", "Worldwide_Gross"])

altair/examples/line_chart_with_datum.py

@@ -0,0 +1,33 @@
+"""
+Line Chart with datum
+---------------------------------
+An example of using ``datum`` to highlight certain values, including a ``DateTime`` value.
+This is adapted from two corresponding Vega-Lite Examples:
+`Highlight a Specific Value <https://vega.github.io/vega-lite/docs/datum.html#highlight-a-specific-data-value>`_.
+"""
+# category: line charts
+
+import altair as alt
+from vega_datasets import data
+
+source = data.stocks()
+no_source = alt.Data(values=[{}])
+
+lines = (
+    alt.Chart(source)
+    .mark_line()
+    .encode(x=alt.X("date"), y=alt.Y("price"), color="symbol")
+)
+
+xrule = (
+    alt.Chart(no_source)
+    .mark_rule(color="cyan", strokeWidth=2)
+    .encode(x=alt.datum(alt.DateTime(year=2006, month="November")))
+)
+
+yrule = (
+    alt.Chart(no_source).mark_rule(strokeDash=[12, 6], size=2).encode(y=alt.datum(350))
+)
+
+
+lines + yrule + xrule

altair/examples/pacman_chart.py

@@ -0,0 +1,19 @@
+"""
+Pacman Chart
+------------
+Chart made using ``mark_arc`` and constant values.
+This could also be made using 
+``alt.Chart(source).mark_arc(color = "gold", theta = (5/8)*np.pi, theta2 = (19/8)*np.pi,radius=100)``.
+"""
+# category: circular plots
+
+import numpy as np
+import altair as alt
+
+no_source = alt.Data(values=[{}])
+
+alt.Chart(no_source).mark_arc(color="gold").encode(
+    theta=alt.datum((5 / 8) * np.pi, scale=None),
+    theta2=alt.datum((19 / 8) * np.pi),
+    radius=alt.datum(100, scale=None),
+)

altair/examples/pie_chart.py

@@ -0,0 +1,18 @@
+"""
+Pie Chart
+---------
+This example shows how to make a Pie Chart using ``mark_arc``.
+This is adapted from a corresponding Vega-Lite Example:
+`Pie Chart <https://vega.github.io/vega-lite/examples/arc_pie.html>`_.
+"""
+# category: circular plots
+
+import pandas as pd
+import altair as alt
+
+source = pd.DataFrame({"category": [1, 2, 3, 4, 5, 6], "value": [4, 6, 10, 3, 7, 8]})
+
+alt.Chart(source).mark_arc().encode(
+    theta=alt.Theta(field="value", type="quantitative"),
+    color=alt.Color(field="category", type="nominal"),
+)

altair/examples/pie_chart_with_labels.py

@@ -0,0 +1,24 @@
+"""
+Pie Chart with Labels
+---------------------
+This example shows how to layer text over arc marks (``mark_arc``) to label pie charts.
+This is adapted from a corresponding Vega-Lite Example:
+`Pie Chart with Labels <https://vega.github.io/vega-lite/examples/layer_arc_label.html>`_.
+"""
+# category: circular plots
+
+import pandas as pd
+import altair as alt
+
+source = pd.DataFrame(
+    {"category": ["a", "b", "c", "d", "e", "f"], "value": [4, 6, 10, 3, 7, 8]}
+)
+
+base = alt.Chart(source).encode(
+    theta=alt.Theta("value:Q", stack=True), color=alt.Color("category:N", legend=None)
+)
+
+pie = base.mark_arc(outerRadius=120)
+text = base.mark_text(radius=140, size=20).encode(text="category:N")
+
+pie + text

altair/examples/radial_chart.py

@@ -0,0 +1,25 @@
+"""
+Radial Chart
+------------
+This radial plot uses both angular and radial extent to convey multiple dimensions of data.
+This is adapted from a corresponding Vega-Lite Example:
+`Radial Plot <https://vega.github.io/vega-lite/examples/arc_radial.html>`_.
+"""
+# category: circular plots
+
+import pandas as pd
+import altair as alt
+
+source = pd.DataFrame({"values": [12, 23, 47, 6, 52, 19]})
+
+base = alt.Chart(source).encode(
+    theta=alt.Theta("values:Q", stack=True),
+    radius=alt.Radius("values", scale=alt.Scale(type="sqrt", zero=True, rangeMin=20)),
+    color="values:N",
+)
+
+c1 = base.mark_arc(innerRadius=20, stroke="#fff")
+
+c2 = base.mark_text(radiusOffset=10).encode(text="values:Q")
+
+c1 + c2

altair/examples/wind_vector_map.py

@@ -0,0 +1,24 @@
+"""
+Wind Vector Map
+---------------
+An example showing a vector array map showing wind speed and direction using ``wedge``
+as shape for ``mark_point`` and ``angle`` encoding for the wind direction.
+This is adapted from this corresponding Vega-Lite Example:
+`Wind Vector Map <https://vega.github.io/vega-lite/examples/point_angle_windvector.html>`_.
+"""
+# category: scatter plots
+
+import altair as alt
+from vega_datasets import data
+
+source = data.windvectors()
+
+alt.Chart(source).mark_point(shape="wedge", filled=True).encode(
+    latitude="latitude",
+    longitude="longitude",
+    color=alt.Color(
+        "dir", scale=alt.Scale(domain=[0, 360], scheme="rainbow"), legend=None
+    ),
+    angle=alt.Angle("dir", scale=alt.Scale(domain=[0, 360], range=[180, 540])),
+    size=alt.Size("speed", scale=alt.Scale(rangeMax=500)),
+).project("equalEarth")

altair/expr/core.py

@@ -15,6 +15,10 @@ def __getattr__(self, attr):
     def __getitem__(self, attr):
         return GetItemExpression("datum", attr)
 
+    def __call__(self, datum, **kwargs):
+        """Specify a datum for use in an encoding"""
+        return dict(datum=datum, **kwargs)
+
 
 datum = DatumType()
 

altair/sphinxext/altairgallery.py

@@ -265,6 +265,7 @@ def main(app):
             "Bar Charts": [],
             "Line Charts": [],
             "Area Charts": [],
+            "Circular Plots": [],
             "Scatter Plots": [],
             "Histograms": [],
             "Maps": [],

altair/utils/core.py

@@ -96,35 +96,14 @@ def infer_dtype(value):
     "nth_value",
 ]
 
-# timeUnits from vega-lite version 4.6.0
+# timeUnits from vega-lite version 4.17.0
 TIMEUNITS = [
-    "utcyear",
-    "utcquarter",
-    "utcmonth",
-    "utcday",
-    "utcdate",
-    "utchours",
-    "utcminutes",
-    "utcseconds",
-    "utcmilliseconds",
-    "utcyearquarter",
-    "utcyearquartermonth",
-    "utcyearmonth",
-    "utcyearmonthdate",
-    "utcyearmonthdatehours",
-    "utcyearmonthdatehoursminutes",
-    "utcyearmonthdatehoursminutesseconds",
-    "utcquartermonth",
-    "utcmonthdate",
-    "utcmonthdatehours",
-    "utchoursminutes",
-    "utchoursminutesseconds",
-    "utcminutesseconds",
-    "utcsecondsmilliseconds",
     "year",
     "quarter",
     "month",
+    "week",
     "day",
+    "dayofyear",
     "date",
     "hours",
     "minutes",
@@ -137,13 +116,68 @@ def infer_dtype(value):
     "yearmonthdatehours",
     "yearmonthdatehoursminutes",
     "yearmonthdatehoursminutesseconds",
+    "yearweek",
+    "yearweekday",
+    "yearweekdayhours",
+    "yearweekdayhoursminutes",
+    "yearweekdayhoursminutesseconds",
+    "yeardayofyear",
     "quartermonth",
     "monthdate",
     "monthdatehours",
+    "monthdatehoursminutes",
+    "monthdatehoursminutesseconds",
+    "weekday",
+    "weeksdayhours",
+    "weekdayhoursminutes",
+    "weekdayhoursminutesseconds",
+    "dayhours",
+    "dayhoursminutes",
+    "dayhoursminutesseconds",
     "hoursminutes",
     "hoursminutesseconds",
     "minutesseconds",
     "secondsmilliseconds",
+    "utcyear",
+    "utcquarter",
+    "utcmonth",
+    "utcweek",
+    "utcday",
+    "utcdayofyear",
+    "utcdate",
+    "utchours",
+    "utcminutes",
+    "utcseconds",
+    "utcmilliseconds",
+    "utcyearquarter",
+    "utcyearquartermonth",
+    "utcyearmonth",
+    "utcyearmonthdate",
+    "utcyearmonthdatehours",
+    "utcyearmonthdatehoursminutes",
+    "utcyearmonthdatehoursminutesseconds",
+    "utcyearweek",
+    "utcyearweekday",
+    "utcyearweekdayhours",
+    "utcyearweekdayhoursminutes",
+    "utcyearweekdayhoursminutesseconds",
+    "utcyeardayofyear",
+    "utcquartermonth",
+    "utcmonthdate",
+    "utcmonthdatehours",
+    "utcmonthdatehoursminutes",
+    "utcmonthdatehoursminutesseconds",
+    "utcweekday",
+    "utcweeksdayhours",
+    "utcweekdayhoursminutes",
+    "utcweekdayhoursminutesseconds",
+    "utcdayhours",
+    "utcdayhoursminutes",
+    "utcdayhoursminutesseconds",
+    "utchoursminutes",
+    "utchoursminutesseconds",
+    "utcminutesseconds",
+    "utcsecondsmilliseconds",
 ]
 
 
@@ -633,7 +667,12 @@ def infer_encoding_types(args, kwargs, channels):
     name_to_channel = {}
     for chan, name in channel_to_name.items():
         chans = name_to_channel.setdefault(name, {})
-        key = "value" if chan.__name__.endswith("Value") else "field"
+        if chan.__name__.endswith("Datum"):
+            key = "datum"
+        elif chan.__name__.endswith("Value"):
+            key = "value"
+        else:
+            key = "field"
         chans[key] = chan
 
     # First use the mapping to convert args to kwargs based on their types.