Polish area and ribbon layers

doc/syntax/index.qmd

@@ -18,6 +18,8 @@ There are many different layers to choose from when visualising your data. Some
 - [`point`](layer/point.qmd) is used to create a scatterplot layer
 - [`line`](layer/line.qmd) is used to produce lineplots with the data sorted along the x axis
 - [`path`](layer/path.qmd) is like `line` above but does not sort the data but plot it according to its own order
+- [`area`](layer/area.qmd) is used to display series as an area chart.
+- [`ribbon`](layer/ribbon.qmd) is used to display series extrema.
 - [`bar`](layer/bar.qmd) creates a bar chart, optionally calculating y from the number of records in each bar
 - [`histogram`](layer/histogram.qmd) bins the data along the x axis and produces a bar for each bin showing the number of records in it
 - [`boxplot`](layer/boxplot.qmd) displays continuous variables as 5-number summaries

doc/syntax/layer/area.qmd

@@ -0,0 +1,72 @@
+---
+title: "Area"
+---
+
+> Layers are declared with the [`DRAW` clause](../clause/draw.qmd). Read the documentation for this clause for a thorough description of how to use it.
+
+The area layer is used to display absolute amounts over a sorted x-axis. It can be seen as a [ribbon layer](ribbon.qmd) where the `ymin` is anchored at zero.
+
+## Aesthetics
+The following aesthetics are recognised by the area layer.
+
+### Required
+* `x`: Position along the x-axis.
+* `y`: Position along the y-axis.
+
+### Optional
+* `stroke`: The colour of the contour lines.
+* `fill`: The colour of the inner area.
+* `colour`: Shorthand for setting `stroke` and `fill` simultaneously.
+* `opacity`: The opacity of the colours.
+* `linewidth`: The width of the contour lines.
+
+## Settings
+* `stacking`: Determines how multiple groups are displayed. One of the following:
+    * `'off'`: The groups `y`-values are displayed as-is (default).
+    * `'on'`: The `y`-values are stacked per `x` position, accumulating over groups.
+    * `'fill'`: Like `'on'` but displayed as a fraction of the total per `x` position.
+
+## Data transformation
+The area layer does not transform its data but passes it through unchanged.
+
+## Examples
+
+Create a typical area chart
+
+```{ggsql}
+VISUALISE FROM ggsql:airquality
+DRAW area 
+  MAPPING Date AS x, Wind AS y
+```
+
+We can reshape the data to 'long format' from our wide format.
+
+```{ggsql}
+CREATE TABLE long_airquality AS
+SELECT * FROM ggsql:airquality
+UNPIVOT(
+  Value FOR Series IN (Temp, Wind)
+) AS u;
+```
+
+Which means we can display multiple series at once, by mapping the identifier to an aesthetic.
+
+```{ggsql}
+VISUALISE Date AS x, Value AS y FROM long_airquality
+  DRAW area MAPPING Series AS colour
+```
+
+We can stack the series by using `stacking => 'on'`. The line serves as a reference for 'unstacked' data.
+
+```{ggsql}
+VISUALISE Date AS x, Value AS y, Series AS colour FROM long_airquality
+  DRAW area SETTING stacking => 'on', opacity => 0.5
+  DRAW line
+```
+
+When `stacking => 'fill'` we're plotting stacked proportions. These only make sense if every series is measured in the same absolute unit. (Wind and temperature have different units and the temperature is not absolute.)
+
+```{ggsql}
+VISUALISE Date AS x, Value AS y, Series AS colour FROM long_airquality
+  DRAW area SETTING stacking => 'fill'
+```

doc/syntax/layer/ribbon.qmd

@@ -0,0 +1,58 @@
+---
+title: "Ribbon"
+---
+
+> Layers are declared with the [`DRAW` clause](../clause/draw.qmd). Read the documentation for this clause for a thorough description of how to use it.
+
+The ribbon layer is used to display extrema over a sorted x-axis. It can be seen as an [area chart](area.qmd) that is unanchored from zero.
+
+## Aesthetics
+The following aesthetics are recognised by the ribbon layer.
+
+### Required
+* `x`: Position along the x-axis
+* `ymin`: Lower position along the y-axis.
+* `ymax`: Upper position along the y-axis.
+
+### Optional
+* `stroke`: The colour of the contour lines.
+* `fill`: The colour of the inner area.
+* `colour`: Shorthand for setting `stroke` and `fill` simultaneously.
+* `opacity`: The opacity of the colours.
+* `linewidth`: The width of the contour lines.
+
+## Settings
+The ribbon layer has no additional settings.
+
+## Data transformation
+The ribbon layer does not transform its data but passes it through unchanged.
+
+## Examples
+
+A ribbon plot with arbitrary values as minima/maxima
+
+```{ggsql}
+VISUALISE FROM ggsql:airquality
+  DRAW ribbon
+    MAPPING Date AS x, Wind AS ymin, Temp AS ymax
+```
+
+Ribbon plots are great for showing the range of some aggregation.
+
+```{ggsql}
+// Weekly aggregation of temperature
+SELECT 
+  WEEKOFYEAR(Date) AS Week, 
+  MAX(Temp) AS MaxTemp, 
+  MEAN(Temp) AS MeanTemp,
+  MIN(Temp) AS MinTemp 
+FROM ggsql:airquality
+GROUP BY WEEKOFYEAR(Date)
+
+VISUALISE Week AS x
+  DRAW ribbon 
+    MAPPING MinTemp AS ymin, MaxTemp AS ymax
+    SETTING opacity => 0.5
+  DRAW line
+    MAPPING MeanTemp AS y
+```

src/plot/layer/geom/area.rs

@@ -1,5 +1,7 @@
 //! Area geom implementation
 
+use crate::plot::{DefaultParam, DefaultParamValue};
+
 use super::{GeomAesthetics, GeomTrait, GeomType};
 
 /// Area geom - filled area charts
@@ -13,11 +15,26 @@ impl GeomTrait for Area {
 
     fn aesthetics(&self) -> GeomAesthetics {
         GeomAesthetics {
-            supported: &["x", "y", "color", "colour", "fill", "stroke", "opacity"],
+            supported: &[
+                "x",
+                "y",
+                "fill",
+                "stroke",
+                "opacity",
+                "linewidth",
+                // "linetype", // vegalite doesn't support strokeDash
+            ],
             required: &["x", "y"],
             hidden: &[],
         }
     }
+
+    fn default_params(&self) -> &'static [DefaultParam] {
+        &[DefaultParam {
+            name: "stacking",
+            default: DefaultParamValue::String("off"),
+        }]
+    }
 }
 
 impl std::fmt::Display for Area {

src/plot/layer/geom/ribbon.rs

@@ -14,7 +14,14 @@ impl GeomTrait for Ribbon {
     fn aesthetics(&self) -> GeomAesthetics {
         GeomAesthetics {
             supported: &[
-                "x", "ymin", "ymax", "color", "colour", "fill", "stroke", "opacity",
+                "x",
+                "ymin",
+                "ymax",
+                "fill",
+                "stroke",
+                "opacity",
+                "linewidth",
+                // "linetype" // vegalite doesn't support strokeDash
             ],
             required: &["x", "ymin", "ymax"],
             hidden: &[],