docs: Use Facet/Trellis/Repeat consistently

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 <https://en.wikipedia.org/wiki/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:
 

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`
-row      :class:`Row`      The row of a faceted plot                        :ref:`gallery_beckers_barley_trellis_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_facet`
 facet    :class:`Facet`    The row and/or column of a general faceted plot  :ref:`gallery_us_population_over_time_facet`
 =======  ================  ===============================================  =============================================

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 <https://en.wikipedia.org/wiki/Anscombe%27s_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,

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)

tests/examples_arguments_syntax/bar_chart_trellis_compact.py → 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

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)

tests/examples_arguments_syntax/beckers_barley_trellis_plot.py → 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." <http://ml.stat.purdue.edu/stat695t/writings/Trellis.User.pdf>`_. 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." <http://ml.stat.purdue.edu/stat695t/writings/Trellis.User.pdf>`_.
 """
 # category: case studies
 import altair as alt

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 <https://vega.github.io/vega-lite/docs/facet.html#facet-full>`_ 
-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." <http://ml.stat.purdue.edu/stat695t/writings/Trellis.User.pdf>`_.
 """
-# 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,

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
+)

tests/examples_arguments_syntax/trellis_histogram.py → 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",
 )

tests/examples_arguments_syntax/ridgeline_plot.py

@@ -2,12 +2,11 @@
 Ridgeline plot
 --------------
 A `Ridgeline plot <https://serialmentor.com/blog/2017/9/15/goodbye-joyplots>`_
-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

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",
+)