From c1a2ae9dd559980db643aaf633e724344bb11e8c Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 1 Dec 2022 11:51:07 +0000 Subject: [PATCH 01/25] Remove key channel as not relevant for Altair and not documented anyway --- doc/user_guide/encoding.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/user_guide/encoding.rst b/doc/user_guide/encoding.rst index 7ac79182c..8c1d0f29e 100644 --- a/doc/user_guide/encoding.rst +++ b/doc/user_guide/encoding.rst @@ -91,7 +91,6 @@ Text and Tooltip Channels Channel Altair Class Description Example ======= ================ ======================== ========================================= text :class:`Text` Text to use for the mark :ref:`gallery_scatter_with_labels` -key :class:`Key` -- N/A tooltip :class:`Tooltip` The tooltip value :ref:`gallery_scatter_tooltips` ======= ================ ======================== ========================================= From f3914668620cc3843d9561f9b2b9a70a1a27896a Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 1 Dec 2022 12:45:20 +0000 Subject: [PATCH 02/25] Add explanation and description to detail channel --- doc/user_guide/encoding.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/doc/user_guide/encoding.rst b/doc/user_guide/encoding.rst index 8c1d0f29e..7fe941d1e 100644 --- a/doc/user_guide/encoding.rst +++ b/doc/user_guide/encoding.rst @@ -106,12 +106,37 @@ href :class:`Href` Hyperlink for points :ref:`gallery_scatter_href` Level of Detail Channel ^^^^^^^^^^^^^^^^^^^^^^^ +Grouping data is an important operation in data visualization. For line and area marks, +mapping an unaggregated data field to any +non-position channel will group the lines and stacked areas by that field. +For aggregated plots, all unaggregated fields encoded are used as grouping fields +in the aggregation (similar to fields in ``GROUP BY`` in SQL). + +The ``detail`` channel specifies an additional grouping field (or fields) for grouping +data without mapping the field(s) to any visual properties. + ======= ================ =============================== ========================================= Channel Altair Class Description Example ======= ================ =============================== ========================================= detail :class:`Detail` Additional property to group by :ref:`gallery_ranged_dot_plot` ======= ================ =============================== ========================================= +For example here is a line chart showing stock prices of 5 tech companies over time. +We map the ``symbol`` variable to ``detail`` to use them to group lines. + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + source = data.stocks() + alt.Chart(source).mark_line().encode( + x="date:T", + y="price:Q", + detail="symbol:N" + ) + + Order Channel ^^^^^^^^^^^^^ From 80fe108cf9b6541ed739a604059d303f6b5d22e1 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 1 Dec 2022 12:58:19 +0000 Subject: [PATCH 03/25] Add explanation on difference between datum and value --- doc/user_guide/encoding.rst | 83 ++++++++++++++++++++++++++++++++++++- 1 file changed, 82 insertions(+), 1 deletion(-) diff --git a/doc/user_guide/encoding.rst b/doc/user_guide/encoding.rst index 7fe941d1e..c35cb7f54 100644 --- a/doc/user_guide/encoding.rst +++ b/doc/user_guide/encoding.rst @@ -38,7 +38,7 @@ Encoding Channels ~~~~~~~~~~~~~~~~~ Altair provides a number of encoding channels that can be useful in different -circumstances; the following table summarizes them: +circumstances. The following tables summarize them: Position Channels ^^^^^^^^^^^^^^^^^ @@ -701,3 +701,84 @@ While the above examples show sorting of axes by specifying ``sort`` in the Here the y-axis is sorted reverse-alphabetically, while the color legend is sorted in the specified order, beginning with ``'Morris'``. + +Datum and Value +~~~~~~~~~~~~~~~ + +So far we always mapped an encoding channel to a column in our dataset. However, sometimes +it is also useful to map to a single constant value. In Altair, you can do this with + +* ``datum``, which describes a constant data value encoded via a scale +* ``value``, which describes an encoded constant visual value + +``datum`` is particularly useful for annotating a specific data value. +For example, you can use it with a rule mark to highlight a +threshold value (e.g., 200 dollars stock price). + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + source = data.stocks() + base = alt.Chart(source) + lines = base.mark_line().encode( + x="date:T", + y="price:Q", + color="symbol:N" + ) + rule = base.mark_rule(strokeDash=[2, 2]).encode( + y=alt.datum(300) + ) + + lines + rule + +You can also use ``datum`` with :class:`DateTime`, for example, to highlight a certain year. +In addition, we will set the color for the rule to the same one as the line for the symbol ``MSFT`` +with ``alt.datum("MSFT")``. + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + source = data.stocks() + base = alt.Chart(source) + lines = base.mark_line().encode( + x="date:T", + y="price:Q", + color="symbol:N" + ) + rule = base.mark_rule(strokeDash=[2, 2]).encode( + x=alt.datum(alt.DateTime(year=2006)), + color=alt.datum("MSFT") + ) + + lines + rule + + +Similar to when mapping to a data column, when using ``datum`` different encoding channels +may support ``band``, ``scale``, ``axis``, ``legend``, ``format``, or ``condition`` properties. +However, data transforms (e.g. ``aggregate``, ``bin``, ``timeUnit``, ``sort``) cannot be applied. + +Expanding on the example above, if you would want to color the ``rule`` mark regardless of +the color scale used for the lines, you can use ``value``, e.g. ``alt.value("red")``: + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + source = data.stocks() + base = alt.Chart(source) + lines = base.mark_line().encode( + x="date:T", + y="price:Q", + color="symbol:N" + ) + rule = base.mark_rule(strokeDash=[2, 2]).encode( + x=alt.datum(alt.DateTime(year=2006)), + color=alt.value("red") + ) + + lines + rule From 93f09f5f938bd4ec7fe5ac4d5f8941b85926b830 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 1 Dec 2022 13:02:10 +0000 Subject: [PATCH 04/25] Remove key and description also from channel option sections --- doc/user_guide/encoding.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/user_guide/encoding.rst b/doc/user_guide/encoding.rst index c35cb7f54..58b36ce44 100644 --- a/doc/user_guide/encoding.rst +++ b/doc/user_guide/encoding.rst @@ -349,17 +349,17 @@ The :class:`Text` encoding accepts the following options: .. altair-object-table:: altair.FieldOrDatumDefWithConditionStringFieldDefText -Description, Href, Tooltip, Url -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Href, Tooltip, Url +^^^^^^^^^^^^^^^^^^ -The :class:`Description`, :class:`Href`, :class:`Tooltip`, and :class:`Url` encodings accept the following options: +The :class:`Href`, :class:`Tooltip`, and :class:`Url` encodings accept the following options: .. altair-object-table:: altair.StringFieldDefWithCondition -Detail and Key -^^^^^^^^^^^^^^ +Detail +^^^^^^ -The :class:`Detail` and :class:`Key` encodings accept the following options: +The :class:`Detail` encoding accepts the following options: .. altair-object-table:: altair.FieldDefWithoutScale From a2720398bf97fda3f3650398bb1c3874957b1275 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 8 Dec 2022 08:29:05 +0100 Subject: [PATCH 05/25] Update doc/user_guide/encoding.rst Co-authored-by: Joel Ostblom --- doc/user_guide/encoding.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user_guide/encoding.rst b/doc/user_guide/encoding.rst index 58b36ce44..cdb47939f 100644 --- a/doc/user_guide/encoding.rst +++ b/doc/user_guide/encoding.rst @@ -103,8 +103,8 @@ Channel Altair Class Description Example href :class:`Href` Hyperlink for points :ref:`gallery_scatter_href` ======= ================ ======================== ========================================= -Level of Detail Channel -^^^^^^^^^^^^^^^^^^^^^^^ +Detail Channel +^^^^^^^^^^^^^^ Grouping data is an important operation in data visualization. For line and area marks, mapping an unaggregated data field to any From 4ca20845d28ace77255557cebe7a0fa6517f3571 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 8 Dec 2022 08:29:40 +0100 Subject: [PATCH 06/25] Update doc/user_guide/encoding.rst Co-authored-by: Joel Ostblom --- doc/user_guide/encoding.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user_guide/encoding.rst b/doc/user_guide/encoding.rst index cdb47939f..d31950986 100644 --- a/doc/user_guide/encoding.rst +++ b/doc/user_guide/encoding.rst @@ -708,8 +708,8 @@ Datum and Value So far we always mapped an encoding channel to a column in our dataset. However, sometimes it is also useful to map to a single constant value. In Altair, you can do this with -* ``datum``, which describes a constant data value encoded via a scale -* ``value``, which describes an encoded constant visual value +* ``datum``, which encodes a constant domain value via a scale using the same units as the underlying data +* ``value``, which encodes a constant visual value, using absolute units such as an exact position in pixels, the name or RGB value of a color, the name of shape, etc ``datum`` is particularly useful for annotating a specific data value. For example, you can use it with a rule mark to highlight a From 92549a9b06137539945c91846be5aabcf382e33c Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 8 Dec 2022 08:30:25 +0100 Subject: [PATCH 07/25] Update doc/user_guide/encoding.rst Co-authored-by: Joel Ostblom --- doc/user_guide/encoding.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/encoding.rst b/doc/user_guide/encoding.rst index d31950986..43b17dd0f 100644 --- a/doc/user_guide/encoding.rst +++ b/doc/user_guide/encoding.rst @@ -713,7 +713,7 @@ it is also useful to map to a single constant value. In Altair, you can do this ``datum`` is particularly useful for annotating a specific data value. For example, you can use it with a rule mark to highlight a -threshold value (e.g., 200 dollars stock price). +threshold value (e.g., 300 dollars stock price). .. altair-plot:: From b9b3258bdc4fdbe5f336fe66021b92230d2b496d Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 8 Dec 2022 08:30:56 +0100 Subject: [PATCH 08/25] Update doc/user_guide/encoding.rst Co-authored-by: Joel Ostblom --- doc/user_guide/encoding.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/user_guide/encoding.rst b/doc/user_guide/encoding.rst index 43b17dd0f..f37c6bc59 100644 --- a/doc/user_guide/encoding.rst +++ b/doc/user_guide/encoding.rst @@ -733,6 +733,16 @@ threshold value (e.g., 300 dollars stock price). lines + rule +If we instead used `alt.value` in this example, we would position the rule 300 pixels from the left of the chart border rather than at the 300 dollars position: + +.. altair-plot:: + + rule = base.mark_rule(strokeDash=[2, 2]).encode( + y=alt.datum(300) + ) + + lines + rule + You can also use ``datum`` with :class:`DateTime`, for example, to highlight a certain year. In addition, we will set the color for the rule to the same one as the line for the symbol ``MSFT`` with ``alt.datum("MSFT")``. From 6dbe37a28c14cfb7b88abc6713c69f571479759f Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 8 Dec 2022 07:33:19 +0000 Subject: [PATCH 09/25] Fix usage of alt.value in rule example --- doc/user_guide/encoding.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user_guide/encoding.rst b/doc/user_guide/encoding.rst index f37c6bc59..9118d7aef 100644 --- a/doc/user_guide/encoding.rst +++ b/doc/user_guide/encoding.rst @@ -733,12 +733,12 @@ threshold value (e.g., 300 dollars stock price). lines + rule -If we instead used `alt.value` in this example, we would position the rule 300 pixels from the left of the chart border rather than at the 300 dollars position: +If we instead used ``alt.value`` in this example, we would position the rule 300 pixels from the bottom of the chart border rather than at the 300 dollars position: .. altair-plot:: rule = base.mark_rule(strokeDash=[2, 2]).encode( - y=alt.datum(300) + y=alt.value(300) ) lines + rule From 01c5dd492ba99015d48ecaa68f349f2930295e19 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 15 Dec 2022 15:40:46 +0000 Subject: [PATCH 10/25] Move section on themes from configuration to customization page --- doc/user_guide/configuration.rst | 141 ------------------------------ doc/user_guide/customization.rst | 142 +++++++++++++++++++++++++++++++ 2 files changed, 142 insertions(+), 141 deletions(-) diff --git a/doc/user_guide/configuration.rst b/doc/user_guide/configuration.rst index 57de55f36..54c4ae051 100644 --- a/doc/user_guide/configuration.rst +++ b/doc/user_guide/configuration.rst @@ -286,144 +286,3 @@ Additional properties are summarized in the following table: .. altair-object-table:: altair.ViewConfig - -.. _chart-themes: - -Altair Themes -------------- -Altair makes available a theme registry that lets users apply chart configurations -globally within any Python session. This is done via the ``alt.themes`` object. - -The themes registry consists of functions which define a specification dictionary -that will be added to every created chart. -For example, the default theme configures the default size of a single chart: - - >>> import altair as alt - >>> default = alt.themes.get() - >>> default() - {'config': {'view': {'continuousWidth': 400, 'continuousHeight': 300}}} - -You can see that any chart you create will have this theme applied, and these configurations -added to its specification: - -.. altair-plot:: - :output: repr - - import altair as alt - from vega_datasets import data - - chart = alt.Chart(data.cars.url).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q' - ) - - chart.to_dict() - -The rendered chart will then reflect these configurations: - -.. altair-plot:: - - chart - -Changing the Theme -~~~~~~~~~~~~~~~~~~ -If you would like to enable any other theme for the length of your Python session, -you can call ``alt.themes.enable(theme_name)``. -For example, Altair includes a theme in which the chart background is opaque -rather than transparent: - -.. altair-plot:: - :output: repr - - alt.themes.enable('opaque') - chart.to_dict() - -.. altair-plot:: - - chart - -Notice that the background color of the chart is now set to white. -If you would like no theme applied to your chart, you can use the -theme named ``'none'``: - -.. altair-plot:: - :output: repr - - alt.themes.enable('none') - chart.to_dict() - -.. altair-plot:: - - chart - -Because the view configuration is not set, the chart is smaller -than the default rendering. - -If you would like to use any theme just for a single chart, you can use the -``with`` statement to enable a temporary theme: - -.. altair-plot:: - :output: none - - with alt.themes.enable('default'): - spec = chart.to_json() - -Currently Altair does not offer many built-in themes, but we plan to add -more options in the future. - -Defining a Custom Theme -~~~~~~~~~~~~~~~~~~~~~~~ -The theme registry also allows defining and registering custom themes. -A theme is simply a function that returns a dictionary of default values -to be added to the chart specification at rendering time, which is then -registered and activated. - -For example, here we define a theme in which all marks are drawn with black -fill unless otherwise specified: - -.. altair-plot:: - - import altair as alt - from vega_datasets import data - - # define the theme by returning the dictionary of configurations - def black_marks(): - return { - 'config': { - 'view': { - 'height': 300, - 'width': 400, - }, - 'mark': { - 'color': 'black', - 'fill': 'black' - } - } - } - - # register the custom theme under a chosen name - alt.themes.register('black_marks', black_marks) - - # enable the newly registered theme - alt.themes.enable('black_marks') - - # draw the chart - cars = data.cars.url - alt.Chart(cars).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q' - ) - - -If you want to restore the default theme, use: - -.. altair-plot:: - :output: none - - alt.themes.enable('default') - - -For more ideas on themes, see the `Vega Themes`_ repository. - - -.. _Vega Themes: https://github.com/vega/vega-themes/ diff --git a/doc/user_guide/customization.rst b/doc/user_guide/customization.rst index 05e8629bd..0c2ac5d51 100644 --- a/doc/user_guide/customization.rst +++ b/doc/user_guide/customization.rst @@ -566,3 +566,145 @@ it is rendererd, you can set ``width`` or ``height`` to the string ``"container" Note that this will only scale with the container if its parent element has a size determined outside the chart itself; For example, the container may be a ``
`` element that has style ``width: 100%; height: 300px``. + + +.. _chart-themes: + +Chart Themes +------------ +Altair makes available a theme registry that lets users apply chart configurations +globally within any Python session. This is done via the ``alt.themes`` object. + +The themes registry consists of functions which define a specification dictionary +that will be added to every created chart. +For example, the default theme configures the default size of a single chart: + + >>> import altair as alt + >>> default = alt.themes.get() + >>> default() + {'config': {'view': {'continuousWidth': 400, 'continuousHeight': 300}}} + +You can see that any chart you create will have this theme applied, and these configurations +added to its specification: + +.. altair-plot:: + :output: repr + + import altair as alt + from vega_datasets import data + + chart = alt.Chart(data.cars.url).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q' + ) + + chart.to_dict() + +The rendered chart will then reflect these configurations: + +.. altair-plot:: + + chart + +Changing the Theme +~~~~~~~~~~~~~~~~~~ +If you would like to enable any other theme for the length of your Python session, +you can call ``alt.themes.enable(theme_name)``. +For example, Altair includes a theme in which the chart background is opaque +rather than transparent: + +.. altair-plot:: + :output: repr + + alt.themes.enable('opaque') + chart.to_dict() + +.. altair-plot:: + + chart + +Notice that the background color of the chart is now set to white. +If you would like no theme applied to your chart, you can use the +theme named ``'none'``: + +.. altair-plot:: + :output: repr + + alt.themes.enable('none') + chart.to_dict() + +.. altair-plot:: + + chart + +Because the view configuration is not set, the chart is smaller +than the default rendering. + +If you would like to use any theme just for a single chart, you can use the +``with`` statement to enable a temporary theme: + +.. altair-plot:: + :output: none + + with alt.themes.enable('default'): + spec = chart.to_json() + +Currently Altair does not offer many built-in themes, but we plan to add +more options in the future. + +Defining a Custom Theme +~~~~~~~~~~~~~~~~~~~~~~~ +The theme registry also allows defining and registering custom themes. +A theme is simply a function that returns a dictionary of default values +to be added to the chart specification at rendering time, which is then +registered and activated. + +For example, here we define a theme in which all marks are drawn with black +fill unless otherwise specified: + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + # define the theme by returning the dictionary of configurations + def black_marks(): + return { + 'config': { + 'view': { + 'height': 300, + 'width': 400, + }, + 'mark': { + 'color': 'black', + 'fill': 'black' + } + } + } + + # register the custom theme under a chosen name + alt.themes.register('black_marks', black_marks) + + # enable the newly registered theme + alt.themes.enable('black_marks') + + # draw the chart + cars = data.cars.url + alt.Chart(cars).mark_point().encode( + x='Horsepower:Q', + y='Miles_per_Gallon:Q' + ) + + +If you want to restore the default theme, use: + +.. altair-plot:: + :output: none + + alt.themes.enable('default') + + +For more ideas on themes, see the `Vega Themes`_ repository. + + +.. _Vega Themes: https://github.com/vega/vega-themes/ From e485e49433a905376978875d0059c824ef33e81c Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 15 Dec 2022 15:57:24 +0000 Subject: [PATCH 11/25] Collapse object tables by default --- altair/sphinxext/schematable.py | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/altair/sphinxext/schematable.py b/altair/sphinxext/schematable.py index b94b4409b..64a6715f3 100644 --- a/altair/sphinxext/schematable.py +++ b/altair/sphinxext/schematable.py @@ -4,6 +4,7 @@ from docutils import nodes, utils from docutils.parsers.rst import Directive +from docutils.parsers.rst.directives import flag from recommonmark.parser import CommonMarkParser from sphinx import addnodes @@ -181,7 +182,7 @@ class AltairObjectTableDirective(Directive): has_content = False required_arguments = 1 - option_spec = {"properties": validate_properties} + option_spec = {"properties": validate_properties, "dont-collapse-table": flag} def run(self): objectname = self.arguments[0] @@ -191,10 +192,22 @@ def run(self): schema = cls.resolve_references(cls._schema) properties = self.options.get("properties", None) + dont_collapse_table = "dont-collapse-table" in self.options + result = [] + if not dont_collapse_table: + html = "
Click to show table" + raw_html = nodes.raw("", html, format="html") + result += [raw_html] # create the table from the object - table = prepare_schema_table(schema, props=properties) - return [table] + result.append(prepare_schema_table(schema, props=properties)) + + if not dont_collapse_table: + html = "
" + raw_html = nodes.raw("", html, format="html") + result += [raw_html] + + return result def setup(app): From a42f7dba0db0770f6def51150bf74cc2b20740d2 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 15 Dec 2022 17:50:30 +0000 Subject: [PATCH 12/25] Move encodings page into subfolder --- doc/user_guide/{encoding.rst => encodings/index.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/user_guide/{encoding.rst => encodings/index.rst} (100%) diff --git a/doc/user_guide/encoding.rst b/doc/user_guide/encodings/index.rst similarity index 100% rename from doc/user_guide/encoding.rst rename to doc/user_guide/encodings/index.rst From 77677b27dd75b0be13860039309e2e6ecaed23fd Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 15 Dec 2022 18:16:30 +0000 Subject: [PATCH 13/25] Move content on channels and channel options into separate subpages --- doc/user_guide/data.rst | 2 +- doc/user_guide/encodings/channel_options.rst | 114 +++++++ doc/user_guide/encodings/channels.rst | 187 +++++++++++ doc/user_guide/encodings/index.rst | 322 +------------------ 4 files changed, 313 insertions(+), 312 deletions(-) create mode 100644 doc/user_guide/encodings/channel_options.rst create mode 100644 doc/user_guide/encodings/channels.rst diff --git a/doc/user_guide/data.rst b/doc/user_guide/data.rst index 8521730f1..12d0bdb96 100644 --- a/doc/user_guide/data.rst +++ b/doc/user_guide/data.rst @@ -441,7 +441,7 @@ data before usage in Altair using GeoPandas for example as such: :hidden: self - encoding + encodings/index marks/index transform/index interactions diff --git a/doc/user_guide/encodings/channel_options.rst b/doc/user_guide/encodings/channel_options.rst new file mode 100644 index 000000000..039fd62f2 --- /dev/null +++ b/doc/user_guide/encodings/channel_options.rst @@ -0,0 +1,114 @@ +.. currentmodule:: altair + +.. _user-guide-encoding-channel-options: + +Channel Options +--------------- + +Each encoding channel allows for a number of additional options to be expressed. +These can control things like axis properties, scale properties, headers and +titles, binning parameters, aggregation, sorting, and many more. + +The section titles below refer to the channels introduced in :ref:`user-guide-encoding-channels` +and show the accepted options for these channels. + + +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 + +Href, Tooltip, Url +~~~~~~~~~~~~~~~~~~ + +The :class:`Href`, :class:`Tooltip`, and :class:`Url` encodings accept the following options: + +.. altair-object-table:: altair.StringFieldDefWithCondition + +Detail +~~~~~~ + +The :class:`Detail` encoding accepts 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 + +Radius and Theta +~~~~~~~~~~~~~~~~ + +The :class:`Radius` and :class:`Theta` encodings accept the following options: + +.. altair-object-table:: altair.PositionFieldDefBase + +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 + diff --git a/doc/user_guide/encodings/channels.rst b/doc/user_guide/encodings/channels.rst new file mode 100644 index 000000000..f4710e7b2 --- /dev/null +++ b/doc/user_guide/encodings/channels.rst @@ -0,0 +1,187 @@ +.. currentmodule:: altair + +.. _user-guide-encoding-channels: + +Channels +-------- + +Altair provides a number of encoding channels that can be useful in different +circumstances. The following sections summarize them: + +Position +~~~~~~~~ + +========== =================== ================================= =================================== +Channel Altair Class Description Example +========== =================== ================================= =================================== +x :class:`X` The x-axis value :ref:`gallery_scatter_tooltips` +y :class:`Y` The y-axis value :ref:`gallery_scatter_tooltips` +x2 :class:`X2` Second x value for ranges :ref:`gallery_gantt_chart` +y2 :class:`Y2` Second y value for ranges :ref:`gallery_candlestick_chart` +longitude :class:`Longitude` Longitude for geo charts :ref:`gallery_point_map` +latitude :class:`Latitude` Latitude for geo charts :ref:`gallery_point_map` +longitude2 :class:`Longitude2` Second longitude value for ranges :ref:`gallery_airport_connections` +latitude2 :class:`Latitude2` Second latitude value for ranges :ref:`gallery_airport_connections` +xError :class:`XError` The x-axis error value N/A +yError :class:`YError` The y-axis error value N/A +xError2 :class:`XError2` The second x-axis error value N/A +yError2 :class:`YError2` The second y-axis error value N/A +xOffset :class:`XOffset` Offset to the x position :ref:`gallery_grouped_bar_chart2` +yOffset :class:`YOffset` Offset to the y position :ref:`gallery_strip_plot_jitter` +theta :class:`Theta` The start arc angle :ref:`gallery_radial_chart` +theta2 :class:`Theta2` The end arc angle (radian) :ref:`gallery_pacman_chart` +========== =================== ================================= =================================== + +Mark Property +~~~~~~~~~~~~~ + +============= ====================== ============================== ========================================= +Channel Altair Class Description Example +============= ====================== ============================== ========================================= +angle :class:`Angle` The angle of the mark :ref:`gallery_wind_vector_map` +color :class:`Color` The color of the mark :ref:`gallery_simple_heatmap` +fill :class:`Fill` The fill for the mark :ref:`gallery_ridgeline_plot` +fillopacity :class:`FillOpacity` The opacity of the mark's fill N/A +opacity :class:`Opacity` The opacity of the mark :ref:`gallery_horizon_graph` +radius :class:`Radius` The radius or the mark :ref:`gallery_radial_chart` +shape :class:`Shape` The shape of the mark :ref:`gallery_us_incomebrackets_by_state_facet` +size :class:`Size` The size of the mark :ref:`gallery_table_bubble_plot_github` +stroke :class:`Stroke` The stroke of the mark N/A +strokeDash :class:`StrokeDash` The stroke dash style :ref:`gallery_multi_series_line` +strokeOpacity :class:`StrokeOpacity` The opacity of the line N/A +strokeWidth :class:`StrokeWidth` The width of the line N/A +============= ====================== ============================== ========================================= + +Text and Tooltip +^^^^^^^^^^^^^^^^ + +======= ================ ======================== ========================================= +Channel Altair Class Description Example +======= ================ ======================== ========================================= +text :class:`Text` Text to use for the mark :ref:`gallery_scatter_with_labels` +tooltip :class:`Tooltip` The tooltip value :ref:`gallery_scatter_tooltips` +======= ================ ======================== ========================================= + +.. _hyperlink-channel: + +Hyperlink +~~~~~~~~~ + +======= ================ ======================== ========================================= +Channel Altair Class Description Example +======= ================ ======================== ========================================= +href :class:`Href` Hyperlink for points :ref:`gallery_scatter_href` +======= ================ ======================== ========================================= + +Detail +~~~~~~ + +Grouping data is an important operation in data visualization. For line and area marks, +mapping an unaggregated data field to any +non-position channel will group the lines and stacked areas by that field. +For aggregated plots, all unaggregated fields encoded are used as grouping fields +in the aggregation (similar to fields in ``GROUP BY`` in SQL). + +The ``detail`` channel specifies an additional grouping field (or fields) for grouping +data without mapping the field(s) to any visual properties. + +======= ================ =============================== ========================================= +Channel Altair Class Description Example +======= ================ =============================== ========================================= +detail :class:`Detail` Additional property to group by :ref:`gallery_ranged_dot_plot` +======= ================ =============================== ========================================= + +For example here is a line chart showing stock prices of 5 tech companies over time. +We map the ``symbol`` variable to ``detail`` to use them to group lines. + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + source = data.stocks() + alt.Chart(source).mark_line().encode( + x="date:T", + y="price:Q", + detail="symbol:N" + ) + + +Order +~~~~~ + +The `order` option and :class:`Order` channel can sort how marks are drawn on the chart. + +For stacked marks, this controls the order of components of the stack. Here, the elements of each bar are sorted alphabetically by the name of the nominal data in the color channel. + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + barley = data.barley() + + alt.Chart(barley).mark_bar().encode( + x='variety:N', + y='sum(yield):Q', + color='site:N', + order=alt.Order("site", sort="ascending") + ) + +The order can be reversed by changing the sort option to `descending`. + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + barley = data.barley() + + alt.Chart(barley).mark_bar().encode( + x='variety:N', + y='sum(yield):Q', + color='site:N', + order=alt.Order("site", sort="descending") + ) + +The same approach works for other mark types, like stacked areas charts. + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + barley = data.barley() + + alt.Chart(barley).mark_area().encode( + x='variety:N', + y='sum(yield):Q', + color='site:N', + order=alt.Order("site", sort="ascending") + ) + +For line marks, the `order` channel encodes the order in which data points are connected. This can be useful for creating a scatter plot that draws lines between the dots using a different field than the x and y axes. + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + driving = data.driving() + + alt.Chart(driving).mark_line(point=True).encode( + alt.X('miles', scale=alt.Scale(zero=False)), + alt.Y('gas', scale=alt.Scale(zero=False)), + order='year' + ) + +Facet +~~~~~ + +======= ================ =============================================== ============================================= +Channel Altair Class Description Example +======= ================ =============================================== ============================================= +column :class:`Column` The column of a faceted plot :ref:`gallery_trellis_scatter_plot` +row :class:`Row` The row of a faceted plot :ref:`gallery_beckers_barley_trellis_plot` +facet :class:`Facet` The row and/or column of a general faceted plot :ref:`gallery_us_population_over_time_facet` +======= ================ =============================================== ============================================= diff --git a/doc/user_guide/encodings/index.rst b/doc/user_guide/encodings/index.rst index 1666ad40d..cde7b6235 100644 --- a/doc/user_guide/encodings/index.rst +++ b/doc/user_guide/encodings/index.rst @@ -28,136 +28,6 @@ encodings: ``x`` (the x-axis value), ``y`` (the y-axis value), shape='Origin' ) -For data specified as a DataFrame, Altair can automatically determine the -correct data type for each encoding, and creates appropriate scales and -legends to represent the data. - -.. _encoding-channels: - -Encoding Channels -~~~~~~~~~~~~~~~~~ - -Altair provides a number of encoding channels that can be useful in different -circumstances. The following tables summarize them: - -Position Channels -^^^^^^^^^^^^^^^^^ - -========== =================== ================================= =================================== -Channel Altair Class Description Example -========== =================== ================================= =================================== -x :class:`X` The x-axis value :ref:`gallery_scatter_tooltips` -y :class:`Y` The y-axis value :ref:`gallery_scatter_tooltips` -x2 :class:`X2` Second x value for ranges :ref:`gallery_gantt_chart` -y2 :class:`Y2` Second y value for ranges :ref:`gallery_candlestick_chart` -longitude :class:`Longitude` Longitude for geo charts :ref:`gallery_point_map` -latitude :class:`Latitude` Latitude for geo charts :ref:`gallery_point_map` -longitude2 :class:`Longitude2` Second longitude value for ranges :ref:`gallery_airport_connections` -latitude2 :class:`Latitude2` Second latitude value for ranges :ref:`gallery_airport_connections` -xError :class:`XError` The x-axis error value N/A -yError :class:`YError` The y-axis error value N/A -xError2 :class:`XError2` The second x-axis error value N/A -yError2 :class:`YError2` The second y-axis error value N/A -xOffset :class:`XOffset` Offset to the x position :ref:`gallery_grouped_bar_chart2` -yOffset :class:`YOffset` Offset to the y position :ref:`gallery_strip_plot_jitter` -theta :class:`Theta` The start arc angle :ref:`gallery_radial_chart` -theta2 :class:`Theta2` The end arc angle (radian) :ref:`gallery_pacman_chart` -========== =================== ================================= =================================== - -Mark Property Channels -^^^^^^^^^^^^^^^^^^^^^^ - -============= ====================== ============================== ========================================= -Channel Altair Class Description Example -============= ====================== ============================== ========================================= -angle :class:`Angle` The angle of the mark :ref:`gallery_wind_vector_map` -color :class:`Color` The color of the mark :ref:`gallery_simple_heatmap` -fill :class:`Fill` The fill for the mark :ref:`gallery_ridgeline_plot` -fillopacity :class:`FillOpacity` The opacity of the mark's fill N/A -opacity :class:`Opacity` The opacity of the mark :ref:`gallery_horizon_graph` -radius :class:`Radius` The radius or the mark :ref:`gallery_radial_chart` -shape :class:`Shape` The shape of the mark :ref:`gallery_us_incomebrackets_by_state_facet` -size :class:`Size` The size of the mark :ref:`gallery_table_bubble_plot_github` -stroke :class:`Stroke` The stroke of the mark N/A -strokeDash :class:`StrokeDash` The stroke dash style :ref:`gallery_multi_series_line` -strokeOpacity :class:`StrokeOpacity` The opacity of the line N/A -strokeWidth :class:`StrokeWidth` The width of the line N/A -============= ====================== ============================== ========================================= - -Text and Tooltip Channels -^^^^^^^^^^^^^^^^^^^^^^^^^ - -======= ================ ======================== ========================================= -Channel Altair Class Description Example -======= ================ ======================== ========================================= -text :class:`Text` Text to use for the mark :ref:`gallery_scatter_with_labels` -tooltip :class:`Tooltip` The tooltip value :ref:`gallery_scatter_tooltips` -======= ================ ======================== ========================================= - -.. _hyperlink-channel: - -Hyperlink Channel -^^^^^^^^^^^^^^^^^ - -======= ================ ======================== ========================================= -Channel Altair Class Description Example -======= ================ ======================== ========================================= -href :class:`Href` Hyperlink for points :ref:`gallery_scatter_href` -======= ================ ======================== ========================================= - -Detail Channel -^^^^^^^^^^^^^^ - -Grouping data is an important operation in data visualization. For line and area marks, -mapping an unaggregated data field to any -non-position channel will group the lines and stacked areas by that field. -For aggregated plots, all unaggregated fields encoded are used as grouping fields -in the aggregation (similar to fields in ``GROUP BY`` in SQL). - -The ``detail`` channel specifies an additional grouping field (or fields) for grouping -data without mapping the field(s) to any visual properties. - -======= ================ =============================== ========================================= -Channel Altair Class Description Example -======= ================ =============================== ========================================= -detail :class:`Detail` Additional property to group by :ref:`gallery_ranged_dot_plot` -======= ================ =============================== ========================================= - -For example here is a line chart showing stock prices of 5 tech companies over time. -We map the ``symbol`` variable to ``detail`` to use them to group lines. - -.. altair-plot:: - - import altair as alt - from vega_datasets import data - - source = data.stocks() - alt.Chart(source).mark_line().encode( - x="date:T", - y="price:Q", - detail="symbol:N" - ) - - -Order Channel -^^^^^^^^^^^^^ - -======= ================ ============================= ===================================== -Channel Altair Class Description Example -======= ================ ============================= ===================================== -order :class:`Order` Sets the order of the marks :ref:`gallery_connected_scatterplot` -======= ================ ============================= ===================================== - -Facet Channels -^^^^^^^^^^^^^^ - -======= ================ =============================================== ============================================= -Channel Altair Class Description Example -======= ================ =============================================== ============================================= -column :class:`Column` The column of a faceted plot :ref:`gallery_trellis_scatter_plot` -row :class:`Row` The row of a faceted plot :ref:`gallery_beckers_barley_trellis_plot` -facet :class:`Facet` The row and/or column of a general faceted plot :ref:`gallery_us_population_over_time_facet` -======= ================ =============================================== ============================================= .. _encoding-data-types: @@ -176,6 +46,10 @@ temporal ``T`` a time or date value geojson ``G`` a geographic shape ============ ============== ================================================ +For data specified as a DataFrame, Altair can automatically determine the +correct data type for each encoding, and creates appropriate scales and +legends to represent the data. + If types are not specified for data input as a DataFrame, Altair defaults to ``quantitative`` for any numeric data, ``temporal`` for date/time data, and ``nominal`` for string data, but be aware that these defaults are by no means @@ -276,117 +150,6 @@ data: a visual encoding that is suitable for categorical data may not be suitable for quantitative data, and vice versa. -.. _encoding-channel-options: - -Encoding Channel Options -~~~~~~~~~~~~~~~~~~~~~~~~ -Each encoding channel allows for a number of additional options to be expressed; -these can control things like axis properties, scale properties, headers and -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 - -Href, Tooltip, Url -^^^^^^^^^^^^^^^^^^ - -The :class:`Href`, :class:`Tooltip`, and :class:`Url` encodings accept the following options: - -.. altair-object-table:: altair.StringFieldDefWithCondition - -Detail -^^^^^^ - -The :class:`Detail` encoding accepts 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 - -Radius and Theta -^^^^^^^^^^^^^^^^ - -The :class:`Radius` and :class:`Theta` encodings accept the following options: - -.. altair-object-table:: altair.PositionFieldDefBase - -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 - - .. _encoding-aggregates: Binning and Aggregation @@ -499,76 +262,6 @@ Shorthand Equivalent long-form =================== ======================================================= -.. _ordering-channels: - -Ordering Marks -~~~~~~~~~~~~~~ - -The `order` option and :class:`Order` channel can sort how marks are drawn on the chart. - -For stacked marks, this controls the order of components of the stack. Here, the elements of each bar are sorted alphabetically by the name of the nominal data in the color channel. - -.. altair-plot:: - - import altair as alt - from vega_datasets import data - - barley = data.barley() - - alt.Chart(barley).mark_bar().encode( - x='variety:N', - y='sum(yield):Q', - color='site:N', - order=alt.Order("site", sort="ascending") - ) - -The order can be reversed by changing the sort option to `descending`. - -.. altair-plot:: - - import altair as alt - from vega_datasets import data - - barley = data.barley() - - alt.Chart(barley).mark_bar().encode( - x='variety:N', - y='sum(yield):Q', - color='site:N', - order=alt.Order("site", sort="descending") - ) - -The same approach works for other mark types, like stacked areas charts. - -.. altair-plot:: - - import altair as alt - from vega_datasets import data - - barley = data.barley() - - alt.Chart(barley).mark_area().encode( - x='variety:N', - y='sum(yield):Q', - color='site:N', - order=alt.Order("site", sort="ascending") - ) - -For line marks, the `order` channel encodes the order in which data points are connected. This can be useful for creating a scatter plot that draws lines between the dots using a different field than the x and y axes. - -.. altair-plot:: - - import altair as alt - from vega_datasets import data - - driving = data.driving() - - alt.Chart(driving).mark_line(point=True).encode( - alt.X('miles', scale=alt.Scale(zero=False)), - alt.Y('gas', scale=alt.Scale(zero=False)), - order='year' - ) - Sorting ~~~~~~~ @@ -794,3 +487,10 @@ the color scale used for the lines, you can use ``value``, e.g. ``alt.value("red ) lines + rule + + +.. toctree:: + :hidden: + + channels + channel_options From 1be0fd72ca03339e2adc14b0ec6d583eec04dca8 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 15 Dec 2022 19:19:46 +0000 Subject: [PATCH 14/25] Introduce both concepts of a channel and channel options in the beginning. Other minor improvements --- doc/user_guide/encodings/index.rst | 70 ++++++++++++++++++------------ 1 file changed, 43 insertions(+), 27 deletions(-) diff --git a/doc/user_guide/encodings/index.rst b/doc/user_guide/encodings/index.rst index cde7b6235..ee2fd466d 100644 --- a/doc/user_guide/encodings/index.rst +++ b/doc/user_guide/encodings/index.rst @@ -12,7 +12,7 @@ as an **encoding**, and is most often expressed through the :meth:`Chart.encode` method. For example, here we will visualize the cars dataset using four of the available -encodings: ``x`` (the x-axis value), ``y`` (the y-axis value), +**encoding channels** (see :ref:`user-guide-encoding-channels`): ``x`` (the x-axis value), ``y`` (the y-axis value), ``color`` (the color of the marker), and ``shape`` (the shape of the point marker): .. altair-plot:: @@ -28,6 +28,22 @@ encodings: ``x`` (the x-axis value), ``y`` (the y-axis value), shape='Origin' ) +Each encoding channel accepts a number of **channel options** which can be used to further configure +the chart. For example, below we adjust the y-axis title and increase the step between the x-axis ticks: + +.. altair-plot:: + import altair as alt + from vega_datasets import data + cars = data.cars() + + alt.Chart(cars).mark_point().encode( + x=alt.X('Horsepower', axis=alt.Axis(tickMinStep=50)), + y=alt.Y('Miles_per_Gallon', title="Miles per Gallon"), + color='Origin', + shape='Origin' + ) + +See :ref:`user-guide-encoding-channel-options` for all available options for each channel. .. _encoding-data-types: @@ -150,6 +166,29 @@ data: a visual encoding that is suitable for categorical data may not be suitable for quantitative data, and vice versa. +.. _shorthand-description: + +Encoding Shorthands +~~~~~~~~~~~~~~~~~~~ + +For convenience, Altair allows the specification of the variable name along +with the aggregate and type within a simple shorthand string syntax. +This makes use of the type shorthand codes listed in :ref:`encoding-data-types` +as well as the aggregate names listed in :ref:`encoding-aggregates`. +The following table shows examples of the shorthand specification alongside +the long-form equivalent: + +=================== ======================================================= +Shorthand Equivalent long-form +=================== ======================================================= +``x='name'`` ``alt.X('name')`` +``x='name:Q'`` ``alt.X('name', type='quantitative')`` +``x='sum(name)'`` ``alt.X('name', aggregate='sum')`` +``x='sum(name):Q'`` ``alt.X('name', aggregate='sum', type='quantitative')`` +``x='count():Q'`` ``alt.X(aggregate='count', type='quantitative')`` +=================== ======================================================= + + .. _encoding-aggregates: Binning and Aggregation @@ -239,33 +278,10 @@ variancep The population variance of field values. ========= =========================================================================== ===================================== -.. _shorthand-description: - -Encoding Shorthands -~~~~~~~~~~~~~~~~~~~ - -For convenience, Altair allows the specification of the variable name along -with the aggregate and type within a simple shorthand string syntax. -This makes use of the type shorthand codes listed in :ref:`encoding-data-types` -as well as the aggregate names listed in :ref:`encoding-aggregates`. -The following table shows examples of the shorthand specification alongside -the long-form equivalent: - -=================== ======================================================= -Shorthand Equivalent long-form -=================== ======================================================= -``x='name'`` ``alt.X('name')`` -``x='name:Q'`` ``alt.X('name', type='quantitative')`` -``x='sum(name)'`` ``alt.X('name', aggregate='sum')`` -``x='sum(name):Q'`` ``alt.X('name', aggregate='sum', type='quantitative')`` -``x='count():Q'`` ``alt.X(aggregate='count', type='quantitative')`` -=================== ======================================================= - - -Sorting -~~~~~~~ +Sort Option +~~~~~~~~~~~ -Specific channels can take a :class:`sort` property which determines the +Some channels can take a :class:`sort` option which determines the order of the scale being used for the channel. There are a number of different sort options available: From 2c89913c3dd0c4eb3f4bceace6b54fccee659fda Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 15 Dec 2022 19:30:38 +0000 Subject: [PATCH 15/25] Format code --- altair/sphinxext/schematable.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/altair/sphinxext/schematable.py b/altair/sphinxext/schematable.py index 64a6715f3..5892604c2 100644 --- a/altair/sphinxext/schematable.py +++ b/altair/sphinxext/schematable.py @@ -201,12 +201,12 @@ def run(self): result += [raw_html] # create the table from the object result.append(prepare_schema_table(schema, props=properties)) - + if not dont_collapse_table: html = "" raw_html = nodes.raw("", html, format="html") result += [raw_html] - + return result From 2d01fa1477ed29c4a04cc30a1e149a84bcfd5dd9 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Thu, 15 Dec 2022 19:38:03 +0000 Subject: [PATCH 16/25] Minor language improvements --- doc/user_guide/encodings/index.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/user_guide/encodings/index.rst b/doc/user_guide/encodings/index.rst index ee2fd466d..389807546 100644 --- a/doc/user_guide/encodings/index.rst +++ b/doc/user_guide/encodings/index.rst @@ -96,8 +96,7 @@ identical plots: The shorthand form, ``x="name:Q"``, is useful for its lack of boilerplate when doing quick data explorations. The long-form, ``alt.X('name', type='quantitative')``, is useful when doing more fine-tuned -adjustments to the encoding, such as binning, axis and scale properties, -or more. +adjustments to the encoding using channel options such as binning, axis, and scale. Specifying the correct type for your data is important, as it affects the way Altair represents your encoding in the resulting plot. @@ -248,7 +247,7 @@ 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: +aggregation functions built into Altair: ========= =========================================================================== ===================================== Aggregate Description Example @@ -272,7 +271,7 @@ stdev The sample standard deviation of field values. stdevp The population standard deviation of field values. N/A sum The sum of field values. :ref:`gallery_streamgraph` valid The count of field values that are not null or undefined. N/A -values ?? N/A +values A list of data objects in the group. N/A variance The sample variance of field values. N/A variancep The population variance of field values. N/A ========= =========================================================================== ===================================== @@ -281,7 +280,7 @@ variancep The population variance of field values. Sort Option ~~~~~~~~~~~ -Some channels can take a :class:`sort` option which determines the +Some channels accept a :class:`sort` option which determines the order of the scale being used for the channel. There are a number of different sort options available: From 93996591ec7f7dacb95756c7b34b42fa144495ac Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Mon, 19 Dec 2022 19:13:47 +0100 Subject: [PATCH 17/25] Update doc/user_guide/encodings/index.rst Co-authored-by: Joel Ostblom --- doc/user_guide/encodings/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/encodings/index.rst b/doc/user_guide/encodings/index.rst index 389807546..0d9540d3a 100644 --- a/doc/user_guide/encodings/index.rst +++ b/doc/user_guide/encodings/index.rst @@ -12,7 +12,7 @@ as an **encoding**, and is most often expressed through the :meth:`Chart.encode` method. For example, here we will visualize the cars dataset using four of the available -**encoding channels** (see :ref:`user-guide-encoding-channels`): ``x`` (the x-axis value), ``y`` (the y-axis value), +**encoding channels** (see :ref:`user-guide-encoding-channels` for details): ``x`` (the x-axis value), ``y`` (the y-axis value), ``color`` (the color of the marker), and ``shape`` (the shape of the point marker): .. altair-plot:: From 7a76bef074112e55dfe6d70ab2da4b3483da89be Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Mon, 19 Dec 2022 19:14:06 +0100 Subject: [PATCH 18/25] Update doc/user_guide/encodings/index.rst Co-authored-by: Joel Ostblom --- doc/user_guide/encodings/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/encodings/index.rst b/doc/user_guide/encodings/index.rst index 0d9540d3a..41bf61309 100644 --- a/doc/user_guide/encodings/index.rst +++ b/doc/user_guide/encodings/index.rst @@ -443,7 +443,7 @@ threshold value (e.g., 300 dollars stock price). lines + rule -If we instead used ``alt.value`` in this example, we would position the rule 300 pixels from the bottom of the chart border rather than at the 300 dollars position: +If we instead used ``alt.value`` in this example, we would position the rule 300 pixels from the top of the chart border rather than at the 300 dollars position. Since the default charts height is 300 pixels, this will show the dotted line just on top of the x-axis -line: .. altair-plot:: From 495a0ee3f073d23dcb77c493b757eea048448743 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Mon, 19 Dec 2022 19:14:18 +0100 Subject: [PATCH 19/25] Update doc/user_guide/encodings/index.rst Co-authored-by: Joel Ostblom --- doc/user_guide/encodings/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/encodings/index.rst b/doc/user_guide/encodings/index.rst index 41bf61309..577274a0b 100644 --- a/doc/user_guide/encodings/index.rst +++ b/doc/user_guide/encodings/index.rst @@ -454,7 +454,7 @@ If we instead used ``alt.value`` in this example, we would position the rule 300 lines + rule You can also use ``datum`` with :class:`DateTime`, for example, to highlight a certain year. -In addition, we will set the color for the rule to the same one as the line for the symbol ``MSFT`` +Here we also set the color for the rule to the same one as the line for the symbol ``MSFT`` with ``alt.datum("MSFT")``. .. altair-plot:: From f69cb9676c5aaa7628424cf22492b0f84b0b1fd8 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Mon, 19 Dec 2022 19:14:34 +0100 Subject: [PATCH 20/25] Update doc/user_guide/encodings/index.rst Co-authored-by: Joel Ostblom --- doc/user_guide/encodings/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/encodings/index.rst b/doc/user_guide/encodings/index.rst index 577274a0b..478c0588e 100644 --- a/doc/user_guide/encodings/index.rst +++ b/doc/user_guide/encodings/index.rst @@ -28,7 +28,7 @@ For example, here we will visualize the cars dataset using four of the available shape='Origin' ) -Each encoding channel accepts a number of **channel options** which can be used to further configure +Each encoding channel accepts a number of **channel options** (see :ref:`user-guide-encoding-channel-options` for details) which can be used to further configure the chart. For example, below we adjust the y-axis title and increase the step between the x-axis ticks: .. altair-plot:: From 2dcdc69f4fe9ef9c0c884cb1ddbc8f5ea79cde21 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Mon, 19 Dec 2022 19:14:49 +0100 Subject: [PATCH 21/25] Update doc/user_guide/encodings/index.rst Co-authored-by: Joel Ostblom --- doc/user_guide/encodings/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/user_guide/encodings/index.rst b/doc/user_guide/encodings/index.rst index 478c0588e..a91abaf94 100644 --- a/doc/user_guide/encodings/index.rst +++ b/doc/user_guide/encodings/index.rst @@ -43,7 +43,6 @@ the chart. For example, below we adjust the y-axis title and increase the step b shape='Origin' ) -See :ref:`user-guide-encoding-channel-options` for all available options for each channel. .. _encoding-data-types: From 1b53c0953f2b90381acd1fa5ed604b9218f15493 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Mon, 19 Dec 2022 19:15:04 +0100 Subject: [PATCH 22/25] Update doc/user_guide/encodings/index.rst Co-authored-by: Joel Ostblom --- doc/user_guide/encodings/index.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/user_guide/encodings/index.rst b/doc/user_guide/encodings/index.rst index a91abaf94..8d3821010 100644 --- a/doc/user_guide/encodings/index.rst +++ b/doc/user_guide/encodings/index.rst @@ -452,7 +452,9 @@ If we instead used ``alt.value`` in this example, we would position the rule 300 lines + rule -You can also use ``datum`` with :class:`DateTime`, for example, to highlight a certain year. +If we want to use ``datum`` to highlight a certain year on the x-axis, +we can't simply type in the year as an integer, +but instead need to use ``datum`` together with :class:`DateTime`. Here we also set the color for the rule to the same one as the line for the symbol ``MSFT`` with ``alt.datum("MSFT")``. From 4932b0eed94b795e9aa9912401537da1e96bee24 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Mon, 19 Dec 2022 19:18:13 +0100 Subject: [PATCH 23/25] Update doc/user_guide/encodings/channels.rst Co-authored-by: Joel Ostblom --- doc/user_guide/encodings/channels.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/user_guide/encodings/channels.rst b/doc/user_guide/encodings/channels.rst index f4710e7b2..6fadf165b 100644 --- a/doc/user_guide/encodings/channels.rst +++ b/doc/user_guide/encodings/channels.rst @@ -144,6 +144,9 @@ The order can be reversed by changing the sort option to `descending`. order=alt.Order("site", sort="descending") ) +If we want to sort stacked segments in a custom order, we can `follow the approach in this issue comment `_, although there might be edge cases where this is not fully supported. This also makes the order of the segments align with the order colors shows up in a legend that uses custom sorting for the color domain. + + The same approach works for other mark types, like stacked areas charts. .. altair-plot:: From c68eb978c5a09e67b30205093e96f2f6e8aa8699 Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Mon, 19 Dec 2022 18:24:33 +0000 Subject: [PATCH 24/25] Add reference to faceted charts section --- doc/user_guide/encodings/channels.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/user_guide/encodings/channels.rst b/doc/user_guide/encodings/channels.rst index 6fadf165b..057db9c71 100644 --- a/doc/user_guide/encodings/channels.rst +++ b/doc/user_guide/encodings/channels.rst @@ -180,6 +180,7 @@ For line marks, the `order` channel encodes the order in which data points are c Facet ~~~~~ +For more information, see :ref:`facet-chart`. ======= ================ =============================================== ============================================= Channel Altair Class Description Example From 20568e0cd365e32a94586696dae7d1aadb0778ac Mon Sep 17 00:00:00 2001 From: Stefan Binder Date: Mon, 19 Dec 2022 18:27:12 +0000 Subject: [PATCH 25/25] Add introductory sentences before tables --- doc/user_guide/configuration.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/user_guide/configuration.rst b/doc/user_guide/configuration.rst index 54c4ae051..86b04380a 100644 --- a/doc/user_guide/configuration.rst +++ b/doc/user_guide/configuration.rst @@ -104,6 +104,8 @@ Here is an example: labelFontSize=14 ) +Additional properties are summarized in the following table: + .. altair-object-table:: altair.HeaderConfig @@ -205,7 +207,8 @@ the following properties: Projection Configuration ------------------------ -:meth:`Chart.configure_projection` +Projections can be configured using :meth:`Chart.configure_projection`, +which has the following properties: .. altair-object-table:: altair.ProjectionConfig @@ -214,7 +217,8 @@ Projection Configuration Selection Configuration ----------------------- -:meth:`Chart.configure_selection` +Selections can be configured using :meth:`Chart.configure_selection`, +which has the following properties: .. altair-object-table:: altair.SelectionConfig