docs: Promote when-then-otherwise in User Guide

[dangotbanned]

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

• Use alt.when in waterfall chart
• Fill out tasks following discussion
• Add callout re: v5.4.0 change comment
  • Probably makes most sense here
    parameters.rst

    altair/doc/user_guide/interactions/parameters.rst

    Lines 148 to 155 in 5207768

    	Conditions & Filters
    	~~~~~~~~~~~~~~~~~~~~
    	Conditional Encodings
    	^^^^^^^^^^^^^^^^^^^^^
    	The example above is neat, but the selection interval doesn't actually *do* anything yet.

• when(..., empty=False) example in User Guide comment
  • Possibly link to example
  • Similar to the zorder link at the end of conditional-encodings
  • Resolved in df5555c (#3544)
• parameters.rst
  • Draft 1
  • Draft 2
• Replace condition references with when comment
  • User Guide
    • Interactions
      • bindings_widgets.rst
      • expressions.rst
      • jupyter_chart.rst
    • Marks
      • geoshape.rst
      • line.rst
      • text.rst
    • Transform
      • filter.rst
      • pivot.rst
    • compound_charts.rst
    • times_and_dates.rst
  • Case Studies
    • exploring-weather.rst
  • README.md
  • Gallery
    • examples_methods_syntax/*.py
    • examples_arguments_syntax/*.py

[dangotbanned]

@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]

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]

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.

[dangotbanned]

@joelostblom I wanted to check in with you, as I'm hoping to merge this PR soon.

The following are complicated somewhat by this remaining open:

• Update Chart.transform_filter() to mirror alt.when() #3657
  • Really needs this PR merged first
• Clarify usage of initial values in selection intervals with dates #3643
  • I've been holding off on suggesting to move forward on this
  • Likely needs to update multiple places in the user guide
• feat: Support datetime.(date|datetime) in Expression(s) #3654
  • Not a huge issue, but documenting will touch similar areas

---

I'm thinking pragmatically here, if the only possibly outstanding concerns were regarding formatting - would you be okay if we tackled that in a follow up?

I'm really happy with these updates we put together and wish to build on them further in the other issues/PRs I linked

[dangotbanned]

@mattijn if you're available

I'm planning to merge this tomorrow and follow it up with another PR #3668 mentioned in #3664 (comment)

The short rundown is that it will be adding support all the classes like this:

• core.Field...Predicate
• core.Logical...Predicate

when used in both of these calls:

• alt.when(*more_predicates)
• alt.Chart.transform_filter(*more_predicates)

---

I can delay this if anyone would have an issue - but as I mentioned in #3544 (comment) - I'd really like to close this PR off if possible

[mattijn]

I haven't had a look to this PR before, but just had a quick glance. I understand the title to promote the when-then-otherwise in the user guide, but (unintentionally?) you ruffed many examples into another style that we did not like to promote in the examples.

[mattijn]

During NumFOCUS summit @binste and I had come up with a config object based on YAPF that comes close to the style of the Altair examples how one would write it manually.

One can test that config style as such:

import yapf
from yapf.yapflib.yapf_api import FormatCode

# Define the code you want to format
code = """
def example_function(x,y):
 return (x+y)* (x-y)
"""

# Define YAPF configuration
style_config = {
    'based_on_style': 'pep8',
    'COLUMN_LIMIT': 88,
    'SPLIT_BEFORE_EXPRESSION_AFTER_OPENING_PAREN': True,
    'SPLIT_BEFORE_FIRST_ARGUMENT': True,
    'ALLOW_SPLIT_BEFORE_DEFAULT_OR_NAMED_ASSIGNS': True,
    'NO_SPACES_AROUND_SELECTED_BINARY_OPERATORS': False,
    'DEDENT_CLOSING_BRACKETS': True,
    'COALESCE_BRACKETS': True,
    'SPLIT_BEFORE_DOT': True,
    'SPLIT_BEFORE_CLOSING_BRACKET': True,
}

# Format the code using YAPF
formatted_code, _ = FormatCode(code, style_config=style_config)

# Display formatted code
print(formatted_code)

I've to mention that this style is not endorsed by @binste, he just prefer to ruff it all! 😄

[joelostblom]

@dangotbanned Sorry for the delay here. I wanted to go in an revert the examples to the old syntax, but I've been buried in work lately =/ I don't want to hold up your future PRs, so I'm ok if this needs to be merged although if there is something that can be done to bring it closer to the old syntax (like what Mattijn is suggesting maybe?) then that might save time long term instead of trying to change these back in a follow up PR.

As I mentioned in #3570 I do see the advantages of adhering to a syntax that is supported by Ruff, and if our current syntax is making it hard to update the docs effectively, then that's another argument in favor of switching.

[dangotbanned]

Thanks for getting back to me @joelostblom (
#3544 (comment)), and @mattijn for your input (#3544 (comment))

I've marked up every instance I spotted that might be considered a change in syntax.

The good news is that @joelostblom's original comment that picked up on the change meant that most of this is limited to the .rst examples.
So despite this PR touching 64 files; only 10 of these may require changes.

---

yapf

@mattijn I haven't looked into this in much detail yet, but have some thoughts.

Since it has both a CLI and module interface - there may be multiple ways we could use it with the code block stuff I added in #3630.

I called out #3570 (comment) directly there, as this was the exact use case I had in mind.
If we went down that route, I'd still prefer to keep that separate from this PR.

I do want to reiterate that I feel more strongly towards some form of autoformatting for examples - than a specific style.
My preference is ruff, but within reason, I'm happy for this to be anything that others agree upon

[joelostblom]

Thank you for going through and reverting the style on all of these examples before merging @dangotbanned !