Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Expand docs on expressions #2904

Closed
joelostblom opened this issue Feb 19, 2023 · 0 comments · Fixed by #2928
Closed

Expand docs on expressions #2904

joelostblom opened this issue Feb 19, 2023 · 0 comments · Fixed by #2928

Comments

@joelostblom
Copy link
Contributor

joelostblom commented Feb 19, 2023

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)
@joelostblom joelostblom moved this to Documentation in Roadmap Apr 12, 2024
dangotbanned added a commit to dangotbanned/altair that referenced this issue Jul 9, 2024
Uses the section heading proposed in vega#3427 (comment)

Expands on vega#2904
jonmmease pushed a commit that referenced this issue Jul 20, 2024
* fix: Use absolute imports explicitly

Fixes the mypy issue referenced in `alt.__init__.py`

* refactor: remove dynamic globals manipulation

The results of `_populate_namespace` were only visible in a `IPython` environment

* feat: Reimplement `expr` as a class w/ identicial semantics as the singleton

- all `ConstExpression`s are now read-only properties stored in a metaclass
- `expr` subclasses `ExprRef`, replacing the `__call__` w/ `__new__`
  - No instances of `expr` are ever created
- All `FunctionExpression`s are now classmethods
- Each `Expression` can now be referenced in autocomplete, without needing `IPython`/`Jupyter`
- Docstrings have been reformatted to be compatible with `sphinx`
- Broken links in docstrings fixed (e.g. for d3)
- class-level doc for `expr`, with references & doctest

* fix: use absolute imports in `test_expr`

Previously relied on the dynamic globals

* test(perf): rewrite `expr` tests to run in parallel

Previously 2 tests, now 170+

* test: confirm `expr` constants stay constant

* chore(typing): add ignores not flagged by mypy

* docs: adds `alt.expr` to API Reference

Uses the section heading proposed in #3427 (comment)

Expands on #2904

* test: ensure `test_expr_consts_immutable` pattern works for all versions

* docs: fix typos, regex artifacts, apply some `ruff` `D` rules

* docs: add doc for `_ConstExpressionType`

* test: make `expr` doctest testable

I left this out initially, but by adding static `Parameter` names it is now possible

* fix: re-run `generate-schema-wrapper`

https://github.com/vega/altair/actions/runs/10005909777/job/27657526013?pr=3466

* refactor: Remove `expr` test dependency on constants

Fixes #3466 (comment)

* style: remove trailing commas in `@pytest.mark.parametrize`
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: Documentation
Development

Successfully merging a pull request may close this issue.

1 participant