You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Previously, expressions were mostly (only?) used with transform_calculate and it makes sense that they were described at this location in the docs. However, it is now possible to use alt.expr/alt.ExprRef with expression strings elsewhere so I think it makes sense to explain this clearly in the docs. A natural place could be under "Interactive charts" just above the heading "Future examples". That page currently already talks a lot about parameters in expressions, but we don't touch upon expr so it is unclear how these two relates.
A few things I think we should cover:
What is an expression?
This can be taken from the transform_calculate docs and expanded upon a bit.
What is the difference between using a string and alt.expr
This can be taken from the transform_calculate docs and expanded upon a bit.
If we think alt.expr should be preferred due to tab completion, maybe we should update some examples in the docs because most seem to use expression strings directly. If we don't think alt.expr is preferred, then is it even worth highlighting in the first place?
Where can an expression be used and where can it not be used?
In which use cases could you use either an expression or a param and when is an expression preferred over a param and vice versa?
How to reference a column inside an expression via datum
Agree on a syntax to use for importing datum. Currently the docs are a mix between alt.datum and alt.expr.datum (maybe we should always use the former and hide the latter from the public API?):
Previously, expressions were mostly (only?) used with
transform_calculateand it makes sense that they were described at this location in the docs. However, it is now possible to usealt.expr/alt.ExprRefwith expression strings elsewhere so I think it makes sense to explain this clearly in the docs. A natural place could be under "Interactive charts" just above the heading "Future examples". That page currently already talks a lot about parameters in expressions, but we don't touch uponexprso it is unclear how these two relates.A few things I think we should cover:
alt.expralt.exprshould be preferred due to tab completion, maybe we should update some examples in the docs because most seem to use expression strings directly. If we don't thinkalt.expris preferred, then is it even worth highlighting in the first place?datumalt.datumandalt.expr.datum(maybe we should always use the former and hide the latter from the public API?):alt.expr.datum:alt.datumExprRefandExprand should they ever be used (if not, should they be hidden from the public API?).alt.expr.if_()which I haven't seen documented anywhere, how does that relate toalt.condition? https://joelostblom.github.io/altair-docs/gallery/us_population_over_time.html and https://joelostblom.github.io/altair-docs/gallery/us_population_pyramid_over_time.htmlexprinstead ofExprRefas per Includealt.ExprRefcapabilities inalt.expr()#2886 (comment)