From aeb0c721cce0c8099e0688d7f83beae2e0fa103d Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Tue, 27 Aug 2024 09:16:48 -0700 Subject: [PATCH 1/7] docs: Unstack area to render cumulative chart correctly (#3558) This has been broken since Vega-Lite changed the default behavior in https://github.com/vega/vega-lite/releases/tag/v5.14.1 --- .../cumulative_count_chart.py | 2 +- .../cumulative_count_chart.py | 21 +++++++++++++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) create mode 100644 tests/examples_methods_syntax/cumulative_count_chart.py diff --git a/tests/examples_arguments_syntax/cumulative_count_chart.py b/tests/examples_arguments_syntax/cumulative_count_chart.py index f6e1df075..6ee7ad277 100644 --- a/tests/examples_arguments_syntax/cumulative_count_chart.py +++ b/tests/examples_arguments_syntax/cumulative_count_chart.py @@ -17,5 +17,5 @@ sort=[{"field": "IMDB_Rating"}], ).mark_area().encode( x="IMDB_Rating:Q", - y="cumulative_count:Q" + y=alt.Y("cumulative_count:Q", stack=False) ) diff --git a/tests/examples_methods_syntax/cumulative_count_chart.py b/tests/examples_methods_syntax/cumulative_count_chart.py new file mode 100644 index 000000000..a9b08361c --- /dev/null +++ b/tests/examples_methods_syntax/cumulative_count_chart.py @@ -0,0 +1,21 @@ +""" +Cumulative Count Chart +---------------------- +This example shows an area chart with cumulative count. +Adapted from https://vega.github.io/vega-lite/examples/area_cumulative_freq.html + +""" +# category: distributions + +import altair as alt +from vega_datasets import data + +source = data.movies.url + +alt.Chart(source).transform_window( + cumulative_count="count()", + sort=[{"field": "IMDB_Rating"}], +).mark_area().encode( + x="IMDB_Rating:Q", + y=alt.Y("cumulative_count:Q").stack(False) +) From 3da2e9ed2d46fff89234ec8ac3d12ef4fa9c9971 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Tue, 27 Aug 2024 11:47:16 -0700 Subject: [PATCH 2/7] docs: Change remote nick to `origin` and capitalize version commit(#3559) --- RELEASING.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 609f61f4d..a35a60af7 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -6,7 +6,7 @@ 2. Make certain your branch is in sync with head: - git pull upstream main + git pull origin main 3. Do a clean doc build: @@ -25,13 +25,13 @@ 5. Commit change and push to main: git add . -u - git commit -m "chore: bump version to 5.0.0" - git push upstream main + git commit -m "chore: Bump version to 5.0.0" + git push origin main 6. Tag the release: git tag -a v5.0.0 -m "version 5.0.0 release" - git push upstream v5.0.0 + git push origin v5.0.0 7. Build source & wheel distributions: @@ -54,11 +54,11 @@ 11. Commit change and push to main: git add . -u - git commit -m "chore: bump version to 5.1.0dev" - git push upstream main + git commit -m "chore: Bump version to 5.1.0dev" + git push origin main 12. Double-check that a conda-forge pull request is generated from the updated - pip package by the conda-forge bot (may take up to ~an hour): + pip package by the conda-forge bot (may take up to several hours): https://github.com/conda-forge/altair-feedstock/pulls 13. Publish a new release in https://github.com/vega/altair/releases/ From 5831a39edeccdb9761c369073841e6cd46f793ad Mon Sep 17 00:00:00 2001 From: Dan Redding <125183946+dangotbanned@users.noreply.github.com> Date: Tue, 27 Aug 2024 22:00:43 +0100 Subject: [PATCH 3/7] ci: Add `typings/` to `.gitignore` (#3560) --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index d72e70d4c..6262da0b7 100644 --- a/.gitignore +++ b/.gitignore @@ -75,3 +75,6 @@ Untitled*.ipynb # hatch, doc generation data.json + +# type stubs +typings/ \ No newline at end of file From 299c418cb1a73a27ff6dac072f821e65669e3f5c Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Sat, 31 Aug 2024 14:41:31 +0200 Subject: [PATCH 4/7] docs: Update releasing notes to reflect that main branch is now protected (#3562) * docs: Update releasing notes to reflect that main branch is now protected * Change checkout to switch Co-authored-by: Joel Ostblom --------- Co-authored-by: Joel Ostblom --- RELEASING.md | 45 ++++++++++++++++++++++++++++++++------------- 1 file changed, 32 insertions(+), 13 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index a35a60af7..a3de236e4 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -4,7 +4,7 @@ hatch env prune -2. Make certain your branch is in sync with head: +2. Make certain your branch is in sync with head. If you work on a fork, replace `origin` with `upstream`: git pull origin main @@ -17,48 +17,67 @@ Navigate to http://localhost:8000 and ensure it looks OK (particularly do a visual scan of the gallery thumbnails). -4. Update version to, e.g. 5.0.0: +4. Create a new release branch: + + git switch -c version_5.0.0 + +5. Update version to, e.g. 5.0.0: - in ``altair/__init__.py`` - in ``doc/conf.py`` -5. Commit change and push to main: +6. Commit changes and push: git add . -u git commit -m "chore: Bump version to 5.0.0" - git push origin main + git push + +7. Merge release branch into main, make sure that all required checks pass -6. Tag the release: +8. Tag the release: git tag -a v5.0.0 -m "version 5.0.0 release" git push origin v5.0.0 -7. Build source & wheel distributions: +9. On main, build source & wheel distributions. If you work on a fork, replace `origin` with `upstream`: + git switch main + git pull origin main hatch clean # clean old builds & distributions hatch build # create a source distribution and universal wheel -8. publish to PyPI (Requires correct PyPI owner permissions): +10. publish to PyPI (Requires correct PyPI owner permissions): hatch publish -9. build and publish docs (Requires write-access to altair-viz/altair-viz.github.io): +11. build and publish docs (Requires write-access to altair-viz/altair-viz.github.io): hatch run doc:publish-clean-build -10. update version to, e.g. 5.1.0dev: +12. On main, tag the release. If you work on a fork, replace `origin` with `upstream`: + + git tag -a v5.0.0 -m "Version 5.0.0 release" + git push origin v5.0.0 + +13. Create a new branch: + + git switch -c maint_5.1.0dev + +14. Update version and add 'dev' suffix, e.g. 5.1.0dev: - in ``altair/__init__.py`` - in ``doc/conf.py`` -11. Commit change and push to main: +15. Commit changes and push: git add . -u git commit -m "chore: Bump version to 5.1.0dev" - git push origin main + git push + +16. Merge maintenance branch into main -12. Double-check that a conda-forge pull request is generated from the updated +17. Double-check that a conda-forge pull request is generated from the updated pip package by the conda-forge bot (may take up to several hours): https://github.com/conda-forge/altair-feedstock/pulls -13. Publish a new release in https://github.com/vega/altair/releases/ +18. Publish a new release in https://github.com/vega/altair/releases/ From de58ec88115c07960fec52a9915df30d49450f61 Mon Sep 17 00:00:00 2001 From: Dan Redding <125183946+dangotbanned@users.noreply.github.com> Date: Sat, 31 Aug 2024 14:16:36 +0100 Subject: [PATCH 5/7] test: Adds `test-(slow|fast)` options (#3555) --- altair/utils/execeval.py | 61 +++++++- pyproject.toml | 12 ++ tests/__init__.py | 201 +++++++++++++++++++++++++ tests/test_examples.py | 97 +++--------- tests/test_transformed_data.py | 52 ++++--- tests/utils/test_core.py | 181 ++++++++++++---------- tests/utils/test_server.py | 2 + tests/utils/test_to_values_narwhals.py | 14 +- tests/utils/test_utils.py | 30 ++-- tests/vegalite/v5/test_api.py | 11 +- 10 files changed, 440 insertions(+), 221 deletions(-) diff --git a/altair/utils/execeval.py b/altair/utils/execeval.py index 5d3da928b..e5e855479 100644 --- a/altair/utils/execeval.py +++ b/altair/utils/execeval.py @@ -1,33 +1,70 @@ +from __future__ import annotations + import ast import sys +from typing import TYPE_CHECKING, Any, Callable, Literal, overload + +if TYPE_CHECKING: + from os import PathLike + + from _typeshed import ReadableBuffer + + if sys.version_info >= (3, 11): + from typing import Self + else: + from typing_extensions import Self class _CatchDisplay: """Class to temporarily catch sys.displayhook.""" - def __init__(self): - self.output = None + def __init__(self) -> None: + self.output: Any | None = None - def __enter__(self): - self.old_hook = sys.displayhook + def __enter__(self) -> Self: + self.old_hook: Callable[[object], Any] = sys.displayhook sys.displayhook = self return self - def __exit__(self, type, value, traceback): + def __exit__(self, type, value, traceback) -> Literal[False]: sys.displayhook = self.old_hook # Returning False will cause exceptions to propagate return False - def __call__(self, output): + def __call__(self, output: Any) -> None: self.output = output -def eval_block(code, namespace=None, filename=""): +@overload +def eval_block( + code: str | Any, + namespace: dict[str, Any] | None = ..., + filename: str | ReadableBuffer | PathLike[Any] = ..., + *, + strict: Literal[False] = ..., +) -> Any | None: ... +@overload +def eval_block( + code: str | Any, + namespace: dict[str, Any] | None = ..., + filename: str | ReadableBuffer | PathLike[Any] = ..., + *, + strict: Literal[True] = ..., +) -> Any: ... +def eval_block( + code: str | Any, + namespace: dict[str, Any] | None = None, + filename: str | ReadableBuffer | PathLike[Any] = "", + *, + strict: bool = False, +) -> Any | None: """ Execute a multi-line block of code in the given namespace. If the final statement in the code is an expression, return the result of the expression. + + If ``strict``, raise a ``TypeError`` when the return value would be ``None``. """ tree = ast.parse(code, filename="", mode="exec") if namespace is None: @@ -50,4 +87,12 @@ def eval_block(code, namespace=None, filename=""): ) exec(compiled, namespace) - return catch_display.output + if strict: + output = catch_display.output + if output is None: + msg = f"Expected a non-None value but got {output!r}" + raise TypeError(msg) + else: + return output + else: + return catch_display.output diff --git a/pyproject.toml b/pyproject.toml index 4c85070a1..3e6dd7533 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -129,6 +129,14 @@ update-init-file = [ "ruff check .", "ruff format .", ] +test-fast = [ + "ruff check .", "ruff format .", + "pytest -p no:randomly -n logical --numprocesses=logical --doctest-modules tests altair -m \"not slow\" {args}" +] +test-slow = [ + "ruff check .", "ruff format .", + "pytest -p no:randomly -n logical --numprocesses=logical --doctest-modules tests altair -m \"slow\" {args}" +] [tool.hatch.envs.hatch-test] # https://hatch.pypa.io/latest/tutorials/testing/overview/ @@ -409,6 +417,10 @@ docstring-code-line-length = 88 # test_examples tests. norecursedirs = ["tests/examples_arguments_syntax", "tests/examples_methods_syntax"] addopts = ["--numprocesses=logical"] +# https://docs.pytest.org/en/stable/how-to/mark.html#registering-marks +markers = [ + "slow: Label tests as slow (deselect with '-m \"not slow\"')" +] [tool.mypy] warn_unused_ignores = true diff --git a/tests/__init__.py b/tests/__init__.py index e69de29bb..1dd5f3999 100644 --- a/tests/__init__.py +++ b/tests/__init__.py @@ -0,0 +1,201 @@ +from __future__ import annotations + +import pkgutil +import re +from importlib.util import find_spec +from typing import TYPE_CHECKING + +import pytest + +from tests import examples_arguments_syntax, examples_methods_syntax + +if TYPE_CHECKING: + import sys + from re import Pattern + from typing import Collection, Iterator, Mapping + + if sys.version_info >= (3, 11): + from typing import TypeAlias + else: + from typing_extensions import TypeAlias + from _pytest.mark import ParameterSet + + MarksType: TypeAlias = ( + "pytest.MarkDecorator | Collection[pytest.MarkDecorator | pytest.Mark]" + ) + +slow: pytest.MarkDecorator = pytest.mark.slow() +""" +Custom ``pytest.mark`` decorator. + +By default **all** tests are run. + +Slow tests can be **excluded** using:: + + >>> hatch run test-fast # doctest: +SKIP + +To run **only** slow tests use:: + + >>> hatch run test-slow # doctest: +SKIP + +Either script can accept ``pytest`` args:: + + >>> hatch run test-slow --durations=25 # doctest: +SKIP +""" + + +skip_requires_vl_convert: pytest.MarkDecorator = pytest.mark.skipif( + find_spec("vl_convert") is None, reason="`vl_convert` not installed." +) +""" +``pytest.mark.skipif`` decorator. + +Applies when `vl-convert`_ import would fail. + +.. _vl-convert: + https://github.com/vega/vl-convert +""" + + +skip_requires_pyarrow: pytest.MarkDecorator = pytest.mark.skipif( + find_spec("pyarrow") is None, reason="`pyarrow` not installed." +) +""" +``pytest.mark.skipif`` decorator. + +Applies when `pyarrow`_ import would fail. + +.. _pyarrow: + https://pypi.org/project/pyarrow/ +""" + + +def id_func_str_only(val) -> str: + """ + Ensures the generated test-id name uses only `filename` and not `source`. + + Without this, the name is repr(source code)-filename + """ + if not isinstance(val, str): + return "" + else: + return val + + +def _wrap_mark_specs( + pattern_marks: Mapping[Pattern[str] | str, MarksType], / +) -> dict[Pattern[str], MarksType]: + return { + (re.compile(p) if not isinstance(p, re.Pattern) else p): marks + for p, marks in pattern_marks.items() + } + + +def _fill_marks( + mark_specs: dict[Pattern[str], MarksType], string: str, / +) -> MarksType | tuple[()]: + it = (v for k, v in mark_specs.items() if k.search(string)) + return next(it, ()) + + +def _distributed_examples( + *exclude_prefixes: str, marks: Mapping[Pattern[str] | str, MarksType] | None = None +) -> Iterator[ParameterSet]: + """ + Yields ``pytest.mark.parametrize`` arguments for all examples. + + Parameters + ---------- + *exclude_prefixes + Any file starting with these will be **skipped**. + marks + Mapping of ``re.search(..., )`` patterns to ``pytest.param(marks=...)``. + + The **first** match (if any) will be inserted into ``marks``. + """ + RE_NAME: Pattern[str] = re.compile(r"^tests\.(.*)") + mark_specs = _wrap_mark_specs(marks) if marks else {} + + for pkg in [examples_arguments_syntax, examples_methods_syntax]: + pkg_name = pkg.__name__ + if match := RE_NAME.match(pkg_name): + pkg_name_unqual: str = match.group(1) + else: + msg = f"Failed to match pattern {RE_NAME.pattern!r} against {pkg_name!r}" + raise ValueError(msg) + for _, mod_name, is_pkg in pkgutil.iter_modules(pkg.__path__): + if not (is_pkg or mod_name.startswith(exclude_prefixes)): + file_name = f"{mod_name}.py" + msg_name = f"{pkg_name_unqual}.{file_name}" + if source := pkgutil.get_data(pkg_name, file_name): + yield pytest.param( + source, msg_name, marks=_fill_marks(mark_specs, msg_name) + ) + else: + msg = ( + f"Failed to get source data from `{pkg_name}.{file_name}`.\n" + f"pkgutil.get_data(...) returned: {pkgutil.get_data(pkg_name, file_name)!r}" + ) + raise TypeError(msg) + + +ignore_DataFrameGroupBy: pytest.MarkDecorator = pytest.mark.filterwarnings( + "ignore:DataFrameGroupBy.apply.*:DeprecationWarning" +) +""" +``pytest.mark.filterwarnings`` decorator. + +Hides ``pandas`` warning(s):: + + "ignore:DataFrameGroupBy.apply.*:DeprecationWarning" +""" + + +distributed_examples: pytest.MarkDecorator = pytest.mark.parametrize( + ("source", "filename"), + tuple( + _distributed_examples( + "_", + "interval_selection_map_quakes", + marks={ + "beckers_barley.+facet": slow, + "lasagna_plot": slow, + "line_chart_with_cumsum_faceted": slow, + "layered_bar_chart": slow, + "multiple_interactions": slow, + "layered_histogram": slow, + "stacked_bar_chart_with_text": slow, + "bar_chart_with_labels": slow, + "interactive_cross_highlight": slow, + "wind_vector_map": slow, + r"\.point_map\.py": slow, + "line_chart_with_color_datum": slow, + }, + ) + ), + ids=id_func_str_only, +) +""" +``pytest.mark.parametrize`` decorator. + +Provides **all** examples, using both `arguments` & `methods` syntax. + +The decorated test can evaluate each resulting chart via:: + + from altair.utils.execeval import eval_block + + @distributed_examples + def test_some_stuff(source: Any, filename: str) -> None: + chart: ChartType | None = eval_block(source) + ... # Perform any assertions + +Notes +----- +- See `#3431 comment`_ for performance benefit. +- `interval_selection_map_quakes` requires `#3418`_ fix + +.. _#3431 comment: + https://github.com/vega/altair/pull/3431#issuecomment-2168508048 +.. _#3418: + https://github.com/vega/altair/issues/3418 +""" diff --git a/tests/test_examples.py b/tests/test_examples.py index 02dd1e23c..07c4ed54b 100644 --- a/tests/test_examples.py +++ b/tests/test_examples.py @@ -20,72 +20,21 @@ from __future__ import annotations import io -import pkgutil -import re -import sys -from typing import Any, Iterable, Iterator - -import pytest +from typing import Any import altair as alt from altair.utils.execeval import eval_block -from tests import examples_arguments_syntax, examples_methods_syntax - -try: - import vl_convert as vlc # noqa: F401, RUF100 -except ImportError: - vlc = None - - -VL_CONVERT_AVAILABLE = "vl_convert" in sys.modules - - -def iter_examples_filenames(syntax_module) -> Iterator[str]: - for _importer, modname, ispkg in pkgutil.iter_modules(syntax_module.__path__): - if not ( - ispkg - or modname.startswith("_") - # Temporarily skip this test until https://github.com/vega/altair/issues/3418 - # is fixed - or modname == "interval_selection_map_quakes" - ): - yield f"{modname}.py" - - -def _distributed_examples() -> Iterator[tuple[Any, str]]: - # `pytest.mark.parametrize` over 2 modules produces 2x workers - # - This raises the total jobs from 400 -> 1200 - # - Preventing the three tests from blocking everything else - RE_NAME: re.Pattern[str] = re.compile(r"^tests\.(.*)") - - for module in [examples_arguments_syntax, examples_methods_syntax]: - for filename in iter_examples_filenames(module): - name = module.__name__ - source = pkgutil.get_data(name, filename) - yield source, f"{RE_NAME.match(name).group(1)}.{filename}" # type: ignore[union-attr] - - -distributed_examples: Iterable[tuple[Any, str]] = tuple(_distributed_examples()) -"""Tried using as a `fixture`, but wasn't able to combine with `@pytest.mark.parametrize`.""" - - -def id_func(val) -> str: - """ - Ensures the generated test-id name uses only `filename` and not `source`. - - Without this, the name is repr(source code)-filename - """ - if not isinstance(val, str): - return "" - else: - return val +from tests import ( + distributed_examples, + ignore_DataFrameGroupBy, + skip_requires_vl_convert, + slow, +) -@pytest.mark.filterwarnings( - "ignore:DataFrameGroupBy.apply.*:DeprecationWarning", -) -@pytest.mark.parametrize(("source", "filename"), distributed_examples, ids=id_func) -def test_render_examples_to_chart(source, filename) -> None: +@ignore_DataFrameGroupBy +@distributed_examples +def test_render_examples_to_chart(source: Any, filename: str) -> None: chart = eval_block(source) if chart is None: msg = f"Example file {filename} should define chart in its final statement." @@ -100,11 +49,9 @@ def test_render_examples_to_chart(source, filename) -> None: raise AssertionError(msg) from err -@pytest.mark.filterwarnings( - "ignore:DataFrameGroupBy.apply.*:DeprecationWarning", -) -@pytest.mark.parametrize(("source", "filename"), distributed_examples, ids=id_func) -def test_from_and_to_json_roundtrip(source, filename) -> None: +@ignore_DataFrameGroupBy +@distributed_examples +def test_from_and_to_json_roundtrip(source: Any, filename: str) -> None: """ Tests if the to_json and from_json work for all examples in the Example Gallery. @@ -131,19 +78,17 @@ def test_from_and_to_json_roundtrip(source, filename) -> None: raise AssertionError(msg) from err -@pytest.mark.filterwarnings( - "ignore:DataFrameGroupBy.apply.*:DeprecationWarning", -) -@pytest.mark.parametrize(("source", "filename"), distributed_examples, ids=id_func) -@pytest.mark.skipif( - not VL_CONVERT_AVAILABLE, - reason="vl_convert not importable; cannot run mimebundle tests", -) -def test_render_examples_to_png(source, filename) -> None: +@slow +@ignore_DataFrameGroupBy +@distributed_examples +@skip_requires_vl_convert +def test_render_examples_to_png(source: Any, filename: str) -> None: chart = eval_block(source) if chart is None: msg = f"Example file {filename} should define chart in its final statement." raise ValueError(msg) out = io.BytesIO() chart.save(out, format="png", engine="vl-convert") - assert out.getvalue().startswith(b"\x89PNG") + buf = out.getbuffer() + prefix = buf[:4].tobytes() + assert prefix == b"\x89PNG" diff --git a/tests/test_transformed_data.py b/tests/test_transformed_data.py index 392359264..1c4d8a095 100644 --- a/tests/test_transformed_data.py +++ b/tests/test_transformed_data.py @@ -6,7 +6,8 @@ import altair as alt from altair.utils.execeval import eval_block -from tests import examples_methods_syntax +from tests import examples_methods_syntax, slow, ignore_DataFrameGroupBy +import narwhals as nw try: import vegafusion as vf # type: ignore @@ -16,9 +17,7 @@ XDIST_ENABLED: bool = "xdist" in sys.modules """Use as an `xfail` condition, if running in parallel may cause the test to fail.""" -@pytest.mark.filterwarnings( - "ignore:DataFrameGroupBy.apply.*:DeprecationWarning" -) +@ignore_DataFrameGroupBy @pytest.mark.skipif(vf is None, reason="vegafusion not installed") # fmt: off @pytest.mark.parametrize("filename,rows,cols", [ @@ -35,9 +34,9 @@ ("gapminder_bubble_plot.py", 187, ["income", "population"]), ("grouped_bar_chart2.py", 9, ["Group", "Value_start"]), ("hexbins.py", 84, ["xFeaturePos", "mean_temp_max"]), - ("histogram_heatmap.py", 378, ["bin_maxbins_40_Rotten_Tomatoes_Rating", "__count"]), + pytest.param("histogram_heatmap.py", 378, ["bin_maxbins_40_Rotten_Tomatoes_Rating", "__count"], marks=slow), ("histogram_scatterplot.py", 64, ["bin_maxbins_10_Rotten_Tomatoes_Rating", "__count"]), - ("interactive_legend.py", 1708, ["sum_count_start", "series"]), + pytest.param("interactive_legend.py", 1708, ["sum_count_start", "series"], marks=slow), ("iowa_electricity.py", 51, ["net_generation_start", "year"]), ("isotype.py", 37, ["animal", "x"]), ("isotype_grid.py", 100, ["row", "col"]), @@ -47,7 +46,7 @@ ("layered_histogram.py", 113, ["bin_maxbins_100_Measurement"]), ("line_chart_with_cumsum.py", 52, ["cumulative_wheat"]), ("line_custom_order.py", 55, ["miles", "gas"]), - ("line_percent.py", 30, ["sex", "perc"]), + pytest.param("line_percent.py", 30, ["sex", "perc"], marks=slow), ("line_with_log_scale.py", 15, ["year", "sum_people"]), ("multifeature_scatter_plot.py", 150, ["petalWidth", "species"]), ("natural_disasters.py", 686, ["Deaths", "Year"]), @@ -59,10 +58,10 @@ ("pyramid.py", 3, ["category", "value_start"]), ("stacked_bar_chart_sorted_segments.py", 60, ["variety", "site"]), ("stem_and_leaf.py", 100, ["stem", "leaf"]), - ("streamgraph.py", 1708, ["series", "sum_count"]), + pytest.param("streamgraph.py", 1708, ["series", "sum_count"], marks=slow), ("top_k_items.py", 10, ["rank", "IMDB_Rating_start"]), ("top_k_letters.py", 9, ["rank", "letters"]), - ("top_k_with_others.py", 10, ["ranked_director", "mean_aggregate_gross"]), + pytest.param("top_k_with_others.py", 10, ["ranked_director", "mean_aggregate_gross"], marks=slow), ("area_faceted.py", 492, ["date", "price"]), ("distributions_faceted_histogram.py", 20, ["Origin", "__count"]), ("us_population_over_time.py", 38, ["sex", "people_start"]), @@ -74,16 +73,18 @@ @pytest.mark.parametrize("to_reconstruct", [True, False]) def test_primitive_chart_examples(filename, rows, cols, to_reconstruct): source = pkgutil.get_data(examples_methods_syntax.__name__, filename) - chart = eval_block(source) + chart = eval_block(source, strict=True) if to_reconstruct: # When reconstructing a Chart, Altair uses different classes # then what might have been originally used. See # https://github.com/hex-inc/vegafusion/issues/354 for more info. chart = alt.Chart.from_dict(chart.to_dict()) df = chart.transformed_data() + assert df is not None + nw_df = nw.from_native(df, eager_only=True, strict=True) - assert len(df) == rows - assert set(cols).issubset(set(df.columns)) + assert len(nw_df) == rows + assert set(cols).issubset(set(nw_df.columns)) @pytest.mark.skipif(vf is None, reason="vegafusion not installed") @@ -97,7 +98,7 @@ def test_primitive_chart_examples(filename, rows, cols, to_reconstruct): ("histogram_responsive.py", [20, 20], [["__count"], ["__count"]]), ("histogram_with_a_global_mean_overlay.py", [9, 1], [["__count"], ["mean_IMDB_Rating"]]), ("horizon_graph.py", [20, 20], [["x"], ["ny"]]), - ("interactive_cross_highlight.py", [64, 64, 13], [["__count"], ["__count"], ["Major_Genre"]]), + pytest.param("interactive_cross_highlight.py", [64, 64, 13], [["__count"], ["__count"], ["Major_Genre"]], marks=slow), ("interval_selection.py", [123, 123], [["price_start"], ["date"]]), ("layered_chart_with_dual_axis.py", [12, 12], [["month_date"], ["average_precipitation"]]), ("layered_heatmap_text.py", [9, 9], [["Cylinders"], ["mean_horsepower"]]), @@ -111,11 +112,11 @@ def test_primitive_chart_examples(filename, rows, cols, to_reconstruct): "scatter_with_layered_histogram.py", [2, 19], [["gender"], ["__count"]], - marks=pytest.mark.xfail( + marks=(slow, pytest.mark.xfail( XDIST_ENABLED, reason="Possibly `numpy` conflict with `xdist`.\n" "Very intermittent, but only affects `to_reconstruct=False`." - ), + )), ), ("scatter_with_minimap.py", [1461, 1461], [["date"], ["date"]]), ("scatter_with_rolling_mean.py", [1461, 1461], [["date"], ["rolling_mean"]]), @@ -130,20 +131,24 @@ def test_primitive_chart_examples(filename, rows, cols, to_reconstruct): @pytest.mark.parametrize("to_reconstruct", [True, False]) def test_compound_chart_examples(filename, all_rows, all_cols, to_reconstruct): source = pkgutil.get_data(examples_methods_syntax.__name__, filename) - chart = eval_block(source) + chart = eval_block(source, strict=True) if to_reconstruct: # When reconstructing a Chart, Altair uses different classes # then what might have been originally used. See # https://github.com/hex-inc/vegafusion/issues/354 for more info. chart = alt.Chart.from_dict(chart.to_dict()) + + assert isinstance(chart, (alt.LayerChart, alt.ConcatChart, alt.HConcatChart, alt.VConcatChart)) dfs = chart.transformed_data() if not to_reconstruct: # Only run assert statements if the chart is not reconstructed. Reason # is that for some charts, the original chart contained duplicated datasets # which disappear when reconstructing the chart. + + nw_dfs = (nw.from_native(d, eager_only=True, strict=True) for d in dfs) assert len(dfs) == len(all_rows) - for df, rows, cols in zip(dfs, all_rows, all_cols): + for df, rows, cols in zip(nw_dfs, all_rows, all_cols): assert len(df) == rows assert set(cols).issubset(set(df.columns)) @@ -166,10 +171,13 @@ def test_transformed_data_exclude(to_reconstruct): # then what might have been originally used. See # https://github.com/hex-inc/vegafusion/issues/354 for more info. chart = alt.Chart.from_dict(chart.to_dict()) + assert isinstance(chart, alt.LayerChart) datasets = chart.transformed_data(exclude=["some_annotation"]) - assert len(datasets) == 2 - assert len(datasets[0]) == 52 - assert "wheat_start" in datasets[0] - assert len(datasets[1]) == 1 - assert "mean_wheat" in datasets[1] + _datasets = [nw.from_native(d, eager_only=True, strict=True) for d in datasets] + assert len(datasets) == len(_datasets) + assert len(_datasets) == 2 + assert len(_datasets[0]) == 52 + assert "wheat_start" in _datasets[0] + assert len(_datasets[1]) == 1 + assert "mean_wheat" in _datasets[1] diff --git a/tests/utils/test_core.py b/tests/utils/test_core.py index 2b74398b0..295e2b38f 100644 --- a/tests/utils/test_core.py +++ b/tests/utils/test_core.py @@ -1,5 +1,8 @@ +from __future__ import annotations + import types from importlib.metadata import version as importlib_version +from typing import Any import numpy as np import pandas as pd @@ -9,14 +12,11 @@ import altair as alt from altair.utils.core import infer_encoding_types, parse_shorthand, update_nested +from tests import skip_requires_pyarrow json_schema_specification = alt.load_schema()["$schema"] json_schema_dict_str = f'{{"$schema": "{json_schema_specification}"}}' -try: - import pyarrow as pa -except ImportError: - pa = None PANDAS_VERSION = Version(importlib_version("pandas")) @@ -70,6 +70,22 @@ class StrokeWidthValue(ValueChannel, schemapi.SchemaBase): ''' +@pytest.fixture(params=[False, True]) +def pd_data(request) -> pd.DataFrame: + data = pd.DataFrame( + { + "x": [1, 2, 3, 4, 5], + "y": ["A", "B", "C", "D", "E"], + "z": pd.date_range("2018-01-01", periods=5, freq="D"), + "t": pd.date_range("2018-01-01", periods=5, freq="D").tz_localize("UTC"), + } + ) + object_dtype = request.param + if object_dtype: + data = data.astype("object") + return data + + @pytest.mark.parametrize( ("value", "expected_type"), [ @@ -84,93 +100,94 @@ def test_infer_dtype(value, expected_type): assert infer_dtype(value, skipna=False) == expected_type -def test_parse_shorthand(): - def check(s, **kwargs): - assert parse_shorthand(s) == kwargs - - check("") - - # Fields alone - check("foobar", field="foobar") - check(r"blah\:(fd ", field=r"blah\:(fd ") - - # Fields with type - check("foobar:quantitative", type="quantitative", field="foobar") - check("foobar:nominal", type="nominal", field="foobar") - check("foobar:ordinal", type="ordinal", field="foobar") - check("foobar:temporal", type="temporal", field="foobar") - check("foobar:geojson", type="geojson", field="foobar") - - check("foobar:Q", type="quantitative", field="foobar") - check("foobar:N", type="nominal", field="foobar") - check("foobar:O", type="ordinal", field="foobar") - check("foobar:T", type="temporal", field="foobar") - check("foobar:G", type="geojson", field="foobar") - - # Fields with aggregate and/or type - check("average(foobar)", field="foobar", aggregate="average") - check("min(foobar):temporal", type="temporal", field="foobar", aggregate="min") - check("sum(foobar):Q", type="quantitative", field="foobar", aggregate="sum") - - # check that invalid arguments are not split-out - check("invalid(blah)", field="invalid(blah)") - check(r"blah\:invalid", field=r"blah\:invalid") - check(r"invalid(blah)\:invalid", field=r"invalid(blah)\:invalid") - - # check parsing in presence of strange characters - check( - r"average(a b\:(c\nd):Q", - aggregate="average", - field=r"a b\:(c\nd", - type="quantitative", - ) - - # special case: count doesn't need an argument - check("count()", aggregate="count", type="quantitative") - check("count():O", aggregate="count", type="ordinal") - - # time units: - check("month(x)", field="x", timeUnit="month", type="temporal") - check("year(foo):O", field="foo", timeUnit="year", type="ordinal") - check("date(date):quantitative", field="date", timeUnit="date", type="quantitative") - check( - "yearmonthdate(field)", field="field", timeUnit="yearmonthdate", type="temporal" - ) +# ruff: noqa: C408 -@pytest.mark.parametrize("object_dtype", [False, True]) -def test_parse_shorthand_with_data(object_dtype): - def check(s, data, **kwargs): - assert parse_shorthand(s, data) == kwargs +@pytest.mark.parametrize( + ("shorthand", "expected"), + [ + ("", {}), + # Fields alone + ("foobar", dict(field="foobar")), + (r"blah\:(fd ", dict(field=r"blah\:(fd ")), + # Fields with type + ("foobar:quantitative", dict(type="quantitative", field="foobar")), + ("foobar:nominal", dict(type="nominal", field="foobar")), + ("foobar:ordinal", dict(type="ordinal", field="foobar")), + ("foobar:temporal", dict(type="temporal", field="foobar")), + ("foobar:geojson", dict(type="geojson", field="foobar")), + ("foobar:Q", dict(type="quantitative", field="foobar")), + ("foobar:N", dict(type="nominal", field="foobar")), + ("foobar:O", dict(type="ordinal", field="foobar")), + ("foobar:T", dict(type="temporal", field="foobar")), + ("foobar:G", dict(type="geojson", field="foobar")), + # Fields with aggregate and/or type + ("average(foobar)", dict(field="foobar", aggregate="average")), + ( + "min(foobar):temporal", + dict(type="temporal", field="foobar", aggregate="min"), + ), + ("sum(foobar):Q", dict(type="quantitative", field="foobar", aggregate="sum")), + # check that invalid arguments are not split-out + ("invalid(blah)", dict(field="invalid(blah)")), + (r"blah\:invalid", dict(field=r"blah\:invalid")), + (r"invalid(blah)\:invalid", dict(field=r"invalid(blah)\:invalid")), + # check parsing in presence of strange characters + ( + r"average(a b\:(c\nd):Q", + dict(aggregate="average", field=r"a b\:(c\nd", type="quantitative"), + ), + # special case: count doesn't need an argument + ("count()", dict(aggregate="count", type="quantitative")), + ("count():O", dict(aggregate="count", type="ordinal")), + # time units: + ("month(x)", dict(field="x", timeUnit="month", type="temporal")), + ("year(foo):O", dict(field="foo", timeUnit="year", type="ordinal")), + ( + "date(date):quantitative", + dict(field="date", timeUnit="date", type="quantitative"), + ), + ( + "yearmonthdate(field)", + dict(field="field", timeUnit="yearmonthdate", type="temporal"), + ), + ], +) +def test_parse_shorthand(shorthand: str, expected: dict[str, Any]) -> None: + assert parse_shorthand(shorthand) == expected - data = pd.DataFrame( - { - "x": [1, 2, 3, 4, 5], - "y": ["A", "B", "C", "D", "E"], - "z": pd.date_range("2018-01-01", periods=5, freq="D"), - "t": pd.date_range("2018-01-01", periods=5, freq="D").tz_localize("UTC"), - } - ) - if object_dtype: - data = data.astype("object") +@pytest.mark.parametrize( + ("shorthand", "expected"), + [ + ("x", dict(field="x", type="quantitative")), + ("y", dict(field="y", type="nominal")), + ("z", dict(field="z", type="temporal")), + ("t", dict(field="t", type="temporal")), + ("count(x)", dict(field="x", aggregate="count", type="quantitative")), + ("count()", dict(aggregate="count", type="quantitative")), + ("month(z)", dict(timeUnit="month", field="z", type="temporal")), + ("month(t)", dict(timeUnit="month", field="t", type="temporal")), + ], +) +def test_parse_shorthand_with_data( + pd_data, shorthand: str, expected: dict[str, Any] +) -> None: + assert parse_shorthand(shorthand, pd_data) == expected - check("x", data, field="x", type="quantitative") - check("y", data, field="y", type="nominal") - check("z", data, field="z", type="temporal") - check("t", data, field="t", type="temporal") - check("count(x)", data, field="x", aggregate="count", type="quantitative") - check("count()", data, aggregate="count", type="quantitative") - check("month(z)", data, timeUnit="month", field="z", type="temporal") - check("month(t)", data, timeUnit="month", field="t", type="temporal") - if Version("1.0.0") <= PANDAS_VERSION: - data["b"] = pd.Series([True, False, True, False, None], dtype="boolean") - check("b", data, field="b", type="nominal") +@pytest.mark.skipif(Version("1.0.0") > PANDAS_VERSION, reason="dtype unavailable") +def test_parse_shorthand_with_data_pandas_v1(pd_data) -> None: + pd_data["b"] = pd.Series([True, False, True, False, None], dtype="boolean") + shorthand = "b" + expected = dict(field="b", type="nominal") + assert parse_shorthand(shorthand, pd_data) == expected -@pytest.mark.skipif(pa is None, reason="pyarrow not installed") +@skip_requires_pyarrow def test_parse_shorthand_for_arrow_timestamp(): + import pyarrow as pa + data = pd.DataFrame( { "z": pd.date_range("2018-01-01", periods=5, freq="D"), diff --git a/tests/utils/test_server.py b/tests/utils/test_server.py index cf5a0f364..b2b775e03 100644 --- a/tests/utils/test_server.py +++ b/tests/utils/test_server.py @@ -1,8 +1,10 @@ """Test http server.""" from altair.utils.server import MockServer, serve +from tests import slow +@slow def test_serve(): html = "Title

Content

" serve(html, open_browser=False, http_server=MockServer) diff --git a/tests/utils/test_to_values_narwhals.py b/tests/utils/test_to_values_narwhals.py index 1a96c6775..ac9fd9ed1 100644 --- a/tests/utils/test_to_values_narwhals.py +++ b/tests/utils/test_to_values_narwhals.py @@ -6,12 +6,8 @@ import pandas as pd import pytest -try: - import pyarrow as pa -except ImportError: - pa = None - from altair.utils.data import to_values +from tests import skip_requires_pyarrow def windows_has_tzdata(): @@ -30,9 +26,11 @@ def windows_has_tzdata(): sys.platform == "win32" and not windows_has_tzdata(), reason="Timezone database is not installed on Windows", ) -@pytest.mark.skipif(pa is None, reason="pyarrow not installed") +@skip_requires_pyarrow def test_arrow_timestamp_conversion(): """Test that arrow timestamp values are converted to ISO-8601 strings.""" + import pyarrow as pa + data = { "date": [datetime(2004, 8, 1), datetime(2004, 9, 1), None], "value": [102, 129, 139], @@ -51,8 +49,10 @@ def test_arrow_timestamp_conversion(): assert values == expected_values -@pytest.mark.skipif(pa is None, reason="pyarrow not installed") +@skip_requires_pyarrow def test_duration_raises(): + import pyarrow as pa + td = pd.timedelta_range(0, periods=3, freq="h") df = pd.DataFrame(td).reset_index() df.columns = ["id", "timedelta"] diff --git a/tests/utils/test_utils.py b/tests/utils/test_utils.py index 0e22ec7e9..f83f76528 100644 --- a/tests/utils/test_utils.py +++ b/tests/utils/test_utils.py @@ -1,7 +1,6 @@ import io import json import sys -import warnings import narwhals.stable.v1 as nw import numpy as np @@ -13,11 +12,7 @@ sanitize_narwhals_dataframe, sanitize_pandas_dataframe, ) - -try: - import pyarrow as pa -except ImportError: - pa = None +from tests import skip_requires_pyarrow def test_infer_vegalite_type(): @@ -36,13 +31,8 @@ def _check(arr, typ): _check(nulled, "quantitative") _check(["a", "b", "c"], "nominal") - if hasattr(pytest, "warns"): # added in pytest 2.8 - with pytest.warns(UserWarning): - _check([], "nominal") - else: - with warnings.catch_warnings(): - warnings.filterwarnings("ignore") - _check([], "nominal") + with pytest.warns(UserWarning): + _check([], "nominal") def test_sanitize_dataframe(): @@ -97,8 +87,10 @@ def test_sanitize_dataframe(): @pytest.mark.filterwarnings("ignore:'H' is deprecated.*:FutureWarning") -@pytest.mark.skipif(pa is None, reason="pyarrow not installed") +@skip_requires_pyarrow def test_sanitize_dataframe_arrow_columns(): + import pyarrow as pa + # create a dataframe with various types df = pd.DataFrame( { @@ -128,11 +120,13 @@ def test_sanitize_dataframe_arrow_columns(): json.dumps(records) -@pytest.mark.skipif(pa is None, reason="pyarrow not installed") +@skip_requires_pyarrow @pytest.mark.xfail( sys.platform == "win32", reason="Timezone database is not installed on Windows" ) def test_sanitize_pyarrow_table_columns() -> None: + import pyarrow as pa + # create a dataframe with various types df = pd.DataFrame( { @@ -187,16 +181,14 @@ def test_sanitize_dataframe_colnames(): # Test that non-string columns result in an error df.columns = [4, "foo", "bar"] - with pytest.raises(ValueError) as err: # noqa: PT011 + with pytest.raises(ValueError, match="Dataframe contains invalid column name: 4."): sanitize_pandas_dataframe(df) - assert str(err.value).startswith("Dataframe contains invalid column name: 4.") def test_sanitize_dataframe_timedelta(): df = pd.DataFrame({"r": pd.timedelta_range(start="1 day", periods=4)}) - with pytest.raises(ValueError) as err: # noqa: PT011 + with pytest.raises(ValueError, match='Field "r" has type "timedelta'): sanitize_pandas_dataframe(df) - assert str(err.value).startswith('Field "r" has type "timedelta') def test_sanitize_dataframe_infs(): diff --git a/tests/vegalite/v5/test_api.py b/tests/vegalite/v5/test_api.py index 241d47378..4f54034d6 100644 --- a/tests/vegalite/v5/test_api.py +++ b/tests/vegalite/v5/test_api.py @@ -23,6 +23,7 @@ import altair as alt from altair.utils.schemapi import Optional, Undefined +from tests import skip_requires_vl_convert, slow try: import vl_convert as vlc @@ -807,11 +808,9 @@ def test_save(format, engine, basic_chart): pathlib.Path(fp).unlink() -@pytest.mark.parametrize("inline", [False, True]) +@pytest.mark.parametrize("inline", [False, pytest.param(True, marks=slow)]) +@skip_requires_vl_convert def test_save_html(basic_chart, inline): - if vlc is None: - pytest.skip("vl_convert not importable; cannot run this test") - out = io.StringIO() basic_chart.save(out, format="html", inline=inline) out.seek(0) @@ -827,10 +826,8 @@ def test_save_html(basic_chart, inline): assert 'src="https://cdn.jsdelivr.net/npm/vega-embed@6' in content +@skip_requires_vl_convert def test_to_url(basic_chart): - if vlc is None: - pytest.skip("vl_convert is not installed") - share_url = basic_chart.to_url() assert share_url.startswith("https://vega.github.io/editor/#/url/vega-lite/") From 98d9fb866c4d3b59ca88493472aca291170a0f5e Mon Sep 17 00:00:00 2001 From: Dan Redding <125183946+dangotbanned@users.noreply.github.com> Date: Sat, 31 Aug 2024 14:28:09 +0100 Subject: [PATCH 6/7] refactor: Reduce `SchemaValidationError` traceback length (#3530) --- altair/utils/schemapi.py | 213 +++++++++++++++++++++---------------- altair/vegalite/v5/api.py | 165 ++++++++++++++-------------- tools/schemapi/schemapi.py | 213 +++++++++++++++++++++---------------- 3 files changed, 324 insertions(+), 267 deletions(-) diff --git a/altair/utils/schemapi.py b/altair/utils/schemapi.py index bc0b40581..84f5be277 100644 --- a/altair/utils/schemapi.py +++ b/altair/utils/schemapi.py @@ -42,6 +42,7 @@ from altair import vegalite if TYPE_CHECKING: + from types import ModuleType from typing import ClassVar from referencing import Registry @@ -57,6 +58,7 @@ from typing import Never, Self else: from typing_extensions import Never, Self + _OptionalModule: TypeAlias = "ModuleType | None" ValidationErrorList: TypeAlias = List[jsonschema.exceptions.ValidationError] GroupedValidationErrors: TypeAlias = Dict[str, ValidationErrorList] @@ -559,9 +561,25 @@ def _resolve_references( class SchemaValidationError(jsonschema.ValidationError): - """A wrapper for jsonschema.ValidationError with friendlier traceback.""" - def __init__(self, obj: SchemaBase, err: jsonschema.ValidationError) -> None: + """ + A wrapper for ``jsonschema.ValidationError`` with friendlier traceback. + + Parameters + ---------- + obj + The instance that failed ``self.validate(...)``. + err + The original ``ValidationError``. + + Notes + ----- + We do not raise `from err` as else the resulting traceback is very long + as it contains part of the Vega-Lite schema. + + It would also first show the less helpful `ValidationError` instead of + the more user friendly `SchemaValidationError`. + """ super().__init__(**err._contents()) self.obj = obj self._errors: GroupedValidationErrors = getattr( @@ -991,88 +1009,45 @@ def to_dict( Parameters ---------- validate : bool, optional - If True (default), then validate the output dictionary - against the schema. + If True (default), then validate the result against the schema. ignore : list[str], optional - A list of keys to ignore. It is usually not needed - to specify this argument as a user. + A list of keys to ignore. context : dict[str, Any], optional - A context dictionary. It is usually not needed - to specify this argument as a user. - - Notes - ----- - Technical: The ignore parameter will *not* be passed to child to_dict - function calls. - - Returns - ------- - dict - The dictionary representation of this object + A context dictionary. Raises ------ SchemaValidationError : - if validate=True and the dict does not conform to the schema + If ``validate`` and the result does not conform to the schema. + + Notes + ----- + - ``ignore``, ``context`` are usually not needed to be specified as a user. + - *Technical*: ``ignore`` will **not** be passed to child :meth:`.to_dict()`. """ - if context is None: - context = {} - if ignore is None: - ignore = [] - # The following return the package only if it has already been - # imported - otherwise they return None. This is useful for - # isinstance checks - for example, if pandas has not been imported, - # then an object is definitely not a `pandas.Timestamp`. - pd_opt = sys.modules.get("pandas") - np_opt = sys.modules.get("numpy") + context = context or {} + ignore = ignore or [] + opts = _get_optional_modules(np_opt="numpy", pd_opt="pandas") if self._args and not self._kwds: - result = _todict( - self._args[0], context=context, np_opt=np_opt, pd_opt=pd_opt - ) + kwds = self._args[0] elif not self._args: kwds = self._kwds.copy() - # parsed_shorthand is added by FieldChannelMixin. - # It's used below to replace shorthand with its long form equivalent - # parsed_shorthand is removed from context if it exists so that it is - # not passed to child to_dict function calls - parsed_shorthand = context.pop("parsed_shorthand", {}) - # Prevent that pandas categorical data is automatically sorted - # when a non-ordinal data type is specifed manually - # or if the encoding channel does not support sorting - if "sort" in parsed_shorthand and ( - "sort" not in kwds or kwds["type"] not in {"ordinal", Undefined} - ): - parsed_shorthand.pop("sort") - - kwds.update( - { - k: v - for k, v in parsed_shorthand.items() - if kwds.get(k, Undefined) is Undefined - } - ) - kwds = { - k: v for k, v in kwds.items() if k not in {*list(ignore), "shorthand"} - } - if "mark" in kwds and isinstance(kwds["mark"], str): - kwds["mark"] = {"type": kwds["mark"]} - result = _todict(kwds, context=context, np_opt=np_opt, pd_opt=pd_opt) + exclude = {*ignore, "shorthand"} + if parsed := context.pop("parsed_shorthand", None): + kwds = _replace_parsed_shorthand(parsed, kwds) + kwds = {k: v for k, v in kwds.items() if k not in exclude} + if (mark := kwds.get("mark")) and isinstance(mark, str): + kwds["mark"] = {"type": mark} else: - msg = ( - f"{self.__class__} instance has both a value and properties : " - "cannot serialize to dict" - ) + msg = f"{type(self)} instance has both a value and properties : cannot serialize to dict" raise ValueError(msg) + result = _todict(kwds, context=context, **opts) if validate: + # NOTE: Don't raise `from err`, see `SchemaValidationError` doc try: self.validate(result) except jsonschema.ValidationError as err: - # We do not raise `from err` as else the resulting - # traceback is very long as it contains part - # of the Vega-Lite schema. It would also first - # show the less helpful ValidationError instead of - # the more user friendly SchemaValidationError raise SchemaValidationError(self, err) from None return result @@ -1092,30 +1067,27 @@ def to_json( Parameters ---------- validate : bool, optional - If True (default), then validate the output dictionary - against the schema. + If True (default), then validate the result against the schema. indent : int, optional The number of spaces of indentation to use. The default is 2. sort_keys : bool, optional If True (default), sort keys in the output. ignore : list[str], optional - A list of keys to ignore. It is usually not needed - to specify this argument as a user. + A list of keys to ignore. context : dict[str, Any], optional - A context dictionary. It is usually not needed - to specify this argument as a user. + A context dictionary. **kwargs Additional keyword arguments are passed to ``json.dumps()`` + Raises + ------ + SchemaValidationError : + If ``validate`` and the result does not conform to the schema. + Notes ----- - Technical: The ignore parameter will *not* be passed to child to_dict - function calls. - - Returns - ------- - str - The JSON specification of the chart object. + - ``ignore``, ``context`` are usually not needed to be specified as a user. + - *Technical*: ``ignore`` will **not** be passed to child :meth:`.to_dict()`. """ if ignore is None: ignore = [] @@ -1143,15 +1115,10 @@ def from_dict( validate : boolean If True (default), then validate the input against the schema. - Returns - ------- - obj : Schema object - The wrapped schema - Raises ------ jsonschema.ValidationError : - if validate=True and dct does not conform to the schema + If ``validate`` and ``dct`` does not conform to the schema """ if validate: cls.validate(dct) @@ -1214,13 +1181,8 @@ def validate_property( cls, name: str, value: Any, schema: dict[str, Any] | None = None ) -> None: """Validate a property against property schema in the context of the rootschema.""" - # The following return the package only if it has already been - # imported - otherwise they return None. This is useful for - # isinstance checks - for example, if pandas has not been imported, - # then an object is definitely not a `pandas.Timestamp`. - pd_opt = sys.modules.get("pandas") - np_opt = sys.modules.get("numpy") - value = _todict(value, context={}, np_opt=np_opt, pd_opt=pd_opt) + opts = _get_optional_modules(np_opt="numpy", pd_opt="pandas") + value = _todict(value, context={}, **opts) props = cls.resolve_references(schema or cls._schema).get("properties", {}) validate_jsonschema( value, props.get(name, {}), rootschema=cls._rootschema or cls._schema @@ -1230,6 +1192,71 @@ def __dir__(self) -> list[str]: return sorted(chain(super().__dir__(), self._kwds)) +def _get_optional_modules(**modules: str) -> dict[str, _OptionalModule]: + """ + Returns packages only if they have already been imported - otherwise they return `None`. + + This is useful for `isinstance` checks. + + For example, if `pandas` has not been imported, then an object is + definitely not a `pandas.Timestamp`. + + Parameters + ---------- + **modules + Keyword-only binding from `{alias: module_name}`. + + Examples + -------- + >>> import pandas as pd # doctest: +SKIP + >>> import polars as pl # doctest: +SKIP + >>> from altair.utils.schemapi import _get_optional_modules # doctest: +SKIP + >>> + >>> _get_optional_modules(pd="pandas", pl="polars", ibis="ibis") # doctest: +SKIP + { + "pd": , + "pl": , + "ibis": None, + } + + If the user later imports ``ibis``, it would appear in subsequent calls. + + >>> import ibis # doctest: +SKIP + >>> + >>> _get_optional_modules(ibis="ibis") # doctest: +SKIP + { + "ibis": , + } + """ + return {k: sys.modules.get(v) for k, v in modules.items()} + + +def _replace_parsed_shorthand( + parsed_shorthand: dict[str, Any], kwds: dict[str, Any] +) -> dict[str, Any]: + """ + `parsed_shorthand` is added by `FieldChannelMixin`. + + It's used below to replace shorthand with its long form equivalent + `parsed_shorthand` is removed from `context` if it exists so that it is + not passed to child `to_dict` function calls. + """ + # Prevent that pandas categorical data is automatically sorted + # when a non-ordinal data type is specifed manually + # or if the encoding channel does not support sorting + if "sort" in parsed_shorthand and ( + "sort" not in kwds or kwds["type"] not in {"ordinal", Undefined} + ): + parsed_shorthand.pop("sort") + + kwds.update( + (k, v) + for k, v in parsed_shorthand.items() + if kwds.get(k, Undefined) is Undefined + ) + return kwds + + TSchemaBase = TypeVar("TSchemaBase", bound=SchemaBase) _CopyImpl = TypeVar("_CopyImpl", SchemaBase, Dict[Any, Any], List[Any]) diff --git a/altair/vegalite/v5/api.py b/altair/vegalite/v5/api.py index 4e8fde039..9ef5659ba 100644 --- a/altair/vegalite/v5/api.py +++ b/altair/vegalite/v5/api.py @@ -27,7 +27,7 @@ from altair import utils from altair.expr import core as _expr_core -from altair.utils import Optional, Undefined +from altair.utils import Optional, SchemaBase, Undefined from altair.utils._vegafusion_data import ( compile_with_vegafusion as _compile_with_vegafusion, ) @@ -125,7 +125,6 @@ ProjectionType, RepeatMapping, RepeatRef, - SchemaBase, SelectionParameter, SequenceGenerator, SortField, @@ -194,7 +193,7 @@ ] ChartDataType: TypeAlias = Optional[Union[DataType, core.Data, str, core.Generator]] -_TSchemaBase = TypeVar("_TSchemaBase", bound=core.SchemaBase) +_TSchemaBase = TypeVar("_TSchemaBase", bound=SchemaBase) # ------------------------------------------------------------------------ @@ -509,7 +508,7 @@ def check_fields_and_encodings(parameter: Parameter, field_name: str) -> bool: ] """Permitted types for `&` reduced predicates.""" -_StatementType: TypeAlias = Union[core.SchemaBase, Map, str] +_StatementType: TypeAlias = Union[SchemaBase, Map, str] """Permitted types for `if_true`/`if_false`. In python terms: @@ -532,7 +531,7 @@ def check_fields_and_encodings(parameter: Parameter, field_name: str) -> bool: _LiteralValue: TypeAlias = Union[str, bool, float, int] """Primitive python value types.""" -_FieldEqualType: TypeAlias = Union[_LiteralValue, Map, Parameter, core.SchemaBase] +_FieldEqualType: TypeAlias = Union[_LiteralValue, Map, Parameter, SchemaBase] """Permitted types for equality checks on field values: - `datum.field == ...` @@ -586,7 +585,7 @@ def _condition_to_selection( **kwargs: Any, ) -> SchemaBase | dict[str, _ConditionType | Any]: selection: SchemaBase | dict[str, _ConditionType | Any] - if isinstance(if_true, core.SchemaBase): + if isinstance(if_true, SchemaBase): if_true = if_true.to_dict() elif isinstance(if_true, str): if isinstance(if_false, str): @@ -600,7 +599,7 @@ def _condition_to_selection( if_true = utils.parse_shorthand(if_true) if_true.update(kwargs) condition.update(if_true) - if isinstance(if_false, core.SchemaBase): + if isinstance(if_false, SchemaBase): # For the selection, the channel definitions all allow selections # already. So use this SchemaBase wrapper if possible. selection = if_false.copy() @@ -662,8 +661,8 @@ def _reveal_parsed_shorthand(obj: Map, /) -> dict[str, Any]: def _is_extra(*objs: Any, kwds: Map) -> Iterator[bool]: for el in objs: - if isinstance(el, (core.SchemaBase, t.Mapping)): - item = el.to_dict(validate=False) if isinstance(el, core.SchemaBase) else el + if isinstance(el, (SchemaBase, t.Mapping)): + item = el.to_dict(validate=False) if isinstance(el, SchemaBase) else el yield not (item.keys() - kwds.keys()).isdisjoint(utils.SHORTHAND_KEYS) else: continue @@ -774,7 +773,7 @@ def _parse_literal(val: Any, /) -> dict[str, Any]: def _parse_then(statement: _StatementType, kwds: dict[str, Any], /) -> dict[str, Any]: - if isinstance(statement, core.SchemaBase): + if isinstance(statement, SchemaBase): statement = statement.to_dict() elif not isinstance(statement, dict): statement = _parse_literal(statement) @@ -786,7 +785,7 @@ def _parse_otherwise( statement: _StatementType, conditions: _Conditional[Any], kwds: dict[str, Any], / ) -> SchemaBase | _Conditional[Any]: selection: SchemaBase | _Conditional[Any] - if isinstance(statement, core.SchemaBase): + if isinstance(statement, SchemaBase): selection = statement.copy() conditions.update(**kwds) # type: ignore[call-arg] selection.condition = conditions["condition"] @@ -879,7 +878,7 @@ def then(self, statement: _StatementType, /, **kwds: Any) -> Then[Any]: return Then(_Conditional(condition=[condition])) -class Then(core.SchemaBase, t.Generic[_C]): +class Then(SchemaBase, t.Generic[_C]): """ Utility class for ``when-then-otherwise`` conditions. @@ -1716,12 +1715,29 @@ def _top_schema_base( # noqa: ANN202 """ Enforces an intersection type w/ `SchemaBase` & `TopLevelMixin` objects. - Use for instance methods. + Use for methods, called from `TopLevelMixin` that are defined in `SchemaBase`. + + Notes + ----- + - The `super` sub-branch is not statically checked *here*. + - It would widen the inferred intersection to: + - `( | super)` + - Both dunder attributes are not in the `super` type stubs + - Requiring 2x *# type: ignore[attr-defined]* + - However it is required at runtime for any cases that use `super(..., copy)`. + - The inferred type **is** used statically **outside** of this function. """ - if isinstance(obj, core.SchemaBase) and isinstance(obj, TopLevelMixin): + if (isinstance(obj, SchemaBase) and isinstance(obj, TopLevelMixin)) or ( + not TYPE_CHECKING + and ( + isinstance(obj, super) + and issubclass(obj.__self_class__, SchemaBase) + and obj.__thisclass__ is TopLevelMixin + ) + ): return obj else: - msg = f"{type(obj).__name__!r} does not derive from {type(core.SchemaBase).__name__!r}" + msg = f"{type(obj).__name__!r} does not derive from {SchemaBase.__name__!r}" raise TypeError(msg) @@ -1735,7 +1751,7 @@ def to_dict( # noqa: C901 self, validate: bool = True, *, - format: str = "vega-lite", + format: Literal["vega-lite", "vega"] = "vega-lite", ignore: list[str] | None = None, context: dict[str, Any] | None = None, ) -> dict[str, Any]: @@ -1745,31 +1761,25 @@ def to_dict( # noqa: C901 Parameters ---------- validate : bool, optional - If True (default), then validate the output dictionary - against the schema. - format : str, optional - Chart specification format, one of "vega-lite" (default) or "vega" + If True (default), then validate the result against the schema. + format : {"vega-lite", "vega"}, optional + The chart specification format. + The `"vega"` format relies on the active Vega-Lite compiler plugin, which + by default requires the vl-convert-python package. ignore : list[str], optional - A list of keys to ignore. It is usually not needed - to specify this argument as a user. + A list of keys to ignore. context : dict[str, Any], optional - A context dictionary. It is usually not needed - to specify this argument as a user. - - Notes - ----- - Technical: The ignore parameter will *not* be passed to child to_dict - function calls. - - Returns - ------- - dict - The dictionary representation of this chart + A context dictionary. Raises ------ - SchemaValidationError - if validate=True and the dict does not conform to the schema + SchemaValidationError : + If ``validate`` and the result does not conform to the schema. + + Notes + ----- + - ``ignore``, ``context`` are usually not needed to be specified as a user. + - *Technical*: ``ignore`` will **not** be passed to child :meth:`.to_dict()`. """ # Validate format if format not in {"vega-lite", "vega"}: @@ -1807,10 +1817,7 @@ def to_dict( # noqa: C901 # remaining to_dict calls are not at top level context["top_level"] = False - # TopLevelMixin instance does not necessarily have to_dict defined - # but due to how Altair is set up this should hold. - # Too complex to type hint right now - vegalite_spec: Any = super(TopLevelMixin, copy).to_dict( # type: ignore[misc] + vegalite_spec: Any = _top_schema_base(super(TopLevelMixin, copy)).to_dict( validate=validate, ignore=ignore, context=dict(context, pre_transform=False) ) @@ -1862,7 +1869,7 @@ def to_json( indent: int | str | None = 2, sort_keys: bool = True, *, - format: str = "vega-lite", + format: Literal["vega-lite", "vega"] = "vega-lite", ignore: list[str] | None = None, context: dict[str, Any] | None = None, **kwargs: Any, @@ -1873,24 +1880,31 @@ def to_json( Parameters ---------- validate : bool, optional - If True (default), then validate the output dictionary - against the schema. + If True (default), then validate the result against the schema. indent : int, optional The number of spaces of indentation to use. The default is 2. sort_keys : bool, optional If True (default), sort keys in the output. - format : str, optional - The chart specification format. One of "vega-lite" (default) or "vega". - The "vega" format relies on the active Vega-Lite compiler plugin, which + format : {"vega-lite", "vega"}, optional + The chart specification format. + The `"vega"` format relies on the active Vega-Lite compiler plugin, which by default requires the vl-convert-python package. ignore : list[str], optional - A list of keys to ignore. It is usually not needed - to specify this argument as a user. + A list of keys to ignore. context : dict[str, Any], optional - A context dictionary. It is usually not needed - to specify this argument as a user. + A context dictionary. **kwargs Additional keyword arguments are passed to ``json.dumps()`` + + Raises + ------ + SchemaValidationError : + If ``validate`` and the result does not conform to the schema. + + Notes + ----- + - ``ignore``, ``context`` are usually not needed to be specified as a user. + - *Technical*: ``ignore`` will **not** be passed to child :meth:`.to_dict()`. """ if ignore is None: ignore = [] @@ -3697,24 +3711,19 @@ def from_dict( cls: type[_TSchemaBase], dct: dict[str, Any], validate: bool = True ) -> _TSchemaBase: """ - Construct class from a dictionary representation. + Construct a ``Chart`` from a dictionary representation. Parameters ---------- dct : dictionary - The dict from which to construct the class + The dict from which to construct the ``Chart``. validate : boolean If True (default), then validate the input against the schema. - Returns - ------- - obj : Chart object - The wrapped schema - Raises ------ jsonschema.ValidationError : - if validate=True and dct does not conform to the schema + If ``validate`` and ``dct`` does not conform to the schema """ _tp: Any for tp in TopLevelMixin.__subclasses__(): @@ -3731,41 +3740,35 @@ def to_dict( self, validate: bool = True, *, - format: str = "vega-lite", + format: Literal["vega-lite", "vega"] = "vega-lite", ignore: list[str] | None = None, context: dict[str, Any] | None = None, ) -> dict[str, Any]: """ - Convert the chart to a dictionary suitable for JSON export. + Convert the ``Chart`` to a dictionary suitable for JSON export. Parameters ---------- validate : bool, optional - If True (default), then validate the output dictionary - against the schema. - format : str, optional - Chart specification format, one of "vega-lite" (default) or "vega" + If True (default), then validate the result against the schema. + format : {"vega-lite", "vega"}, optional + The chart specification format. + The `"vega"` format relies on the active Vega-Lite compiler plugin, which + by default requires the vl-convert-python package. ignore : list[str], optional - A list of keys to ignore. It is usually not needed - to specify this argument as a user. + A list of keys to ignore. context : dict[str, Any], optional - A context dictionary. It is usually not needed - to specify this argument as a user. - - Notes - ----- - Technical: The ignore parameter will *not* be passed to child to_dict - function calls. - - Returns - ------- - dict - The dictionary representation of this chart + A context dictionary. Raises ------ - SchemaValidationError - if validate=True and the dict does not conform to the schema + SchemaValidationError : + If ``validate`` and the result does not conform to the schema. + + Notes + ----- + - ``ignore``, ``context`` are usually not needed to be specified as a user. + - *Technical*: ``ignore`` will **not** be passed to child :meth:`.to_dict()`. """ context = context or {} kwds: Map = {"validate": validate, "format": format, "ignore": ignore, "context": context} # fmt: skip @@ -3861,7 +3864,7 @@ def _check_if_valid_subspec( ], ) -> None: """Raise a `TypeError` if `spec` is not a valid sub-spec.""" - if not isinstance(spec, core.SchemaBase): + if not isinstance(spec, SchemaBase): msg = f"Only chart objects can be used in {classname}." raise TypeError(msg) for attr in TOPLEVEL_ONLY_KEYS: diff --git a/tools/schemapi/schemapi.py b/tools/schemapi/schemapi.py index 9d21ab793..5140073ad 100644 --- a/tools/schemapi/schemapi.py +++ b/tools/schemapi/schemapi.py @@ -40,6 +40,7 @@ from altair import vegalite if TYPE_CHECKING: + from types import ModuleType from typing import ClassVar from referencing import Registry @@ -55,6 +56,7 @@ from typing import Never, Self else: from typing_extensions import Never, Self + _OptionalModule: TypeAlias = "ModuleType | None" ValidationErrorList: TypeAlias = List[jsonschema.exceptions.ValidationError] GroupedValidationErrors: TypeAlias = Dict[str, ValidationErrorList] @@ -557,9 +559,25 @@ def _resolve_references( class SchemaValidationError(jsonschema.ValidationError): - """A wrapper for jsonschema.ValidationError with friendlier traceback.""" - def __init__(self, obj: SchemaBase, err: jsonschema.ValidationError) -> None: + """ + A wrapper for ``jsonschema.ValidationError`` with friendlier traceback. + + Parameters + ---------- + obj + The instance that failed ``self.validate(...)``. + err + The original ``ValidationError``. + + Notes + ----- + We do not raise `from err` as else the resulting traceback is very long + as it contains part of the Vega-Lite schema. + + It would also first show the less helpful `ValidationError` instead of + the more user friendly `SchemaValidationError`. + """ super().__init__(**err._contents()) self.obj = obj self._errors: GroupedValidationErrors = getattr( @@ -989,88 +1007,45 @@ def to_dict( Parameters ---------- validate : bool, optional - If True (default), then validate the output dictionary - against the schema. + If True (default), then validate the result against the schema. ignore : list[str], optional - A list of keys to ignore. It is usually not needed - to specify this argument as a user. + A list of keys to ignore. context : dict[str, Any], optional - A context dictionary. It is usually not needed - to specify this argument as a user. - - Notes - ----- - Technical: The ignore parameter will *not* be passed to child to_dict - function calls. - - Returns - ------- - dict - The dictionary representation of this object + A context dictionary. Raises ------ SchemaValidationError : - if validate=True and the dict does not conform to the schema + If ``validate`` and the result does not conform to the schema. + + Notes + ----- + - ``ignore``, ``context`` are usually not needed to be specified as a user. + - *Technical*: ``ignore`` will **not** be passed to child :meth:`.to_dict()`. """ - if context is None: - context = {} - if ignore is None: - ignore = [] - # The following return the package only if it has already been - # imported - otherwise they return None. This is useful for - # isinstance checks - for example, if pandas has not been imported, - # then an object is definitely not a `pandas.Timestamp`. - pd_opt = sys.modules.get("pandas") - np_opt = sys.modules.get("numpy") + context = context or {} + ignore = ignore or [] + opts = _get_optional_modules(np_opt="numpy", pd_opt="pandas") if self._args and not self._kwds: - result = _todict( - self._args[0], context=context, np_opt=np_opt, pd_opt=pd_opt - ) + kwds = self._args[0] elif not self._args: kwds = self._kwds.copy() - # parsed_shorthand is added by FieldChannelMixin. - # It's used below to replace shorthand with its long form equivalent - # parsed_shorthand is removed from context if it exists so that it is - # not passed to child to_dict function calls - parsed_shorthand = context.pop("parsed_shorthand", {}) - # Prevent that pandas categorical data is automatically sorted - # when a non-ordinal data type is specifed manually - # or if the encoding channel does not support sorting - if "sort" in parsed_shorthand and ( - "sort" not in kwds or kwds["type"] not in {"ordinal", Undefined} - ): - parsed_shorthand.pop("sort") - - kwds.update( - { - k: v - for k, v in parsed_shorthand.items() - if kwds.get(k, Undefined) is Undefined - } - ) - kwds = { - k: v for k, v in kwds.items() if k not in {*list(ignore), "shorthand"} - } - if "mark" in kwds and isinstance(kwds["mark"], str): - kwds["mark"] = {"type": kwds["mark"]} - result = _todict(kwds, context=context, np_opt=np_opt, pd_opt=pd_opt) + exclude = {*ignore, "shorthand"} + if parsed := context.pop("parsed_shorthand", None): + kwds = _replace_parsed_shorthand(parsed, kwds) + kwds = {k: v for k, v in kwds.items() if k not in exclude} + if (mark := kwds.get("mark")) and isinstance(mark, str): + kwds["mark"] = {"type": mark} else: - msg = ( - f"{self.__class__} instance has both a value and properties : " - "cannot serialize to dict" - ) + msg = f"{type(self)} instance has both a value and properties : cannot serialize to dict" raise ValueError(msg) + result = _todict(kwds, context=context, **opts) if validate: + # NOTE: Don't raise `from err`, see `SchemaValidationError` doc try: self.validate(result) except jsonschema.ValidationError as err: - # We do not raise `from err` as else the resulting - # traceback is very long as it contains part - # of the Vega-Lite schema. It would also first - # show the less helpful ValidationError instead of - # the more user friendly SchemaValidationError raise SchemaValidationError(self, err) from None return result @@ -1090,30 +1065,27 @@ def to_json( Parameters ---------- validate : bool, optional - If True (default), then validate the output dictionary - against the schema. + If True (default), then validate the result against the schema. indent : int, optional The number of spaces of indentation to use. The default is 2. sort_keys : bool, optional If True (default), sort keys in the output. ignore : list[str], optional - A list of keys to ignore. It is usually not needed - to specify this argument as a user. + A list of keys to ignore. context : dict[str, Any], optional - A context dictionary. It is usually not needed - to specify this argument as a user. + A context dictionary. **kwargs Additional keyword arguments are passed to ``json.dumps()`` + Raises + ------ + SchemaValidationError : + If ``validate`` and the result does not conform to the schema. + Notes ----- - Technical: The ignore parameter will *not* be passed to child to_dict - function calls. - - Returns - ------- - str - The JSON specification of the chart object. + - ``ignore``, ``context`` are usually not needed to be specified as a user. + - *Technical*: ``ignore`` will **not** be passed to child :meth:`.to_dict()`. """ if ignore is None: ignore = [] @@ -1141,15 +1113,10 @@ def from_dict( validate : boolean If True (default), then validate the input against the schema. - Returns - ------- - obj : Schema object - The wrapped schema - Raises ------ jsonschema.ValidationError : - if validate=True and dct does not conform to the schema + If ``validate`` and ``dct`` does not conform to the schema """ if validate: cls.validate(dct) @@ -1212,13 +1179,8 @@ def validate_property( cls, name: str, value: Any, schema: dict[str, Any] | None = None ) -> None: """Validate a property against property schema in the context of the rootschema.""" - # The following return the package only if it has already been - # imported - otherwise they return None. This is useful for - # isinstance checks - for example, if pandas has not been imported, - # then an object is definitely not a `pandas.Timestamp`. - pd_opt = sys.modules.get("pandas") - np_opt = sys.modules.get("numpy") - value = _todict(value, context={}, np_opt=np_opt, pd_opt=pd_opt) + opts = _get_optional_modules(np_opt="numpy", pd_opt="pandas") + value = _todict(value, context={}, **opts) props = cls.resolve_references(schema or cls._schema).get("properties", {}) validate_jsonschema( value, props.get(name, {}), rootschema=cls._rootschema or cls._schema @@ -1228,6 +1190,71 @@ def __dir__(self) -> list[str]: return sorted(chain(super().__dir__(), self._kwds)) +def _get_optional_modules(**modules: str) -> dict[str, _OptionalModule]: + """ + Returns packages only if they have already been imported - otherwise they return `None`. + + This is useful for `isinstance` checks. + + For example, if `pandas` has not been imported, then an object is + definitely not a `pandas.Timestamp`. + + Parameters + ---------- + **modules + Keyword-only binding from `{alias: module_name}`. + + Examples + -------- + >>> import pandas as pd # doctest: +SKIP + >>> import polars as pl # doctest: +SKIP + >>> from altair.utils.schemapi import _get_optional_modules # doctest: +SKIP + >>> + >>> _get_optional_modules(pd="pandas", pl="polars", ibis="ibis") # doctest: +SKIP + { + "pd": , + "pl": , + "ibis": None, + } + + If the user later imports ``ibis``, it would appear in subsequent calls. + + >>> import ibis # doctest: +SKIP + >>> + >>> _get_optional_modules(ibis="ibis") # doctest: +SKIP + { + "ibis": , + } + """ + return {k: sys.modules.get(v) for k, v in modules.items()} + + +def _replace_parsed_shorthand( + parsed_shorthand: dict[str, Any], kwds: dict[str, Any] +) -> dict[str, Any]: + """ + `parsed_shorthand` is added by `FieldChannelMixin`. + + It's used below to replace shorthand with its long form equivalent + `parsed_shorthand` is removed from `context` if it exists so that it is + not passed to child `to_dict` function calls. + """ + # Prevent that pandas categorical data is automatically sorted + # when a non-ordinal data type is specifed manually + # or if the encoding channel does not support sorting + if "sort" in parsed_shorthand and ( + "sort" not in kwds or kwds["type"] not in {"ordinal", Undefined} + ): + parsed_shorthand.pop("sort") + + kwds.update( + (k, v) + for k, v in parsed_shorthand.items() + if kwds.get(k, Undefined) is Undefined + ) + return kwds + + TSchemaBase = TypeVar("TSchemaBase", bound=SchemaBase) _CopyImpl = TypeVar("_CopyImpl", SchemaBase, Dict[Any, Any], List[Any]) From 5b5877903bce55392c66d9dd08b21e0da58a5fda Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Sat, 31 Aug 2024 12:10:25 -0700 Subject: [PATCH 7/7] docs: Split interactive docs section into subpages (#3561) * Split interactivity doc section into subpages To make it easier to navigate instead of having one giant page. * Move JupyterChart under main interactivity section The parts about performance and JupyterChart are under the Large Datasets section, so it seems natural that the part about interactivity would go together with the other interactive parts of the library. * Note that streamlit can access params from python * Standardize use of ampersand in headings * Remove dashboard sentence from JupyterChart page * Add heading to interaction landing page I think this looks more pleasing as content without a right-side ToC stretches wider across the page. * fix: Add missing imports to `altair-plot` directives * Reword interactive intro * Apply suggestions from code review Co-authored-by: Dan Redding <125183946+dangotbanned@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Dan Redding <125183946+dangotbanned@users.noreply.github.com> --------- Co-authored-by: Dan Redding <125183946+dangotbanned@users.noreply.github.com> --- doc/user_guide/compound_charts.rst | 4 +- doc/user_guide/data.rst | 3 +- doc/user_guide/display_frontends.rst | 2 +- doc/user_guide/interactions.rst | 1105 ----------------- .../interactions/bindings_widgets.rst | 408 ++++++ doc/user_guide/interactions/expressions.rst | 198 +++ doc/user_guide/interactions/index.rst | 48 + .../{ => interactions}/jupyter_chart.rst | 2 + doc/user_guide/interactions/parameters.rst | 484 ++++++++ doc/user_guide/scale_resolve.rst | 4 +- doc/user_guide/times_and_dates.rst | 4 +- 11 files changed, 1148 insertions(+), 1114 deletions(-) delete mode 100644 doc/user_guide/interactions.rst create mode 100644 doc/user_guide/interactions/bindings_widgets.rst create mode 100644 doc/user_guide/interactions/expressions.rst create mode 100644 doc/user_guide/interactions/index.rst rename doc/user_guide/{ => interactions}/jupyter_chart.rst (99%) create mode 100644 doc/user_guide/interactions/parameters.rst diff --git a/doc/user_guide/compound_charts.rst b/doc/user_guide/compound_charts.rst index 025eb8116..503add798 100644 --- a/doc/user_guide/compound_charts.rst +++ b/doc/user_guide/compound_charts.rst @@ -2,8 +2,8 @@ .. _user-guide-compound: -Layered and Multi-View Charts ------------------------------ +Layered & Multi-View Charts +--------------------------- Along with the basic :class:`Chart` object, Altair provides a number of compound plot types that can be used to create stacked, layered, faceted, and repeated charts. They are summarized in the following tables: diff --git a/doc/user_guide/data.rst b/doc/user_guide/data.rst index 48a09db29..696e9e8ea 100644 --- a/doc/user_guide/data.rst +++ b/doc/user_guide/data.rst @@ -620,14 +620,13 @@ data before usage in Altair using GeoPandas for example as such: encodings/index marks/index transform/index - interactions + interactions/index compound_charts scale_resolve times_and_dates customization configuration saving_charts - jupyter_chart .. toctree:: diff --git a/doc/user_guide/display_frontends.rst b/doc/user_guide/display_frontends.rst index 1596e05b6..b8ecbe67e 100644 --- a/doc/user_guide/display_frontends.rst +++ b/doc/user_guide/display_frontends.rst @@ -171,7 +171,7 @@ Package `Marimo `_ ✔ ✔ `Shiny `_ using :ref:`JupyterChart ` ✔ ✔ `Solara `_ ✔ ✔ -`Streamlit `_ ✔ +`Streamlit `_ ✔ ✔ =================================================================================================================================== =================================== ============================= The above mentioned frameworks all require you to run a web application on a server if you want to share your work with others. A web application gives you a lot of flexibility, you can for example fetch data from a database based on the value of a dropdown menu in the dashboard. However, it comes with some complexity as well. diff --git a/doc/user_guide/interactions.rst b/doc/user_guide/interactions.rst deleted file mode 100644 index 4829c371f..000000000 --- a/doc/user_guide/interactions.rst +++ /dev/null @@ -1,1105 +0,0 @@ -.. currentmodule:: altair - -.. _user-guide-interactions: - -Interactive Charts -================== - -One of the unique features of Altair, inherited from Vega-Lite, is a -declarative grammar of not just visualization, but also *interaction*. -This is both convenient and powerful, -as we will see in this section. -There are three core concepts of this grammar: - -- Parameters are the basic building blocks in the grammar of interaction. - They can either be simple variables or more complex selections - that map user input (e.g., mouse clicks and drags) to data queries. -- Conditions and filters can respond to changes in parameter values - and update chart elements based on that input. -- Widgets and other chart input elements can bind to parameters - so that charts can be manipulated via drop-down menus, radio buttons, sliders, legends, etc. - -.. _parameters: - -Parameters -~~~~~~~~~~ - -Parameters are the building blocks of interaction in Altair. -There are two types of parameters: *variables* and *selections*. We introduce these concepts through a series of examples. - -.. note:: - - This material was changed considerably with the release of Altair 5. - -.. _basic variable: - -Variables: Reusing Values -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Variable parameters allow for a value to be defined once -and then reused throughout the rest of the chart. -Here is a simple scatter-plot created from the ``cars`` dataset: - -.. altair-plot:: - - import altair as alt - from vega_datasets import data - - cars = data.cars.url - - alt.Chart(cars).mark_circle().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color='Origin:N' - ) - -Variable parameters are created using the :func:`param` function. -Here, -we create a parameter with a default value of 0.1 using the ``value`` property: - -.. altair-plot:: - :output: none - - op_var = alt.param(value=0.1) - -In order to use this variable in the chart specification, we explicitly add it to the chart using the :meth:`add_params` method, and we can then reference the variable within the chart specification. Here we set the opacity using our ``op_var`` parameter. - -.. altair-plot:: - - op_var = alt.param(value=0.1) - - alt.Chart(cars).mark_circle(opacity=op_var).encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color='Origin:N' - ).add_params( - op_var - ) - -It's reasonable to ask whether all this effort is necessary. Here is a more natural way to accomplish the same thing that avoids the use of both :func:`param` and ``add_params``. - -.. altair-plot:: - - op_var2 = 0.1 - - alt.Chart(cars).mark_circle(opacity=op_var2).encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color='Origin:N' - ) - -The benefit of using :func:`param` doesn't become apparent until we incorporate an additional component. In the following example we use the ``bind`` property of the parameter, so that the parameter becomes bound to an input element. In this example, that input element is a slider widget. - -.. altair-plot:: - - slider = alt.binding_range(min=0, max=1, step=0.05, name='opacity:') - op_var = alt.param(value=0.1, bind=slider) - - alt.Chart(cars).mark_circle(opacity=op_var).encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color='Origin:N' - ).add_params( - op_var - ) - -Now we can dynamically change the opacity of the points in our chart using the slider. You will learn much more about binding parameters to input elements such as widgets in the section :ref:`binding-parameters`. - -.. note:: - - A noteworthy aspect of Altair's interactivity is that these effects are controlled entirely within the web browser. This means that you can save charts as HTML files and share them with your colleagues who can access the interactivity via their browser without the need to install Python. - -Selections: Capturing Chart Interactions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Selection parameters define data queries -that are driven by interactive manipulation of the chart -by the user (e.g., via mouse clicks or drags). -There are two types of selections: -:func:`selection_interval` and :func:`selection_point`. - -Here we will create a simple chart and then add an selection interval to it. -We could create a selection interval via ``param(select="interval")``, -but it is more convenient to use the shorter ``selection_interval``. - -Here is a simple scatter-plot created from the ``cars`` dataset: - -.. altair-plot:: - - import altair as alt - from vega_datasets import data - - cars = data.cars.url - - alt.Chart(cars).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color='Origin:N' - ) - -First we'll create an interval selection using the :func:`selection_interval` -function (an interval selection is also referred to as a "brush"): - -.. altair-plot:: - :output: none - - brush = alt.selection_interval() - -We can now add this selection interval to our chart via ``add_params``: - -.. altair-plot:: - - alt.Chart(cars).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color='Origin:N' - ).add_params( - brush - ) - -The result above is a chart that allows you to click and drag to create -a selection region, and to move this region once the region is created. - -So far this example is very similar to what we did in the :ref:`variable example `: -we created a selection parameter using ``brush = alt.selection_interval()``, -and we attached that parameter to the chart using ``add_params``. -One difference is that here we have not defined how the chart should respond to the selection; you will learn this in the next section. - -Conditions & Filters -~~~~~~~~~~~~~~~~~~~~ - -Conditional Encodings -^^^^^^^^^^^^^^^^^^^^^ - -The example above is neat, but the selection interval doesn't actually *do* anything yet. -To make the chart respond to this selection, we need to reference the selection in within -the chart specification. Here, we will use the :func:`condition` function to create -a conditional color encoding: we'll tie the color to the ``"Origin"`` -column for points in the selection, and set the color to ``"lightgray"`` -for points outside the selection: - -.. altair-plot:: - - alt.Chart(cars).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color=alt.condition(brush, 'Origin:N', alt.value('lightgray')) - ).add_params( - brush - ) - -As you can see, the color of the points now changes depending on whether they are inside or outside the selection. -Above we are using the selection parameter ``brush`` as a *predicate* -(something that evaluates as `True` or `False`). -This is controlled by the line ``color=alt.condition(brush, 'Origin:N', alt.value('lightgray'))``. -Data points which fall within the selection evaluate as ``True``, -and data points which fall outside the selection evaluate to ``False``. -The ``'Origin:N'`` specifies how to color the points which fall within the selection, -and the ``alt.value('lightgray')`` specifies that the outside points should be given a constant color value; -you can remember this as ``alt.condition(, , )``. - -This approach becomes even more powerful when the selection behavior is -tied across multiple views of the data within a compound chart. -For example, here we create a ``chart`` object using the same code as -above, and horizontally concatenate two versions of this chart: one -with the x-encoding tied to ``"Horsepower"``, and one with the x-encoding -tied to ``"Acceleration"`` - -.. altair-plot:: - - chart = alt.Chart(cars).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color=alt.condition(brush, 'Origin:N', alt.value('lightgray')) - ).properties( - width=250, - height=250 - ).add_params( - brush - ) - - chart | chart.encode(x='Acceleration:Q') - -Because both copies of the chart reference the same selection object, the -renderer ties the selections together across panels, leading to a dynamic -display that helps you gain insight into the relationships within the -dataset. - -Each selection type has attributes through which its behavior can be -customized; for example we might wish for our brush to be tied only -to the ``"x"`` encoding to emphasize that feature in the data. -We can modify the brush definition, and leave the rest of the code unchanged: - -.. altair-plot:: - - brush = alt.selection_interval(encodings=['x']) - - chart = alt.Chart(cars).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color=alt.condition(brush, 'Origin:N', alt.value('lightgray')) - ).properties( - width=250, - height=250 - ).add_params( - brush - ) - - chart | chart.encode(x='Acceleration:Q') - -As you might have noticed, -the selected points are sometimes obscured by some of the unselected points. -To bring the selected points to the foreground, -we can change the order in which they are laid out via the following -encoding: ``order=alt.condition(hover, alt.value(1), alt.value(0))``. -You can see and example of this in the :ref:`gallery_selection_zorder` gallery example. - -Filtering Data -^^^^^^^^^^^^^^ - -Using a selection parameter to filter data works in much the same way -as using it within ``condition``, -For example, in ``transform_filter(brush)``, -we are again using the selection parameter ``brush`` as a predicate. -Data points which evaluate to ``True`` (i.e., data points which lie within the selection) are kept, -and data points which evaluate to ``False`` are filtered out. - -It is not possible to both select and filter in the same chart, -so typically this functionality will be used when at least two sub-charts are present. -In the following example, -we attach the selection parameter to the upper chart, -and then filter data in the lower chart based on the selection in the upper chart. -You can explore how the counts change in the bar chart -depending on the size and position of the selection in the scatter plot. - -.. altair-plot:: - - brush = alt.selection_interval() - - points = alt.Chart(cars).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color='Origin:N' - ).add_params( - brush - ) - - bars = alt.Chart(cars).mark_bar().encode( - x='count()', - y='Origin:N', - color='Origin:N' - ).transform_filter( - brush - ) - - points & bars - - -Selection Types -~~~~~~~~~~~~~~~ - -Now that we have seen the basics of how we can use a selection to interact with a chart, -let's take a more systematic look at some of the types of selection parameters available in Altair. -For simplicity, we'll use a common chart in all the following examples; a -simple heat-map based on the ``cars`` dataset. -For convenience, let's write a quick Python function that will take a selection -object and create a chart with the color of the chart elements linked to this -selection: - -.. altair-plot:: - :output: none - - def make_example(selector): - cars = data.cars.url - - return alt.Chart(cars).mark_rect().encode( - x="Cylinders:O", - y="Origin:N", - color=alt.condition(selector, 'count()', alt.value('lightgray')) - ).properties( - width=300, - height=180 - ).add_params( - selector - ) - -Next we'll use this function to demonstrate the properties of various selections. - -Interval Selections -^^^^^^^^^^^^^^^^^^^ -An *interval* selection allows you to select chart elements by clicking and dragging. -You can create such a selection using the :func:`selection_interval` function: - -.. altair-plot:: - - interval = alt.selection_interval() - make_example(interval) - -As you click and drag on the plot, you'll find that your mouse creates a box -that can be subsequently moved to change the selection. - -The :func:`selection_interval` function takes a few additional arguments; for -example we can bind the interval to only the x-axis, and set it such that the -empty selection contains none of the points: - -.. altair-plot:: - - interval_x = alt.selection_interval(encodings=['x'], empty=False) - make_example(interval_x) - -Point Selections -^^^^^^^^^^^^^^^^ -A *point* selection allows you to select chart elements one at a time -via mouse actions. By default, points are selected on click: - -.. altair-plot:: - - point = alt.selection_point() - make_example(point) - -By changing some arguments, we can select points when hovering over them rather than on -click. We can also set the ``nearest`` flag to ``True`` so that the nearest -point is highlighted: - -.. altair-plot:: - - point_nearest = alt.selection_point(on='pointerover', nearest=True) - make_example(point_nearest) - -Point selections also allow for multiple chart objects to be selected. -By default, chart elements can be added to and removed from the selection -by clicking on them while holding the *shift* key, you can try in the two charts above. - -Selection Targets -~~~~~~~~~~~~~~~~~ - -For any but the simplest selections, the user needs to think about exactly -what is targeted by the selection, and this can be controlled with either the -``fields`` or ``encodings`` arguments. These control what data properties are -used to determine which points are part of the selection. - -For example, here we create a small chart that acts as an interactive legend, -by targeting the Origin field using ``fields=['Origin']``. Clicking on points -in the upper-right plot (the legend) will propagate a selection for all points -with a matching ``Origin``. - -.. altair-plot:: - - selection = alt.selection_point(fields=['Origin']) - color = alt.condition( - selection, - alt.Color('Origin:N').legend(None), - alt.value('lightgray') - ) - - scatter = alt.Chart(cars).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color=color, - tooltip='Name:N' - ) - - legend = alt.Chart(cars).mark_point().encode( - alt.Y('Origin:N').axis(orient='right'), - color=color - ).add_params( - selection - ) - - scatter | legend - -The above could be equivalently replace ``fields=['Origin']`` with -``encodings=['color']``, because in this case the chart maps ``color`` to -``'Origin'``. Also note that there is a shortcut to create interactive legends in Altair -described in the section :ref:`legend-binding`. - -Similarly, we can specify multiple fields and/or encodings that must be -matched in order for a datum to be included in a selection. -For example, we could modify the above chart to create a two-dimensional -clickable legend that will select points by both Origin and number of -cylinders: - -.. altair-plot:: - - selection = alt.selection_point(fields=['Origin', 'Cylinders']) - color = alt.condition( - selection, - alt.Color('Origin:N').legend(None), - alt.value('lightgray') - ) - - scatter = alt.Chart(cars).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color=color, - tooltip='Name:N' - ) - - legend = alt.Chart(cars).mark_rect().encode( - alt.Y('Origin:N').axis(orient='right'), - x='Cylinders:O', - color=color - ).add_params( - selection - ) - - scatter | legend - -By fine-tuning the behavior of selections in this way, they can be used to -create a wide variety of linked interactive chart types. - - -Parameter Composition -~~~~~~~~~~~~~~~~~~~~~ - -Altair also supports combining multiple parameters using the ``&``, ``|`` -and ``~`` for respectively ``AND``, ``OR`` and ``NOT`` logical composition -operands. - -Returning to our heatmap examples, -we can construct a scenario where there are two people who can make an interval -selection in the same chart. The person Alex makes a selection box when the -alt-key (macOS: option-key) is selected and Morgan can make a selection -box when the shift-key is selected. -We use the ``Brushconfig`` to give the selection box of Morgan a different -style. -Now, we color the rectangles when they fall within Alex's or Morgan's -selection -(note that you need to create both selections before seeing the effect). - -.. altair-plot:: - - alex = alt.selection_interval( - on="[pointerdown[event.altKey], pointerup] > pointermove", - name='alex' - ) - morgan = alt.selection_interval( - on="[pointerdown[event.shiftKey], pointerup] > pointermove", - mark=alt.BrushConfig(fill="#fdbb84", fillOpacity=0.5, stroke="#e34a33"), - name='morgan' - ) - - alt.Chart(cars).mark_rect().encode( - x='Cylinders:O', - y='Origin:O', - color=alt.condition(alex | morgan, 'count()', alt.ColorValue("grey")) - ).add_params( - alex, morgan - ).properties( - width=300, - height=180 - ) - -With these operators, selections can be combined in arbitrary ways: - -- ``~(alex & morgan)``: to select the rectangles that fall outside - Alex's and Morgan's selections. - -- ``alex | ~morgan``: to select the rectangles that fall within Alex's - selection or outside the selection of Morgan - -.. _binding-parameters: - -Bindings & Widgets -~~~~~~~~~~~~~~~~~~ - -With an understanding of the parameter types and conditions, you can now bind parameters to chart elements (e.g. legends) and widgets (e.g. drop-downs and sliders). This is done using the ``bind`` option inside ``param`` and ``selection``. As specified by `the Vega-lite binding docs `_, there are three types of bindings available: - -1. Point and interval selections can be used for data-driven interactive elements, such as highlighting and filtering based on values in the data. -2. Sliders and checkboxes can be used for logic-driven interactive elements, such as highlighting and filtering based on the absolute values in these widgets. -3. Interval selections can be bound to a scale, such as zooming in on a map. - -The following table summarizes the input elements that are supported in Vega-Lite: - -========================= =========================================================================== =============================================== -Input Element Description Example -========================= =========================================================================== =============================================== -:class:`binding_checkbox` Renders as checkboxes allowing for multiple selections of items. :ref:`gallery_multiple_interactions` -:class:`binding_radio` Radio buttons that force only a single selection :ref:`gallery_multiple_interactions` -:class:`binding_select` Drop down box for selecting a single item from a list :ref:`gallery_multiple_interactions` -:class:`binding_range` Shown as a slider to allow for selection along a scale. :ref:`gallery_us_population_over_time` -:class:`binding` General method that supports many HTML input elements -========================= =========================================================================== =============================================== - -Widget Binding -^^^^^^^^^^^^^^ - -Widgets are HTML input elements, such as drop-downs, sliders, radio buttons, and search boxes. -There are a three strategies for how variable and selection parameters -can be used together with widgets: -data-driven lookups, data-driven comparisons, and logic-driven comparisons. - -Data-Driven Lookups -------------------- - -Data-driven lookups use the active value(s) of the widget -together with a ``selection`` parameter -to look up points with matching values in the chart's dataset. -For example, -we can establish a binding between an input widget and a point selection -to filter the data as in the example below -where a drop-down is used to highlight cars of a specific ``Origin``: - -.. altair-plot:: - - input_dropdown = alt.binding_select(options=['Europe', 'Japan', 'USA'], name='Region ') - selection = alt.selection_point(fields=['Origin'], bind=input_dropdown) - color = alt.condition( - selection, - alt.Color('Origin:N').legend(None), - alt.value('lightgray') - ) - - alt.Chart(cars).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color=color, - ).add_params( - selection - ) - -Note that although it looks like a value is selected in the dropdown from the start, -we need to set `value=` to actually start out with an initial selection in the chart. -We did this previously with variable parameters -and selection parameters follow the same pattern as you will see further down -in the :ref:`encoding-channel-binding` section. - -As you can see above, -we are still using ``conditions`` to make the chart respond to the selection, -just as we did without widgets. -Bindings and input elements can also be used to filter data -allowing the user to see just the selected points as in the example below. -In this example, we also add an empty selection -to illustrate how to revert to showing all points -after a selection has been made in a radio button or drop-down -(which cannot be deselected). - - -.. altair-plot:: - - # Make radio button less cramped by adding a space after each label - # The spacing will only show up in your IDE, not on this doc page - options = ['Europe', 'Japan', 'USA'] - labels = [option + ' ' for option in options] - - input_dropdown = alt.binding_radio( - # Add the empty selection which shows all when clicked - options=options + [None], - labels=labels + ['All'], - name='Region: ' - ) - selection = alt.selection_point( - fields=['Origin'], - bind=input_dropdown, - ) - - alt.Chart(cars).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - # We need to set a constant domain to preserve the colors - # when only one region is shown at a time - color=alt.Color('Origin:N').scale(domain=options), - ).add_params( - selection - ).transform_filter( - selection - ) - -In addition to the widgets listed in the table above, -Altair has access to `any html widget `_ -via the more general ``binding`` function. -In the example below, -we use a search input to filter points that match the search string exactly. -You can hover over the points to see the car names -and try typing one into the search box, e.g. ``vw pickup`` -to see the point highlighted -(you need to type out the full name). - -.. altair-plot:: - - search_input = alt.selection_point( - fields=['Name'], - empty=False, # Start with no points selected - bind=alt.binding( - input='search', - placeholder="Car model", - name='Search ', - ) - ) - alt.Chart(data.cars.url).mark_point(size=60).encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - tooltip='Name:N', - opacity=alt.condition( - search_input, - alt.value(1), - alt.value(0.05) - ) - ).add_params( - search_input - ) - -It is not always useful to require an exact match to the search syntax, -and when we will be learning about :ref:`expressions`, -we will see how we can match partial strings via a regex instead. - -Data-Driven Comparisons ------------------------ - -So far we have seen the use of selections -to lookup points with precisely matching values in our data. -This is often useful, -but sometimes we might want to make a more complex comparison -than an exact match. -For example, -we might want to create a condition -we select the points in the data that are above or below a threshold value, -which is specified via a slider. -For this workflow it is recommended to use variable parameters via ``param`` -and as you can see below, -we use the special syntax ``datum.xval`` -to reference the column to compare against. -Prefixing the column name with ``datum`` -tells Altair that we want to compare to a column in the dataframe, -rather than to a Python variable called ``xval``, -which would have been the case if we just wrote ``xval < selector``. - -.. altair-plot:: - - import numpy as np - import pandas as pd - - - rand = np.random.RandomState(42) - df = pd.DataFrame({ - 'xval': range(100), - 'yval': rand.randn(100).cumsum() - }) - - slider = alt.binding_range(min=0, max=100, step=1, name='Cutoff ') - selector = alt.param(name='SelectorName', value=50, bind=slider) - - alt.Chart(df).mark_point().encode( - x='xval', - y='yval', - color=alt.condition( - alt.datum.xval < selector, - # 'datum.xval < SelectorName', # An equivalent alternative - alt.value('red'), - alt.value('blue') - ) - ).add_params( - selector - ) - -In this particular case we could actually have used a selection parameter -since selection values can be accessed directly and used in expressions that affect the -chart. For example, here we create a slider to choose a cutoff value, and color -points based on whether they are smaller or larger than the value: - -.. altair-plot:: - - slider = alt.binding_range(min=0, max=100, step=1, name='Cutoff ') - selector = alt.selection_point( - name="SelectorName", - fields=['cutoff'], - bind=slider, - value=[{'cutoff': 50}] - ) - - alt.Chart(df).mark_point().encode( - x='xval', - y='yval', - color=alt.condition( - alt.datum.xval < selector.cutoff, - # 'datum.xval < SelectorName.cutoff', # An equivalent alternative - alt.value('red'), - alt.value('blue') - ) - ).add_params( - selector - ) - -While it can be useful to know -how to access selection values -in expression strings, -using the parameters syntax introduced in Altair 5 -often provides a more convenient syntax -for simple interactions like this one -since they can also be accessed in expression strings -as we saw above. -Similarly, -it is often possible to use equality statements -such as ``alt.datum.xval == selector`` to lookup exact values -but it is often more convenient to switch to a selection parameter -and specify a field/encoding. - -Logic-Driven Comparisons ------------------------- - -A logic comparison is a type of comparison -that is based on logical rules and conditions, -rather than on the actual data values themselves. -For example, for a checkbox widget -we want to check if the state of the checkbox is True or False -and execute some action depending on whether it is checked or not. -When we are using a checkbox as a toggle like this, -we need to use `param` instead of `selection_point`, -since we don't want to check if there are True/False values in our data, -just if the value of the check box is True (checked) or False (unchecked): - -.. altair-plot:: - - bind_checkbox = alt.binding_checkbox(name='Scale point size by "Acceleration": ') - param_checkbox = alt.param(bind=bind_checkbox) - - alt.Chart(cars).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - size=alt.condition( - param_checkbox, - 'Acceleration:Q', - alt.value(25) - ) - ).add_params( - param_checkbox - ) - -Another example of creating a widget binding that is independent of the data, -involves an interesting use case for the more general ``binding`` function. -In the next example, -this function introduces a color picker -where the user can choose the colors of the chart interactively: - -.. altair-plot:: - - color_usa = alt.param(value="#317bb4", bind=alt.binding(input='color', name='USA ')) - color_europe = alt.param(value="#ffb54d", bind=alt.binding(input='color', name='Europe ')) - color_japan = alt.param(value="#adadad", bind=alt.binding(input='color', name='Japan ')) - - alt.Chart(data.cars.url).mark_circle().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color=alt.Color( - 'Origin:N', - scale=alt.Scale( - domain=['USA', 'Europe', 'Japan'], - range=[color_usa, color_europe, color_japan] - ) - ) - ).add_params( - color_usa, color_europe, color_japan - ) - -.. _legend-binding: - -Legend Binding -^^^^^^^^^^^^^^ - -An interactive legend can often be helpful to assist in focusing in on groups of data. -Instead of manually having to build a separate chart to use as a legend, -Altair provides the ``bind='legend'`` option to facilitate the creation of clickable legends: - -.. altair-plot:: - - selection = alt.selection_point(fields=['Origin'], bind='legend') - - alt.Chart(cars).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color='Origin:N', - opacity=alt.condition(selection, alt.value(0.8), alt.value(0.2)) - ).add_params( - selection - ) - -Scale Binding -^^^^^^^^^^^^^ - -With interval selections, the ``bind`` property can be set to the value of ``"scales"``. In these cases, the binding will automatically respond to the panning and zooming along the chart: - -.. altair-plot:: - - selection = alt.selection_interval(bind='scales') - - alt.Chart(cars).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color='Origin:N', - ).add_params( - selection - ) - -Because this is such a common pattern, -Altair provides the :meth:`interactive` method -which creates a scale-bound selection more concisely: - -.. altair-plot:: - - alt.Chart(cars).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - color='Origin:N', - ).interactive() - -.. _encoding-channel-binding: - -Encoding Channel Binding -^^^^^^^^^^^^^^^^^^^^^^^^ - -To update which columns are displayed in a chart -based on the selection in a widget, -we would need to bind the widget to an encoding channel. -In contrast to legend and scale bindings, -it is not possible to setup a binding to an encoding channel -in the selection initialization -(e.g. by typing ``bind='x'``). -Instead, -parameters can be used to pass the value of a selection -to an encoding channel. -This gives more flexibility, -but requires the use of a separate calculation transform -(as in the example below) -until https://github.com/vega/vega-lite/issues/7365 is resolved. - -In this example, -we access the parameter value by referencing the parameter by name. -By indexing the data with the parameter value (via ``datum[]``) -we can extract the data column that matches the selected value of the parameter, -and populate the x-channel with the values from this data column. - -.. altair-plot:: - - dropdown = alt.binding_select( - options=['Horsepower', 'Displacement', 'Weight_in_lbs', 'Acceleration'], - name='X-axis column ' - ) - xcol_param = alt.param( - value='Horsepower', - bind=dropdown - ) - - alt.Chart(data.cars.url).mark_circle().encode( - x=alt.X('x:Q').title(''), - y='Miles_per_Gallon:Q', - color='Origin:N' - ).transform_calculate( - x=f'datum[{xcol_param.name}]' - ).add_params( - xcol_param - ) - -Using parameters inside calculate transforms allows us to define dynamic computations -(e.g. subtracting different pairs of columns), -as you can see in the :ref:`gallery_interactive_column_selection` gallery example. -In that example, -the chart title is also dynamically updated using a parameter inside an expression -which is described in more detail in :ref:`accessing-parameter-values`. -Note that it is currently not possible to change the axis titles dynamically based on the selected parameter value, -but a text mark could be used instead -(as in `this SO answer `_), -until https://github.com/vega/vega-lite/issues/7264 is resolved. - -.. _expressions: - -Expressions -~~~~~~~~~~~ - -Altair allows custom interactions by utilizing the `expression language of Vega `_ for writing basic formulas. A Vega expression string is a well-defined set of JavaScript-style operations. -To simplify building these expressions in Python, Altair provides the ``expr`` module, which offers constants and functions to construct expressions using Python syntax. Both JavaScript-syntax and Python-syntax are supported within Altair to define an expression -and an introductory example of each is available in the :ref:`user-guide-calculate-transform` transform documentation so we recommend checking out that page before continuing. - -Expressions inside Parameters -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In the following example, we define a range connected to a parameter named ``param_width``. We then assign two expressions via ``param`` using both JavaScript and Python-syntax. -As previously, -we access the parameter values by referencing the parameters by name; -in JavaScript that is done via ``f"{param_width.name}"`` -whereas in Python it is sufficient to just type the variable name. -Using these two expressions defined inside parameters, we can connect them to an encoding channel option, such as the title color of the axis. If the width is below ``200``, then the color is ``red``; otherwise, the color is ``blue``. - -.. altair-plot:: - - bind_range = alt.binding_range(min=100, max=300, name='Slider value: ') - param_width = alt.param(bind=bind_range) - - # Examples of how to write both js and python expressions - param_color_js_expr = alt.param(expr=f"{param_width.name} < 200 ? 'red' : 'black'") - param_color_py_expr = alt.param(expr=alt.expr.if_(param_width < 200, 'red', 'black')) - - chart = alt.Chart(df).mark_point().encode( - alt.X('xval').axis(titleColor=param_color_js_expr), - alt.Y('yval').axis(titleColor=param_color_py_expr) - ).add_params( - param_width, - param_color_js_expr, - param_color_py_expr - ) - chart - -In the example above, we used a JavaScript-style ternary operator ``f"{param_width.name} < 200 ? 'red' : 'blue'"`` which is equivalent to the Python function ``expr.if_(param_width < 200, 'red', 'blue')``. -The expressions defined as parameters also needed to be added to the chart within ``.add_params()``. - -Inline Expressions -^^^^^^^^^^^^^^^^^^ - -In addition to assigning an expression within a parameter definition as shown above, -the ``expr()`` utility function allows us to define inline expressions. -Inline expressions are not parameters, -so they can be added directly in the chart spec instead of via ``add_params``, -which is a convenient shorthand for writing out the full parameter code. - -In this example, we modify the chart above to change the size of the points based on an inline expression. Instead of creating a conditional statement, we use the value of the expression as the size directly and therefore only need to specify the name of the parameter. - -.. altair-plot:: - - chart.mark_point(size=alt.expr(param_width.name)) - -In addition to modifying the ``mark_*`` parameters, -inline expressions can be passed to encoding channels as a value definition. -Here, we make the exact same modification to the chart as in the previous example -via this alternate approach: - -.. altair-plot:: - - chart.encode(size=alt.value(alt.expr(param_width.name))) - -`Some parameter names have special meaning in Vega-Lite `_, for example, naming a parameter ``width`` will automatically link it to the width of the chart. - -.. altair-plot:: - - bind_range = alt.binding_range(min=100, max=300, name='Chart width: ') - param_width = alt.param('width', bind=bind_range) - - alt.Chart(df).mark_point().encode( - alt.X('xval'), - alt.Y('yval') - ).add_params( - param_width - ) - -.. _accessing-parameter-values: - -Inline Expressions in Titles ----------------------------- - -An inline expression can be used to -update the chart title to show the current value of the parameter. -Here, we extend the code from the previous example -by using an f-string inside an inline expression. -The additional quotations and plus signs are needed -for the parameter value to be interpreted correctly. - -.. altair-plot:: - - bind_range = alt.binding_range(min=100, max=300, name='Chart width: ') - param_width = alt.param('width', bind=bind_range) - - # In Javascript, a number is converted to a string when added to an existing string, - # which is why we use this nested quotation. - title=alt.Title(alt.expr(f'"This chart is " + {param_width.name} + " px wide"')) - alt.Chart(df, title=title).mark_point().encode( - alt.X('xval'), - alt.Y('yval') - ).add_params( - param_width - ) - -In the example above, -we accessed the value of a variable parameter -and inserted it into the chart title. -If we instead want our chart title to reflect the value from a selection parameter, -it is not enough to reference only the name of the parameter. -We also need to reference the field specified by the selection parameter -(i.e. ``Origin`` in the example below): - -.. altair-plot:: - - input_dropdown = alt.binding_select(options=['Europe', 'Japan', 'USA'], name='Region ') - selection = alt.selection_point(fields=['Origin'], bind=input_dropdown, value='Europe') - - title = alt.Title(alt.expr(f'"Cars from " + {selection.name}.Origin')) - - alt.Chart(cars, title=title).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - ).add_params( - selection - ).transform_filter( - selection - ) - - -A Regex Search Widget ---------------------- - -Now that we know the basics of expressions, -let's see how we can improve on our search input example -to make the search string match via a regex pattern. -To do this we need to use ``expr.regex`` to define the regex string, -and ``expr.test`` to test it against another string -(in this case the string in the ``Name`` column). -The ``i`` option makes the regex case insensitive, -and you can see that we have switched to using ``param`` instead of ``selection_point`` -since we are doing something more complex -than looking up values with an exact match in the data. -To try this out, you can type ``mazda|ford`` in the search input box below. - -.. altair-plot:: - - search_input = alt.param( - value='', - bind=alt.binding( - input='search', - placeholder="Car model", - name='Search ', - ) - ) - alt.Chart(data.cars.url).mark_point(size=60).encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - tooltip='Name:N', - opacity=alt.condition( - alt.expr.test(alt.expr.regexp(search_input, 'i'), alt.datum.Name), - # f"test(regexp({search_input.name}, 'i'), datum.Name)", # Equivalent js alternative - alt.value(1), - alt.value(0.05) - ) - ).add_params( - search_input - ) - -And remember, all this interactivity is client side. -You can save this chart as an HTML file or put it on a static site generator such as GitHub/GitLab pages -and anyone can interact with it without having to install Python. -Quite powerful! - -Summary of Expressions -^^^^^^^^^^^^^^^^^^^^^^ - -- Altair can utilize the expression language of Vega for writing basic formulas to enable custom interactions. -- Both JavaScript-style syntax and Python-style syntax are supported in Altair to define expressions. -- Altair provides the ``expr`` module which allows expressions to be constructed with Python syntax. -- Expressions can be included within a chart specification using two approaches: through a ``param(expr=...)`` parameter definition or inline using the ``expr(...)`` utility function. -- Expressions can be used anywhere the documentation mentions that an `ExprRef` is an accepted value. This is mainly in three locations within a chart specification: mark properties, encoding channel options, and within a value definition for an encoding channel. They are also supported in the chart title, but not yet for subtitles or guide titles (i.e. axis and legends, see https://github.com/vega/vega-lite/issues/7408 for details). - -Further Examples -~~~~~~~~~~~~~~~~ -Now that you understand the basics of Altair selections and bindings, you might wish to look -through the :ref:`gallery-category-Interactive Charts` section of the example gallery -for ideas about how they can be applied to more interesting charts. - -For more information on how to fine-tune selections, including specifying other -mouse and keystroke options, see the `Vega-Lite Selection documentation -`_. - -Access Params from Python -~~~~~~~~~~~~~~~~~~~~~~~~~ -As of Vega-Altair 5.1, it's now possible to access the values of variable and selection parameters -from Python using the :ref:`user-guide-jupyterchart` class. - -Additionally, the dashboarding packages ``Panel`` and ``Dash`` include support for processing Altair selections -with custom callbacks. See the -`Panel documentation `_ -and the `Dash documentation `_. diff --git a/doc/user_guide/interactions/bindings_widgets.rst b/doc/user_guide/interactions/bindings_widgets.rst new file mode 100644 index 000000000..dc62a6e11 --- /dev/null +++ b/doc/user_guide/interactions/bindings_widgets.rst @@ -0,0 +1,408 @@ +.. currentmodule:: altair + +.. _binding-parameters: + +Bindings & Widgets +~~~~~~~~~~~~~~~~~~ + +With an understanding of the parameter types and conditions, you can now bind parameters to chart elements (e.g. legends) and widgets (e.g. drop-downs and sliders). This is done using the ``bind`` option inside ``param`` and ``selection``. As specified by `the Vega-lite binding docs `_, there are three types of bindings available: + +1. Point and interval selections can be used for data-driven interactive elements, such as highlighting and filtering based on values in the data. +2. Sliders and checkboxes can be used for logic-driven interactive elements, such as highlighting and filtering based on the absolute values in these widgets. +3. Interval selections can be bound to a scale, such as zooming in on a map. + +The following table summarizes the input elements that are supported in Vega-Lite: + +========================= =========================================================================== =============================================== +Input Element Description Example +========================= =========================================================================== =============================================== +:class:`binding_checkbox` Renders as checkboxes allowing for multiple selections of items. :ref:`gallery_multiple_interactions` +:class:`binding_radio` Radio buttons that force only a single selection :ref:`gallery_multiple_interactions` +:class:`binding_select` Drop down box for selecting a single item from a list :ref:`gallery_multiple_interactions` +:class:`binding_range` Shown as a slider to allow for selection along a scale. :ref:`gallery_us_population_over_time` +:class:`binding` General method that supports many HTML input elements +========================= =========================================================================== =============================================== + +Widget Binding +^^^^^^^^^^^^^^ + +Widgets are HTML input elements, such as drop-downs, sliders, radio buttons, and search boxes. +There are a three strategies for how variable and selection parameters +can be used together with widgets: +data-driven lookups, data-driven comparisons, and logic-driven comparisons. + +Data-Driven Lookups +------------------- + +Data-driven lookups use the active value(s) of the widget +together with a ``selection`` parameter +to look up points with matching values in the chart's dataset. +For example, +we can establish a binding between an input widget and a point selection +to filter the data as in the example below +where a drop-down is used to highlight cars of a specific ``Origin``: + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + cars = data.cars.url + + input_dropdown = alt.binding_select(options=['Europe', 'Japan', 'USA'], name='Region ') + selection = alt.selection_point(fields=['Origin'], bind=input_dropdown) + color = alt.condition( + selection, + alt.Color('Origin:N').legend(None), + alt.value('lightgray') + ) + + alt.Chart(cars).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color=color, + ).add_params( + selection + ) + +Note that although it looks like a value is selected in the dropdown from the start, +we need to set `value=` to actually start out with an initial selection in the chart. +We did this previously with variable parameters +and selection parameters follow the same pattern as you will see further down +in the :ref:`encoding-channel-binding` section. + +As you can see above, +we are still using ``conditions`` to make the chart respond to the selection, +just as we did without widgets. +Bindings and input elements can also be used to filter data +allowing the user to see just the selected points as in the example below. +In this example, we also add an empty selection +to illustrate how to revert to showing all points +after a selection has been made in a radio button or drop-down +(which cannot be deselected). + + +.. altair-plot:: + + # Make radio button less cramped by adding a space after each label + # The spacing will only show up in your IDE, not on this doc page + options = ['Europe', 'Japan', 'USA'] + labels = [option + ' ' for option in options] + + input_dropdown = alt.binding_radio( + # Add the empty selection which shows all when clicked + options=options + [None], + labels=labels + ['All'], + name='Region: ' + ) + selection = alt.selection_point( + fields=['Origin'], + bind=input_dropdown, + ) + + alt.Chart(cars).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + # We need to set a constant domain to preserve the colors + # when only one region is shown at a time + color=alt.Color('Origin:N').scale(domain=options), + ).add_params( + selection + ).transform_filter( + selection + ) + +In addition to the widgets listed in the table above, +Altair has access to `any html widget `_ +via the more general ``binding`` function. +In the example below, +we use a search input to filter points that match the search string exactly. +You can hover over the points to see the car names +and try typing one into the search box, e.g. ``vw pickup`` +to see the point highlighted +(you need to type out the full name). + +.. altair-plot:: + + search_input = alt.selection_point( + fields=['Name'], + empty=False, # Start with no points selected + bind=alt.binding( + input='search', + placeholder="Car model", + name='Search ', + ) + ) + alt.Chart(data.cars.url).mark_point(size=60).encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + tooltip='Name:N', + opacity=alt.condition( + search_input, + alt.value(1), + alt.value(0.05) + ) + ).add_params( + search_input + ) + +It is not always useful to require an exact match to the search syntax, +and when we will be learning about :ref:`expressions`, +we will see how we can match partial strings via a regex instead. + +Data-Driven Comparisons +----------------------- + +So far we have seen the use of selections +to lookup points with precisely matching values in our data. +This is often useful, +but sometimes we might want to make a more complex comparison +than an exact match. +For example, +we might want to create a condition +we select the points in the data that are above or below a threshold value, +which is specified via a slider. +For this workflow it is recommended to use variable parameters via ``param`` +and as you can see below, +we use the special syntax ``datum.xval`` +to reference the column to compare against. +Prefixing the column name with ``datum`` +tells Altair that we want to compare to a column in the dataframe, +rather than to a Python variable called ``xval``, +which would have been the case if we just wrote ``xval < selector``. + +.. altair-plot:: + + import numpy as np + import pandas as pd + + + rand = np.random.RandomState(42) + df = pd.DataFrame({ + 'xval': range(100), + 'yval': rand.randn(100).cumsum() + }) + + slider = alt.binding_range(min=0, max=100, step=1, name='Cutoff ') + selector = alt.param(name='SelectorName', value=50, bind=slider) + + alt.Chart(df).mark_point().encode( + x='xval', + y='yval', + color=alt.condition( + alt.datum.xval < selector, + # 'datum.xval < SelectorName', # An equivalent alternative + alt.value('red'), + alt.value('blue') + ) + ).add_params( + selector + ) + +In this particular case we could actually have used a selection parameter +since selection values can be accessed directly and used in expressions that affect the +chart. For example, here we create a slider to choose a cutoff value, and color +points based on whether they are smaller or larger than the value: + +.. altair-plot:: + + slider = alt.binding_range(min=0, max=100, step=1, name='Cutoff ') + selector = alt.selection_point( + name="SelectorName", + fields=['cutoff'], + bind=slider, + value=[{'cutoff': 50}] + ) + + alt.Chart(df).mark_point().encode( + x='xval', + y='yval', + color=alt.condition( + alt.datum.xval < selector.cutoff, + # 'datum.xval < SelectorName.cutoff', # An equivalent alternative + alt.value('red'), + alt.value('blue') + ) + ).add_params( + selector + ) + +While it can be useful to know +how to access selection values +in expression strings, +using the parameters syntax introduced in Altair 5 +often provides a more convenient syntax +for simple interactions like this one +since they can also be accessed in expression strings +as we saw above. +Similarly, +it is often possible to use equality statements +such as ``alt.datum.xval == selector`` to lookup exact values +but it is often more convenient to switch to a selection parameter +and specify a field/encoding. + +Logic-Driven Comparisons +------------------------ + +A logic comparison is a type of comparison +that is based on logical rules and conditions, +rather than on the actual data values themselves. +For example, for a checkbox widget +we want to check if the state of the checkbox is True or False +and execute some action depending on whether it is checked or not. +When we are using a checkbox as a toggle like this, +we need to use `param` instead of `selection_point`, +since we don't want to check if there are True/False values in our data, +just if the value of the check box is True (checked) or False (unchecked): + +.. altair-plot:: + + bind_checkbox = alt.binding_checkbox(name='Scale point size by "Acceleration": ') + param_checkbox = alt.param(bind=bind_checkbox) + + alt.Chart(cars).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + size=alt.condition( + param_checkbox, + 'Acceleration:Q', + alt.value(25) + ) + ).add_params( + param_checkbox + ) + +Another example of creating a widget binding that is independent of the data, +involves an interesting use case for the more general ``binding`` function. +In the next example, +this function introduces a color picker +where the user can choose the colors of the chart interactively: + +.. altair-plot:: + + color_usa = alt.param(value="#317bb4", bind=alt.binding(input='color', name='USA ')) + color_europe = alt.param(value="#ffb54d", bind=alt.binding(input='color', name='Europe ')) + color_japan = alt.param(value="#adadad", bind=alt.binding(input='color', name='Japan ')) + + alt.Chart(data.cars.url).mark_circle().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color=alt.Color( + 'Origin:N', + scale=alt.Scale( + domain=['USA', 'Europe', 'Japan'], + range=[color_usa, color_europe, color_japan] + ) + ) + ).add_params( + color_usa, color_europe, color_japan + ) + +.. _legend-binding: + +Legend Binding +^^^^^^^^^^^^^^ + +An interactive legend can often be helpful to assist in focusing in on groups of data. +Instead of manually having to build a separate chart to use as a legend, +Altair provides the ``bind='legend'`` option to facilitate the creation of clickable legends: + +.. altair-plot:: + + selection = alt.selection_point(fields=['Origin'], bind='legend') + + alt.Chart(cars).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color='Origin:N', + opacity=alt.condition(selection, alt.value(0.8), alt.value(0.2)) + ).add_params( + selection + ) + +Scale Binding +^^^^^^^^^^^^^ + +With interval selections, the ``bind`` property can be set to the value of ``"scales"``. In these cases, the binding will automatically respond to the panning and zooming along the chart: + +.. altair-plot:: + + selection = alt.selection_interval(bind='scales') + + alt.Chart(cars).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color='Origin:N', + ).add_params( + selection + ) + +Because this is such a common pattern, +Altair provides the :meth:`interactive` method +which creates a scale-bound selection more concisely: + +.. altair-plot:: + + alt.Chart(cars).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color='Origin:N', + ).interactive() + +.. _encoding-channel-binding: + +Encoding Channel Binding +^^^^^^^^^^^^^^^^^^^^^^^^ + +To update which columns are displayed in a chart +based on the selection in a widget, +we would need to bind the widget to an encoding channel. +In contrast to legend and scale bindings, +it is not possible to setup a binding to an encoding channel +in the selection initialization +(e.g. by typing ``bind='x'``). +Instead, +parameters can be used to pass the value of a selection +to an encoding channel. +This gives more flexibility, +but requires the use of a separate calculation transform +(as in the example below) +until https://github.com/vega/vega-lite/issues/7365 is resolved. + +In this example, +we access the parameter value by referencing the parameter by name. +By indexing the data with the parameter value (via ``datum[]``) +we can extract the data column that matches the selected value of the parameter, +and populate the x-channel with the values from this data column. + +.. altair-plot:: + + dropdown = alt.binding_select( + options=['Horsepower', 'Displacement', 'Weight_in_lbs', 'Acceleration'], + name='X-axis column ' + ) + xcol_param = alt.param( + value='Horsepower', + bind=dropdown + ) + + alt.Chart(data.cars.url).mark_circle().encode( + x=alt.X('x:Q').title(''), + y='Miles_per_Gallon:Q', + color='Origin:N' + ).transform_calculate( + x=f'datum[{xcol_param.name}]' + ).add_params( + xcol_param + ) + +Using parameters inside calculate transforms allows us to define dynamic computations +(e.g. subtracting different pairs of columns), +as you can see in the :ref:`gallery_interactive_column_selection` gallery example. +In that example, +the chart title is also dynamically updated using a parameter inside an expression +which is described in more detail in :ref:`accessing-parameter-values`. +Note that it is currently not possible to change the axis titles dynamically based on the selected parameter value, +but a text mark could be used instead +(as in `this SO answer `_), +until https://github.com/vega/vega-lite/issues/7264 is resolved. diff --git a/doc/user_guide/interactions/expressions.rst b/doc/user_guide/interactions/expressions.rst new file mode 100644 index 000000000..a73751ef4 --- /dev/null +++ b/doc/user_guide/interactions/expressions.rst @@ -0,0 +1,198 @@ +.. currentmodule:: altair + +.. _expressions: + +Expressions +~~~~~~~~~~~ + +Altair allows custom interactions by utilizing the `expression language of Vega `_ for writing basic formulas. A Vega expression string is a well-defined set of JavaScript-style operations. +To simplify building these expressions in Python, Altair provides the ``expr`` module, which offers constants and functions to construct expressions using Python syntax. Both JavaScript-syntax and Python-syntax are supported within Altair to define an expression +and an introductory example of each is available in the :ref:`user-guide-calculate-transform` transform documentation so we recommend checking out that page before continuing. + +Expressions inside Parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the following example, we define a range connected to a parameter named ``param_width``. We then assign two expressions via ``param`` using both JavaScript and Python-syntax. +As previously, +we access the parameter values by referencing the parameters by name; +in JavaScript that is done via ``f"{param_width.name}"`` +whereas in Python it is sufficient to just type the variable name. +Using these two expressions defined inside parameters, we can connect them to an encoding channel option, such as the title color of the axis. If the width is below ``200``, then the color is ``red``; otherwise, the color is ``blue``. + +.. altair-plot:: + + import altair as alt + import numpy as np + import pandas as pd + + rand = np.random.RandomState(42) + df = pd.DataFrame({ + 'xval': range(100), + 'yval': rand.randn(100).cumsum() + }) + + bind_range = alt.binding_range(min=100, max=300, name='Slider value: ') + param_width = alt.param(bind=bind_range) + + # Examples of how to write both js and python expressions + param_color_js_expr = alt.param(expr=f"{param_width.name} < 200 ? 'red' : 'black'") + param_color_py_expr = alt.param(expr=alt.expr.if_(param_width < 200, 'red', 'black')) + + chart = alt.Chart(df).mark_point().encode( + alt.X('xval').axis(titleColor=param_color_js_expr), + alt.Y('yval').axis(titleColor=param_color_py_expr) + ).add_params( + param_width, + param_color_js_expr, + param_color_py_expr + ) + chart + +In the example above, we used a JavaScript-style ternary operator ``f"{param_width.name} < 200 ? 'red' : 'blue'"`` which is equivalent to the Python function ``expr.if_(param_width < 200, 'red', 'blue')``. +The expressions defined as parameters also needed to be added to the chart within ``.add_params()``. + +Inline Expressions +^^^^^^^^^^^^^^^^^^ + +In addition to assigning an expression within a parameter definition as shown above, +the ``expr()`` utility function allows us to define inline expressions. +Inline expressions are not parameters, +so they can be added directly in the chart spec instead of via ``add_params``, +which is a convenient shorthand for writing out the full parameter code. + +In this example, we modify the chart above to change the size of the points based on an inline expression. Instead of creating a conditional statement, we use the value of the expression as the size directly and therefore only need to specify the name of the parameter. + +.. altair-plot:: + + chart.mark_point(size=alt.expr(param_width.name)) + +In addition to modifying the ``mark_*`` parameters, +inline expressions can be passed to encoding channels as a value definition. +Here, we make the exact same modification to the chart as in the previous example +via this alternate approach: + +.. altair-plot:: + + chart.encode(size=alt.value(alt.expr(param_width.name))) + +`Some parameter names have special meaning in Vega-Lite `_, for example, naming a parameter ``width`` will automatically link it to the width of the chart. + +.. altair-plot:: + + bind_range = alt.binding_range(min=100, max=300, name='Chart width: ') + param_width = alt.param('width', bind=bind_range) + + alt.Chart(df).mark_point().encode( + alt.X('xval'), + alt.Y('yval') + ).add_params( + param_width + ) + +.. _accessing-parameter-values: + +Inline Expressions in Titles +---------------------------- + +An inline expression can be used to +update the chart title to show the current value of the parameter. +Here, we extend the code from the previous example +by using an f-string inside an inline expression. +The additional quotations and plus signs are needed +for the parameter value to be interpreted correctly. + +.. altair-plot:: + + bind_range = alt.binding_range(min=100, max=300, name='Chart width: ') + param_width = alt.param('width', bind=bind_range) + + # In Javascript, a number is converted to a string when added to an existing string, + # which is why we use this nested quotation. + title=alt.Title(alt.expr(f'"This chart is " + {param_width.name} + " px wide"')) + alt.Chart(df, title=title).mark_point().encode( + alt.X('xval'), + alt.Y('yval') + ).add_params( + param_width + ) + +In the example above, +we accessed the value of a variable parameter +and inserted it into the chart title. +If we instead want our chart title to reflect the value from a selection parameter, +it is not enough to reference only the name of the parameter. +We also need to reference the field specified by the selection parameter +(i.e. ``Origin`` in the example below): + +.. altair-plot:: + + from vega_datasets import data + + cars = data.cars.url + input_dropdown = alt.binding_select(options=['Europe', 'Japan', 'USA'], name='Region ') + selection = alt.selection_point(fields=['Origin'], bind=input_dropdown, value='Europe') + + title = alt.Title(alt.expr(f'"Cars from " + {selection.name}.Origin')) + + alt.Chart(cars, title=title).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + ).add_params( + selection + ).transform_filter( + selection + ) + + +A Regex Search Widget +--------------------- + +Now that we know the basics of expressions, +let's see how we can improve on our search input example +to make the search string match via a regex pattern. +To do this we need to use ``expr.regex`` to define the regex string, +and ``expr.test`` to test it against another string +(in this case the string in the ``Name`` column). +The ``i`` option makes the regex case insensitive, +and you can see that we have switched to using ``param`` instead of ``selection_point`` +since we are doing something more complex +than looking up values with an exact match in the data. +To try this out, you can type ``mazda|ford`` in the search input box below. + +.. altair-plot:: + + search_input = alt.param( + value='', + bind=alt.binding( + input='search', + placeholder="Car model", + name='Search ', + ) + ) + alt.Chart(cars).mark_point(size=60).encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + tooltip='Name:N', + opacity=alt.condition( + alt.expr.test(alt.expr.regexp(search_input, 'i'), alt.datum.Name), + # f"test(regexp({search_input.name}, 'i'), datum.Name)", # Equivalent js alternative + alt.value(1), + alt.value(0.05) + ) + ).add_params( + search_input + ) + +And remember, all this interactivity is client side. +You can save this chart as an HTML file or put it on a static site generator such as GitHub/GitLab pages +and anyone can interact with it without having to install Python. +Quite powerful! + +Summary of Expressions +^^^^^^^^^^^^^^^^^^^^^^ + +- Altair can utilize the expression language of Vega for writing basic formulas to enable custom interactions. +- Both JavaScript-style syntax and Python-style syntax are supported in Altair to define expressions. +- Altair provides the ``expr`` module which allows expressions to be constructed with Python syntax. +- Expressions can be included within a chart specification using two approaches: through a ``param(expr=...)`` parameter definition or inline using the ``expr(...)`` utility function. +- Expressions can be used anywhere the documentation mentions that an `ExprRef` is an accepted value. This is mainly in three locations within a chart specification: mark properties, encoding channel options, and within a value definition for an encoding channel. They are also supported in the chart title, but not yet for subtitles or guide titles (i.e. axis and legends, see https://github.com/vega/vega-lite/issues/7408 for details). diff --git a/doc/user_guide/interactions/index.rst b/doc/user_guide/interactions/index.rst new file mode 100644 index 000000000..439dda294 --- /dev/null +++ b/doc/user_guide/interactions/index.rst @@ -0,0 +1,48 @@ +.. currentmodule:: altair + +.. _user-guide-interactions: + +Interactive Charts +================== + +One of the unique features of Altair, inherited from Vega-Lite, is a +declarative grammar of not just visualization, but also *interaction*. +This is both convenient and powerful, +as we will see in this section. +There are three core concepts of this grammar: + +- Parameters are the basic building blocks in the grammar of interaction. + They can either be simple variables or more complex selections + that map user input (e.g., mouse clicks and drags) to data queries. +- Conditions and filters can respond to changes in parameter values + and update chart elements based on that input. +- Widgets and other chart input elements can bind to parameters + so that charts can be manipulated via drop-down menus, radio buttons, sliders, legends, etc. + +In addition to these concepts, +there are two additional components that enhance the capabilities +of interactive visualizations in Altair: + +- Expressions allow for custom calculation via writing basic formulas. + These can be used for fine-controlled interactivity, + and are also available outside encodings. +- JupyterCharts allow access to Altair's parameters from Python, + e.g. printing the values of a selection in the plot. + +Further reading +--------------- + +Once you have worked through the subpages for the topics listed above, +you might wish to look through the :ref:`gallery-category-Interactive Charts` section of the example gallery +for ideas about how they can be applied to more interesting charts. + +If you are planning to use Altair charts together with Dashboard packages, +see the section on :ref:`Dashboards `. + +.. toctree:: + :hidden: + + parameters + bindings_widgets + expressions + jupyter_chart diff --git a/doc/user_guide/jupyter_chart.rst b/doc/user_guide/interactions/jupyter_chart.rst similarity index 99% rename from doc/user_guide/jupyter_chart.rst rename to doc/user_guide/interactions/jupyter_chart.rst index c3c8ce255..88982c06b 100644 --- a/doc/user_guide/jupyter_chart.rst +++ b/doc/user_guide/interactions/jupyter_chart.rst @@ -1,3 +1,5 @@ +.. currentmodule:: altair + .. _user-guide-jupyterchart: JupyterChart diff --git a/doc/user_guide/interactions/parameters.rst b/doc/user_guide/interactions/parameters.rst new file mode 100644 index 000000000..1dce8c116 --- /dev/null +++ b/doc/user_guide/interactions/parameters.rst @@ -0,0 +1,484 @@ +.. currentmodule:: altair + +.. _parameters: + +Parameters, Conditions, & Filters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Parameters are the building blocks of interaction in Altair. +There are two types of parameters: *variables* and *selections*. We introduce these concepts through a series of examples. + +.. note:: + + This material was changed considerably with the release of Altair 5. + +.. _basic variable: + +Variables: Reusing Values +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Variable parameters allow for a value to be defined once +and then reused throughout the rest of the chart. +Here is a simple scatter-plot created from the ``cars`` dataset: + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + cars = data.cars.url + + alt.Chart(cars).mark_circle().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color='Origin:N' + ) + +Variable parameters are created using the :func:`param` function. +Here, +we create a parameter with a default value of 0.1 using the ``value`` property: + +.. altair-plot:: + :output: none + + op_var = alt.param(value=0.1) + +In order to use this variable in the chart specification, we explicitly add it to the chart using the :meth:`add_params` method, and we can then reference the variable within the chart specification. Here we set the opacity using our ``op_var`` parameter. + +.. altair-plot:: + + op_var = alt.param(value=0.1) + + alt.Chart(cars).mark_circle(opacity=op_var).encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color='Origin:N' + ).add_params( + op_var + ) + +It's reasonable to ask whether all this effort is necessary. Here is a more natural way to accomplish the same thing that avoids the use of both :func:`param` and ``add_params``. + +.. altair-plot:: + + op_var2 = 0.1 + + alt.Chart(cars).mark_circle(opacity=op_var2).encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color='Origin:N' + ) + +The benefit of using :func:`param` doesn't become apparent until we incorporate an additional component. In the following example we use the ``bind`` property of the parameter, so that the parameter becomes bound to an input element. In this example, that input element is a slider widget. + +.. altair-plot:: + + slider = alt.binding_range(min=0, max=1, step=0.05, name='opacity:') + op_var = alt.param(value=0.1, bind=slider) + + alt.Chart(cars).mark_circle(opacity=op_var).encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color='Origin:N' + ).add_params( + op_var + ) + +Now we can dynamically change the opacity of the points in our chart using the slider. You will learn much more about binding parameters to input elements such as widgets in the section :ref:`binding-parameters`. + +.. note:: + + A noteworthy aspect of Altair's interactivity is that these effects are controlled entirely within the web browser. This means that you can save charts as HTML files and share them with your colleagues who can access the interactivity via their browser without the need to install Python. + +Selections: Capturing Chart Interactions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Selection parameters define data queries +that are driven by interactive manipulation of the chart +by the user (e.g., via mouse clicks or drags). +There are two types of selections: +:func:`selection_interval` and :func:`selection_point`. + +Here we will create a simple chart and then add an selection interval to it. +We could create a selection interval via ``param(select="interval")``, +but it is more convenient to use the shorter ``selection_interval``. + +Here is a simple scatter-plot created from the ``cars`` dataset: + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + cars = data.cars.url + + alt.Chart(cars).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color='Origin:N' + ) + +First we'll create an interval selection using the :func:`selection_interval` +function (an interval selection is also referred to as a "brush"): + +.. altair-plot:: + :output: none + + brush = alt.selection_interval() + +We can now add this selection interval to our chart via ``add_params``: + +.. altair-plot:: + + alt.Chart(cars).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color='Origin:N' + ).add_params( + brush + ) + +The result above is a chart that allows you to click and drag to create +a selection region, and to move this region once the region is created. + +So far this example is very similar to what we did in the :ref:`variable example `: +we created a selection parameter using ``brush = alt.selection_interval()``, +and we attached that parameter to the chart using ``add_params``. +One difference is that here we have not defined how the chart should respond to the selection; you will learn this in the next section. + +Conditions & Filters +~~~~~~~~~~~~~~~~~~~~ + +Conditional Encodings +^^^^^^^^^^^^^^^^^^^^^ + +The example above is neat, but the selection interval doesn't actually *do* anything yet. +To make the chart respond to this selection, we need to reference the selection in within +the chart specification. Here, we will use the :func:`condition` function to create +a conditional color encoding: we'll tie the color to the ``"Origin"`` +column for points in the selection, and set the color to ``"lightgray"`` +for points outside the selection: + +.. altair-plot:: + + alt.Chart(cars).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color=alt.condition(brush, 'Origin:N', alt.value('lightgray')) + ).add_params( + brush + ) + +As you can see, the color of the points now changes depending on whether they are inside or outside the selection. +Above we are using the selection parameter ``brush`` as a *predicate* +(something that evaluates as `True` or `False`). +This is controlled by the line ``color=alt.condition(brush, 'Origin:N', alt.value('lightgray'))``. +Data points which fall within the selection evaluate as ``True``, +and data points which fall outside the selection evaluate to ``False``. +The ``'Origin:N'`` specifies how to color the points which fall within the selection, +and the ``alt.value('lightgray')`` specifies that the outside points should be given a constant color value; +you can remember this as ``alt.condition(, , )``. + +This approach becomes even more powerful when the selection behavior is +tied across multiple views of the data within a compound chart. +For example, here we create a ``chart`` object using the same code as +above, and horizontally concatenate two versions of this chart: one +with the x-encoding tied to ``"Horsepower"``, and one with the x-encoding +tied to ``"Acceleration"`` + +.. altair-plot:: + + chart = alt.Chart(cars).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color=alt.condition(brush, 'Origin:N', alt.value('lightgray')) + ).properties( + width=250, + height=250 + ).add_params( + brush + ) + + chart | chart.encode(x='Acceleration:Q') + +Because both copies of the chart reference the same selection object, the +renderer ties the selections together across panels, leading to a dynamic +display that helps you gain insight into the relationships within the +dataset. + +Each selection type has attributes through which its behavior can be +customized; for example we might wish for our brush to be tied only +to the ``"x"`` encoding to emphasize that feature in the data. +We can modify the brush definition, and leave the rest of the code unchanged: + +.. altair-plot:: + + brush = alt.selection_interval(encodings=['x']) + + chart = alt.Chart(cars).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color=alt.condition(brush, 'Origin:N', alt.value('lightgray')) + ).properties( + width=250, + height=250 + ).add_params( + brush + ) + + chart | chart.encode(x='Acceleration:Q') + +As you might have noticed, +the selected points are sometimes obscured by some of the unselected points. +To bring the selected points to the foreground, +we can change the order in which they are laid out via the following +encoding: ``order=alt.condition(hover, alt.value(1), alt.value(0))``. +You can see an example of this in the :ref:`gallery_selection_zorder` gallery example. + +Filtering Data +^^^^^^^^^^^^^^ + +Using a selection parameter to filter data works in much the same way +as using it within ``condition``. +For example, in ``transform_filter(brush)``, +we are again using the selection parameter ``brush`` as a predicate. +Data points which evaluate to ``True`` (i.e., data points which lie within the selection) are kept, +and data points which evaluate to ``False`` are filtered out. + +It is not possible to both select and filter in the same chart, +so typically this functionality will be used when at least two sub-charts are present. +In the following example, +we attach the selection parameter to the upper chart, +and then filter data in the lower chart based on the selection in the upper chart. +You can explore how the counts change in the bar chart +depending on the size and position of the selection in the scatter plot. + +.. altair-plot:: + + brush = alt.selection_interval() + + points = alt.Chart(cars).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color='Origin:N' + ).add_params( + brush + ) + + bars = alt.Chart(cars).mark_bar().encode( + x='count()', + y='Origin:N', + color='Origin:N' + ).transform_filter( + brush + ) + + points & bars + + +Selection Types +~~~~~~~~~~~~~~~ + +Now that we have seen the basics of how we can use a selection to interact with a chart, +let's take a more systematic look at some of the types of selection parameters available in Altair. +For simplicity, we'll use a common chart in all the following examples; a +simple heat-map based on the ``cars`` dataset. +For convenience, let's write a quick Python function that will take a selection +object and create a chart with the color of the chart elements linked to this +selection: + +.. altair-plot:: + :output: none + + def make_example(selector: alt.Parameter) -> alt.Chart: + cars = data.cars.url + + return alt.Chart(cars).mark_rect().encode( + x="Cylinders:O", + y="Origin:N", + color=alt.condition(selector, 'count()', alt.value('lightgray')) + ).properties( + width=300, + height=180 + ).add_params( + selector + ) + +Next we'll use this function to demonstrate the properties of various selections. + +Interval Selections +^^^^^^^^^^^^^^^^^^^ +An *interval* selection allows you to select chart elements by clicking and dragging. +You can create such a selection using the :func:`selection_interval` function: + +.. altair-plot:: + + interval = alt.selection_interval() + make_example(interval) + +As you click and drag on the plot, you'll find that your mouse creates a box +that can be subsequently moved to change the selection. + +The :func:`selection_interval` function takes a few additional arguments; for +example we can bind the interval to only the x-axis, and set it such that the +empty selection contains none of the points: + +.. altair-plot:: + + interval_x = alt.selection_interval(encodings=['x'], empty=False) + make_example(interval_x) + +Point Selections +^^^^^^^^^^^^^^^^ +A *point* selection allows you to select chart elements one at a time +via mouse actions. By default, points are selected on click: + +.. altair-plot:: + + point = alt.selection_point() + make_example(point) + +By changing some arguments, we can select points when hovering over them rather than on +click. We can also set the ``nearest`` flag to ``True`` so that the nearest +point is highlighted: + +.. altair-plot:: + + point_nearest = alt.selection_point(on='pointerover', nearest=True) + make_example(point_nearest) + +Point selections also allow for multiple chart objects to be selected. +By default, chart elements can be added to and removed from the selection +by clicking on them while holding the *shift* key, you can try in the two charts above. + +Selection Targets +~~~~~~~~~~~~~~~~~ + +For any but the simplest selections, the user needs to think about exactly +what is targeted by the selection, and this can be controlled with either the +``fields`` or ``encodings`` arguments. These control what data properties are +used to determine which points are part of the selection. + +For example, here we create a small chart that acts as an interactive legend, +by targeting the Origin field using ``fields=['Origin']``. Clicking on points +in the upper-right plot (the legend) will propagate a selection for all points +with a matching ``Origin``. + +.. altair-plot:: + + selection = alt.selection_point(fields=['Origin']) + color = alt.condition( + selection, + alt.Color('Origin:N').legend(None), + alt.value('lightgray') + ) + + scatter = alt.Chart(cars).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color=color, + tooltip='Name:N' + ) + + legend = alt.Chart(cars).mark_point().encode( + alt.Y('Origin:N').axis(orient='right'), + color=color + ).add_params( + selection + ) + + scatter | legend + +Alternatively, we could express ``fields=['Origin']`` as ``encodings=['color']``, because our chart maps ``color`` to +``'Origin'``. Also note that there is a shortcut to create interactive legends in Altair +described in the section :ref:`legend-binding`. + +Similarly, we can specify multiple fields and/or encodings that must be +matched in order for a datum to be included in a selection. +For example, we could modify the above chart to create a two-dimensional +clickable legend that will select points by both Origin and number of +cylinders: + +.. altair-plot:: + + selection = alt.selection_point(fields=['Origin', 'Cylinders']) + color = alt.condition( + selection, + alt.Color('Origin:N').legend(None), + alt.value('lightgray') + ) + + scatter = alt.Chart(cars).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color=color, + tooltip='Name:N' + ) + + legend = alt.Chart(cars).mark_rect().encode( + alt.Y('Origin:N').axis(orient='right'), + x='Cylinders:O', + color=color + ).add_params( + selection + ) + + scatter | legend + +By fine-tuning the behavior of selections in this way, they can be used to +create a wide variety of linked interactive chart types. + + +Parameter Composition +~~~~~~~~~~~~~~~~~~~~~ + +Altair also supports combining multiple parameters using the ``&``, ``|`` +and ``~`` for respectively ``AND``, ``OR`` and ``NOT`` logical composition +operands. + +Returning to our heatmap examples, +we can construct a scenario where there are two people who can make an interval +selection in the same chart. The person Alex makes a selection box when the +alt-key (macOS: option-key) is selected and Morgan can make a selection +box when the shift-key is selected. +We use :class:`BrushConfig` to give the selection box of Morgan a different +style. +Now, we color the rectangles when they fall within Alex's or Morgan's +selection +(note that you need to create both selections before seeing the effect). + +.. altair-plot:: + + alex = alt.selection_interval( + on="[pointerdown[event.altKey], pointerup] > pointermove", + name='alex' + ) + morgan = alt.selection_interval( + on="[pointerdown[event.shiftKey], pointerup] > pointermove", + mark=alt.BrushConfig(fill="#fdbb84", fillOpacity=0.5, stroke="#e34a33"), + name='morgan' + ) + + alt.Chart(cars).mark_rect().encode( + x='Cylinders:O', + y='Origin:O', + color=alt.condition(alex | morgan, 'count()', alt.ColorValue("grey")) + ).add_params( + alex, morgan + ).properties( + width=300, + height=180 + ) + +With these operators, selections can be combined in arbitrary ways: + +- ``~(alex & morgan)``: to select the rectangles that fall outside + Alex's and Morgan's selections. + +- ``alex | ~morgan``: to select the rectangles that fall within Alex's + selection or outside the selection of Morgan + +For more information on how to fine-tune selections, including specifying other +mouse and keystroke options, see the `Vega-Lite Selection documentation +`_. + diff --git a/doc/user_guide/scale_resolve.rst b/doc/user_guide/scale_resolve.rst index af73efac5..80bc1509f 100644 --- a/doc/user_guide/scale_resolve.rst +++ b/doc/user_guide/scale_resolve.rst @@ -2,8 +2,8 @@ .. _user-guide-resolve: -Scale and Guide Resolution --------------------------- +Scale & Guide Resolution +------------------------ When creating compound charts (see :ref:`user-guide-compound`), altair defaults to using shared chart scales and guides (e.g. axes, legends, etc.). This default can be adjusted using the :meth:`Chart.resolve_scale`, diff --git a/doc/user_guide/times_and_dates.rst b/doc/user_guide/times_and_dates.rst index c1db1f526..a8cd47ab3 100644 --- a/doc/user_guide/times_and_dates.rst +++ b/doc/user_guide/times_and_dates.rst @@ -2,8 +2,8 @@ .. _user-guide-time: -Times and Dates -=============== +Times & Dates +============= Working with dates, times, and timezones is often one of the more challenging aspects of data analysis. In Altair, the difficulties are compounded by the fact that users are writing Python code, which outputs JSON-serialized