feat: Support Chart.transform_filter(*predicates, **constraints)

[dangotbanned]

Will close #3657

Description

This PR enables the same syntax from alt.when to be used in alt.TopLevelMixin.transform_filter.

Honestly, I'm still a bit shocked by how little needed changing in the implementation.
Besides tweaking the signature and handling the deprecated argument, it really was just these 2 lines:

altair/altair/vegalite/v5/api.py

Lines 3102 to 3103 in 2d57d6e

	cond = _parse_when(predicate, *more_predicates, empty=empty, **constraints)
	return self._add_transform(core.FilterTransform(filter=cond.get("test", cond)))

To explain this, _parse_when returns our version of VL-Condition.
We can either use that as-is or unwrap the "test" key, which stores an already parsed test VL-Predicate.

Besides this small change, most of the PR consists of new docs & tests.

Doc (Examples)

Setting up a common chart:

source = data.population.url
chart = (
    alt.Chart(source)
    .mark_line()
    .encode(
        x="age:O",
        y="sum(people):Q",
        color=alt.Color("year:O").legend(symbolType="square"),
    )
)
chart

Singular predicates can be expressed via datum:

chart.transform_filter(datum.year <= 1980)

We can also use selection parameters directly:

selection = alt.selection_point(encodings=["color"], bind="legend")
chart.transform_filter(selection).add_params(selection)

Or a field predicate:

between_1950_60 = alt.FieldRangePredicate(field="year", range=[1950, 1960])
chart.transform_filter(between_1950_60) | chart.transform_filter(~between_1950_60)

Predicates can be composed together using logical operands:

chart.transform_filter(between_1950_60 | (datum.year == 1850))

Predicates passed as positional arguments will be reduced with &:

chart.transform_filter(datum.year > 1980, datum.age != 90)

Using keyword-argument constraints can simplify compositions like:

verbose_composition = chart.transform_filter((datum.year == 2000) & (datum.sex == 1))
chart.transform_filter(year=2000, sex=1)

Tasks

• Deprecate using filter as a keyword argument
  • plan
  • related PR
  • commit
• Replace current .transform_filter() implementation
• Review current tests/failures
  • Was expecting this to be more complicated
  • No test failures
  • One typing issue
• Add new tests for (*predicates, **constraints) syntax (b497039)
• Address predicate dict typing issue
  • Found in (fc672bc)
  • thread
• Update .transform_filter() docstring (7a0cc42)

[mattijn]

Thanks @dangotbanned! This looks great!

Would it be possible to add the examples that you describe within the docstring of the .transform_filter() method also within the data transformations in the official documentation around here: https://altair-viz.github.io/user_guide/transform/filter.html#logical-operands?

[dangotbanned]

Thanks @dangotbanned! This looks great!

Would it be possible to add the examples that you describe within the docstring of the .transform_filter() method also within the data transformations in the official documentation around here: altair-viz.github.io/user_guide/transform/filter.html#logical-operands?

Thanks @mattijn!

Yeah that sounds like a good idea, will try and take a look later today

[dangotbanned]

@mattijn preview from (3efc144)

I'm quite happy with the flow in the transform_filter() docstring.
But the other parts are already covered earlier in the page

[mattijn]

Thanks @dangotbanned 🥳!