docs: when-then-otherwise examples

[dangotbanned]

Follow-up referenced in #3427 (comment)

Developing each function/method doc further with example(s)

Tasks

• empty note (adapted from docs: Add empty as a explicit condition kwarg #3490)
• Each method has a situational example
  • Then.when
  • Then.otherwise
  • When.then
  • ChainedWhen.then
• Multiple examples
  • alt.when (using vega_datasets)
• Adding a __repr__ for When, ChainedWhen
  • Then inherits one

Possible tasks

Just some ideas that came up while working on this.
Can work on them if there's interest, but not planning to otherwise:

• Moving parts of the Parameters section into examples
  • E.g. empty note

Comments from original PR

Linking these as I raised them as potential issues, but they were not discussed:

• Then method autocomplete visibility
• [When | Then | ChainedWhen] method docs not in API reference
• How should polars be referenced and/or accredited for idea?

[mattijn]

Thanks! This looks great. I was expecting these examples to be around here: https://altair-viz.github.io/user_guide/interactions.html#conditions-filters, but the examples in this PR are part of the docstrings, which is very nice too! We should have more of these.

Will add a note to #3500.

I noticed when playing with this that I agree with your suggestion that it would be nice to have a __repr__ for When and ChainedWhen.

Regarding, your three linked comments from original PR. I don't have clear insight on these either. I don't think it is necessary to use intersphinx, but a reference to the polars docs page of the pl.when syntax makes sense though.

[dangotbanned]

Thanks! This looks great. I was expecting these examples to be around here: altair-viz.github.io/user_guide/interactions.html#conditions-filters, but the examples in this PR are part of the docstrings, which is very nice too! We should have more of these.

Will add a note to #3500.

Thank you for reviewing, but my bad for misunderstanding the assignment @mattijn

Hopefully they will make writing the User Guide parts easier in #3500, since most of the examples already produce a valid chart.
The last one for alt.when I wanted to adapt - but the cars dataset wasn't a good fit.

---

I noticed when playing with this that I agree with your suggestion that it would be nice to have a __repr__ for When and ChainedWhen.

For reference, following 0e7b49f (#3492)

The ChainedWhen one is tricky as it represents

• a list of complete conditions (self._conditions)
• a single partial condition (self._condition), prior to the next .then()

[dangotbanned]

@mattijn are we good to go with this one?

Sorry I can't seem to request a review

[mattijn]

Looks great. One suggested change.

I like the examples. Really clean.

# Simple conditions may be expressed without defining a default
import altair as alt
from vega_datasets import data

source = data.movies()
predicate = (alt.datum.IMDB_Rating == None) | (alt.datum.Rotten_Tomatoes_Rating == None)

alt.Chart(source).mark_point(invalid=None).encode(
    x="IMDB_Rating:Q",
    y="Rotten_Tomatoes_Rating:Q",
    color=alt.when(predicate).then(alt.value("grey")),
)

# Points outside of `brush` will not appear highlighted
import altair as alt
from vega_datasets import data

source = data.cars()
brush = alt.selection_interval()
color = alt.when(brush).then("Origin:N").otherwise(alt.value("grey"))

alt.Chart(source).mark_point().encode(
    x="Horsepower:Q",
    y="Miles_per_Gallon:Q",
    color=color,
).add_params(brush)

 # Chain calls to express precise queries
import altair as alt
from vega_datasets import data

source = data.cars()
color = (
    alt.when(alt.datum.Miles_per_Gallon >= 30, Origin="Europe")
    .then(alt.value("crimson"))
    .when(alt.datum.Horsepower > 150)
    .then(alt.value("goldenrod"))
    .otherwise(alt.value("grey"))
)

alt.Chart(source).mark_point().encode(x="Horsepower", y="Miles_per_Gallon", color=color)

# Multiple conditions with an implicit default
import altair as alt
from vega_datasets import data

source = data.movies()
predicate = (alt.datum.IMDB_Rating == None) | (alt.datum.Rotten_Tomatoes_Rating == None)
color = (
    alt.when(predicate)
    .then(alt.value("grey"))
    .when(alt.datum.IMDB_Votes < 5000)
    .then(alt.value("lightblue"))
)

alt.Chart(source).mark_point(invalid=None).encode(
    x="IMDB_Rating:Q", y="Rotten_Tomatoes_Rating:Q", color=color
)

# Setting up a common chart
import altair as alt
from vega_datasets import data

source = data.cars()
brush = alt.selection_interval()

points = (
    alt.Chart(source)
    .mark_point()
    .encode(x="Horsepower", y="Miles_per_Gallon")
    .add_params(brush)
)
points

# Basic `if-then-else` conditions translate directly to `when-then-otherwise`
points.encode(color=alt.when(brush).then("Origin").otherwise(alt.value("lightgray")))

# Omitting the `.otherwise()` clause will use the channel default instead
points.encode(color=alt.when(brush).then("Origin"))

# Predicates passed as positional arguments will be reduced with `&`
points.encode(
    color=alt.when(
        brush, (alt.datum.Miles_per_Gallon >= 30) | (alt.datum.Horsepower >= 130)
    )
    .then("Origin")
    .otherwise(alt.value("lightgray"))
)

# Using keyword-argument `constraints` can simplify compositions like
verbose_composition = (
    (alt.datum.Name == "Name_1")
    & (alt.datum.Color == "Green")
    & (alt.datum.Age == 25)
    & (alt.datum.StartDate == "2000-10-01")
)
when_verbose = alt.when(verbose_composition)
# To
when_concise = alt.when(Name="Name_1", Color="Green", Age=25, StartDate="2000-10-01")

[dangotbanned]

Thanks @mattijn for the review and well spotted on the missing )

Seeing them all together in #3492 (review) really looks like this will fit into the User Guide nicely

[mattijn]

Yes! Beautiful new addition to the Altair library! Well done @dangotbanned!