docs: Promote `when-then-otherwise` in User Guide #3544

dangotbanned · 2024-08-18T13:51:11Z

Will close #3500

Status

All outstanding work should be scoped to parameters.rst.
Corrections/suggestions elsewhere are still welcome

The linked version represents Draft 1.

Kept things mostly as they were for alt.condition
Hoping to get feedback on
- How much of alt.when feels missing?
- If something is missing, can a link to an example improve the read?
Potentially missing
- Chaining, reuse e.g. https://github.com/vega/altair/pull/3544/files#r1746885701
- Simply repeating these in order docs: when-then-otherwise examples #3492 (review)

Tasks

No visual change, but makes the markup itself easier to read

…d/altair into when-then-user-guide

- Replaced `dict` with `when-then-otherwise` - Replaced string expressions with `python` equivalent - Formatting update to avoid horizontal overflow

…d/altair into when-then-user-guide

dangotbanned · 2024-09-04T14:35:30Z

@joelostblom since your mention of this PR in #3548 (reply in thread), I've circled back to this.

If you have the time, would you be able to double-check the tasks I've added in the description please?

Going to start working through them now

joelostblom · 2024-09-04T16:09:53Z

Looks great! The location for the callout seems suitable to me. The only thing I would add is that I think we should include an example in the user guide section for the use of empty inside the conditional, as opposed to in the parameter definition (#3490).

dangotbanned · 2024-09-04T17:18:21Z

Looks great! The location for the callout seems suitable to me. The only thing I would add is that I think we should include an example in the user guide section for the use of empty inside the conditional, as opposed to in the parameter definition (#3490).

Perfect thanks @joelostblom, I've added that to the list.

Managed to get through a good chunk today, I'm expecting parameters.rst will require the most work since it calls out alt.condition directly

joelostblom

I had a peak and it is looking great so far! One comment regarding syntax, curious to hear what you think.

doc/case_studies/exploring-weather.rst

First draft version. Unlike the other commits, this has to introduce the concept - so will require more scrutiny. vega#3544 (comment)

…d/altair into when-then-user-guide

joelostblom · 2024-09-09T19:48:19Z

@dangotbanned I noticed that you tagged me for review here, but also that the PR is still marked as draft, so I just want to double check whether you want a review now or you are waiting to finish something up first.

dangotbanned · 2024-09-09T20:39:01Z

@dangotbanned I noticed that you tagged me for review here, but also that the PR is still marked as draft, so I just want to double check whether you want a review now or you are waiting to finish something up first.

Thanks for checking in @joelostblom!

I was hoping to get feedback focused on the Status section of the description.

Do you think I should move this out of draft - to make it clearer that I'm interested in a review?

joelostblom

Thanks for your patience @dangotbanned and sorry for not getting here earlier. I had a quick read in the docs and think this is looking great already!

I think it would be instructor to include the following examples in a subsection at the end of "Conditions and Filters":

Simple conditions may be expressed without defining a default (maybe with a simpler example than invalid=None)
Chain calls to express precise queries
Reuse defined when variable

Whereas the following seem more like "another way of doing something we already have shown" and I would leave them out of the User Guide (maybe a link a the bottom of the new subsection mentioning there are even more example in the when API reference?)

Predicates passed as positional arguments will be reduced with & (since this is just an alternative way of achieving something)
Using keyword-argument constraints can simplify compositions (since this is only for AND and ==)

doc/user_guide/interactions/parameters.rst

All of the charts using this function were silently producing no output. `brush` had been defined globally in an earlier directive vega#3544 (comment)

dangotbanned · 2024-09-18T10:50:59Z

Thanks for your patience @dangotbanned and sorry for not getting here earlier. I had a quick read in the docs and think this is looking great already!

No worries @joelostblom, thanks for taking the time to review

I think it would be instructor to include the following examples in a subsection at the end of "Conditions and Filters":

Simple conditions may be expressed without defining a default (maybe with a simpler example than invalid=None)

Chain calls to express precise queries

Reuse defined when variable

Sounds good to me.
Just to be sure I've understood correctly, which of these locations did you mean?

End of Conditional Encodings
- The end of the alt.when section of Conditions & Filters
End of Conditions & Filters
- The actual end of Conditions & Filters

Whereas the following seem more like "another way of doing something we already have shown" and I would leave them out of the User Guide (maybe a link a the bottom of the new subsection mentioning there are even more example in the when API reference?)

Predicates passed as positional arguments will be reduced with & (since this is just an alternative way of achieving something)

Using keyword-argument constraints can simplify compositions (since this is only for AND and ==)

That makes sense, I definitely want to avoid adding too much here - especially if as you've said there is already a documented way to do it

@joelostblom

Not sure what the title should be, but @joelostblom proposed making this a new subsection vega#3544 (review)

https://altair-viz.github.io/gallery/interactive_bar_select_highlight.html

joelostblom · 2024-09-18T22:46:43Z

While reviewing 50a520e, I got some ideas for rearranging sections on this page to make it easier to follow. I have most of it done and will finish it off tomorrow to show you my suggestion instead of trying to explain it.

dangotbanned · 2024-09-19T09:08:49Z

While reviewing 50a520e, I got some ideas for rearranging sections on this page to make it easier to follow. I have most of it done and will finish it off tomorrow to show you my suggestion instead of trying to explain it.

All good with me @joelostblom

Feel free to move this PR out of draft when you're ready.
I was waiting until either I came up with a heading for Untitled More When or you took a look

To be able to fully document the behavior of `when`, I made a few organizational changes: - Split "Conditions" and "Filter" since these are two different concept anyways. - I also renamed the first heading to illustratet that the three big concepts are "Parameter", "Conditions", and "Filters". - Named the main new "when" section "Understanding when()" and included an example of conditional branches in pseudocode early on and a runnable example later. - I also added an additional subheading for "Linking across charts" - Included mention of the use of `empty=False` inside `when` together with a short pseudocode example. - Creating a new section at the end about combining parameters, which contains both the previous section on parameter composition, but also two new subsection on multiple conditions and conditional when branches. - I expanded on the parameter composition examples as well.

joelostblom

@dangotbanned To be able to fully document the behavior of when,
I made a few organizational changes in e363abd

Split "Conditions" and "Filter" since these are two
different concept anyways.
I also renamed the first heading to illustratet that
the three big concepts are "Parameter", "Conditions", and "Filters".
Named the main new "when" section "Understanding when()"
and included an example of conditional branches in pseudocode early on
and a runnable example later.
I also added an additional subheading for "Linking across charts"
Included mention of the use of empty=False inside when together
with a short pseudocode example.
Creating a new section at the end about combining parameters,
which contains both the previous section on parameter composition,
but also two new subsection on multiple conditions and conditional
when branches.
I expanded on the parameter composition examples as well.

Please have a look and let me know what you think
I moved the PR out of draft and will go through your other examples today or tomorrow.
I noticed a few unrelated doc changes that I will include in a follow up PR after we merge this.

joelostblom · 2024-09-19T19:22:38Z

doc/user_guide/interactions/parameters.rst

+    # empty=False ensure that no points are selected before a selection is drawn
+    brush = alt.selection_interval(empty=False)
+    brush2 = alt.selection_interval(empty=False)
+


Note that this and the next example will not quite work as intended until #3598 is fixed, but I don't think that is blocking for this PR.

Note that this and the next example will not quite work as intended until #3598 is fixed, but I don't think that is blocking for this PR.

I tried this, but it seems to break bars

verbose_compose = alt.LogicalAndPredicate( **{"and": [dict(brush.to_dict(), empty=False), dict(brush2.to_dict(), empty=False)]} )

After seeing

altair/altair/vegalite/v5/api.py

Lines 2855 to 2862 in 62cd377

if isinstance(filter, Parameter):

new_filter: dict[str, Any] = {"param": filter.name}

if "empty" in kwargs:

new_filter["empty"] = kwargs.pop("empty")

elif isinstance(filter.empty, bool):

new_filter["empty"] = filter.empty

filter = new_filter

return self._add_transform(core.FilterTransform(filter=filter, **kwargs))

I also tried this:

bars = base.mark_bar().encode(x="count()", y="Origin:N").transform_filter(brush & brush2, empty=False)

Output

SchemaValidationError: `FilterTransform` has no parameter named 'empty' Existing parameter names are: filter See the help for `FilterTransform` to read the full description of these parameters

It is a cool example, but if it isn't working as you'd like - maybe its best to add in a follow up PR?

Since it doesn't use alt.when, I don't think we need to rush it into this PR

dangotbanned

I'm liking the reorganization @joelostblom!

I picked up a few rst corrections that need to be made, and some questions/suggestions on content.

Overall I think we're very close, really appreciate your help with this PR 🤝

dangotbanned · 2024-09-20T09:40:05Z

doc/user_guide/interactions/parameters.rst

+
+Multiple parameters can be combined in a single chart,
+either via multiple separate response conditions,
+different conditional branches in :fun:`when`,


Suggested change

different conditional branches in :fun:`when`,

different conditional branches in :func:`when`,

dangotbanned · 2024-09-20T09:40:32Z

doc/user_guide/interactions/parameters.rst

+Conditional branches
+^^^^^^^^^^^^^^^^^^^^
+
+:fun:`when` allows the use of multiple ``then`` (``elif``) branches


Suggested change

:fun:`when` allows the use of multiple ``then`` (``elif``) branches

:func:`when` allows the use of multiple ``then`` (``elif``) branches

dangotbanned · 2024-09-20T10:04:20Z

doc/user_guide/interactions/parameters.rst

    )

+    either_or_but_not_both = (alex | morgan) & ~(alex & morgan)


Would this be clearer using exclusive or?

I've noticed we don't have an __xor__ (^) defined for alt.expr.core.OperatorMixin, but we do have implementations for most others.

js bitwise operators include XOR and use the same symbol (^).

Rename variable to align closer to exclusive or. You can always link to another resource (probably not wiki) to explain the concept in more detail. Or show a truth table?

Look into adding alt.expr.core.OperatorMixin.__xor__ in a new issue (non-blocking here)

dangotbanned · 2024-09-20T11:06:08Z

doc/user_guide/interactions/parameters.rst

+As a convenience,
+simple conditions may be expressed without defining a default:


If we want to add to the original quote:

Simple conditions may be expressed without defining a default

I'm not sure "As a convenience" is the right fit.
It isn't really a convenience of the syntax itself, but functionality inherited from vega-lite - which wasn't possible using alt.condition since it required if_false.

I would think commenting on what value would be used instead may be more helpful.
Specifically, it would fall back to the default value of the given channel.

From the end of vega-lite condition

The next plot uses a conditional value definition to color data points with null values in grey. Note that if the “else” case value is not specified, default mark color will be applied.

I adapted that here:

altair/altair/vegalite/v5/api.py

Lines 1217 to 1219 in 62cd377

Omitting the ``.otherwise()`` clause will use the channel default instead::

points.encode(color=alt.when(brush).then("Origin"))

dangotbanned · 2024-09-20T11:16:34Z

doc/user_guide/interactions/parameters.rst

+    )
+    points
+
+Multiple conditional branches (``elif`` in Python)


I think we should stick with the same style used in polars.when for this.

Chained when-then operations should be read as Python if, elif, ... elif blocks,

One of these maybe?

1

Multiple conditional branches (``if, elif, ..., elif`` in Python)

2

Multiple conditional branches (``if-elif-else`` in Python)

3

Multiple conditional branches (``if-elif-...-else`` in Python)

dangotbanned · 2024-09-20T11:51:58Z

doc/user_guide/interactions/parameters.rst

+
+
+.. altair-plot::


Suggested change

.. altair-plot::

Was causing an empty code block:

dangotbanned · 2024-09-20T11:56:31Z

doc/user_guide/interactions/parameters.rst

+The ``empty=False`` argument could instead be set inside :func:`when`,
+so that you don't need to redefine the same selection, e.g.::
+
+    brush = alt.selection()


Suggested change

brush = alt.selection()

brush = alt.selection_interval()

dangotbanned · 2024-09-20T12:40:52Z

doc/user_guide/interactions/parameters.rst

+The ``empty=False`` argument could instead be set inside :func:`when`,
+so that you don't need to redefine the same selection, e.g.::


I wrote a more detailed comment here but it seems to not have saved 😞

The motivation for using empty=False outside of the parameter definition is to change the behavior for the condition, not the parameter.

brush will still have empty=True on every other use

altair/altair/vegalite/v5/api.py

Lines 1172 to 1178 in 62cd377

empty

For selection parameters, the predicate of empty selections returns ``True`` by default.

Override this behavior, with ``empty=False``.

.. note::

When ``predicate`` is a ``Parameter`` that is used more than once,

``alt.when(..., empty=...)`` provides granular control for each occurrence.

Related

https://vega.github.io/vega-lite/docs/parameter.html#as-predicates

Improve the syntax for conditions with multiple predicates #2759 (comment)

docs: Add example for *Bar Chart with Highlighting on Hover and Selection on Click* #3485 (comment)

docs: Add example for *Bar Chart with Highlighting on Hover and Selection on Click* #3485 (review)

dangotbanned · 2024-09-20T13:39:50Z

doc/user_guide/interactions/parameters.rst

+    # empty=False ensure that no points are selected before a selection is drawn
+    brush = alt.selection_interval(empty=False)
+    brush2 = alt.selection_interval(empty=False)
+


Note that this and the next example will not quite work as intended until #3598 is fixed, but I don't think that is blocking for this PR.

I tried this, but it seems to break bars

verbose_compose = alt.LogicalAndPredicate( **{"and": [dict(brush.to_dict(), empty=False), dict(brush2.to_dict(), empty=False)]} )

After seeing

altair/altair/vegalite/v5/api.py

Lines 2855 to 2862 in 62cd377

if isinstance(filter, Parameter):

new_filter: dict[str, Any] = {"param": filter.name}

if "empty" in kwargs:

new_filter["empty"] = kwargs.pop("empty")

elif isinstance(filter.empty, bool):

new_filter["empty"] = filter.empty

filter = new_filter

return self._add_transform(core.FilterTransform(filter=filter, **kwargs))

I also tried this:

bars = base.mark_bar().encode(x="count()", y="Origin:N").transform_filter(brush & brush2, empty=False)

Output

SchemaValidationError: `FilterTransform` has no parameter named 'empty' Existing parameter names are: filter See the help for `FilterTransform` to read the full description of these parameters

dangotbanned · 2024-09-20T13:55:09Z

doc/user_guide/interactions/parameters.rst

+    # empty=False ensure that no points are selected before a selection is drawn
+    brush = alt.selection_interval(empty=False)
+    brush2 = alt.selection_interval(empty=False)
+


It is a cool example, but if it isn't working as you'd like - maybe its best to add in a follow up PR?

Since it doesn't use alt.when, I don't think we need to rush it into this PR

docs: Replace some inline references

e46a493

No visual change, but makes the markup itself easier to read

dangotbanned added the documentation label Aug 18, 2024

Merge branch 'main' into when-then-user-guide

abdcf3a

dangotbanned mentioned this pull request Aug 27, 2024

Promote the use of alt.when().then().otherwise() over alt.condition() in the User Guide? #3500

Open

dangotbanned added 4 commits August 28, 2024 14:13

Merge remote-tracking branch 'upstream/main' into when-then-user-guide

a365083

Merge branch 'when-then-user-guide' of https://github.com/dangotbanne…

9ca55a8

…d/altair into when-then-user-guide

docs: Update waterfall_chart.py example

a681ec5

- Replaced `dict` with `when-then-otherwise` - Replaced string expressions with `python` equivalent - Formatting update to avoid horizontal overflow

wip

f454093

dangotbanned mentioned this pull request Aug 29, 2024

Improve expr method signatures #3563

Open

dangotbanned added 3 commits September 1, 2024 09:12

Merge branch 'main' into when-then-user-guide

ab6c4b4

Merge branch 'when-then-user-guide' of https://github.com/dangotbanne…

3b72a83

…d/altair into when-then-user-guide

Merge remote-tracking branch 'upstream/main' into when-then-user-guide

089759e

dangotbanned added 2 commits September 4, 2024 15:48

docs: Use when in expressions.rst

729b7de

docs: Use when in bindings_widgets.rst

1bc65ce

dangotbanned added 9 commits September 4, 2024 17:19

docs: Use when in exploring-weather.rst

f9277fa

docs: Use when in filter.rst

961eb13

docs: Use when in pivot.rst

d886fbe

docs: Use when in compound_charts.rst

9ca591e

docs: Use when in times_and_dates.rst

fe5f8e5

docs: Use when in line.rst

b0893e2

docs: Use when in text.rst

008ff8d

docs: Use when in geoshape.rst

4fe1e9c

docs: Use when in README.md

6269533

docs: Use when in jupyter_chart.rst

f08d96f

joelostblom reviewed Sep 4, 2024

View reviewed changes

doc/case_studies/exploring-weather.rst Show resolved Hide resolved

dangotbanned added 2 commits September 5, 2024 12:19

Merge branch 'main' into when-then-user-guide

60f859f

docs(DRAFT): Use when in parameters.rst

1d6be16

First draft version. Unlike the other commits, this has to introduce the concept - so will require more scrutiny. vega#3544 (comment)

dangotbanned requested review from joelostblom, mattijn, jonmmease and binste September 6, 2024 10:24

Merge branch 'main' into when-then-user-guide

3caf2e7

dangotbanned mentioned this pull request Sep 6, 2024

channels.py parameters, properties types too strict #3572

Closed

dangotbanned added 4 commits September 6, 2024 14:01

Merge branch 'main' into when-then-user-guide

ebff622

Merge branch 'when-then-user-guide' of https://github.com/dangotbanne…

731728e

…d/altair into when-then-user-guide

Merge remote-tracking branch 'upstream/main' into when-then-user-guide

1a5c0b9

chore(typing): Removed fixed ignore comments

6d6b8a6

dangotbanned added 2 commits September 9, 2024 21:39

Merge branch 'main' into when-then-user-guide

222deb5

Merge branch 'main' into when-then-user-guide

1c7663c

dangotbanned marked this pull request as ready for review September 10, 2024 06:38

dangotbanned added 2 commits September 12, 2024 20:57

Merge branch 'main' into when-then-user-guide

9ebb90b

Merge branch 'main' into when-then-user-guide

f43d331

joelostblom mentioned this pull request Sep 17, 2024

"No such file" when file seemingly exists trevorcampbell/website_diff#28

Closed

joelostblom reviewed Sep 18, 2024

View reviewed changes

doc/user_guide/interactions/parameters.rst Outdated Show resolved Hide resolved

doc/user_guide/interactions/parameters.rst Outdated Show resolved Hide resolved

dangotbanned marked this pull request as draft September 18, 2024 10:26

fix: Use selector argument in make_example

fb42da7

All of the charts using this function were silently producing no output. `brush` had been defined globally in an earlier directive vega#3544 (comment)

dangotbanned added 2 commits September 18, 2024 13:13

docs: Add new subsection content

50a520e

Not sure what the title should be, but @joelostblom proposed making this a new subsection vega#3544 (review)

docs: Add link to interactive_bar_select_highlight.rst

df5555c

https://altair-viz.github.io/gallery/interactive_bar_select_highlight.html

joelostblom reviewed Sep 19, 2024

View reviewed changes

joelostblom marked this pull request as ready for review September 19, 2024 19:24

dangotbanned commented Sep 20, 2024

View reviewed changes


	Conditions & Filters
	~~~~~~~~~~~~~~~~~~~~

	Conditional Encodings
	^^^^^^^^^^^^^^^^^^^^^

	The example above is neat, but the selection interval doesn't actually do anything yet.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Promote `when-then-otherwise` in User Guide #3544

docs: Promote `when-then-otherwise` in User Guide #3544

dangotbanned commented Aug 18, 2024 •

edited

Loading

dangotbanned commented Sep 4, 2024

joelostblom commented Sep 4, 2024

dangotbanned commented Sep 4, 2024

joelostblom left a comment

joelostblom commented Sep 9, 2024

dangotbanned commented Sep 9, 2024

joelostblom left a comment

dangotbanned commented Sep 18, 2024

joelostblom commented Sep 18, 2024

dangotbanned commented Sep 19, 2024

joelostblom left a comment

joelostblom Sep 19, 2024

dangotbanned Sep 20, 2024

dangotbanned Sep 20, 2024

dangotbanned left a comment

dangotbanned Sep 20, 2024

dangotbanned Sep 20, 2024

dangotbanned Sep 20, 2024 •

edited

Loading

dangotbanned Sep 20, 2024

dangotbanned Sep 20, 2024

dangotbanned Sep 20, 2024

dangotbanned Sep 20, 2024

dangotbanned Sep 20, 2024

dangotbanned Sep 20, 2024

dangotbanned Sep 20, 2024

dangotbanned Sep 20, 2024

	if isinstance(filter, Parameter):
	new_filter: dict[str, Any] = {"param": filter.name}
	if "empty" in kwargs:
	new_filter["empty"] = kwargs.pop("empty")
	elif isinstance(filter.empty, bool):
	new_filter["empty"] = filter.empty
	filter = new_filter
	return self._add_transform(core.FilterTransform(filter=filter, **kwargs))

	different conditional branches in :fun:`when`,
	different conditional branches in :func:`when`,

	:fun:`when` allows the use of multiple ``then`` (``elif``) branches
	:func:`when` allows the use of multiple ``then`` (``elif``) branches

		)

		either_or_but_not_both = (alex \| morgan) & ~(alex & morgan)

		As a convenience,
		simple conditions may be expressed without defining a default:

	Omitting the ``.otherwise()`` clause will use the channel default instead::

	points.encode(color=alt.when(brush).then("Origin"))

		The ``empty=False`` argument could instead be set inside :func:`when`,
		so that you don't need to redefine the same selection, e.g.::

	empty
	For selection parameters, the predicate of empty selections returns ``True`` by default.
	Override this behavior, with ``empty=False``.

	.. note::
	When ``predicate`` is a ``Parameter`` that is used more than once,
	``alt.when(..., empty=...)`` provides granular control for each occurrence.

docs: Promote when-then-otherwise in User Guide #3544

Are you sure you want to change the base?

docs: Promote when-then-otherwise in User Guide #3544

Conversation

dangotbanned commented Aug 18, 2024 • edited Loading

Status

Tasks

dangotbanned commented Sep 4, 2024

joelostblom commented Sep 4, 2024

dangotbanned commented Sep 4, 2024

joelostblom left a comment

Choose a reason for hiding this comment

joelostblom commented Sep 9, 2024

dangotbanned commented Sep 9, 2024

joelostblom left a comment

Choose a reason for hiding this comment

dangotbanned commented Sep 18, 2024

joelostblom commented Sep 18, 2024

dangotbanned commented Sep 19, 2024

joelostblom left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dangotbanned left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dangotbanned Sep 20, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

1

2

3

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Related

Choose a reason for hiding this comment

Choose a reason for hiding this comment

docs: Promote `when-then-otherwise` in User Guide #3544

docs: Promote `when-then-otherwise` in User Guide #3544

dangotbanned commented Aug 18, 2024 •

edited

Loading

dangotbanned Sep 20, 2024 •

edited

Loading