feat: Support `&`, `|`, `~` on all `...Predicate` classes

[dangotbanned]

Resolves #695

Description

This PR enables the use of logical composition operators (&, |, ~) directly on all 12 of:

...Predicate classes

- `core.FieldEqualPredicate` - `core.FieldGTEPredicate` - `core.FieldGTPredicate` - `core.FieldLTEPredicate` - `core.FieldLTPredicate` - `core.FieldOneOfPredicate` - `core.FieldRangePredicate` - `core.FieldValidPredicate` - `core.LogicalAndPredicate` - `core.LogicalOrPredicate` - `core.LogicalNotPredicate` - `core.ParameterPredicate`

It appears this functionality has been desired for some time, but never implemented fully.

api.SelectionPredicateComposition already contained the code required to get this working - this PR moves that to core.PredicateComposition.

The change is fully backwards compatible, turning the old class into an alias (https://github.com/vega/altair/pull/3668/commits/1dc15b72c01fe47a5b87222d26258eb08b75cdea)

This also provides a cleaner solution to (https://github.com/vega/altair/pull/3664#discussion_r1823177593) - than any of the alternatives documented there

Example

import altair as alt
from vega_datasets import data

source = data.disasters()
columns_sorted = ["Drought", "Epidemic", "Earthquake", "Flood"]

base = (
    alt.Chart(source, height=200)
    .mark_line(interpolate="monotone")
    .encode(
        x=alt.X("Year:Q").axis(format="d"),
        color="Entity",
        column="Entity",
        y="sum(Deaths)",
    )
)

chart_old = base.transform_filter(
    {
        "and": [
            alt.FieldOneOfPredicate(field="Entity", oneOf=columns_sorted),
            alt.FieldRangePredicate(field="Year", range=[1900, 2000]),
        ]
    }
)

chart_new = base.transform_filter(
    alt.FieldOneOfPredicate(field="Entity", oneOf=columns_sorted)
    & alt.FieldRangePredicate(field="Year", range=[1900, 2000])
)
chart_old & chart_new

Output


User Guide

Tasks

• [x] Core implementation & tests (commits)
• [x] Update User Guide- Logical Operands (commit)

Other Future Work

• I mentioned in (https://github.com/vega/altair/pull/3668/commits/c1d05ec9f1ca5bb7382e746e5d425f98bc5e4643) that something similar could be done for expr.core.Expression -> core.Expr
  • possibly as part of #3616

• 3505

  • That PR features similar functionality via _wrap_composition
  • This PR can therefore simplify the implementation there, removing the need for that extra step entirely

Related

• 3664

• https://github.com/vega/altair/pull/3544#issuecomment-2450700954
• https://altair-viz.github.io/user_guide/transform/filter.html#logical-operands