Skip to content

Expand docs on expressions #2904

@joelostblom

Description

@joelostblom

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:

  1. What is an expression?
    • This can be taken from the transform_calculate docs and expanded upon a bit.
  2. 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?
  3. Where can an expression be used and where can it not be used?
  4. 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?
  5. How to reference a column inside an expression via datum
  6. What is ExprRef and Expr and should they ever be used (if not, should they be hidden from the public API?).
  7. This page use alt.expr.if_() which I haven't seen documented anywhere, how does that relate to alt.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.html
  8. Make docs link to expr instead of ExprRef as per Include alt.ExprRef capabilities in alt.expr() #2886 (comment)

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    Status

    Documentation

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions