docs: Promote when-then-otherwise in User Guide

README.md

@@ -57,7 +57,7 @@ brush = alt.selection_interval()
 points = alt.Chart(source).mark_point().encode(
     x='Horsepower',
     y='Miles_per_Gallon',
-    color=alt.condition(brush, 'Origin', alt.value('lightgray'))
+    color=alt.when(brush).then("Origin").otherwise(alt.value("lightgray"))
 ).add_params(
     brush
 )

altair/vegalite/v5/api.py

@@ -859,14 +859,17 @@ def then(self, statement: _StatementType, /, **kwds: Any) -> Then[Any]:
             A spec or value to use when the preceding :func:`.when()` clause is true.
 
             .. note::
-                ``str`` will be encoded as `shorthand<https://altair-viz.github.io/user_guide/encodings/index.html#encoding-shorthands>`__.
+                ``str`` will be encoded as `shorthand`_.
         **kwds
             Additional keyword args are added to the resulting ``dict``.
 
         Returns
         -------
         :class:`Then`
 
+        .. _shorthand:
+            https://altair-viz.github.io/user_guide/encodings/index.html#encoding-shorthands
+
         Examples
         --------
         Simple conditions may be expressed without defining a default::
@@ -939,10 +942,12 @@ def otherwise(
                 Roughly equivalent to an ``else`` clause.
 
             .. note::
-                ``str`` will be encoded as `shorthand<https://altair-viz.github.io/user_guide/encodings/index.html#encoding-shorthands>`__.
+                ``str`` will be encoded as `shorthand`_.
         **kwds
             Additional keyword args are added to the resulting ``dict``.
 
+        .. _shorthand:
+            https://altair-viz.github.io/user_guide/encodings/index.html#encoding-shorthands
 
         Examples
         --------
@@ -1020,14 +1025,16 @@ def when(
                 When ``predicate`` is a ``Parameter`` that is used more than once,
                 ``alt.when().then().when(..., empty=...)`` provides granular control for each occurrence.
         **constraints
-            Specify `Field Equal Predicate <https://vega.github.io/vega-lite/docs/predicate.html#equal-predicate>`__'s.
+            Specify `Field Equal Predicate`_'s.
             Shortcut for ``alt.datum.field_name == value``, see examples for usage.
 
         Returns
         -------
         :class:`ChainedWhen`
             A partial state which requires calling :meth:`ChainedWhen.then()` to finish the condition.
 
+        .. _Field Equal Predicate:
+            https://vega.github.io/vega-lite/docs/predicate.html#equal-predicate
 
         Examples
         --------
@@ -1115,14 +1122,17 @@ def then(self, statement: _StatementType, /, **kwds: Any) -> Then[_Conditions]:
             A spec or value to use when the preceding :meth:`Then.when()` clause is true.
 
             .. note::
-                ``str`` will be encoded as `shorthand<https://altair-viz.github.io/user_guide/encodings/index.html#encoding-shorthands>`__.
+                ``str`` will be encoded as `shorthand`_.
         **kwds
             Additional keyword args are added to the resulting ``dict``.
 
         Returns
         -------
         :class:`Then`
 
+        .. _shorthand:
+            https://altair-viz.github.io/user_guide/encodings/index.html#encoding-shorthands
+
         Examples
         --------
         Multiple conditions with an implicit default::
@@ -1177,7 +1187,7 @@ def when(
             When ``predicate`` is a ``Parameter`` that is used more than once,
             ``alt.when(..., empty=...)`` provides granular control for each occurrence.
     **constraints
-        Specify `Field Equal Predicate <https://vega.github.io/vega-lite/docs/predicate.html#equal-predicate>`__'s.
+        Specify `Field Equal Predicate`_'s.
         Shortcut for ``alt.datum.field_name == value``, see examples for usage.
 
     Returns
@@ -1187,11 +1197,12 @@ def when(
 
     Notes
     -----
-    - Directly inspired by the ``when-then-otherwise`` syntax used in ``polars.when``.
+    - Directly inspired by the ``when-then-otherwise`` syntax used in `polars.when`_.
 
-    References
-    ----------
-    `polars.when <https://docs.pola.rs/py-polars/html/reference/expressions/api/polars.when.html>`__
+    .. _Field Equal Predicate:
+        https://vega.github.io/vega-lite/docs/predicate.html#equal-predicate
+    .. _polars.when:
+        https://docs.pola.rs/py-polars/html/reference/expressions/api/polars.when.html
 
     Examples
     --------
@@ -4907,7 +4918,7 @@ def remove_prop(subchart: ChartType, prop: str) -> ChartType:
             # or it must be Undefined or identical to proceed.
             output_dict[prop] = chart[prop]
         else:
-            msg = f"There are inconsistent values {values} for {prop}"
+            msg = f"There are inconsistent values {values} for {prop}"  # pyright: ignore[reportPossiblyUnboundVariable]
             raise ValueError(msg)
         subcharts = [remove_prop(c, prop) for c in subcharts]
 

doc/case_studies/exploring-weather.rst

@@ -226,33 +226,33 @@ of the selection (for more information on selections, see
 .. altair-plot::
 
     brush = alt.selection_interval()
-
-    points = alt.Chart().mark_point().encode(
-        alt.X('temp_max:Q').title('Maximum Daily Temperature (C)'),
-        alt.Y('temp_range:Q').title('Daily Temperature Range (C)'),
-        color=alt.condition(brush, 'weather:N', alt.value('lightgray'), scale=scale),
-        size=alt.Size('precipitation:Q').scale(range=[1, 200])
-    ).transform_calculate(
-        "temp_range", "datum.temp_max - datum.temp_min"
-    ).properties(
-        width=600,
-        height=400
-    ).add_params(
-        brush
+    color = (
+        alt.when(brush)
+        .then(alt.Color("weather:N").scale(scale))
+        .otherwise(alt.value("lightgray"))
     )
 
-    bars = alt.Chart().mark_bar().encode(
-        x='count()',
-        y='weather:N',
-        color=alt.Color('weather:N').scale(scale),
-    ).transform_calculate(
-        "temp_range", "datum.temp_max - datum.temp_min"
-    ).transform_filter(
-        brush
-    ).properties(
-        width=600
+    points = (
+        alt.Chart()
+        .mark_point()
+        .encode(
+            alt.X("temp_max:Q").title("Maximum Daily Temperature (C)"),
+            alt.Y("temp_range:Q").title("Daily Temperature Range (C)"),
+            color=color,
+            size=alt.Size("precipitation:Q").scale(range=[1, 200]),
+        )
+        .transform_calculate("temp_range", "datum.temp_max - datum.temp_min")
+        .properties(width=600, height=400)
+        .add_params(brush)
+    )
+    bars = (
+        alt.Chart()
+        .mark_bar()
+        .encode(x="count()", y="weather:N", color=alt.Color("weather:N").scale(scale))
+        .transform_calculate("temp_range", "datum.temp_max - datum.temp_min")
+        .transform_filter(brush)
+        .properties(width=600)
     )
-
     alt.vconcat(points, bars, data=df)
 
 This chart, containing concatenations, data transformations, selections, and

doc/user_guide/compound_charts.rst

@@ -364,28 +364,24 @@ layered chart with a hover selection:
 .. altair-plot::
 
     hover = alt.selection_point(on='pointerover', nearest=True, empty=False)
-
-    base = alt.Chart(iris).encode(
-        x='petalLength:Q',
-        y='petalWidth:Q',
-        color=alt.condition(hover, 'species:N', alt.value('lightgray'))
-    ).properties(
-        width=180,
-        height=180,
+    when_hover = alt.when(hover)
+
+    base = (
+        alt.Chart(iris)
+        .encode(
+            x="petalLength:Q",
+            y="petalWidth:Q",
+            color=when_hover.then("species:N").otherwise(alt.value("lightgray")),
+        )
+        .properties(width=180, height=180)
     )
-
-    points = base.mark_point().add_params(
-        hover
-    )
-
+    points = base.mark_point().add_params(hover)
     text = base.mark_text(dy=-5).encode(
-        text = 'species:N',
-        opacity = alt.condition(hover, alt.value(1), alt.value(0))
-    )
-
-    alt.layer(points, text).facet(
-        'species:N',
+        text="species:N", 
+        opacity=when_hover.then(alt.value(1)).otherwise(alt.value(0)),
     )
+
+    (points + text).facet("species:N")
 
 Though each of the above examples have faceted the data across columns,
 faceting across rows (or across rows *and* columns) is supported as

doc/user_guide/interactions/bindings_widgets.rst

@@ -51,10 +51,10 @@ where a drop-down is used to highlight cars of a specific ``Origin``:
 
     input_dropdown = alt.binding_select(options=['Europe', 'Japan', 'USA'], name='Region ')
     selection = alt.selection_point(fields=['Origin'], bind=input_dropdown)
-    color = alt.condition(
-        selection,
-        alt.Color('Origin:N').legend(None),
-        alt.value('lightgray')
+    color = (
+        alt.when(selection)
+        .then(alt.Color("Origin:N").legend(None))
+        .otherwise(alt.value("lightgray"))
     )
 
     alt.Chart(cars).mark_point().encode(
@@ -72,7 +72,7 @@ and selection parameters follow the same pattern as you will see further down
 in the :ref:`encoding-channel-binding` section.
 
 As you can see above,
-we are still using ``conditions`` to make the chart respond to the selection,
+we are still using :ref:`conditions <conditions>` to make the chart respond to the selection,
 just as we did without widgets.
 Bindings and input elements can also be used to filter data
 allowing the user to see just the selected points as in the example below.
@@ -137,11 +137,7 @@ to see the point highlighted
         x='Horsepower:Q',
         y='Miles_per_Gallon:Q',
         tooltip='Name:N',
-        opacity=alt.condition(
-            search_input,
-            alt.value(1),
-            alt.value(0.05)
-        )
+        opacity=alt.when(search_input).then(alt.value(1)).otherwise(alt.value(0.05)),
     ).add_params(
         search_input
     )
@@ -185,16 +181,12 @@ which would have been the case if we just wrote ``xval < selector``.
 
     slider = alt.binding_range(min=0, max=100, step=1, name='Cutoff ')
     selector = alt.param(name='SelectorName', value=50, bind=slider)
+    predicate = alt.datum.xval < selector
 
     alt.Chart(df).mark_point().encode(
        x='xval',
        y='yval',
-       color=alt.condition(
-           alt.datum.xval < selector,
-           # 'datum.xval < SelectorName',  # An equivalent alternative
-           alt.value('red'),
-           alt.value('blue')
-       )
+       color=alt.when(predicate).then(alt.value("red")).otherwise(alt.value("blue")),
     ).add_params(
        selector
     )
@@ -213,16 +205,12 @@ points based on whether they are smaller or larger than the value:
         bind=slider,
         value=[{'cutoff': 50}]
     )
+    predicate = alt.datum.xval < selector.cutoff
 
     alt.Chart(df).mark_point().encode(
         x='xval',
         y='yval',
-        color=alt.condition(
-            alt.datum.xval < selector.cutoff,
-            # 'datum.xval < SelectorName.cutoff',  # An equivalent alternative
-            alt.value('red'),
-            alt.value('blue')
-        )
+        color=alt.when(predicate).then(alt.value("red")).otherwise(alt.value("blue")),
     ).add_params(
         selector
     )
@@ -263,11 +251,7 @@ just if the value of the check box is True (checked) or False (unchecked):
     alt.Chart(cars).mark_point().encode(
         x='Horsepower:Q',
         y='Miles_per_Gallon:Q',
-        size=alt.condition(
-            param_checkbox,
-            'Acceleration:Q',
-            alt.value(25)
-        )
+        size=alt.when(param_checkbox).then("Acceleration:Q").otherwise(alt.value(25)),
     ).add_params(
         param_checkbox
     )
@@ -315,7 +299,7 @@ Altair provides the ``bind='legend'`` option to facilitate the creation of click
         x='Horsepower:Q',
         y='Miles_per_Gallon:Q',
         color='Origin:N',
-        opacity=alt.condition(selection, alt.value(0.8), alt.value(0.2))
+        opacity=alt.when(selection).then(alt.value(0.8)).otherwise(alt.value(0.2)),
     ).add_params(
         selection
     )

doc/user_guide/interactions/expressions.rst

@@ -169,19 +169,14 @@ To try this out, you can type ``mazda|ford`` in the search input box below.
             name='Search ',
         )
     )
+    search_matches = alt.expr.test(alt.expr.regexp(search_input, "i"), alt.datum.Name)
+
     alt.Chart(cars).mark_point(size=60).encode(
         x='Horsepower:Q',
         y='Miles_per_Gallon:Q',
         tooltip='Name:N',
-        opacity=alt.condition(
-            alt.expr.test(alt.expr.regexp(search_input, 'i'), alt.datum.Name),
-            # f"test(regexp({search_input.name}, 'i'), datum.Name)",  # Equivalent js alternative
-            alt.value(1),
-            alt.value(0.05)
-        )
-    ).add_params(
-        search_input
-    )
+        opacity=alt.when(search_matches).then(alt.value(1)).otherwise(alt.value(0.05)),
+    ).add_params(search_input)
 
 And remember, all this interactivity is client side.
 You can save this chart as an HTML file or put it on a static site generator such as GitHub/GitLab pages