From 96961c7659d0e1d6bf94a61ca6193098001f75e2 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Mon, 21 Mar 2022 12:15:35 -0700 Subject: [PATCH 01/23] Change to sphinx pydata theme --- doc/conf.py | 4 ++-- doc/requirements.txt | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 82dd2d983..fab93ee77 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -73,7 +73,7 @@ # built documents. # # The short X.Y version. -version = "4.3.0.dev0" +version = "5.0.0" # The full version, including alpha/beta/rc tags. release = version @@ -127,7 +127,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "sphinx_rtd_theme" +html_theme = "pydata_sphinx_theme" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/doc/requirements.txt b/doc/requirements.txt index 2b04086f3..bd6db4365 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -2,5 +2,5 @@ sphinx jinja2 numpydoc pillow -sphinx_rtd_theme mistune<=0.8.4 +pydata-sphinx-theme From 802e146f223867aaafc97f5cf0e4144ded9a56d5 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Mon, 21 Mar 2022 12:21:11 -0700 Subject: [PATCH 02/23] Update templates, css, and config for the pydata theme --- doc/_static/custom.css | 41 +++++++++++++++++++++++++++++- doc/_templates/navbar-project.html | 4 +++ doc/_templates/sidebar-logo.html | 13 ++++++++++ doc/conf.py | 11 ++++++++ 4 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 doc/_templates/navbar-project.html create mode 100644 doc/_templates/sidebar-logo.html diff --git a/doc/_static/custom.css b/doc/_static/custom.css index fd823a163..94707e008 100644 --- a/doc/_static/custom.css +++ b/doc/_static/custom.css @@ -23,4 +23,43 @@ table.docutils td p { table.docutils td li { line-height: 18px; -} \ No newline at end of file +} + +/* Everything below this comment is for the pydata sphinx theme*/ + +/* Blue topbar */ +.navbar-light { + background-color: #16A7F0 !important; +} +/* White text in topbar */ +.navbar-light a { + color: #fff !important; +} +/* White bold project title in topbar */ +.navbar-light p.title { + font-size: 26px !important; + font-weight: 800 !important; + color: #fff !important; + margin-left: 180%; +} + +/* Version number in the same darkblue color as other text */ +div.navbar-brand-box p#site-version.site-version { + color: #130654 !important; +} +/* The box that contains the logo and the version number */ +div.navbar-brand-box a { + width: 100% !important; + height: auto !important; + flex-direction: column !important; +} +/* The logo */ +div.navbar-brand-box img { + display: block !important; + height: auto !important; + width: auto !important; + max-height: 18vh !important; + max-width: 100% !important; + margin: 0 auto !important; + margin-top: -40px !important; +} diff --git a/doc/_templates/navbar-project.html b/doc/_templates/navbar-project.html new file mode 100644 index 000000000..2b8ece77e --- /dev/null +++ b/doc/_templates/navbar-project.html @@ -0,0 +1,4 @@ + +

{{ project }}

+ + diff --git a/doc/_templates/sidebar-logo.html b/doc/_templates/sidebar-logo.html new file mode 100644 index 000000000..e3c1e8f3a --- /dev/null +++ b/doc/_templates/sidebar-logo.html @@ -0,0 +1,13 @@ +
+ + {% if logo %} + + {% set logo_url=logo %} + {% endif %} + {% if logo_url %} + +
+

{{ version }}

+ {% endif %} + +
diff --git a/doc/conf.py b/doc/conf.py index fab93ee77..ff3033f6b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -159,6 +159,17 @@ html_static_path = ["_static", "_images"] +html_theme_options = { +"navbar_start": ["navbar-project"], +"navbar_center": ["navbar-nav"], +"navbar_end": ["navbar-icon-links"], +} + +html_sidebars = { + "**": ["sidebar-logo", "search-field", "sidebar-nav-bs", "sidebar-ethical-ads"], + "gallery/index": ["sidebar-logo", "search-field", "sidebar-ethical-ads"] +} + # adapted from: http://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html # and # https://github.com/rtfd/sphinx_rtd_theme/issues/117 From 645e5e37b1f65a57099583d4047a7f5e35a06b48 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Mon, 21 Mar 2022 12:22:33 -0700 Subject: [PATCH 03/23] Update index structure for the pydata theme --- doc/getting_started/overview.rst | 10 +++++ doc/index.rst | 72 ++++---------------------------- doc/releases/changes.rst | 4 +- doc/user_guide/API.rst | 4 ++ doc/user_guide/data.rst | 48 +++++++++++++++++++++ doc/user_guide/ecosystem.rst | 4 +- 6 files changed, 75 insertions(+), 67 deletions(-) diff --git a/doc/getting_started/overview.rst b/doc/getting_started/overview.rst index 995d02b42..787987569 100644 --- a/doc/getting_started/overview.rst +++ b/doc/getting_started/overview.rst @@ -33,3 +33,13 @@ concise grammar. .. _Vega: http://vega.github.io/vega .. _Vega-Lite: http://vega.github.io/vega-lite + + +.. toctree:: + :maxdepth: 1 + :caption: Getting Started + :hidden: + + self + installation + starting diff --git a/doc/index.rst b/doc/index.rst index ec0a18b1e..466a9db24 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -17,80 +17,26 @@ Altair's API is simple, friendly and consistent and built on top of the powerful Vega-Lite_ visualization grammar. This elegant simplicity produces beautiful and effective visualizations with a minimal amount of code. -.. toctree:: - :maxdepth: 1 - :caption: Getting Started +Altair is BSD-licensed and the source is available on `GitHub`_, +where you can also report `bugs and feature requests`_. +For general questions, please use `StackOverflow`_. - getting_started/overview - getting_started/installation - getting_started/starting +You can browse this documentation via the link in the top navigation panel or by viewing the full site :ref:`genindex`. .. toctree:: :maxdepth: 1 - :caption: Gallery + :hidden: + Getting Started + User Guide gallery/index - -.. toctree:: - :maxdepth: 1 - :caption: User Guide - - user_guide/data - user_guide/encoding - user_guide/marks - user_guide/transform/index - user_guide/interactions - user_guide/interactions2 - user_guide/configuration - user_guide/compound_charts - user_guide/scale_resolve - user_guide/saving_charts - user_guide/customization - user_guide/times_and_dates - user_guide/faq - user_guide/troubleshooting - user_guide/internals user_guide/API user_guide/ecosystem - -.. toctree:: - :maxdepth: 1 - :caption: Case Studies - - case_studies/exploring-weather - -.. toctree:: - :maxdepth: 1 - :caption: Advanced Usage - - user_guide/importing - user_guide/display_frontends - user_guide/custom_renderers - user_guide/data_transformers - -.. toctree:: - :maxdepth: 1 - :caption: Release Notes - releases/changes -Bug Reports & Questions ------------------------ - -Altair is BSD-licensed and the source is available on `GitHub`_. If any -questions or issues come up as you use Altair, please get in touch via -`Git Issues`_ or our `Google Group`_. - - -Indices and tables ------------------- - -* :ref:`genindex` -* :ref:`modindex` - - .. _GitHub: http://github.com/altair-viz/altair .. _Git Issues: http://github.com/altair-viz/altair/issues .. _Vega: http://vega.github.io/vega .. _Vega-Lite: http://vega.github.io/vega-lite -.. _Google Group: https://groups.google.com/forum/#!forum/altair-viz +.. _bugs and feature requests: https://github.com/altair-viz/altair/issues/new/choose +.. _StackOverflow: https://stackoverflow.com/tags/altair diff --git a/doc/releases/changes.rst b/doc/releases/changes.rst index 859f703f4..9b5ff7544 100644 --- a/doc/releases/changes.rst +++ b/doc/releases/changes.rst @@ -1,7 +1,7 @@ .. _changes: -Altair Change Log -================= +Release Notes +============= Version 4.3.0 (unreleased) -------------------------- diff --git a/doc/user_guide/API.rst b/doc/user_guide/API.rst index 94f89230b..fcddd7f93 100644 --- a/doc/user_guide/API.rst +++ b/doc/user_guide/API.rst @@ -15,6 +15,7 @@ Top-Level Objects .. autosummary:: :toctree: generated/toplevel/ + :caption: Top-Level Objects :nosignatures: Chart @@ -32,6 +33,7 @@ Encoding Channels .. autosummary:: :toctree: generated/channels/ + :caption: Encoding Channels :nosignatures: Angle @@ -140,6 +142,7 @@ API Functions .. autosummary:: :toctree: generated/api/ + :caption: API Functions :nosignatures: binding @@ -170,6 +173,7 @@ Low-Level Schema Wrappers .. autosummary:: :toctree: generated/core/ + :caption: Low-Level Schema Wrappers :nosignatures: Aggregate diff --git a/doc/user_guide/data.rst b/doc/user_guide/data.rst index c76a742c9..7c6ac9fad 100644 --- a/doc/user_guide/data.rst +++ b/doc/user_guide/data.rst @@ -432,3 +432,51 @@ data before usage in Altair using GeoPandas for example as such: .. _Protocol geo_interface: https://gist.github.com/sgillies/2217756 .. _Packages supporting the geo_interface: https://github.com/mlaloux/Python-geo_interface-applications .. _The GeoJSON format: https://tools.ietf.org/html/rfc7946#section-3.1.9 + + +.. toctree:: + :maxdepth: 1 + :caption: User Guide + :hidden: + + self + encoding + marks + transform/index + interactions + interactions2 + configuration + compound_charts + scale_resolve + saving_charts + customization + times_and_dates + + +.. toctree:: + :maxdepth: 1 + :caption: Advanced Usage + :hidden: + + internals + importing + display_frontends + custom_renderers + data_transformers + + +.. toctree:: + :maxdepth: 1 + :caption: Case Studies + :hidden: + + case_studies/exploring-weather + + +.. toctree:: + :maxdepth: 1 + :caption: Getting Help + :hidden: + + faq + troubleshooting diff --git a/doc/user_guide/ecosystem.rst b/doc/user_guide/ecosystem.rst index 0ebdd52bf..e4ce96dae 100644 --- a/doc/user_guide/ecosystem.rst +++ b/doc/user_guide/ecosystem.rst @@ -1,7 +1,7 @@ .. _ecosystem: -Altair Ecosystem -================ +Ecosystem +========= This is a list of projects related to or built on top of Altair. We hope to make it easier to find these projects by listing them here. If you know of a project that should be added, please let us know. From 6f0affaa1854f7c4c3f5bbdf060a89b7ee2ab45c Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Mon, 21 Mar 2022 12:23:24 -0700 Subject: [PATCH 04/23] Move case studies and setup redirect --- doc/conf.py | 4 ++++ doc/{ => user_guide}/case_studies/exploring-weather.rst | 0 2 files changed, 4 insertions(+) rename doc/{ => user_guide}/case_studies/exploring-weather.rst (100%) diff --git a/doc/conf.py b/doc/conf.py index ff3033f6b..fc583c07e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -38,6 +38,7 @@ "altair.sphinxext.altairplot", "altair.sphinxext.altairgallery", "altair.sphinxext.schematable", + "sphinxext.rediraffe", ] altair_plot_links = {"editor": True, "source": False, "export": False} @@ -170,6 +171,9 @@ "gallery/index": ["sidebar-logo", "search-field", "sidebar-ethical-ads"] } +rediraffe_redirects = { + 'case_studies/exploring-weather.rst': 'user_guide/case_studies/exploring-weather.rst' +} # adapted from: http://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html # and # https://github.com/rtfd/sphinx_rtd_theme/issues/117 diff --git a/doc/case_studies/exploring-weather.rst b/doc/user_guide/case_studies/exploring-weather.rst similarity index 100% rename from doc/case_studies/exploring-weather.rst rename to doc/user_guide/case_studies/exploring-weather.rst From 273f6b7fb5e2df69c15df9b39baa41333490b38b Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Mon, 21 Mar 2022 12:24:26 -0700 Subject: [PATCH 05/23] Point to Vega-Lite docs for mark properties --- doc/user_guide/marks.rst | 56 +++++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/doc/user_guide/marks.rst b/doc/user_guide/marks.rst index 4fbcf547c..a82a17a53 100644 --- a/doc/user_guide/marks.rst +++ b/doc/user_guide/marks.rst @@ -10,36 +10,38 @@ used to map columns to visual attributes of the plot. The ``mark`` property is what specifies how exactly those attributes should be represented on the plot. -Altair provides a number of basic mark properties: - -========== ============================ =================================================== ==================================== -Mark Name Method Description Example -========== ============================ =================================================== ==================================== -arc :meth:`~Chart.mark_arc` A pie chart. :ref:`gallery_pie_chart` -area :meth:`~Chart.mark_area` A filled area plot. :ref:`gallery_simple_stacked_area_chart` -bar :meth:`~Chart.mark_bar` A bar plot. :ref:`gallery_simple_bar_chart` -circle :meth:`~Chart.mark_circle` A scatter plot with filled circles. :ref:`gallery_one_dot_per_zipcode` -geoshape :meth:`~Chart.mark_geoshape` A geographic shape :ref:`gallery_choropleth` -image :meth:`~Chart.mark_image` A scatter plot with image markers. :ref:`user-guide-image-mark` -line :meth:`~Chart.mark_line` A line plot. :ref:`gallery_simple_line_chart` -point :meth:`~Chart.mark_point` A scatter plot with configurable point shapes. :ref:`gallery_scatter_linked_brush` -rect :meth:`~Chart.mark_rect` A filled rectangle, used for heatmaps :ref:`gallery_simple_heatmap` -rule :meth:`~Chart.mark_rule` A vertical or horizontal line spanning the axis. :ref:`gallery_candlestick_chart` -square :meth:`~Chart.mark_square` A scatter plot with filled squares. N/A -text :meth:`~Chart.mark_text` A scatter plot with points represented by text. :ref:`gallery_bar_chart_with_labels` -tick :meth:`~Chart.mark_tick` A vertical or horizontal tick mark. :ref:`gallery_strip_plot` -trail :meth:`~Chart.mark_trail` A line with variable widths. :ref:`gallery_trail_marker` -========== ============================ =================================================== ==================================== +Altair provides a number of basic mark properties +(the mark properties column links to the Vega-Lite documentation +that allows you to interactively explore the effects of modifying each property): + +============================ =================================================== ======================================== ================================================================ +Mark Description Example Mark Properties +============================ =================================================== ======================================== ================================================================ +:meth:`~Chart.mark_arc` A pie chart. :ref:`gallery_pie_chart` `Vega-Lite Docs `_ +:meth:`~Chart.mark_area` A filled area plot. :ref:`gallery_simple_stacked_area_chart` `Vega-Lite Docs `_ +:meth:`~Chart.mark_bar` A bar plot. :ref:`gallery_simple_bar_chart` `Vega-Lite Docs `_ +:meth:`~Chart.mark_circle` A scatter plot with filled circles. :ref:`gallery_one_dot_per_zipcode` `Vega-Lite Docs `_ +:meth:`~Chart.mark_geoshape` A geographic shape :ref:`gallery_choropleth` `Vega-Lite Docs `_ +:meth:`~Chart.mark_image` A scatter plot with image markers. :ref:`user-guide-image-mark` `Vega-Lite Docs `_ +:meth:`~Chart.mark_line` A line plot. :ref:`gallery_simple_line_chart` `Vega-Lite Docs `_ +:meth:`~Chart.mark_point` A scatter plot with configurable point shapes. :ref:`gallery_scatter_linked_brush` `Vega-Lite Docs `_ +:meth:`~Chart.mark_rect` A filled rectangle, used for heatmaps :ref:`gallery_simple_heatmap` `Vega-Lite Docs `_ +:meth:`~Chart.mark_rule` A vertical or horizontal line spanning the axis. :ref:`gallery_candlestick_chart` `Vega-Lite Docs `_ +:meth:`~Chart.mark_square` A scatter plot with filled squares. N/A `Vega-Lite Docs `_ +:meth:`~Chart.mark_text` A scatter plot with points represented by text. :ref:`gallery_bar_chart_with_labels` `Vega-Lite Docs `_ +:meth:`~Chart.mark_tick` A vertical or horizontal tick mark. :ref:`gallery_strip_plot` `Vega-Lite Docs `_ +:meth:`~Chart.mark_trail` A line with variable widths. :ref:`gallery_trail_marker` `Vega-Lite Docs `_ +============================ =================================================== ======================================== ================================================================ In addition, Altair provides the following compound marks: -========== ============================== ================================ ================================== -Mark Name Method Description Example -========== ============================== ================================ ================================== -box plot :meth:`~Chart.mark_boxplot` A box plot. :ref:`gallery_boxplot` -error band :meth:`~Chart.mark_errorband` A continuous band around a line. :ref:`gallery_line_with_ci` -error bar :meth:`~Chart.mark_errorbar` An errorbar around a point. :ref:`gallery_errorbars_with_ci` -========== ============================== ================================ ================================== +============================== ================================ ================================== ================================================================ +Mark Description Example Mark Properties +============================== ================================ ================================== ================================================================ +:meth:`~Chart.mark_boxplot` A box plot. :ref:`gallery_boxplot` `Vega-Lite Docs `_ +:meth:`~Chart.mark_errorband` A continuous band around a line. :ref:`gallery_line_with_ci` `Vega-Lite Docs `_ +:meth:`~Chart.mark_errorbar` An errorbar around a point. :ref:`gallery_errorbars_with_ci` `Vega-Lite Docs `_ +============================== ================================ ================================== ================================================================ In Altair, marks can be most conveniently specified by the ``mark_*`` methods of the Chart object, which take optional keyword arguments that are passed to From d9d6c59160dcdea426c67ee3bd831b8e4d9a2df2 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Mon, 21 Mar 2022 17:28:56 -0700 Subject: [PATCH 06/23] Add headings and reorganize order of sections and headings for clarity --- doc/index.rst | 17 ++++--- doc/user_guide/data.rst | 22 ++------- doc/user_guide/encoding.rst | 85 ++++++++++++++++++++++++++------- doc/user_guide/interactions.rst | 4 +- 4 files changed, 84 insertions(+), 44 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 466a9db24..1942857eb 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -9,8 +9,7 @@ Altair: Declarative Visualization in Python :size: 15 Altair is a declarative statistical visualization library for Python, based on -Vega_ and Vega-Lite_, and the source is available on -`GitHub `_. +Vega_ and Vega-Lite_. With Altair, you can spend more time understanding your data and its meaning. Altair's API is simple, friendly and consistent and built on top of the @@ -19,9 +18,14 @@ beautiful and effective visualizations with a minimal amount of code. Altair is BSD-licensed and the source is available on `GitHub`_, where you can also report `bugs and feature requests`_. -For general questions, please use `StackOverflow`_. +For general questions, please ask on `StackOverflow`_ +using the `altair` tag. -You can browse this documentation via the link in the top navigation panel or by viewing the full site :ref:`genindex`. +You can browse this documentation +via the links in the top navigation panel +or by viewing the full site :ref:`genindex`. +In addition to reading this documentation page, +it can be helpful to also browse the `Vega-Lite documentation `_. .. toctree:: :maxdepth: 1 @@ -29,10 +33,11 @@ You can browse this documentation via the link in the top navigation panel or by Getting Started User Guide - gallery/index - user_guide/API + Examples + API user_guide/ecosystem releases/changes + Help .. _GitHub: http://github.com/altair-viz/altair .. _Git Issues: http://github.com/altair-viz/altair/issues diff --git a/doc/user_guide/data.rst b/doc/user_guide/data.rst index 7c6ac9fad..69b1fae5b 100644 --- a/doc/user_guide/data.rst +++ b/doc/user_guide/data.rst @@ -448,9 +448,10 @@ data before usage in Altair using GeoPandas for example as such: configuration compound_charts scale_resolve - saving_charts - customization times_and_dates + customization + configuration + saving_charts .. toctree:: @@ -463,20 +464,3 @@ data before usage in Altair using GeoPandas for example as such: display_frontends custom_renderers data_transformers - - -.. toctree:: - :maxdepth: 1 - :caption: Case Studies - :hidden: - - case_studies/exploring-weather - - -.. toctree:: - :maxdepth: 1 - :caption: Getting Help - :hidden: - - faq - troubleshooting diff --git a/doc/user_guide/encoding.rst b/doc/user_guide/encoding.rst index 3841d1234..de984f6ec 100644 --- a/doc/user_guide/encoding.rst +++ b/doc/user_guide/encoding.rst @@ -40,7 +40,8 @@ Encoding Channels Altair provides a number of encoding channels that can be useful in different circumstances; the following table summarizes them: -Position Channels: +Position Channels +^^^^^^^^^^^^^^^^^ ========== =================== ================================= =================================== Channel Altair Class Description Example @@ -63,7 +64,8 @@ theta :class:`Theta` The start arc angle :ref:`galler theta2 :class:`Theta2` The end arc angle (radian) :ref:`gallery_pacman_chart` ========== =================== ================================= =================================== -Mark Property Channels: +Mark Property Channels +^^^^^^^^^^^^^^^^^^^^^^ ============= ====================== ============================== ========================================= Channel Altair Class Description Example @@ -82,7 +84,8 @@ strokeOpacity :class:`StrokeOpacity` The opacity of the line N/A strokeWidth :class:`StrokeWidth` The width of the line N/A ============= ====================== ============================== ========================================= -Text and Tooltip Channels: +Text and Tooltip Channels +^^^^^^^^^^^^^^^^^^^^^^^^^ ======= ================ ======================== ========================================= Channel Altair Class Description Example @@ -92,7 +95,8 @@ key :class:`Key` -- N/A tooltip :class:`Tooltip` The tooltip value :ref:`gallery_scatter_tooltips` ======= ================ ======================== ========================================= -Hyperlink Channel: +Hyperlink Channel +^^^^^^^^^^^^^^^^^ ======= ================ ======================== ========================================= Channel Altair Class Description Example @@ -100,7 +104,8 @@ Channel Altair Class Description Example href :class:`Href` Hyperlink for points :ref:`gallery_scatter_href` ======= ================ ======================== ========================================= -Level of Detail Channel: +Level of Detail Channel +^^^^^^^^^^^^^^^^^^^^^^^ ======= ================ =============================== ========================================= Channel Altair Class Description Example @@ -108,7 +113,8 @@ Channel Altair Class Description Example detail :class:`Detail` Additional property to group by :ref:`gallery_ranged_dot_plot` ======= ================ =============================== ========================================= -Order Channel: +Order Channel +^^^^^^^^^^^^^ ======= ================ ============================= ===================================== Channel Altair Class Description Example @@ -116,7 +122,8 @@ Channel Altair Class Description Example order :class:`Order` Sets the order of the marks :ref:`gallery_connected_scatterplot` ======= ================ ============================= ===================================== -Facet Channels: +Facet Channels +^^^^^^^^^^^^^^ ======= ================ =============================================== ============================================= Channel Altair Class Description Example @@ -254,64 +261,105 @@ titles, binning parameters, aggregation, sorting, and many more. The particular options that are available vary by encoding type; the various options are listed below. +X and Y +^^^^^^^ The :class:`X` and :class:`Y` encodings accept the following options: .. altair-object-table:: altair.PositionFieldDef +Color, Fill, and Stroke +^^^^^^^^^^^^^^^^^^^^^^^ + The :class:`Color`, :class:`Fill`, and :class:`Stroke` encodings accept the following options: .. altair-object-table:: altair.FieldOrDatumDefWithConditionMarkPropFieldDefGradientstringnull +Shape +^^^^^ + The :class:`Shape` encoding accepts the following options: .. altair-object-table:: altair.FieldOrDatumDefWithConditionMarkPropFieldDefTypeForShapestringnull +Order +^^^^^ + +The :class:`Order` encoding accepts the following options: + +.. altair-object-table:: altair.OrderFieldDef + +Angle, FillOpacity, Opacity, Size, StrokeOpacity, and StrokeWidth +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + The :class:`Angle`, :class:`FillOpacity`, :class:`Opacity`, :class:`Size`, :class:`StrokeOpacity`, and :class:`StrokeWidth` encodings accept the following options: .. altair-object-table:: altair.FieldOrDatumDefWithConditionMarkPropFieldDefnumber +StrokeDash +^^^^^^^^^^ + +The :class:`StrokeDash` encoding accepts the following options: + +.. altair-object-table:: altair.FieldOrDatumDefWithConditionMarkPropFieldDefnumberArray + +Row and Column +^^^^^^^^^^^^^^ + The :class:`Row` and :class:`Column`, and :class:`Facet` encodings accept the following options: .. altair-object-table:: altair.RowColumnEncodingFieldDef +Facet +^^^^^ + The :class:`Facet` encoding accepts the following options: .. altair-object-table:: altair.FacetEncodingFieldDef +Text +^^^^ + The :class:`Text` encoding accepts the following options: .. altair-object-table:: altair.FieldOrDatumDefWithConditionStringFieldDefText +Description, Href, Tooltip, Url +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + The :class:`Description`, :class:`Href`, :class:`Tooltip`, and :class:`Url` encodings accept the following options: .. altair-object-table:: altair.StringFieldDefWithCondition +Detail and Key +^^^^^^^^^^^^^^ + The :class:`Detail` and :class:`Key` encodings accept the following options: .. altair-object-table:: altair.FieldDefWithoutScale +Latitude and Longitude +^^^^^^^^^^^^^^^^^^^^^^ + The :class:`Latitude` and :class:`Longitude` encodings accept the following options: .. altair-object-table:: altair.LatLongFieldDef -The :class:`Latitude2`, :class:`Longitude2`, :class:`Radius2`, :class:`Theta2`, :class:`X2`, :class:`Y2`, :class:`XError`, :class:`YError`, -:class:`XError2`, and :class:`YError2` encodings accept the following options: - -.. altair-object-table:: altair.SecondaryFieldDef - -The :class:`Order` encoding accepts the following options: - -.. altair-object-table:: altair.OrderFieldDef +Radius and Theta +^^^^^^^^^^^^^^^^ The :class:`Radius` and :class:`Theta` encodings accept the following options: .. altair-object-table:: altair.PositionFieldDefBase -The :class:`StrokeDash` encoding accepts the following options: +Latitude2, Longitude2, Radius2, Theta2, X2, Y2, XError, YError, XError2, and YError2 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The :class:`Latitude2`, :class:`Longitude2`, :class:`Radius2`, :class:`Theta2`, :class:`X2`, :class:`Y2`, :class:`XError`, :class:`YError`, :class:`XError2`, and :class:`YError2` encodings accept the following options: + +.. altair-object-table:: altair.SecondaryFieldDef -.. altair-object-table:: altair.FieldOrDatumDefWithConditionMarkPropFieldDefnumberArray .. _encoding-aggregates: @@ -368,6 +416,9 @@ represents the mean of a third quantity, such as acceleration: color='average(Acceleration):Q' ) +Aggregation Functions +^^^^^^^^^^^^^^^^^^^^^ + In addition to ``count`` and ``average``, there are a large number of available aggregation functions built into Altair; they are listed in the following table: diff --git a/doc/user_guide/interactions.rst b/doc/user_guide/interactions.rst index eecff9c9d..847362dfe 100644 --- a/doc/user_guide/interactions.rst +++ b/doc/user_guide/interactions.rst @@ -2,8 +2,8 @@ .. _user-guide-interactions: -Bindings, Selections, Conditions: Making Charts Interactive -=========================================================== +Interactive Charts: Bindings, Selections, Conditions +==================================================== One of the unique features of Altair, inherited from Vega-Lite, is a declarative grammar of not just visualization, but *interaction*. There are three From 9de2dfb1fc64a2fda956a34c99d262abce65c7cd Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Mon, 21 Mar 2022 18:34:14 -0700 Subject: [PATCH 07/23] Remove ToC dropdown error created from empty ToC --- altair/sphinxext/altairgallery.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/altair/sphinxext/altairgallery.py b/altair/sphinxext/altairgallery.py index 0a768e831..2dc4bd311 100644 --- a/altair/sphinxext/altairgallery.py +++ b/altair/sphinxext/altairgallery.py @@ -105,9 +105,6 @@ {% if strict %}:strict:{% endif %} {{ code | indent(4) }} - -.. toctree:: - :hidden: """ ) From 411c9508ea5e7ebee331a7e6b01e2f08f6848b52 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Mon, 21 Mar 2022 19:41:14 -0700 Subject: [PATCH 08/23] Improve ToC for galleries and move seattle weather to original location --- altair/sphinxext/altairgallery.py | 13 ++++++++----- .../case_studies/exploring-weather.rst | 9 ++++++++- doc/conf.py | 1 - 3 files changed, 16 insertions(+), 7 deletions(-) rename doc/{user_guide => }/case_studies/exploring-weather.rst (99%) diff --git a/altair/sphinxext/altairgallery.py b/altair/sphinxext/altairgallery.py index 2dc4bd311..72bb47068 100644 --- a/altair/sphinxext/altairgallery.py +++ b/altair/sphinxext/altairgallery.py @@ -67,13 +67,16 @@
+{% endfor %} + + .. toctree:: - :hidden: -{% for example in group %} - {{ example.name }} -{%- endfor %} + :maxdepth: 2 + :caption: Examples + :hidden: -{% endfor %} + Gallery + Tutorials <../case_studies/exploring-weather> """ ) diff --git a/doc/user_guide/case_studies/exploring-weather.rst b/doc/case_studies/exploring-weather.rst similarity index 99% rename from doc/user_guide/case_studies/exploring-weather.rst rename to doc/case_studies/exploring-weather.rst index b85609e23..69309a2f6 100644 --- a/doc/user_guide/case_studies/exploring-weather.rst +++ b/doc/case_studies/exploring-weather.rst @@ -1,7 +1,7 @@ .. _exploring-weather: Exploring Seattle Weather -========================= +------------------------- (This tutorial is adapted from `Vega-Lite's documentation `_) @@ -266,3 +266,10 @@ If you want to further customize your charts, you can refer to Altair's :ref:`API`. .. _Pandas: http://pandas.pydata.org/ + + +.. toctree:: + :maxdepth: 1 + :hidden: + + self diff --git a/doc/conf.py b/doc/conf.py index fc583c07e..8d1429164 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -168,7 +168,6 @@ html_sidebars = { "**": ["sidebar-logo", "search-field", "sidebar-nav-bs", "sidebar-ethical-ads"], - "gallery/index": ["sidebar-logo", "search-field", "sidebar-ethical-ads"] } rediraffe_redirects = { From 193f7cc4ffaafd695214d6b1d98fccc21122218a Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Mon, 21 Mar 2022 19:44:37 -0700 Subject: [PATCH 09/23] Do not use rediraffe since it is now not needed Also move a couple of section inside conf.py --- doc/conf.py | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 8d1429164..bf65ce8f7 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -38,7 +38,7 @@ "altair.sphinxext.altairplot", "altair.sphinxext.altairgallery", "altair.sphinxext.schematable", - "sphinxext.rediraffe", + # "sphinxext.rediraffe", ] altair_plot_links = {"editor": True, "source": False, "export": False} @@ -133,7 +133,11 @@ # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -# html_theme_options = {} +html_theme_options = { +"navbar_start": ["navbar-project"], +"navbar_center": ["navbar-nav"], +"navbar_end": ["navbar-icon-links"], +} # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] @@ -159,20 +163,6 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static", "_images"] - -html_theme_options = { -"navbar_start": ["navbar-project"], -"navbar_center": ["navbar-nav"], -"navbar_end": ["navbar-icon-links"], -} - -html_sidebars = { - "**": ["sidebar-logo", "search-field", "sidebar-nav-bs", "sidebar-ethical-ads"], -} - -rediraffe_redirects = { - 'case_studies/exploring-weather.rst': 'user_guide/case_studies/exploring-weather.rst' -} # adapted from: http://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html # and # https://github.com/rtfd/sphinx_rtd_theme/issues/117 @@ -195,7 +185,15 @@ def setup(app): # html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -# html_sidebars = {} +html_sidebars = { + "**": ["sidebar-logo", "search-field", "sidebar-nav-bs", "sidebar-ethical-ads"], +} + +# Redirection of old page locations via the rediraffe sphinx-extension +# It seems like only pages can be redirected, not headings within pages +# rediraffe_redirects = { +# 'case_studies/exploring-weather.rst': 'user_guide/case_studies/exploring-weather.rst' +# } # Additional templates that should be rendered to pages, maps page names to # template names. From 901320f8929476884109daab93e383bea8d19ea4 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Mon, 21 Mar 2022 19:44:51 -0700 Subject: [PATCH 10/23] Rename API Reference topbar entry --- doc/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/index.rst b/doc/index.rst index 1942857eb..800ef06ab 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -34,7 +34,7 @@ it can be helpful to also browse the `Vega-Lite documentation User Guide Examples - API + Reference user_guide/ecosystem releases/changes Help From c2bff55c524b62b6f23ce8544db7ab751b9dd5a4 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Mon, 21 Mar 2022 19:45:25 -0700 Subject: [PATCH 11/23] Move the `...` button next to each chart --- doc/_static/altair-plot.css | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/_static/altair-plot.css b/doc/_static/altair-plot.css index 06e9a91b7..a80013846 100644 --- a/doc/_static/altair-plot.css +++ b/doc/_static/altair-plot.css @@ -8,6 +8,5 @@ .vega-embed { margin-bottom: 20px; margin-top: 20px; - width: 100%; } From 4c5093cc219ebac11c698f2fde8b0e122a1f8ffc Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Mon, 21 Mar 2022 19:59:59 -0700 Subject: [PATCH 12/23] Add getting help landing page --- doc/user_guide/getting_help.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 doc/user_guide/getting_help.rst diff --git a/doc/user_guide/getting_help.rst b/doc/user_guide/getting_help.rst new file mode 100644 index 000000000..f033066af --- /dev/null +++ b/doc/user_guide/getting_help.rst @@ -0,0 +1,28 @@ +Getting Help +============ + +Altair is BSD-licensed and the source is available on `GitHub`_, +where you can also report `bugs and feature requests`_. +For general questions, please ask on `StackOverflow`_ +using the `altair` tag. + +You can browse this documentation +via the links in the top navigation panel +or by viewing the full site :ref:`genindex`. +In addition to reading this documentation page, +it can be helpful to also browse the `Vega-Lite documentation `_. + +.. toctree:: + :maxdepth: 1 + :caption: Getting Help + :hidden: + + faq + troubleshooting + +.. _GitHub: http://github.com/altair-viz/altair +.. _Git Issues: http://github.com/altair-viz/altair/issues +.. _Vega: http://vega.github.io/vega +.. _Vega-Lite: http://vega.github.io/vega-lite +.. _bugs and feature requests: https://github.com/altair-viz/altair/issues/new/choose +.. _StackOverflow: https://stackoverflow.com/tags/altair From 0a651728f2935eec5733f6516656487c548d2cf3 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Mon, 21 Mar 2022 20:46:23 -0700 Subject: [PATCH 13/23] Format to pass flake8 tests --- doc/conf.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index bf65ce8f7..9caa858f6 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -134,9 +134,9 @@ # further. For a list of options available for each theme, see the # documentation. html_theme_options = { -"navbar_start": ["navbar-project"], -"navbar_center": ["navbar-nav"], -"navbar_end": ["navbar-icon-links"], + "navbar_start": ["navbar-project"], + "navbar_center": ["navbar-nav"], + "navbar_end": ["navbar-icon-links"], } # Add any paths that contain custom themes here, relative to this directory. @@ -163,6 +163,7 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static", "_images"] + # adapted from: http://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html # and # https://github.com/rtfd/sphinx_rtd_theme/issues/117 @@ -170,6 +171,7 @@ def setup(app): app.add_css_file("theme_overrides.css") app.add_css_file("custom.css") + # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied # directly to the root of the documentation. From 42f29058ebd3f5706920a2446e1cacf64c1d6933 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Mon, 21 Mar 2022 21:08:15 -0700 Subject: [PATCH 14/23] Make gallery and mini-gallery paths relative so that images show up --- altair/sphinxext/altairgallery.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/altair/sphinxext/altairgallery.py b/altair/sphinxext/altairgallery.py index 72bb47068..e0bb5ac39 100644 --- a/altair/sphinxext/altairgallery.py +++ b/altair/sphinxext/altairgallery.py @@ -59,7 +59,7 @@ {% for example in group %} - + {{ example.title }} {% endfor %} @@ -87,7 +87,7 @@
{% for example in examples %} - + {% endfor %}
From c1d1b552a4499850b87debbc960ae6136332f2fc Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Tue, 22 Mar 2022 19:12:29 -0700 Subject: [PATCH 15/23] Compute current copyright year --- doc/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 9caa858f6..ebb4ca716 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -14,6 +14,7 @@ import sys import os +from datetime import datetime # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -66,7 +67,7 @@ # General information about the project. project = "Altair" -copyright = "2016-2020, Altair Developers" +copyright = "2016-{}, Altair Developers".format(datetime.now().year) author = "Brian Granger and Jake VanderPlas" # The version info for the project you're documenting, acts as replacement for From 073526f38bc9e901c6792497d56fa9bb3aedf904 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Thu, 24 Mar 2022 23:10:18 -0700 Subject: [PATCH 16/23] Use recommend way to install via pip Remove dollar sign for easy copy paste --- altair/sphinxext/altairgallery.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/altair/sphinxext/altairgallery.py b/altair/sphinxext/altairgallery.py index e0bb5ac39..7c8dea866 100644 --- a/altair/sphinxext/altairgallery.py +++ b/altair/sphinxext/altairgallery.py @@ -45,7 +45,7 @@ .. code-block:: none - $ pip install vega_datasets + python -m pip install vega_datasets {% for grouper, group in examples %} From 27f0789cbf9b3492c945f9c83c5b8c8807e562d4 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Tue, 22 Mar 2022 20:29:05 -0700 Subject: [PATCH 17/23] Adjust title positioning for narrow screens/windows --- doc/_static/custom.css | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/doc/_static/custom.css b/doc/_static/custom.css index 94707e008..36fe8f625 100644 --- a/doc/_static/custom.css +++ b/doc/_static/custom.css @@ -40,7 +40,27 @@ table.docutils td li { font-size: 26px !important; font-weight: 800 !important; color: #fff !important; - margin-left: 180%; + text-align: center; + width: 100%; +} +/* There is a small jump in the title positionin when the navbar transitions full */ +/* title to the collapse button. 27% width here makes that jump as discrete as possible */ +div#navbar-start { + width: 27%; + margin-left: 0px !important; +} +/* Adjust the title position for narrow screens, such as mobile phones. */ +/* This also prevents that the collapse button stacks under the title, */ +/* which would cover a bit of the logo. 719px makes the title */ +/* switch to narrow screen layout at the same time as the rest of the page. */ +@media only screen and (max-width: 719px) { + div#navbar-start { + width: 60%; + margin-left: 0px !important; + } + .navbar-light p.title { + text-align: right; + } } /* Version number in the same darkblue color as other text */ From cb197d16f7a3a2c78f00172c75702f0fd25bb13a Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Thu, 24 Mar 2022 23:01:27 -0700 Subject: [PATCH 18/23] Remove use of deprecated functionality from the documentation --- doc/case_studies/exploring-weather.rst | 2 +- doc/user_guide/compound_charts.rst | 6 +- doc/user_guide/interactions.rst | 88 ++++++++++++-------------- doc/user_guide/transform/filter.rst | 4 +- doc/user_guide/transform/pivot.rst | 4 +- 5 files changed, 48 insertions(+), 56 deletions(-) diff --git a/doc/case_studies/exploring-weather.rst b/doc/case_studies/exploring-weather.rst index 69309a2f6..6146de4fb 100644 --- a/doc/case_studies/exploring-weather.rst +++ b/doc/case_studies/exploring-weather.rst @@ -237,7 +237,7 @@ of the selection (for more information on selections, see ).properties( width=600, height=400 - ).add_selection( + ).add_parameter( brush ) diff --git a/doc/user_guide/compound_charts.rst b/doc/user_guide/compound_charts.rst index ecf711990..d85f322ba 100644 --- a/doc/user_guide/compound_charts.rst +++ b/doc/user_guide/compound_charts.rst @@ -195,7 +195,7 @@ with a ``brush`` selection to add interaction: lower = base.properties( height=60 - ).add_selection(brush) + ).add_parameter(brush) alt.vconcat(upper, lower) @@ -362,7 +362,7 @@ layered chart with a hover selection: .. altair-plot:: - hover = alt.selection_single(on='mouseover', nearest=True, empty='none') + hover = alt.selection_point(on='mouseover', nearest=True, empty='none') base = alt.Chart(iris).encode( x='petalLength:Q', @@ -373,7 +373,7 @@ layered chart with a hover selection: height=180, ) - points = base.mark_point().add_selection( + points = base.mark_point().add_parameter( hover ) diff --git a/doc/user_guide/interactions.rst b/doc/user_guide/interactions.rst index 847362dfe..d6f4947d8 100644 --- a/doc/user_guide/interactions.rst +++ b/doc/user_guide/interactions.rst @@ -60,7 +60,7 @@ property: x='Miles_per_Gallon:Q', y='Horsepower:Q', color='Origin:N' - ).add_selection( + ).add_parameter( brush ) @@ -83,7 +83,7 @@ for points outside the selection: x='Miles_per_Gallon:Q', y='Horsepower:Q', color=alt.condition(brush, 'Origin:N', alt.value('lightgray')) - ).add_selection( + ).add_parameter( brush ) @@ -105,7 +105,7 @@ tied to ``"Miles_per_Gallon"`` ).properties( width=250, height=250 - ).add_selection( + ).add_parameter( brush ) @@ -131,14 +131,14 @@ We can modify the brush definition, and leave the rest of the code unchanged: ).properties( width=250, height=250 - ).add_selection( + ).add_parameter( brush ) chart.encode(x='Acceleration:Q') | chart.encode(x='Miles_per_Gallon:Q') -Selection Types: Interval, Single, Multi -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Selection Types: Interval and Point +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ With this interesting example under our belt, let's take a more systematic look at some of the types of selections available in Altair. @@ -161,7 +161,7 @@ selection: ).properties( width=300, height=180 - ).add_selection( + ).add_parameter( selector ) @@ -200,7 +200,7 @@ chart scales; this is how Altair plots can be made interactive: x='Horsepower:Q', y='Miles_per_Gallon:Q', color='Origin:N' - ).add_selection( + ).add_parameter( scales ) @@ -208,15 +208,15 @@ Because this is such a common pattern, Altair provides the :meth:`Chart.interact method which creates such a selection more concisely. -Single Selections -^^^^^^^^^^^^^^^^^ -A *single* selection allows you to select a single chart element at a time using -mouse actions. By default, points are selected on click: +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:: - single = alt.selection_single() - make_example(single) + point = alt.selection_point() + make_example(point) By changing some arguments, we can select points on mouseover rather than on click. We can also set the ``nearest`` flag to ``True`` so that the nearest @@ -224,32 +224,24 @@ point is highlighted: .. altair-plot:: - single_nearest = alt.selection_single(on='mouseover', nearest=True) - make_example(single_nearest) + point_nearest = alt.selection_point(on='mouseover', nearest=True) + make_example(point_nearest) -Multiple Selections -^^^^^^^^^^^^^^^^^^^ -A *multi* selection is similar to a *single* selection, but it allows for -multiple chart objects to be selected at once. +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: -.. altair-plot:: - - multi = alt.selection_multi() - make_example(multi) - -In addition to the options seen in :func:`selection_single`, the multi selection -accepts the ``toggle`` parameter, which controls whether points can be removed -from the selection once they are added. - -For example, here is a plot where you can "paint" the chart objects by hovering -over them with your mouse: +The point selection accepts the ``toggle`` parameter, +which controls whether points can be removed from the selection +once they are added. +For example, +here is a plot where you can "paint" the chart objects +by hovering over them with your mouse: .. altair-plot:: - multi_mouseover = alt.selection_multi(on='mouseover', toggle=False, empty='none') - make_example(multi_mouseover) + point_mouseover = alt.selection_point(on='mouseover', toggle=False, empty='none') + make_example(point_mouseover) Composing Multiple Selections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -283,7 +275,7 @@ selection. x='Cylinders:O', y='Origin:O', color=alt.condition(alex | morgan, 'count()', alt.ColorValue("grey")) - ).add_selection( + ).add_parameter( alex, morgan ).properties( width=300, @@ -313,7 +305,7 @@ with a matching ``Origin``. .. altair-plot:: - selection = alt.selection_multi(fields=['Origin']) + selection = alt.selection_point(fields=['Origin']) color = alt.condition(selection, alt.Color('Origin:N', legend=None), alt.value('lightgray')) @@ -328,7 +320,7 @@ with a matching ``Origin``. legend = alt.Chart(cars).mark_point().encode( y=alt.Y('Origin:N', axis=alt.Axis(orient='right')), color=color - ).add_selection( + ).add_parameter( selection ) @@ -346,7 +338,7 @@ cylinders: .. altair-plot:: - selection = alt.selection_multi(fields=['Origin', 'Cylinders']) + selection = alt.selection_point(fields=['Origin', 'Cylinders']) color = alt.condition(selection, alt.Color('Origin:N', legend=None), alt.value('lightgray')) @@ -362,7 +354,7 @@ cylinders: y=alt.Y('Origin:N', axis=alt.Axis(orient='right')), x='Cylinders:O', color=color - ).add_selection( + ).add_parameter( selection ) @@ -375,19 +367,19 @@ Binding: Adding Data Driven Inputs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ With an understanding of the selection types and conditions, you can now add data-driven input elements to the charts using the ``bind`` option. As specified by `Vega-lite binding `_, selections can be bound two-ways: -1. Single selections can be bound directly to an input element, *for example, a radio button.* +1. Point selections can be bound directly to an input element, *for example, a radio button.* 2. Interval selections which can be bound to scale, *for example, zooming in on a map.* Input Element Binding ^^^^^^^^^^^^^^^^^^^^^ -With single selections, an input element can be added to the chart to establish a binding between the input and the selection. +With point selections, an input element can be added to the chart to establish a binding between the input and the selection. For instance, using our example from above a dropdown can be used to highlight cars from a specific ``origin`` : .. altair-plot:: input_dropdown = alt.binding_select(options=['Europe','Japan','USA'], name='Country') - selection = alt.selection_single(fields=['Origin'], bind=input_dropdown) + selection = alt.selection_point(fields=['Origin'], bind=input_dropdown) color = alt.condition(selection, alt.Color('Origin:N', legend=None), alt.value('lightgray')) @@ -397,7 +389,7 @@ For instance, using our example from above a dropdown can be used to highlight c y='Miles_per_Gallon:Q', color=color, tooltip='Name:N' - ).add_selection( + ).add_parameter( selection ) @@ -424,14 +416,14 @@ Bindings and input elements can also be used to filter data on the client side. .. altair-plot:: input_dropdown = alt.binding_select(options=['Europe','Japan','USA'], name='Country') - selection = alt.selection_single(fields=['Origin'], bind=input_dropdown) + selection = alt.selection_point(fields=['Origin'], bind=input_dropdown) alt.Chart(cars).mark_point().encode( x='Horsepower:Q', y='Miles_per_Gallon:Q', color='Origin:N', tooltip='Name:N' - ).add_selection( + ).add_parameter( selection ).transform_filter( selection @@ -451,7 +443,7 @@ With interval selections, the ``bind`` property can be set to the value of ``"sc y='Miles_per_Gallon:Q', color='Origin:N', tooltip='Name:N' - ).add_selection( + ).add_parameter( selection ) @@ -476,8 +468,8 @@ points based on whether they are smaller or larger than the value: }) slider = alt.binding_range(min=0, max=100, step=1, name='cutoff:') - selector = alt.selection_single(name="SelectorName", fields=['cutoff'], - bind=slider, init={'cutoff': 50}) + selector = alt.selection_point(name="SelectorName", fields=['cutoff'], + bind=slider, value=[{'cutoff': 50}]) alt.Chart(df).mark_point().encode( x='xval', @@ -486,7 +478,7 @@ points based on whether they are smaller or larger than the value: alt.datum.xval < selector.cutoff, alt.value('red'), alt.value('blue') ) - ).add_selection( + ).add_parameter( selector ) diff --git a/doc/user_guide/transform/filter.rst b/doc/user_guide/transform/filter.rst index b4e2757f0..733d9a1dd 100644 --- a/doc/user_guide/transform/filter.rst +++ b/doc/user_guide/transform/filter.rst @@ -133,7 +133,7 @@ to select the data to be shown in the top chart: from vega_datasets import data pop = data.population.url - selection = alt.selection_multi(fields=['year']) + selection = alt.selection_point(fields=['year']) top = alt.Chart().mark_line().encode( x='age:O', @@ -151,7 +151,7 @@ to select the data to be shown in the top chart: color=alt.condition(selection, alt.value('steelblue'), alt.value('lightgray')) ).properties( width=600, height=100 - ).add_selection( + ).add_parameter( selection ) diff --git a/doc/user_guide/transform/pivot.rst b/doc/user_guide/transform/pivot.rst index c095b54c7..4b5ce297f 100644 --- a/doc/user_guide/transform/pivot.rst +++ b/doc/user_guide/transform/pivot.rst @@ -49,7 +49,7 @@ values on multiple lines: source = data.stocks() base = alt.Chart(source).encode(x='date:T') columns = sorted(source.symbol.unique()) - selection = alt.selection_single( + selection = alt.selection_point( fields=['date'], nearest=True, on='mouseover', empty='none', clear='mouseout' ) @@ -61,7 +61,7 @@ values on multiple lines: ).mark_rule().encode( opacity=alt.condition(selection, alt.value(0.3), alt.value(0)), tooltip=[alt.Tooltip(c, type='quantitative') for c in columns] - ).add_selection(selection) + ).add_parameter(selection) lines + points + rule From 73238f307506e55201ddbef5914144bdf4d907b1 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Fri, 25 Mar 2022 01:32:15 -0700 Subject: [PATCH 19/23] Merge interactions 1 and 2 --- doc/user_guide/data.rst | 2 - doc/user_guide/interactions.rst | 237 ++++++++++++++++++++++++++++--- doc/user_guide/interactions2.rst | 219 ---------------------------- 3 files changed, 217 insertions(+), 241 deletions(-) delete mode 100644 doc/user_guide/interactions2.rst diff --git a/doc/user_guide/data.rst b/doc/user_guide/data.rst index 69b1fae5b..7cbcfca0b 100644 --- a/doc/user_guide/data.rst +++ b/doc/user_guide/data.rst @@ -444,8 +444,6 @@ data before usage in Altair using GeoPandas for example as such: marks transform/index interactions - interactions2 - configuration compound_charts scale_resolve times_and_dates diff --git a/doc/user_guide/interactions.rst b/doc/user_guide/interactions.rst index d6f4947d8..5d40a9266 100644 --- a/doc/user_guide/interactions.rst +++ b/doc/user_guide/interactions.rst @@ -2,33 +2,146 @@ .. _user-guide-interactions: -Interactive Charts: Bindings, Selections, Conditions +Interactive Charts: Parameters, Conditions, Bindings ==================================================== One of the unique features of Altair, inherited from Vega-Lite, is a -declarative grammar of not just visualization, but *interaction*. There are three -core concepts of this grammar: - -- the :func:`selection` object which captures interactions from the mouse or through other inputs to effect the chart. Inputs can either be events like mouse clicks or drags. Inputs can also be elements like a drop-down, radio button or slider. Selections can be used alone but if you want to change any element of your chart you will need to connect them to a *condition*. -- the :func:`condition` function takes the selection input and changes an element of the chart based on that input. -- the ``bind`` property of a selection which establishes a two-way binding between the selection and an input element of your chart. +declarative grammar of not just visualization, but *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 a simple variable or the more complex :func:`selection` + that map user input (e.g., mouse clicks and drags) to data queries. +- The :func:`condition` function takes the selection input + and changes an element of the chart based on that input. +- The ``bind`` property of selections establishes a two-way binding + between the selection and an input element of your chart, + such as a drop-down, radio button or slider. Interactive charts can use one or more of these elements to create rich interactivity between the viewer and the data. -Selections: Building Blocks of Interactions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Parameters: Building Blocks of Interaction +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Interactivity in Altair is built around *parameters*, of which there are two types: variables and selections. We introduce these concepts through a series examples. + +.. note:: + + This material was changed considerably with the release of Altair 5. In particular, Altair 4 had selections but not variables, and the term ``parameter`` first appeared in Altair 5. + +.. _basic variable: + +Variables: Storing and Reusing Values +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Variables are the simplest forms of parameters can take. +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='Miles_per_Gallon:Q', + y='Horsepower:Q', + color='Origin:N' + ) + +We can create a variable parameter using :func:`parameter`, and assign that parameter a default value of 0.1 using the ``value`` property, as follows: + +.. altair-plot:: + :output: none + + op_var = alt.parameter(value=0.1) + +In order to use this variable in the chart specification, we explicitly add it to the chart using the :meth:`Chart.add_parameter` method, and we can then reference the variable within the chart specification. Here we set the opacity using our ``op_var`` parameter. + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + cars = data.cars.url + + op_var = alt.parameter(value=0.1) + + alt.Chart(cars).mark_circle(opacity=op_var).encode( + x='Miles_per_Gallon:Q', + y='Horsepower:Q', + color='Origin:N' + ).add_parameter( + op_var + ) + +It's reasonable to ask whether all this effort is necessary. Here is a more natural way to accomplish the same thing. We avoid the use of both :func:`alt.parameter` and ``add_parameter``. + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + cars = data.cars.url + + op_var2 = 0.1 + + alt.Chart(cars).mark_circle(opacity=op_var2).encode( + x='Miles_per_Gallon:Q', + y='Horsepower:Q', + color='Origin:N' + ) + +The benefit of using :func:`alt.parameter` doesn't become apparent until we incorporate an additional component, such as in the following, where 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:: + + import altair as alt + from vega_datasets import data + + cars = data.cars.url + + slider = alt.binding_range(min=0, max=1, step=0.05, name='opacity:') + op_var = alt.parameter(value=0.1, bind=slider) + alt.Chart(cars).mark_circle(opacity=op_var).encode( + x='Miles_per_Gallon:Q', + y='Horsepower:Q', + color='Origin:N' + ).add_parameter( + op_var + ) -Selections in Altair come in a few flavors, and they can be *bound* to +Now we can dynamically change the opacity of the points in our chart using the slider. A noteworthy aspect of this chart is that these effects are controlled entirely within your web browser. Once the Vega-Lite chart specification has been created by Altair, the result is an interactive chart, and that interactivity no longer requires a running Python environment. + +The above example includes some aspects which occur frequently when creating interactive charts in Altair: + +1. Creating a variable parameter using :func:`parameter`. +2. Attaching the parameter to a chart using the :meth:`Chart.add_parameter` method. +3. Binding the parameter to an input widget (such as the slider above) using the parameter's ``bind`` property. + + +Selections: Capturing Inputs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Selections parameters capture inputs such as mouse clicks and they can be *bound* to particular charts or sub-charts in your visualization, then referenced in other parts of the visualization. +There are two types of selections: +:func:`selection_interval` and :func:`selection_point`. -Example: Linked-Brush Scatter-Plot -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Here we will create a simple chart and then add an selection interval to it. +We could create a selection interval via ``alt.parameter(select="interval")``, +but it is more convenient to use the shorter ``alt.selection_interval`` +(and this also matches the syntax that was used in Altair 4). -As a motivation, let's create a simple chart and then add some selections -to it. Here is a simple scatter-plot created from the ``cars`` dataset: +Here is a simple scatter-plot created from the ``cars`` dataset: .. altair-plot:: @@ -67,10 +180,14 @@ property: 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. -Conditions: Making the chart respond +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_parameter``. + +Conditions: Making the Chart Respond ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This is neat, but the selection doesn't actually *do* anything yet. +The example above is neat, but the selection doesn't actually *do* anything yet. To use this selection, we need to reference it in some way within the chart. Here, we will use the :func:`condition` function to create a conditional color encoding: we'll tie the color to the ``"Origin"`` @@ -89,6 +206,15 @@ for points outside the selection: As you can see, with this simple change, the color of the points responds to the selection. +In the sample 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. @@ -140,8 +266,8 @@ We can modify the brush definition, and leave the rest of the code unchanged: Selection Types: Interval and Point ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -With this interesting example under our belt, let's take a more systematic -look at some of the types of selections available in Altair. +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 @@ -363,6 +489,48 @@ cylinders: By fine-tuning the behavior of selections in this way, they can be used to create a wide variety of linked interactive chart types. + +Filtering Data with Selections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Using a selection parameter to filter data works in much the same way +as using it within ``alt.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 selection in the upper chart. +You can explore how the counts changes 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_circle().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q', + color='Origin:N' + ).add_parameter( + brush + ) + + bars = alt.Chart(cars).mark_bar().encode( + x='count()', + y='Origin:N', + color='Origin:N' + ).transform_filter( + brush + ) + + points & bars + + Binding: Adding Data Driven Inputs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ With an understanding of the selection types and conditions, you can now add data-driven input elements to the charts using the ``bind`` option. As specified by `Vega-lite binding `_, selections can be bound two-ways: @@ -378,7 +546,7 @@ For instance, using our example from above a dropdown can be used to highlight c .. altair-plot:: - input_dropdown = alt.binding_select(options=['Europe','Japan','USA'], name='Country') + 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), @@ -415,7 +583,7 @@ Bindings and input elements can also be used to filter data on the client side. .. altair-plot:: - input_dropdown = alt.binding_select(options=['Europe','Japan','USA'], name='Country') + input_dropdown = alt.binding_select(options=['Europe','Japan','USA'], name='Region ') selection = alt.selection_point(fields=['Origin'], bind=input_dropdown) alt.Chart(cars).mark_point().encode( @@ -496,3 +664,32 @@ 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 `_. + +Limitations +~~~~~~~~~~~ + +Some possible use cases for the above interactivity are not currently supported by Vega-Lite, and hence are not currently supported by Altair. Here are some examples. + +1. If we are using a ``selection_point``, it would be natural to want to return information about the chosen data point, and then process that information using Python. This is not currently possible (and as of December 2021 it does not seem likely to become possible any time soon), so any data processing will have to be handled using tools such as ``transform_calculate``, etc. You can follow the progress on this in the following issue: https://github.com/altair-viz/altair/issues/1153. +2. It is not possible to use an encoding such as ``y=column_variable`` to then dynamically display different charts based on different column choices. Similar functionality could be created using for example ``ipywidgets`` or ``panel``, but the resulting interactivity would be controlled by Python, and would not work for example as a stand-alone web page. The underlying reason this is not possible is that in Vega-Lite, the ``field`` property does not accept a parameter as value; see the `field Vega-Lite documentation `_. You can follow the discussion in this issue https://github.com/vega/vega-lite/issues/7365. In the meantime you can workaround this by transforming the data into long form using either `melt` in pandas or :meth:`transform_fold` in Altair. + +.. altair-plot:: + source = data.cars().melt(id_vars=['Origin', 'Name', 'Year', 'Horsepower']) + dropdown_options = source['variable'].drop_duplicates().tolist() + + dropdown = alt.binding_select(options=dropdown_options, name='X-axis column ') + selection = alt.selection_point( + fields=['variable'], + value=[{'variable': dropdown_options[0]}], + bind=dropdown + ) + + alt.Chart(source).mark_circle().encode( + x=alt.X('value:Q', title=''), + y='Horsepower', + color='Origin', + ).add_parameter( + selection + ).transform_filter( + selection + ) diff --git a/doc/user_guide/interactions2.rst b/doc/user_guide/interactions2.rst deleted file mode 100644 index c1e15b023..000000000 --- a/doc/user_guide/interactions2.rst +++ /dev/null @@ -1,219 +0,0 @@ -.. currentmodule:: altair - -.. _user-guide-interactions2: - -Parameters: Variables and Selections -==================================== - -Interactivity in Altair is built around *parameters*, of which there are two types: variables and selections. We introduce these concepts through a series examples. - -.. note:: - - This material was changed considerably with the release of Altair 5. In particular, Altair 4 had selections but not variables, and the term ``parameter`` first appeared in Altair 5. - -.. _basic variable: - -Basic Example: Using a variable -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -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='Miles_per_Gallon:Q', - y='Horsepower:Q', - color='Origin:N' - ) - -We can create a variable parameter using :func:`parameter`, and assign that parameter a default value of 0.1 using the ``value`` property, as follows: - -.. altair-plot:: - :output: none - - op_var = alt.parameter(value=0.1) - -In order to use this variable in the chart specification, we explicitly add it to the chart using the :meth:`Chart.add_parameter` method, and we can then reference the variable within the chart specification. Here we set the opacity using our ``op_var`` parameter. - -.. altair-plot:: - - import altair as alt - from vega_datasets import data - - cars = data.cars.url - - op_var = alt.parameter(value=0.1) - - alt.Chart(cars).mark_circle(opacity=op_var).encode( - x='Miles_per_Gallon:Q', - y='Horsepower:Q', - color='Origin:N' - ).add_parameter( - op_var - ) - -It's reasonable to ask whether all this effort is necessary. Here is a more natural way to accomplish the same thing. We avoid the use of both :func:`alt.parameter` and ``add_parameter``. - -.. altair-plot:: - - import altair as alt - from vega_datasets import data - - cars = data.cars.url - - op_var2 = 0.1 - - alt.Chart(cars).mark_circle(opacity=op_var2).encode( - x='Miles_per_Gallon:Q', - y='Horsepower:Q', - color='Origin:N' - ) - -The benefit of using :func:`alt.parameter` doesn't become apparent until we incorporate an additional component, such as in the following, where 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:: - - import altair as alt - from vega_datasets import data - - cars = data.cars.url - - slider = alt.binding_range(min=0, max=1, step=0.05, name='opacity:') - op_var = alt.parameter(value=0.1, bind=slider) - - alt.Chart(cars).mark_circle(opacity=op_var).encode( - x='Miles_per_Gallon:Q', - y='Horsepower:Q', - color='Origin:N' - ).add_parameter( - op_var - ) - -Now we can dynamically change the opacity of the points in our chart using the slider. A noteworthy aspect of this chart is that these effects are controlled entirely within your web browser. Once the Vega-Lite chart specification has been created by Altair, the result is an interactive chart, and that interactivity no longer requires a running Python environment. - -The above example includes some aspects which occur frequently when creating interactive charts in Altair: - -- Creating a variable parameter using :func:`parameter`. -- Attaching the parameter to a chart using the :meth:`Chart.add_parameter` method. -- Binding the parameter to an input widget using the parameter's ``bind`` property. (In the above example, the input widget is a slider widget.) - -Some further aspects that we will see below include: - -- Creating a *selection* parameter. -- Using a parameter within a :func:`condition`. -- Using a parameter within a :meth:`Chart.transform_filter`. - -Using selection parameters -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The basic syntax for adding a selection parameter to a chart is similar to the syntax for a variable parameter. Instead of creating the parameter using ``alt.parameter``, we will typically use ``alt.selection_interval`` or ``alt.selection_point``. Here is a basic example, again using the ``cars`` dataset: - -.. altair-plot:: - - import altair as alt - from vega_datasets import data - - cars = data.cars.url - - brush = alt.selection_interval() - - alt.Chart(cars).mark_circle().encode( - x='Miles_per_Gallon:Q', - y='Horsepower:Q', - color='Origin:N' - ).add_parameter( - brush - ) - - -If you click and drag on the above chart, you will see that the corresponding region gets highlighted. - -So far this example is very similar to what we did in the :ref:`variable example `. Here we have done two things: we created a selection parameter using ``brush = alt.selection_interval()``, and we attached that parameter to the chart using ``add_parameter``. - -The line ``brush = alt.selection_interval()`` is equivalent to ``brush = alt.parameter(select="interval")``; we will typically use the ``selection_interval`` version, because it is shorter and because it matches the syntax that was used in Altair 4. - -Typically selection parameters will be used in conjunction with ``condition`` or with ``transform_filter``. Here are some possibilities. - -Using a selection within a condition -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In the following example, 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. - -.. altair-plot:: - - import altair as alt - from vega_datasets import data - - cars = data.cars.url - - brush = alt.selection_interval() - - alt.Chart(cars).mark_circle().encode( - x='Miles_per_Gallon:Q', - y='Horsepower:Q', - color=alt.condition(brush, 'Origin:N', alt.value('lightgray')) - ).add_parameter( - brush - ) - -Using a selection to filter the data -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Once you are comfortable with using a parameter within ``alt.condition``, using a parameter within ``transform_filter`` works in much the same way. 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 removed. - -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 left chart, and then filter data using the selection parameter on the right chart. We specify explicit domains for the right chart so that the positions of the points remain steady. - -.. altair-plot:: - - import altair as alt - from vega_datasets import data - - cars = data.cars.url - - brush = alt.selection_interval() - - c1 = alt.Chart(cars).mark_point().encode( - x = "Horsepower:Q", - y = "Miles_per_Gallon:Q" - ).add_parameter(brush) - - c2 = alt.Chart(cars).mark_point().encode( - x = alt.X("Acceleration:Q", scale=alt.Scale(domain=[0,25])), - y = alt.Y("Displacement:Q", scale=alt.Scale(domain=[0,500])), - ).transform_filter(brush) - - alt.vconcat(c1,c2) - - -Limitations -^^^^^^^^^^^ - -Some possible use cases for the above interactivity are not currently supported by Vega-Lite, and hence are not currently supported by Altair. Here are some examples. - -1. If we are using a ``selection_point``, it would be natural to want to return information about the chosen data point, and then process that information using Python. This is not currently possible (and as of December 2021 it does not seem likely to become possible any time soon), so any data processing will have to be handled using tools such as ``transform_calculate``, etc. - -2. It is not possible to use an encoding such as ``y=column_variable`` to then dynamically display different charts based on different column choices. Similar functionality could be created using for example ``ipywidgets``, but the resulting interactivity would be controlled by Python, and would not work for example as a stand-alone web page. The underlying reason this is not possible is that in Vega-Lite, the ``field`` property does not accept a parameter as value; see the `field Vega-Lite documentation `_. A first approximation of a workaround is given in the following example. - -.. altair-plot:: - import pandas as pd - import altair as alt - - df = pd.DataFrame({'col0':range(4), 'col1':list('ABAA'), 'col2':list('CDDC')}) - df_long = df.melt(id_vars=['col0'], var_name='column') - - col_dropdown = alt.binding_select(options=df_long['column'].unique()) - col_param = alt.parameter(bind=col_dropdown, name="ColumnParam", value='col1') - - alt.Chart(df_long).mark_bar().encode( - x = "value:N", - y = "count()", - ).transform_filter( - "datum.column == ColumnParam" - ).add_parameter( - col_param - ) \ No newline at end of file From 2fe884fa3fe3a92435b1cead4a7e79bb9b1319b2 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Fri, 25 Mar 2022 11:45:49 -0700 Subject: [PATCH 20/23] Contrast variable and selection parameters in expression strings --- doc/user_guide/interactions.rst | 41 +++++++++++++++++++++++++++++---- 1 file changed, 37 insertions(+), 4 deletions(-) diff --git a/doc/user_guide/interactions.rst b/doc/user_guide/interactions.rst index 5d40a9266..a9a94501d 100644 --- a/doc/user_guide/interactions.rst +++ b/doc/user_guide/interactions.rst @@ -614,10 +614,14 @@ With interval selections, the ``bind`` property can be set to the value of ``"sc ).add_parameter( selection ) - -Selection Values in Expressions + +Parameter Values in Expressions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Selection Parameters +^^^^^^^^^^^^^^^^^^^^ + 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: @@ -635,15 +639,16 @@ points based on whether they are smaller or larger than the value: 'yval': rand.randn(100).cumsum() }) - slider = alt.binding_range(min=0, max=100, step=1, name='cutoff:') + 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_parameter( @@ -654,6 +659,34 @@ Selector values can be similarly used anywhere that expressions are valid, for example, in a :ref:`user-guide-calculate-transform` or a :ref:`user-guide-filter-transform`. +Variable Parameters +^^^^^^^^^^^^^^^^^^^ + +While it is useful to know +how to access selection parameter values +in expression strings, +the variable parameters 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: + +.. altair-plot:: + + slider = alt.binding_range(min=0, max=100, step=1, name='Cutoff ') + selector = alt.parameter(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_parameter( + selector + ) + Further Examples ~~~~~~~~~~~~~~~~ From 1e608042c97de8cd63ce7faa11d1b0026c21faa8 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Fri, 15 Apr 2022 11:47:17 -0700 Subject: [PATCH 21/23] Note how to use custom Panel callbacks with Altair selections --- doc/user_guide/interactions.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/user_guide/interactions.rst b/doc/user_guide/interactions.rst index a9a94501d..c19231e64 100644 --- a/doc/user_guide/interactions.rst +++ b/doc/user_guide/interactions.rst @@ -704,6 +704,9 @@ Limitations Some possible use cases for the above interactivity are not currently supported by Vega-Lite, and hence are not currently supported by Altair. Here are some examples. 1. If we are using a ``selection_point``, it would be natural to want to return information about the chosen data point, and then process that information using Python. This is not currently possible (and as of December 2021 it does not seem likely to become possible any time soon), so any data processing will have to be handled using tools such as ``transform_calculate``, etc. You can follow the progress on this in the following issue: https://github.com/altair-viz/altair/issues/1153. + + - The dashboarding package ``Panel`` has added support for processing Altair selections with custom callbacks in their 0.13 release. This is currently the only Python dashboarding package that supports custom callbacks for Altair selections and you can read more about how to use this functionality in `the Panel documentation `_. + 2. It is not possible to use an encoding such as ``y=column_variable`` to then dynamically display different charts based on different column choices. Similar functionality could be created using for example ``ipywidgets`` or ``panel``, but the resulting interactivity would be controlled by Python, and would not work for example as a stand-alone web page. The underlying reason this is not possible is that in Vega-Lite, the ``field`` property does not accept a parameter as value; see the `field Vega-Lite documentation `_. You can follow the discussion in this issue https://github.com/vega/vega-lite/issues/7365. In the meantime you can workaround this by transforming the data into long form using either `melt` in pandas or :meth:`transform_fold` in Altair. .. altair-plot:: From a417d6def38df98c3e634eb7191555b941bc8340 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Fri, 15 Apr 2022 11:53:35 -0700 Subject: [PATCH 22/23] Add more succinct example of selecting columns from dropdowns --- doc/user_guide/interactions.rst | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/doc/user_guide/interactions.rst b/doc/user_guide/interactions.rst index c19231e64..0a1f1c5fb 100644 --- a/doc/user_guide/interactions.rst +++ b/doc/user_guide/interactions.rst @@ -713,10 +713,14 @@ Some possible use cases for the above interactivity are not currently supported source = data.cars().melt(id_vars=['Origin', 'Name', 'Year', 'Horsepower']) dropdown_options = source['variable'].drop_duplicates().tolist() - dropdown = alt.binding_select(options=dropdown_options, name='X-axis column ') + dropdown = alt.binding_select( + options=dropdown_options, + name='X-axis column' + ) selection = alt.selection_point( fields=['variable'], value=[{'variable': dropdown_options[0]}], + # init={'variable': dropdown_options[0]}, # For Altair 4 bind=dropdown ) @@ -724,8 +728,31 @@ Some possible use cases for the above interactivity are not currently supported x=alt.X('value:Q', title=''), y='Horsepower', color='Origin', - ).add_parameter( + ).add_selection( selection ).transform_filter( selection ) + +Taking advantage of the parameter interface introduced in Altair 5, we can express this more succinctly: + +.. altair-plot:: + dropdown = alt.binding_select( + options=['Miles_per_Gallon', 'Acceleration', 'Displacement'], + name='X-axis column ' + ) + param = alt.parameter( + name='selected_column', + value='Miles_per_Gallon', + bind=dropdown + ) + + alt.Chart(data.cars.url).mark_circle().encode( + x='x:Q', + y='Horsepower:Q', + color='Origin:N' + ).transform_calculate( + x='datum[selected_column]' + ).add_parameter( + param + ) From c6eafbcf4991f3062db622dc601ecba3812c5f43 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Fri, 15 Apr 2022 12:19:03 -0700 Subject: [PATCH 23/23] Make examples equivalent --- doc/user_guide/interactions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user_guide/interactions.rst b/doc/user_guide/interactions.rst index 0a1f1c5fb..3cfbee39c 100644 --- a/doc/user_guide/interactions.rst +++ b/doc/user_guide/interactions.rst @@ -710,7 +710,7 @@ Some possible use cases for the above interactivity are not currently supported 2. It is not possible to use an encoding such as ``y=column_variable`` to then dynamically display different charts based on different column choices. Similar functionality could be created using for example ``ipywidgets`` or ``panel``, but the resulting interactivity would be controlled by Python, and would not work for example as a stand-alone web page. The underlying reason this is not possible is that in Vega-Lite, the ``field`` property does not accept a parameter as value; see the `field Vega-Lite documentation `_. You can follow the discussion in this issue https://github.com/vega/vega-lite/issues/7365. In the meantime you can workaround this by transforming the data into long form using either `melt` in pandas or :meth:`transform_fold` in Altair. .. altair-plot:: - source = data.cars().melt(id_vars=['Origin', 'Name', 'Year', 'Horsepower']) + source = data.cars().melt(id_vars=['Origin', 'Name', 'Year', 'Horsepower', 'Cylinders']) dropdown_options = source['variable'].drop_duplicates().tolist() dropdown = alt.binding_select( @@ -738,7 +738,7 @@ Taking advantage of the parameter interface introduced in Altair 5, we can expre .. altair-plot:: dropdown = alt.binding_select( - options=['Miles_per_Gallon', 'Acceleration', 'Displacement'], + options=['Miles_per_Gallon', 'Displacement', 'Weight_in_lbs', 'Acceleration'], name='X-axis column ' ) param = alt.parameter(