Add bidirectionality to layers (#183)

Author: thomasp85

doc/syntax/clause/draw.qmd

@@ -98,3 +98,6 @@ ORDER BY <column>, ...
 ```
 
 For some layers the order of records in the data is important, e.g. the path layer which connect records in the order they are provided. Since databases often doesn't guarantee a specific order of the data, the `ORDER BY` clause can be used to enforce such and order. Even for layers where the order doesn't immediately seem to matter it may have an effect, e.g. an overplottet scatterplot where the records in the end of the data are plottet on top of the one in the start.
+
+## Layer orientation
+Some layer types treat the two axes differently. For instance, a boxplot has categories along a discrete axis and summary statistics along a continuous one. While we are used to seeing boxplots with categories along the x-axis, this is not a necessity. The orientation can be deduced directly from the mappings in the layer. So, if you map discrete data to the x axis and continuous data to the y axis you get a boxplot in the standard orientation, whereas if you switch the mapping the boxes will "lay down" instead. The vast majority of layers that have an orientation also have a unique mapping pattern that allows us to deduce the orientation directly from the mapping. The few layers where the mapping is ambiguous (e.g. `line`) have an `orientation` setting that allows you to set the orientation explicitly.

doc/syntax/coord/polar.qmd

@@ -7,16 +7,16 @@ The polar coordinate system interprets its primary aesthetic as the angular posi
 ## Default aesthetics
 The polar coordinate system has the following default positional aesthetics which will be used if no others have been provided:
 
-* **Primary**: `theta` (angular position)
-* **Secondary**: `radius` (distance from center)
+* **Primary**: `radius` (distance from center)
+* **Secondary**: `theta` (angular position)
 
 Users can provide their own aesthetic names if needed. For example, if using `x` and `y` aesthetics:
 
 ```ggsql
 PROJECT y, x TO polar
 ```
 
-This maps `y` to theta (angle) and `x` to radius. This is useful when converting from a cartesian coordinate system without editing all the mappings.
+This maps `y` to radius and `x` to theta (angle). This is useful when converting from a cartesian coordinate system without editing all the mappings.
 
 ## Settings
 * `clip`: Should data be removed if it appears outside the bounds of the coordinate system. Defaults to `true`

doc/syntax/layer/type/area.qmd

@@ -10,8 +10,8 @@ The area layer is used to display absolute amounts over a sorted x-axis. It can
 The following aesthetics are recognised by the area layer.
 
 ### Required
-* `x`: Position along the x-axis.
-* `y`: Position along the y-axis.
+* Primary axis (e.g. `x`): The value of the independent variable.
+* Secondary axis (e.g. `y`): The value of the dependent variable.
 
 ### Optional
 * `stroke`: The colour of the contour lines.
@@ -22,9 +22,15 @@ The following aesthetics are recognised by the area layer.
 
 ## Settings
 * `position`: Determines the position adjustment to use for the layer (default is `'stack'`)
+* `orientation`: The orientation of the layer, see the [Orientation section](#orientation). One of the following: 
+    * `'aligned'` to align the layer's primary axis with the coordinate system's first axis.
+    * `'transposed'` to align the layer's primary axis with the coordinate system's second axis.
 
 ## Data transformation
-The area layer does not transform its data but passes it through unchanged.
+The area layer sorts the data along its primary axis
+
+## Orientation
+Area plots are sorted and connected along their primary axis. Since the primary axis cannot be deduced from the mapping it must be specified using the `orientation` setting. E.g. if you wish to create a vertical area plot you need to set `orientation => 'transposed'` to indicate that the primary layer axis follows the second axis of the coordinate system.
 
 ## Examples
 
@@ -73,3 +79,11 @@ An alternative is to center the stacks to create a steamgraph
 VISUALISE Date AS x, Value AS y, Series AS colour FROM long_airquality
   DRAW area SETTING position => 'stack', center => true
 ```
+
+You can combine this with the `orientation` setting to make a vertical steamgraph
+
+```{ggsql}
+VISUALISE Date AS y, Value AS x, Series AS colour FROM long_airquality
+DRAW area 
+  SETTING position => 'stack', center => true, orientation => 'transposed'
+```

doc/syntax/layer/type/bar.qmd

@@ -13,8 +13,8 @@ The following aesthetics are recognised by the bar layer.
 The bar layer has no required aesthetics
 
 ### Optional
-* `x`: Position on the x-axis. If missing all records will be shown in the same bar
-* `y`: The height of the plot. If missing, it will be calculated by the layer
+* Primary axis (e.g. `x`): The categories to create bars for. If missing all records will be shown in the same bar
+* Secondary axis (e.g. `y`): The height of the bars. If missing, it will be calculated by the layer
 * `colour`: The default colour of each bar
 * `stroke`: The colour of the stroke around each bar. Overrides `colour`
 * `fill`: The fill colour of each bar. Overrides `colour`
@@ -27,7 +27,7 @@ The bar layer has no required aesthetics
 * `width`: The width of the bars as a proportion of the available width
 
 ## Data transformation
-If `y` has not been mapped the layer will calculate it for you.
+If the secondary axis has not been mapped the layer will calculate counts for you and display these as the secondary axis.
 
 ### Properties
 
@@ -40,7 +40,10 @@ If `y` has not been mapped the layer will calculate it for you.
 
 ### Default remappings
 
-* `count AS y`: By default the barplot will show count as the height of the bars
+* `count AS <secondary axis>`: By default the barplot will show count as the height of the bars
+
+## Orientation
+Bar plots have categories along their primary axis. The orientation is deduced directly from the mapping. To create a horizontal bar plot you map the categories to `y` instead of `x` (assuming a default Cartesian coordinate system).
 
 ## Examples
 
@@ -97,6 +100,19 @@ SCALE BINNED x
     SETTING breaks => 10
 ```
 
+Create a horizontal bar plot by changing the mapping
+
+```{ggsql}
+VISUALISE FROM ggsql:penguins
+DRAW bar
+    MAPPING species AS y
+```
+
 And use with a polar coordinate system to create a pie chart
 
-**TBD**
+```{ggsql}
+VISUALISE FROM ggsql:penguins
+DRAW bar
+    MAPPING species AS fill
+PROJECT TO polar
+```

doc/syntax/layer/type/boxplot.qmd

@@ -9,8 +9,8 @@ Boxplots display a summary of a continuous distribution. In the style of Tukey,
 The following aesthetics are recognised by the boxplot layer.
 
 ### Required
-* `x`: Position on the x-axis
-* `y`: Position on the y-axis
+* Primary axis (e.g. `x`): The categorical variable to group by
+* Secondary axis (e.g. `y`): The continuous variable to summarize
 
 ### Optional
 * `stroke`: The colour of the box contours, whiskers, median line and outliers.
@@ -29,11 +29,11 @@ The following aesthetics are recognised by the boxplot layer.
 * `width`: Relative width of the boxes. Defaults to `0.9`.
 
 ## Data transformation
-Per group, data will be divided into 4 quartiles and summary statistics will be derived from their extremes.
-Because number of observations per quartile may differ by one, the result of this approach may slightly differ from a pure quantile-based approach.
-The central line represents the median.
-The boxes are displayed from the 25th up to the 75th percentiles.
-The whiskers are calculated from the 25th/75th percentiles +/- the IQR times `coef`, but no more extreme than the data extrema.
+Per group, data will be divided into 4 quartiles and summary statistics will be derived from their extremes. 
+Because number of observations per quartile may differ by one, the result of this approach may slightly differ from a pure quantile-based approach. 
+The central line represents the median. 
+The boxes are displayed from the 25th up to the 75th percentiles. 
+The whiskers are calculated from the 25th/75th percentiles +/- the IQR times `coef`, but no more extreme than the data extrema. 
 Observations are considered outliers when they are more extreme than the whiskers.
 
 ### Calculated statistics
@@ -43,7 +43,10 @@ Observations are considered outliers when they are more extreme than the whisker
 
 ### Default remapping
 
-* `value AS y`: By default the values are displayed along the y-axis.
+* `value AS <secondary axis>`: By default the values are displayed along the secondary axis.
+
+## Orientation
+The boxplot has its categorical groups along the primary axis and the continuous values along the secondary axis. The orientation can be deduced from the scale types or from the mapping. To create a horizontal boxplot, map the categorical variable to `y` and the continuous variable to `x` (assuming a default Cartesian coordinate system).
 
 ### Examples
 
@@ -83,3 +86,11 @@ DRAW boxplot
   MAPPING species AS x, bill_len AS y
   SETTING coef => 0.1
 ```
+
+Create a horizontal boxplot by swapping `x` and `y`:
+
+```{ggsql}
+VISUALISE FROM ggsql:penguins
+DRAW boxplot
+  MAPPING species AS y, bill_len AS x
+```

doc/syntax/layer/type/density.qmd

@@ -10,7 +10,7 @@ Visualise the distribution of a single continuous variable by computing a kernel
 The following aesthetics are recognised by the density layer.
 
 ### Required
-* `x`: Position on the x-axis.
+* Primary axis (e.g. `x`): The continuous variable for which to estimate density.
 
 ### Optional
 * `stroke`: The colour of the contour lines.
@@ -62,7 +62,10 @@ $$
 
 ### Default remappings
 
-* `density AS y`: By default the density layer will display the computed density along the y-axis.
+* `density AS <secondary axis>`: By default the density layer will display the computed density along the secondary axis.
+
+## Orientation
+The density has its primary axis along the variable for which density is computed. The orientation can be deduced from the mapping. To create a horizontal density plot, map the variable to `y` instead of `x` (assuming a default Cartesian coordinate system).
 
 ## Examples
 

doc/syntax/layer/type/errorbar.qmd

@@ -10,11 +10,9 @@ Errorbars are used to display paired metrics, typically some interval, for a var
 The following aesthetics are recognised by the errorbar layer.
 
 ### Required
-* `x` or `y`: Position on the x- or y-axis. These are mutually exclusive.
-* `xmin` or `ymin`: Position of one of the interval ends orthogonal to the main position. These are also mutually exclusive.
-* `xmax` or `ymax`: Position of the other interval end orthogonal to the main position. These are also mutually exclusive.
-
-Note that the required aesthetics is either a set of {`x`, `ymin`, `ymax`} or {`y`, `xmin`, `xmax`} and *not* a combination of the two.
+* Primary axis (e.g. `x`): Position along the primary axis
+* Secondary axis minimum (e.g. `ymin`): Lower position along the secondary axis.
+* Secondary axis maximum (e.g. `ymax`): Upper position along the secondary axis.
 
 ### Optional
 * `stroke`/`colour`: The colour of the lines in the errorbar.
@@ -28,6 +26,9 @@ Note that the required aesthetics is either a set of {`x`, `ymin`, `ymax`} or {`
 ## Data transformation
 The errorbar layer does not transform its data but passes it through unchanged.
 
+## Orientation
+The orientation of errorbar layers is deduced directly from the mapping, because the interval is mapped to the secondary axis. To create a horizontal errorbar layer, you map the independent variable to `y` instead of `x` and the interval to `xmin` and `xmax` (assuming a default Cartesian coordinate system).
+
 ## Examples
 
 ```{ggsql}

doc/syntax/layer/type/histogram.qmd

@@ -4,13 +4,13 @@ title: "Histogram"
 
 > 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.
 
-Visualise the distribution of a single continuous variable by dividing the x axis into bins and counting the number of observations in each bin. If providing a weight then a weighted histogram is calculated instead.
+Visualise the distribution of a single continuous variable by dividing the primary axis into bins and counting the number of observations in each bin. If providing a weight then a weighted histogram is calculated instead.
 
 ## Aesthetics
 The following aesthetics are recognised by the bar layer.
 
 ### Required
-* `x`: Position on the x-axis
+* Primary axis (e.g. `x`): The continuous variable to bin
 
 ### Optional
 * `colour`: The default colour of each bar
@@ -27,7 +27,7 @@ The following aesthetics are recognised by the bar layer.
 * `closed`: Either `'left'` or `'right'` (default). Determines whether the bin intervals are closed to the left or right side
 
 ## Data transformation
-The histogram layer will bin the records in each group and count them. By default it will map the count to `y`.
+The histogram layer will bin the records in each group and count them. By default it will map the count to the secondary axis.
 
 ### Properties
 
@@ -40,7 +40,10 @@ The histogram layer will bin the records in each group and count them. By defaul
 
 ### Default remappings
 
-* `count AS y`: By default the histogram will show count as the height of the bars
+* `count AS <secondary axis>`: By default the histogram will show count as the height of the bars
+
+## Orientation
+The histogram has its primary axis along the binned variable. The orientation is deduced directly from the mapping. To create a horizontal histogram, you map the variable to `y` instead of `x` (assuming a default Cartesian coordinate system).
 
 ## Examples
 
@@ -86,3 +89,11 @@ DRAW histogram
     MAPPING body_mass AS x
     SETTING binwidth => 100
 ```
+
+Create a histogram along the y axis by changing the mapping
+
+```{ggsql}
+VISUALISE FROM ggsql:penguins
+DRAW histogram
+    MAPPING body_mass AS y
+```

doc/syntax/layer/type/line.qmd

@@ -10,8 +10,8 @@ The line layer is used to create lineplots. Lineplots always connects records al
 The following aesthetics are recognised by the line layer.
 
 ### Required
-* `x`: Position along the x-axis
-* `y`: Position along the y-axis
+* Primary axis (e.g. `x`): The value of the independent variable.
+* Secondary axis (e.g. `y`): The value of the dependent variable.
 
 ### Optional
 * `colour`/`stroke`: The colour of the line
@@ -21,9 +21,15 @@ The following aesthetics are recognised by the line layer.
 
 ## Settings
 * `position`: Determines the position adjustment to use for the layer (default is `'identity'`)
+* `orientation`: The orientation of the layer, see the [Orientation section](#orientation). One of the following: 
+    * `'aligned'` to align the layer's primary axis with the coordinate system's first axis.
+    * `'transposed'` to align the layer's primary axis with the coordinate system's second axis.
 
 ## Data transformation
-The line layer does not transform its data but passes it through unchanged
+The line layer sorts the data along its primary axis.
+
+## Orientation
+Line plots are sorted and connected along their primary axis. Since the primary axis cannot be deduced from the mapping it must be specified using the `orientation` setting. If you wish to create a vertical line plot, you need to set `orientation => 'transposed'` to indicate that the primary layer axis follows the second axis of the coordinate system.  
 
 ## Examples
 

doc/syntax/layer/type/linear.qmd

@@ -13,6 +13,8 @@ $$
 
 Where $a$ is the `intercept` and $\beta$ is the `coef`.
 
+> The linear layer doesn't have a natural extend along either axes and the scale ranges can thus not be deduced from it. If the linear layer is the only layer in the visualisation you must specify the position scale ranges manually.
+
 ## Aesthetics
 The following aesthetics are recognised by the abline layer.
 
@@ -27,11 +29,16 @@ The following aesthetics are recognised by the abline layer.
 * `linetype`: The type of the line, i.e. the dashing pattern
 
 ## Settings
-The linear layer has no additional settings.
+* `orientation`: The orientation of the layer, see the [Orientation section](#orientation). One of the following: 
+    * `'aligned'` to align the layer's primary axis with the coordinate system's first axis.
+    * `'transposed'` to align the layer's primary axis with the coordinate system's second axis.
 
 ## Data transformation
 The linear layer does not transform its data but passes it through unchanged.
 
+## Orientation
+Linear layers use the predictor ($x$) for their primary axis and the response $y$ for its secondary axis. Since the primary axis cannot be deduced from the mapping it must be specified using the `orientation` setting. E.g. to create a vertical linear plot, you need to set `orientation => 'transposed'` to indicate that the primary layer axis follows the second axis of the coordinate system.
+
 ## Examples
 
 Add a simple reference line to a scatterplot: