From 80f8662a9ce5d7a93a29c98cb1ab6fc3fb173108 Mon Sep 17 00:00:00 2001 From: Nick Crews Date: Tue, 29 Aug 2023 17:02:16 -0800 Subject: [PATCH 01/12] example: update trellis_area to use facet See https://github.com/altair-viz/altair/issues/3178 This removes the old trellis_area example, because that is just a simpler version of the sorted version. Might as well just have the sorted version, it is easy enough to see how you would jusst remove the sort to get back to the original example. This also adds some commas to the code so that black keeps the formatting the same. I wanted to update the name of the example so that it didn't contain the word "trellis". While I was at it I also wanted the examples to be in better sort order. --- .../examples_arguments_syntax/area_faceted.py | 21 +++++++++++++++++++ .../examples_arguments_syntax/trellis_area.py | 19 ----------------- .../trellis_area_sort_array.py | 21 ------------------- tests/examples_methods_syntax/area_faceted.py | 19 +++++++++++++++++ .../trellis_area_sort_array.py | 21 ------------------- tests/test_transformed_data.py | 12 ++++++----- 6 files changed, 47 insertions(+), 66 deletions(-) create mode 100644 tests/examples_arguments_syntax/area_faceted.py delete mode 100644 tests/examples_arguments_syntax/trellis_area.py delete mode 100644 tests/examples_arguments_syntax/trellis_area_sort_array.py create mode 100644 tests/examples_methods_syntax/area_faceted.py delete mode 100644 tests/examples_methods_syntax/trellis_area_sort_array.py diff --git a/tests/examples_arguments_syntax/area_faceted.py b/tests/examples_arguments_syntax/area_faceted.py new file mode 100644 index 000000000..4869a4157 --- /dev/null +++ b/tests/examples_arguments_syntax/area_faceted.py @@ -0,0 +1,21 @@ +""" +Faceted Area Chart +------------------ +Multiple area subcharts, one for each company. +We also show filtering out one of the companies, +and sorting the companies in a custom order. +""" +# category: area charts +import altair as alt +from vega_datasets import data + +source = data.stocks() + +alt.Chart(source).transform_filter( + alt.datum.symbol != "GOOG", +).mark_area().encode( + x="date:T", + y="price:Q", + color="symbol:N", + row=alt.Row("symbol:N", sort=["MSFT", "AAPL", "IBM", "AMZN"]), +).properties(height=50, width=400) diff --git a/tests/examples_arguments_syntax/trellis_area.py b/tests/examples_arguments_syntax/trellis_area.py deleted file mode 100644 index 08cb18df0..000000000 --- a/tests/examples_arguments_syntax/trellis_area.py +++ /dev/null @@ -1,19 +0,0 @@ -""" -Trellis Area Chart ------------------- -This example shows small multiples of an area chart. -""" -# category: area charts -import altair as alt -from vega_datasets import data - -source = data.iowa_electricity() - -alt.Chart(source).mark_area().encode( - x="year:T", - y="net_generation:Q", - color="source:N", - row="source:N" -).properties( - height=100 -) diff --git a/tests/examples_arguments_syntax/trellis_area_sort_array.py b/tests/examples_arguments_syntax/trellis_area_sort_array.py deleted file mode 100644 index a8c74532e..000000000 --- a/tests/examples_arguments_syntax/trellis_area_sort_array.py +++ /dev/null @@ -1,21 +0,0 @@ -''' -Trellis Area Sort Chart ------------------------ -This example shows small multiples of an area chart. -Stock prices of four large companies -sorted by `['MSFT', 'AAPL', 'IBM', 'AMZN']` -''' -# category: area charts -import altair as alt -from vega_datasets import data - -source = data.stocks() - -alt.Chart(source).transform_filter( - alt.datum.symbol != 'GOOG' -).mark_area().encode( - x='date:T', - y='price:Q', - color='symbol:N', - row=alt.Row('symbol:N', sort=['MSFT', 'AAPL', 'IBM', 'AMZN']) -).properties(height=50, width=400) diff --git a/tests/examples_methods_syntax/area_faceted.py b/tests/examples_methods_syntax/area_faceted.py new file mode 100644 index 000000000..b729e8c43 --- /dev/null +++ b/tests/examples_methods_syntax/area_faceted.py @@ -0,0 +1,19 @@ +""" +Faceted Area Chart +------------------ +Multiple area subcharts, one for each company. +We also show filtering out one of the companies, +and sorting the companies in a custom order. +""" +# category: area charts +import altair as alt +from vega_datasets import data + +source = data.stocks() + +alt.Chart(source).transform_filter(alt.datum.symbol != "GOOG").mark_area().encode( + x="date:T", + y="price:Q", + color="symbol:N", + row=alt.Row("symbol:N").sort(["MSFT", "AAPL", "IBM", "AMZN"]), +).properties(height=50, width=400) diff --git a/tests/examples_methods_syntax/trellis_area_sort_array.py b/tests/examples_methods_syntax/trellis_area_sort_array.py deleted file mode 100644 index 2dab32fde..000000000 --- a/tests/examples_methods_syntax/trellis_area_sort_array.py +++ /dev/null @@ -1,21 +0,0 @@ -''' -Trellis Area Sort Chart ------------------------ -This example shows small multiples of an area chart. -Stock prices of four large companies -sorted by `['MSFT', 'AAPL', 'IBM', 'AMZN']` -''' -# category: area charts -import altair as alt -from vega_datasets import data - -source = data.stocks() - -alt.Chart(source).transform_filter( - alt.datum.symbol != 'GOOG' -).mark_area().encode( - x='date:T', - y='price:Q', - color='symbol:N', - row=alt.Row('symbol:N').sort(['MSFT', 'AAPL', 'IBM', 'AMZN']) -).properties(height=50, width=400) diff --git a/tests/test_transformed_data.py b/tests/test_transformed_data.py index 64675486e..4c8e9e24c 100644 --- a/tests/test_transformed_data.py +++ b/tests/test_transformed_data.py @@ -1,9 +1,11 @@ -from altair.utils.execeval import eval_block -import altair as alt -from tests import examples_methods_syntax -from vega_datasets import data import pkgutil + import pytest +from vega_datasets import data + +import altair as alt +from altair.utils.execeval import eval_block +from tests import examples_methods_syntax try: import vegafusion as vf # type: ignore @@ -55,7 +57,7 @@ ("top_k_items.py", 10, ["rank", "IMDB_Rating_start"]), ("top_k_letters.py", 9, ["rank", "letters"]), ("top_k_with_others.py", 10, ["ranked_director", "mean_aggregate_gross"]), - ("trellis_area_sort_array.py", 492, ["date", "price"]), + ("area_faceted.py", 492, ["date", "price"]), ("trellis_histogram.py", 20, ["Origin", "__count"]), ("us_population_over_time.py", 38, ["sex", "people_start"]), ("us_population_over_time_facet.py", 285, ["year", "sum_people"]), From a348b02639e8c146d8661e7edc059abf31f43f7d Mon Sep 17 00:00:00 2001 From: Nick Crews Date: Tue, 29 Aug 2023 17:11:54 -0800 Subject: [PATCH 02/12] example: Use facet in trellist_stacked_bar_chart See https://github.com/altair-viz/altair/issues/3178 --- .../bar_faceted_stacked.py | 19 +++++++++++++++++++ .../trellis_stacked_bar_chart.py | 17 ----------------- 2 files changed, 19 insertions(+), 17 deletions(-) create mode 100644 tests/examples_arguments_syntax/bar_faceted_stacked.py delete mode 100644 tests/examples_arguments_syntax/trellis_stacked_bar_chart.py diff --git a/tests/examples_arguments_syntax/bar_faceted_stacked.py b/tests/examples_arguments_syntax/bar_faceted_stacked.py new file mode 100644 index 000000000..57f3816d7 --- /dev/null +++ b/tests/examples_arguments_syntax/bar_faceted_stacked.py @@ -0,0 +1,19 @@ +""" +Faceted Stacked Bar Chart +========================= +A horizontal stacked bar chart using barley crop yield data. +The chart is horizontally faceted based on the year, +and vertically faceted based on variety. +""" +# category: bar charts +import altair as alt +from vega_datasets import data + +source = data.barley() + +alt.Chart(source).mark_bar().encode( + column="year:O", + x="yield", + y="variety", + color="site", +).properties(width=220) diff --git a/tests/examples_arguments_syntax/trellis_stacked_bar_chart.py b/tests/examples_arguments_syntax/trellis_stacked_bar_chart.py deleted file mode 100644 index 7fa5d8c22..000000000 --- a/tests/examples_arguments_syntax/trellis_stacked_bar_chart.py +++ /dev/null @@ -1,17 +0,0 @@ -""" -Trellis Stacked Bar Chart -========================= -This is an example of a horizontal stacked bar chart using data which contains crop yields over different regions and different years in the 1930s. -""" -# category: bar charts -import altair as alt -from vega_datasets import data - -source = data.barley() - -alt.Chart(source).mark_bar().encode( - column='year:O', - x='yield', - y='variety', - color='site' -).properties(width=220) From 7a904598616e615c3d449176b1f39c5e4ee01c8e Mon Sep 17 00:00:00 2001 From: Nick Crews Date: Tue, 29 Aug 2023 17:16:31 -0800 Subject: [PATCH 03/12] example: Use facet in bar_chart_trellis_compact See https://github.com/altair-viz/altair/issues/3178 --- ...chart_trellis_compact.py => bar_chart_faceted_compact.py} | 5 +++-- ...chart_trellis_compact.py => bar_chart_faceted_compact.py} | 5 +++-- tests/test_transformed_data.py | 2 +- 3 files changed, 7 insertions(+), 5 deletions(-) rename tests/examples_arguments_syntax/{bar_chart_trellis_compact.py => bar_chart_faceted_compact.py} (93%) rename tests/examples_methods_syntax/{bar_chart_trellis_compact.py => bar_chart_faceted_compact.py} (93%) diff --git a/tests/examples_arguments_syntax/bar_chart_trellis_compact.py b/tests/examples_arguments_syntax/bar_chart_faceted_compact.py similarity index 93% rename from tests/examples_arguments_syntax/bar_chart_trellis_compact.py rename to tests/examples_arguments_syntax/bar_chart_faceted_compact.py index 6fb011476..0f5bfea0c 100644 --- a/tests/examples_arguments_syntax/bar_chart_trellis_compact.py +++ b/tests/examples_arguments_syntax/bar_chart_faceted_compact.py @@ -1,7 +1,8 @@ """ -Compact Trellis Grid of Bar Charts +Compact Faceted Grid of Bar Charts ================================== -This example shows a simple grid of bar charts to compare performance data.. +A simple grid of bar charts to compare performance data, +one subchart for each subset of the data. """ # category: bar charts import altair as alt diff --git a/tests/examples_methods_syntax/bar_chart_trellis_compact.py b/tests/examples_methods_syntax/bar_chart_faceted_compact.py similarity index 93% rename from tests/examples_methods_syntax/bar_chart_trellis_compact.py rename to tests/examples_methods_syntax/bar_chart_faceted_compact.py index 2cb0e4b7d..ba46e3b92 100644 --- a/tests/examples_methods_syntax/bar_chart_trellis_compact.py +++ b/tests/examples_methods_syntax/bar_chart_faceted_compact.py @@ -1,7 +1,8 @@ """ -Compact Trellis Grid of Bar Charts +Compact Faceted Grid of Bar Charts ================================== -This example shows a simple grid of bar charts to compare performance data.. +A simple grid of bar charts to compare performance data, +one subchart for each subset of the data. """ # category: bar charts import altair as alt diff --git a/tests/test_transformed_data.py b/tests/test_transformed_data.py index 4c8e9e24c..91dd092fc 100644 --- a/tests/test_transformed_data.py +++ b/tests/test_transformed_data.py @@ -19,7 +19,7 @@ ("annual_weather_heatmap.py", 366, ["monthdate_date_end", "max_temp_max"]), ("anscombe_plot.py", 44, ["Series", "X", "Y"]), ("bar_chart_sorted.py", 6, ["site", "sum_yield"]), - ("bar_chart_trellis_compact.py", 27, ["p", "p_end"]), + ("bar_chart_faceted_compact.py", 27, ["p", "p_end"]), ("beckers_barley_trellis_plot.py", 120, ["year", "site"]), ("beckers_barley_wrapped_facet.py", 120, ["site", "median_yield"]), ("bump_chart.py", 100, ["rank", "yearmonth_date"]), From e264009cf2ee8c033203a3091591333e1dfe2892 Mon Sep 17 00:00:00 2001 From: Nick Crews Date: Tue, 29 Aug 2023 17:24:55 -0800 Subject: [PATCH 04/12] example: Use facet in trellis_scatter_plot See https://github.com/altair-viz/altair/issues/3178 --- doc/user_guide/encodings/channels.rst | 4 ++-- .../examples_arguments_syntax/scatter_faceted.py | 16 ++++++++++++++++ .../trellis_scatter_plot.py | 16 ---------------- 3 files changed, 18 insertions(+), 18 deletions(-) create mode 100644 tests/examples_arguments_syntax/scatter_faceted.py delete mode 100644 tests/examples_arguments_syntax/trellis_scatter_plot.py diff --git a/doc/user_guide/encodings/channels.rst b/doc/user_guide/encodings/channels.rst index 9a056a25d..c75d54bc3 100644 --- a/doc/user_guide/encodings/channels.rst +++ b/doc/user_guide/encodings/channels.rst @@ -95,7 +95,7 @@ For example here is a line chart showing stock prices of 5 tech companies over t We map the ``symbol`` variable to ``detail`` to use them to group lines. .. altair-plot:: - + import altair as alt from vega_datasets import data @@ -187,7 +187,7 @@ For more information, see :ref:`facet-chart`. ======= ================ =============================================== ============================================= Channel Altair Class Description Example ======= ================ =============================================== ============================================= -column :class:`Column` The column of a faceted plot :ref:`gallery_trellis_scatter_plot` +column :class:`Column` The column of a faceted plot :ref:`gallery_scatter_faceted` 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/tests/examples_arguments_syntax/scatter_faceted.py b/tests/examples_arguments_syntax/scatter_faceted.py new file mode 100644 index 000000000..65968f932 --- /dev/null +++ b/tests/examples_arguments_syntax/scatter_faceted.py @@ -0,0 +1,16 @@ +""" +Faceted Scatter Plot +-------------------- +A series of scatter plots, one for each country/area of origin. +""" +# category: scatter plots +import altair as alt +from vega_datasets import data + +source = data.cars() + +alt.Chart(source, width=100, height=100).mark_point().encode( + x="Horsepower:Q", + y="Miles_per_Gallon:Q", + row="Origin:N", +) diff --git a/tests/examples_arguments_syntax/trellis_scatter_plot.py b/tests/examples_arguments_syntax/trellis_scatter_plot.py deleted file mode 100644 index 590a41922..000000000 --- a/tests/examples_arguments_syntax/trellis_scatter_plot.py +++ /dev/null @@ -1,16 +0,0 @@ -""" -Trellis Scatter Plot ------------------------ -This example shows how to make a trellis scatter plot. -""" -# category: scatter plots -import altair as alt -from vega_datasets import data - -source = data.cars() - -alt.Chart(source).mark_point().encode( - x='Horsepower:Q', - y='Miles_per_Gallon:Q', - row='Origin:N' -) From 7ee72976adce383208520762301897043bc67e34 Mon Sep 17 00:00:00 2001 From: Nick Crews Date: Tue, 29 Aug 2023 17:29:12 -0800 Subject: [PATCH 05/12] example: Use facet in trellis_histogram See https://github.com/altair-viz/altair/issues/3178 --- ...istogram.py => distributions_faceted_histogram.py} | 11 +++++++---- ...istogram.py => distributions_faceted_histogram.py} | 11 +++++++---- tests/test_transformed_data.py | 2 +- 3 files changed, 15 insertions(+), 9 deletions(-) rename tests/examples_arguments_syntax/{trellis_histogram.py => distributions_faceted_histogram.py} (56%) rename tests/examples_methods_syntax/{trellis_histogram.py => distributions_faceted_histogram.py} (56%) diff --git a/tests/examples_arguments_syntax/trellis_histogram.py b/tests/examples_arguments_syntax/distributions_faceted_histogram.py similarity index 56% rename from tests/examples_arguments_syntax/trellis_histogram.py rename to tests/examples_arguments_syntax/distributions_faceted_histogram.py index c124f2caf..7aeb2f6e1 100644 --- a/tests/examples_arguments_syntax/trellis_histogram.py +++ b/tests/examples_arguments_syntax/distributions_faceted_histogram.py @@ -1,7 +1,10 @@ """ -Trellis Histogram +Faceted Histogram ----------------- -This example shows how to make a basic trellis histogram. +This example shows how to make a basic faceted histogram, +with one histogram subplot for different subsets of the data. + +Based off the vega-lite example: https://vega.github.io/vega-lite/examples/trellis_bar_histogram.html """ # category: distributions @@ -12,6 +15,6 @@ alt.Chart(source).mark_bar().encode( alt.X("Horsepower:Q", bin=True), - y='count()', - row='Origin' + y="count()", + row="Origin", ) diff --git a/tests/examples_methods_syntax/trellis_histogram.py b/tests/examples_methods_syntax/distributions_faceted_histogram.py similarity index 56% rename from tests/examples_methods_syntax/trellis_histogram.py rename to tests/examples_methods_syntax/distributions_faceted_histogram.py index 8c45ccf20..23506d60e 100644 --- a/tests/examples_methods_syntax/trellis_histogram.py +++ b/tests/examples_methods_syntax/distributions_faceted_histogram.py @@ -1,7 +1,10 @@ """ -Trellis Histogram +Faceted Histogram ----------------- -This example shows how to make a basic trellis histogram. +This example shows how to make a basic faceted histogram, +with one histogram subplot for different subsets of the data. + +Based off the vega-lite example: https://vega.github.io/vega-lite/examples/trellis_bar_histogram.html """ # category: distributions @@ -12,6 +15,6 @@ alt.Chart(source).mark_bar().encode( alt.X("Horsepower:Q").bin(), - y='count()', - row='Origin' + y="count()", + row="Origin", ) diff --git a/tests/test_transformed_data.py b/tests/test_transformed_data.py index 91dd092fc..216c3aee4 100644 --- a/tests/test_transformed_data.py +++ b/tests/test_transformed_data.py @@ -58,7 +58,7 @@ ("top_k_letters.py", 9, ["rank", "letters"]), ("top_k_with_others.py", 10, ["ranked_director", "mean_aggregate_gross"]), ("area_faceted.py", 492, ["date", "price"]), - ("trellis_histogram.py", 20, ["Origin", "__count"]), + ("distributions_faceted_histogram.py", 20, ["Origin", "__count"]), ("us_population_over_time.py", 38, ["sex", "people_start"]), ("us_population_over_time_facet.py", 285, ["year", "sum_people"]), ("wilkinson-dot-plot.py", 21, ["data", "id"]), From 144047ea8e90deef17316b624eca37d33db1e058 Mon Sep 17 00:00:00 2001 From: Nick Crews Date: Tue, 29 Aug 2023 17:43:59 -0800 Subject: [PATCH 06/12] example: Use facet in beckers_barley_trellis_plot See https://github.com/altair-viz/altair/issues/3178 --- doc/user_guide/encodings/channels.rst | 2 +- ..._barley_trellis_plot.py => beckers_barley_facet.py} | 10 ++++++++-- ..._barley_trellis_plot.py => beckers_barley_facet.py} | 10 ++++++++-- tests/test_transformed_data.py | 2 +- 4 files changed, 18 insertions(+), 6 deletions(-) rename tests/examples_arguments_syntax/{beckers_barley_trellis_plot.py => beckers_barley_facet.py} (60%) rename tests/examples_methods_syntax/{beckers_barley_trellis_plot.py => beckers_barley_facet.py} (57%) diff --git a/doc/user_guide/encodings/channels.rst b/doc/user_guide/encodings/channels.rst index c75d54bc3..27e886d30 100644 --- a/doc/user_guide/encodings/channels.rst +++ b/doc/user_guide/encodings/channels.rst @@ -188,6 +188,6 @@ For more information, see :ref:`facet-chart`. Channel Altair Class Description Example ======= ================ =============================================== ============================================= column :class:`Column` The column of a faceted plot :ref:`gallery_scatter_faceted` -row :class:`Row` The row of a faceted plot :ref:`gallery_beckers_barley_trellis_plot` +row :class:`Row` The row of a faceted plot :ref:`gallery_beckers_barley_facet` facet :class:`Facet` The row and/or column of a general faceted plot :ref:`gallery_us_population_over_time_facet` ======= ================ =============================================== ============================================= diff --git a/tests/examples_arguments_syntax/beckers_barley_trellis_plot.py b/tests/examples_arguments_syntax/beckers_barley_facet.py similarity index 60% rename from tests/examples_arguments_syntax/beckers_barley_trellis_plot.py rename to tests/examples_arguments_syntax/beckers_barley_facet.py index 4f780d963..5ae4cfa39 100644 --- a/tests/examples_arguments_syntax/beckers_barley_trellis_plot.py +++ b/tests/examples_arguments_syntax/beckers_barley_facet.py @@ -1,7 +1,13 @@ """ -Becker's Barley Trellis Plot +Becker's Barley Faceted Plot ---------------------------- -The example demonstrates the trellis charts created by Richard Becker, William Cleveland and others in the 1990s. Using the visualization technique below they identified an anomoly in a widely used agriculatural dataset, which they termed `"The Morris Mistake." `_. It became their favored way of showcasing the power of this pioneering plot. +The example demonstrates the faceted charts created by Richard Becker, +William Cleveland and others in the 1990s. Using the visualization technique +where each row is a different site (i.e. the chart is faceted by site), +they identified an anomaly in a widely used agriculatural dataset, +where the "Morris" site accidentally had the years 1931 and 1932 swapped. +They named this +`"The Morris Mistake." `_. """ # category: case studies import altair as alt diff --git a/tests/examples_methods_syntax/beckers_barley_trellis_plot.py b/tests/examples_methods_syntax/beckers_barley_facet.py similarity index 57% rename from tests/examples_methods_syntax/beckers_barley_trellis_plot.py rename to tests/examples_methods_syntax/beckers_barley_facet.py index 9f7c68867..d3dcac894 100644 --- a/tests/examples_methods_syntax/beckers_barley_trellis_plot.py +++ b/tests/examples_methods_syntax/beckers_barley_facet.py @@ -1,7 +1,13 @@ """ -Becker's Barley Trellis Plot +Becker's Barley Faceted Plot ---------------------------- -The example demonstrates the trellis charts created by Richard Becker, William Cleveland and others in the 1990s. Using the visualization technique below they identified an anomoly in a widely used agriculatural dataset, which they termed `"The Morris Mistake." `_. It became their favored way of showcasing the power of this pioneering plot. +The example demonstrates the faceted charts created by Richard Becker, +William Cleveland and others in the 1990s. Using the visualization technique +where each row is a different site (i.e. the chart is faceted by site), +they identified an anomaly in a widely used agriculatural dataset, +where the "Morris" site accidentally had the years 1931 and 1932 swapped. +They named this +`"The Morris Mistake." `_. """ # category: case studies import altair as alt diff --git a/tests/test_transformed_data.py b/tests/test_transformed_data.py index 216c3aee4..aabc1af3f 100644 --- a/tests/test_transformed_data.py +++ b/tests/test_transformed_data.py @@ -20,7 +20,7 @@ ("anscombe_plot.py", 44, ["Series", "X", "Y"]), ("bar_chart_sorted.py", 6, ["site", "sum_yield"]), ("bar_chart_faceted_compact.py", 27, ["p", "p_end"]), - ("beckers_barley_trellis_plot.py", 120, ["year", "site"]), + ("beckers_barley_facet.py", 120, ["year", "site"]), ("beckers_barley_wrapped_facet.py", 120, ["site", "median_yield"]), ("bump_chart.py", 100, ["rank", "yearmonth_date"]), ("comet_chart.py", 120, ["variety", "delta"]), From 6a4dfa627d015d9b81afd770cb7570fc0d3c25c6 Mon Sep 17 00:00:00 2001 From: Nick Crews Date: Tue, 29 Aug 2023 17:52:26 -0800 Subject: [PATCH 07/12] example: Remove trellis in beckers_barley_wrapped See https://github.com/altair-viz/altair/issues/3178 This also re-categorizes this example as a case study. I think this makes more sense, as it puts it with the other beckers barley example. And there aren't really any advance calculations going on. --- .../beckers_barley_wrapped_facet.py | 24 +++++++++++-------- .../beckers_barley_wrapped_facet.py | 24 +++++++++++-------- 2 files changed, 28 insertions(+), 20 deletions(-) diff --git a/tests/examples_arguments_syntax/beckers_barley_wrapped_facet.py b/tests/examples_arguments_syntax/beckers_barley_wrapped_facet.py index b67af69d4..82d682d8f 100644 --- a/tests/examples_arguments_syntax/beckers_barley_wrapped_facet.py +++ b/tests/examples_arguments_syntax/beckers_barley_wrapped_facet.py @@ -1,21 +1,25 @@ """ -Becker's Barley Trellis Plot (Wrapped Facet) --------------------------------------------- -The example demonstrates the trellis charts created by Richard Becker, William Cleveland and others in the 1990s. -This is the Altair replicate of `the VegaLite version `_ -demonstrating the usage of `columns` argument to create wrapped facet. +Becker's Barley Wrapped Facet Plot +---------------------------------- +The example demonstrates the faceted charts created by Richard Becker, +William Cleveland and others in the 1990s. Using the visualization technique +where each row is a different site (i.e. the chart is faceted by site), +they identified an anomaly in a widely used agriculatural dataset, +where the "Morris" site accidentally had the years 1931 and 1932 swapped. +They named this +`"The Morris Mistake." `_. """ -# category: advanced calculations +# category: case studies import altair as alt from vega_datasets import data source = data.barley.url alt.Chart(source).mark_point().encode( - alt.X('median(yield):Q', scale=alt.Scale(zero=False)), - y='variety:O', - color='year:N', - facet=alt.Facet('site:O', columns=2), + alt.X("median(yield):Q", scale=alt.Scale(zero=False)), + y="variety:O", + color="year:N", + facet=alt.Facet("site:O", columns=2), ).properties( width=200, height=100, diff --git a/tests/examples_methods_syntax/beckers_barley_wrapped_facet.py b/tests/examples_methods_syntax/beckers_barley_wrapped_facet.py index 1b36dfbc0..a540d00dd 100644 --- a/tests/examples_methods_syntax/beckers_barley_wrapped_facet.py +++ b/tests/examples_methods_syntax/beckers_barley_wrapped_facet.py @@ -1,21 +1,25 @@ """ -Becker's Barley Trellis Plot (Wrapped Facet) --------------------------------------------- -The example demonstrates the trellis charts created by Richard Becker, William Cleveland and others in the 1990s. -This is the Altair replicate of `the VegaLite version `_ -demonstrating the usage of `columns` argument to create wrapped facet. +Becker's Barley Wrapped Facet Plot +---------------------------------- +The example demonstrates the faceted charts created by Richard Becker, +William Cleveland and others in the 1990s. Using the visualization technique +where each row is a different site (i.e. the chart is faceted by site), +they identified an anomaly in a widely used agriculatural dataset, +where the "Morris" site accidentally had the years 1931 and 1932 swapped. +They named this +`"The Morris Mistake." `_. """ -# category: advanced calculations +# category: case studies import altair as alt from vega_datasets import data source = data.barley.url alt.Chart(source).mark_point().encode( - alt.X('median(yield):Q').scale(zero=False), - y='variety:O', - color='year:N', - facet=alt.Facet('site:O', columns=2), + alt.X("median(yield):Q").scale(zero=False), + y="variety:O", + color="year:N", + facet=alt.Facet("site:O", columns=2), ).properties( width=200, height=100, From d5c0b1079d54e15515eada8b178c7e6902e2f613 Mon Sep 17 00:00:00 2001 From: Nick Crews Date: Tue, 29 Aug 2023 18:00:28 -0800 Subject: [PATCH 08/12] example: remove facet in density_facet This isn't an example of faceting, but repeating. See https://github.com/altair-viz/altair/issues/3178 --- .../density_facet.py | 28 --------------- .../density_repeat.py | 34 +++++++++++++++++++ 2 files changed, 34 insertions(+), 28 deletions(-) delete mode 100644 tests/examples_arguments_syntax/density_facet.py create mode 100644 tests/examples_arguments_syntax/density_repeat.py diff --git a/tests/examples_arguments_syntax/density_facet.py b/tests/examples_arguments_syntax/density_facet.py deleted file mode 100644 index 5bfbc27bb..000000000 --- a/tests/examples_arguments_syntax/density_facet.py +++ /dev/null @@ -1,28 +0,0 @@ -""" -Faceted Density Estimates -------------------------- -Density estimates of measurements for each iris flower feature -""" -# category: distributions - -import altair as alt -from vega_datasets import data - -source = data.iris() - -alt.Chart(source).transform_fold( - ['petalWidth', - 'petalLength', - 'sepalWidth', - 'sepalLength'], - as_ = ['Measurement_type', 'value'] -).transform_density( - density='value', - bandwidth=0.3, - groupby=['Measurement_type'], - extent= [0, 8] -).mark_area().encode( - alt.X('value:Q'), - alt.Y('density:Q'), - alt.Row('Measurement_type:N') -).properties(width=300, height=50) diff --git a/tests/examples_arguments_syntax/density_repeat.py b/tests/examples_arguments_syntax/density_repeat.py new file mode 100644 index 000000000..1db2b4c60 --- /dev/null +++ b/tests/examples_arguments_syntax/density_repeat.py @@ -0,0 +1,34 @@ +""" +Repeated Density Estimates +-------------------------- +Density estimates for each feature of iris flower. +This is what we call a "repeated" plot, with one subplot +for each feature. +""" +# category: distributions + +import altair as alt +from vega_datasets import data + +source = data.iris() + +alt.Chart(source).transform_fold( + [ + "petalWidth", + "petalLength", + "sepalWidth", + "sepalLength", + ], + as_=["Measurement_type", "value"], +).transform_density( + density="value", + bandwidth=0.3, + groupby=["Measurement_type"], + extent=[0, 8], +).mark_area().encode( + alt.X("value:Q"), + alt.Y("density:Q"), + alt.Row("Measurement_type:N"), +).properties( + width=300, height=50 +) From 8a2903ff2c084d2e3ea837c9c4c46190b3c4788b Mon Sep 17 00:00:00 2001 From: Nick Crews Date: Tue, 29 Aug 2023 18:06:36 -0800 Subject: [PATCH 09/12] example: Fix "facet" use in scatter_marginal_hist The scatter plot is not faceted, but the marginal scatter plots are, with one histogram for eadch subset. See https://github.com/altair-viz/altair/issues/3178 --- .../scatter_marginal_hist.py | 71 +++++++++++-------- .../scatter_marginal_hist.py | 63 ++++++++-------- 2 files changed, 74 insertions(+), 60 deletions(-) diff --git a/tests/examples_arguments_syntax/scatter_marginal_hist.py b/tests/examples_arguments_syntax/scatter_marginal_hist.py index 52455dcc0..b2718b524 100644 --- a/tests/examples_arguments_syntax/scatter_marginal_hist.py +++ b/tests/examples_arguments_syntax/scatter_marginal_hist.py @@ -1,9 +1,8 @@ """ -Facetted Scatter Plot with Marginal Histograms ----------------------------------------------- -This example demonstrates how to generate a facetted scatter plot, -with marginal facetted histograms, and how to share their respective -- x,some y-limits. +Scatter Plot with Faceted Marginal Histograms +--------------------------------------------- +This example demonstrates how to generate a scatter plot, +with faceted marginal histograms that share their respective x- and y-limits. """ # category: distributions import altair as alt @@ -16,35 +15,45 @@ xscale = alt.Scale(domain=(4.0, 8.0)) yscale = alt.Scale(domain=(1.9, 4.55)) -bar_args = {'opacity': .3, 'binSpacing': 0} +bar_args = {"opacity": 0.3, "binSpacing": 0} points = base.mark_circle().encode( - alt.X('sepalLength', scale=xscale), - alt.Y('sepalWidth', scale=yscale), - color='species', + alt.X("sepalLength", scale=xscale), + alt.Y("sepalWidth", scale=yscale), + color="species", ) -top_hist = base.mark_bar(**bar_args).encode( - alt.X('sepalLength:Q', - # when using bins, the axis scale is set through - # the bin extent, so we do not specify the scale here - # (which would be ignored anyway) - bin=alt.Bin(maxbins=20, extent=xscale.domain), - stack=None, - title='' - ), - alt.Y('count()', stack=None, title=''), - alt.Color('species:N'), -).properties(height=60) - -right_hist = base.mark_bar(**bar_args).encode( - alt.Y('sepalWidth:Q', - bin=alt.Bin(maxbins=20, extent=yscale.domain), - stack=None, - title='', - ), - alt.X('count()', stack=None, title=''), - alt.Color('species:N'), -).properties(width=60) +top_hist = ( + base.mark_bar(**bar_args) + .encode( + alt.X( + "sepalLength:Q", + # when using bins, the axis scale is set through + # the bin extent, so we do not specify the scale here + # (which would be ignored anyway) + bin=alt.Bin(maxbins=20, extent=xscale.domain), + stack=None, + title="", + ), + alt.Y("count()", stack=None, title=""), + alt.Color("species:N"), + ) + .properties(height=60) +) + +right_hist = ( + base.mark_bar(**bar_args) + .encode( + alt.Y( + "sepalWidth:Q", + bin=alt.Bin(maxbins=20, extent=yscale.domain), + stack=None, + title="", + ), + alt.X("count()", stack=None, title=""), + alt.Color("species:N"), + ) + .properties(width=60) +) top_hist & (points | right_hist) diff --git a/tests/examples_methods_syntax/scatter_marginal_hist.py b/tests/examples_methods_syntax/scatter_marginal_hist.py index 02ddc37fe..4905de5ba 100644 --- a/tests/examples_methods_syntax/scatter_marginal_hist.py +++ b/tests/examples_methods_syntax/scatter_marginal_hist.py @@ -1,9 +1,8 @@ """ -Facetted Scatter Plot with Marginal Histograms ----------------------------------------------- -This example demonstrates how to generate a facetted scatter plot, -with marginal facetted histograms, and how to share their respective -- x,some y-limits. +Scatter Plot with Faceted Marginal Histograms +--------------------------------------------- +This example demonstrates how to generate a scatter plot, +with faceted marginal histograms that share their respective x- and y-limits. """ # category: distributions import altair as alt @@ -16,33 +15,39 @@ xscale = alt.Scale(domain=(4.0, 8.0)) yscale = alt.Scale(domain=(1.9, 4.55)) -bar_args = {'opacity': .3, 'binSpacing': 0} +bar_args = {"opacity": 0.3, "binSpacing": 0} points = base.mark_circle().encode( - alt.X('sepalLength').scale(xscale), - alt.Y('sepalWidth').scale(yscale), - color='species', + alt.X("sepalLength").scale(xscale), + alt.Y("sepalWidth").scale(yscale), + color="species", ) -top_hist = base.mark_bar(**bar_args).encode( - alt.X('sepalLength:Q') - # when using bins, the axis scale is set through - # the bin extent, so we do not specify the scale here - # (which would be ignored anyway) - .bin(maxbins=20, extent=xscale.domain) - .stack(None) - .title(''), - alt.Y('count()').stack(None).title(''), - alt.Color('species:N'), -).properties(height=60) - -right_hist = base.mark_bar(**bar_args).encode( - alt.Y('sepalWidth:Q') - .bin(maxbins=20, extent=yscale.domain) - .stack(None) - .title(''), - alt.X('count()').stack(None).title(''), - alt.Color('species:N'), -).properties(width=60) +top_hist = ( + base.mark_bar(**bar_args) + .encode( + alt.X("sepalLength:Q") + # when using bins, the axis scale is set through + # the bin extent, so we do not specify the scale here + # (which would be ignored anyway) + .bin(maxbins=20, extent=xscale.domain).stack(None).title(""), + alt.Y("count()").stack(None).title(""), + alt.Color("species:N"), + ) + .properties(height=60) +) + +right_hist = ( + base.mark_bar(**bar_args) + .encode( + alt.Y("sepalWidth:Q") + .bin(maxbins=20, extent=yscale.domain) + .stack(None) + .title(""), + alt.X("count()").stack(None).title(""), + alt.Color("species:N"), + ) + .properties(width=60) +) top_hist & (points | right_hist) From 731e33fcd8fc96f3facf948245eaee0527aed1a4 Mon Sep 17 00:00:00 2001 From: Nick Crews Date: Tue, 29 Aug 2023 18:13:04 -0800 Subject: [PATCH 10/12] example: Use facet in ridgeline_plot This is using faceting, so let's call it out explicitly so people learn the terminology. See https://github.com/altair-viz/altair/issues/3178 --- tests/examples_arguments_syntax/ridgeline_plot.py | 5 ++--- tests/examples_methods_syntax/ridgeline_plot.py | 5 ++--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/tests/examples_arguments_syntax/ridgeline_plot.py b/tests/examples_arguments_syntax/ridgeline_plot.py index 79520b465..7c9625cf9 100644 --- a/tests/examples_arguments_syntax/ridgeline_plot.py +++ b/tests/examples_arguments_syntax/ridgeline_plot.py @@ -2,12 +2,11 @@ Ridgeline plot -------------- A `Ridgeline plot `_ -chart is a chart that lets you visualize distribution of a numeric value for -several groups. +lets you visualize distribution of a numeric value for different +subsets of data (what we call "facets" in Altair). Such a chart can be created in Altair by first transforming the data into a suitable representation. - """ # category: distributions import altair as alt diff --git a/tests/examples_methods_syntax/ridgeline_plot.py b/tests/examples_methods_syntax/ridgeline_plot.py index 963679e45..8ac691d64 100644 --- a/tests/examples_methods_syntax/ridgeline_plot.py +++ b/tests/examples_methods_syntax/ridgeline_plot.py @@ -2,12 +2,11 @@ Ridgeline plot -------------- A `Ridgeline plot `_ -chart is a chart that lets you visualize distribution of a numeric value for -several groups. +lets you visualize distribution of a numeric value for different +subsets of data (what we call "facets" in Altair). Such a chart can be created in Altair by first transforming the data into a suitable representation. - """ # category: distributions import altair as alt From f69cb81f081f14327fe5c197223170403533c058 Mon Sep 17 00:00:00 2001 From: Nick Crews Date: Tue, 29 Aug 2023 18:25:40 -0800 Subject: [PATCH 11/12] example: Use facet in anscombe_plot See https://github.com/altair-viz/altair/issues/3178 --- tests/examples_arguments_syntax/anscombe_plot.py | 15 +++++++++++---- tests/examples_methods_syntax/anscombe_plot.py | 15 +++++++++++---- 2 files changed, 22 insertions(+), 8 deletions(-) diff --git a/tests/examples_arguments_syntax/anscombe_plot.py b/tests/examples_arguments_syntax/anscombe_plot.py index 9e2007485..71342fd90 100644 --- a/tests/examples_arguments_syntax/anscombe_plot.py +++ b/tests/examples_arguments_syntax/anscombe_plot.py @@ -2,7 +2,14 @@ Anscombe's Quartet ------------------ -This example shows how to use the column channel to make a trellis plot. Anscombe's Quartet is a famous dataset constructed by Francis Anscombe. Common summary statistics are identical for each subset of the data, despite the subsets having vastly different characteristics. +`Anscombe's Quartet `_ +is a famous dataset constructed by Francis Anscombe. +It is made of 4 different subsets of data. +Each subset has very different characteristics, even though common summary +statistics such as mean and variance are identical. + +This example shows how to make a faceted plot, with each facet +showing a different subset of the data. """ # category: case studies import altair as alt @@ -11,9 +18,9 @@ source = data.anscombe() alt.Chart(source).mark_circle().encode( - alt.X('X', scale=alt.Scale(zero=False)), - alt.Y('Y', scale=alt.Scale(zero=False)), - alt.Facet('Series', columns=2), + alt.X("X", scale=alt.Scale(zero=False)), + alt.Y("Y", scale=alt.Scale(zero=False)), + alt.Facet("Series", columns=2), ).properties( width=180, height=180, diff --git a/tests/examples_methods_syntax/anscombe_plot.py b/tests/examples_methods_syntax/anscombe_plot.py index 906f15ee7..2b369f19a 100644 --- a/tests/examples_methods_syntax/anscombe_plot.py +++ b/tests/examples_methods_syntax/anscombe_plot.py @@ -2,7 +2,14 @@ Anscombe's Quartet ------------------ -This example shows how to use the column channel to make a trellis plot. Anscombe's Quartet is a famous dataset constructed by Francis Anscombe. Common summary statistics are identical for each subset of the data, despite the subsets having vastly different characteristics. +`Anscombe's Quartet `_ +is a famous dataset constructed by Francis Anscombe. +It is made of 4 different subsets of data. +Each subset has very different characteristics, even though common summary +statistics such as mean and variance are identical. + +This example shows how to make a faceted plot, with each facet +showing a different subset of the data. """ # category: case studies import altair as alt @@ -11,9 +18,9 @@ source = data.anscombe() alt.Chart(source).mark_circle().encode( - alt.X('X').scale(zero=False), - alt.Y('Y').scale(zero=False), - alt.Facet('Series', columns=2), + alt.X("X").scale(zero=False), + alt.Y("Y").scale(zero=False), + alt.Facet("Series", columns=2), ).properties( width=180, height=180, From d3ca696ddfb308f57b06831f78c57216e91225ec Mon Sep 17 00:00:00 2001 From: Nick Crews Date: Tue, 29 Aug 2023 18:46:06 -0800 Subject: [PATCH 12/12] docs: Link to "trellis" etc in definition of Facet See https://github.com/altair-viz/altair/issues/3178 Also improve the intro to Faceted charts. --- doc/user_guide/compound_charts.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/doc/user_guide/compound_charts.rst b/doc/user_guide/compound_charts.rst index dfeaba29b..828cc619b 100644 --- a/doc/user_guide/compound_charts.rst +++ b/doc/user_guide/compound_charts.rst @@ -269,7 +269,7 @@ encoding specification using ``alt.repeat('row')`` or ``alt.repeat('column')``. Another option to use the ``repeat`` method is for layering. Here below the columns ``US_Gross`` and ``Worldwide_Gross`` are layered on the ``y``-axis -using ``alt.repeat('layer')``: +using ``alt.repeat('layer')``: .. altair-plot:: @@ -292,9 +292,13 @@ more general in the future. Faceted Charts ~~~~~~~~~~~~~~ -Like repeated charts, Faceted charts provide a more convenient API for creating -multiple views of a dataset for a specific type of chart: one where each panel -contains a different subset of data. +Like repeated charts, Faceted charts provide multiple views of a dataset. +But instead of having different panels for different encodings, +we have different panels for different subsets of data. For example, +one panel for each of the three species of flower in the iris dataset. + +This is also called a `small multiple `_ +chart, trellis chart, lattice chart, grid chart, or panel chart. We could do this manually using a filter transform along with a horizontal concatenation: @@ -323,7 +327,7 @@ concatenation: As with the manual approach to :ref:`repeat-chart`, this is straightforward, if a bit verbose. -Using ``alt.facet`` it becomes a bit cleaner: +Using ``.facet`` it becomes a bit cleaner: .. altair-plot:: @@ -353,7 +357,7 @@ can give the same results: height=180 ) -The advantage of using ``alt.facet`` is that it can create faceted views of +The advantage of using ``.facet`` is that it can create faceted views of more complicated compound charts. For example, here is a faceted view of a layered chart with a hover selection: