Add bidirectionality to layers

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,13 @@ 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. Either `'aligned'` (default), or `'transposed'`. Determines if the layers primary axis is aligned with the coordinate systems first axis or not
 
 ## 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
 

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 it for you.
 
 ### 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 can be deduced purely 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,12 +29,7 @@ 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.
-Observations are considered outliers when they are more extreme than the whiskers.
+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 +38,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 +81,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 to estimate density for.
 
 ### 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 min (e.g. `ymin`): Lower position along the secondary axis.
+* Secondary axis max (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
+Ribbon layers are sorted and connected along their primary axis. The orientation can be deduced purely from the mapping since interval is mapped to the secodnary axis. To create a vertical ribbon 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 can be deduced 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 horizontal histogram 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,13 @@ 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. Either `'aligned'` (default), or `'transposed'`. Determines if the layers primary axis is aligned with the coordinate systems first axis or not
 
 ## 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. E.g. 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,14 @@ 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. Either `'aligned'` (default), or `'transposed'`. Determines if the layers primary axis ($x$ in the equation) is aligned with the coordinate systems first axis or not
 
 ## Data transformation
 The linear layer does not transform its data but passes it through unchanged.
 
+## Orientation
+Linear layers uses 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. if you wish 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:

doc/syntax/layer/type/path.qmd

@@ -10,8 +10,8 @@ The path layer is used to create lineplots, but contrary to the [line layer](lin
 The following aesthetics are recognised by the path layer.
 
 ### Required
-* `x`: Position along the x-axis
-* `y`: Position along the y-axis
+* Primary axis (e.g. `x`): Position along the primary axis.
+* Secondary axis (e.g. `y`): Position along the secondary axis.
 
 ### Optional
 * `colour`/`stroke`: The colour of the path
@@ -23,7 +23,10 @@ The following aesthetics are recognised by the path layer.
 * `position`: Determines the position adjustment to use for the layer (default is `'identity'`)
 
 ## Data transformation
-The line layer does not transform its data but passes it through unchanged
+The path layer does not transform its data but passes it through unchanged
+
+## Orientation
+The path layer is symmetric in how it regards its axes and thus doesn't exhibit any orientation.
 
 ## Examples
 

doc/syntax/layer/type/point.qmd

@@ -10,8 +10,8 @@ The point layer is used to create scatterplots. The scatterplot is most useful f
 The following aesthetics are recognised by the point layer.
 
 ### Required
-* `x`: Position along the x-axis
-* `y`: Position along the y-axis
+* Primary axis (e.g. `x`): Position along the primary axis.
+* Secondary axis (e.g. `y`): Position along the secondary axis.
 
 ### Optional
 * `size`: The size of each point
@@ -27,6 +27,9 @@ The following aesthetics are recognised by the point layer.
 ## Data transformation
 The point layer does not transform its data but passes it through unchanged
 
+## Orientation
+The point layer is symmetric in how it regards its axes and thus doesn't exhibit any orientation.
+
 ## Examples
 
 Create a classic scatterplot

doc/syntax/layer/type/polygon.qmd

@@ -10,8 +10,8 @@ Polygons can be used to draw arbitrary closed shapes based on an ordered sequenc
 The following aesthetics are recognised by the polygon layer.
 
 ### Required
-* `x` Position along the x-axis.
-* `y` Position along the y-axis.
+* Primary axis (e.g. `x`): Position along the primary axis.
+* Secondary axis (e.g. `y`): Position along the secondary axis.
 
 ### Optional
 * `stroke` The colour of the contour lines.
@@ -27,6 +27,9 @@ The following aesthetics are recognised by the polygon layer.
 ## Data transformation
 The polygon layer does not transform its data but passes it through unchanged
 
+## Orientation
+The polygon layer is symmetric in how it regards its axes and thus doesn't exhibit any orientation.
+
 ## Examples
 
 ```{ggsql}

doc/syntax/layer/type/ribbon.qmd

@@ -10,9 +10,9 @@ The ribbon layer is used to display extrema over a sorted x-axis. It can be seen
 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.
+* Primary axis (e.g. `x`): Position along the primary axis
+* Secondary axis min (e.g. `ymin`): Lower position along the secondary axis.
+* Secondary axis max (e.g. `ymax`): Upper position along the secondary axis.
 
 ### Optional
 * `stroke`: The colour of the contour lines.
@@ -25,7 +25,10 @@ The following aesthetics are recognised by the ribbon layer.
 * `position`: Determines the position adjustment to use for the layer (default is `'identity'`)
 
 ## Data transformation
-The ribbon layer does not transform its data but passes it through unchanged.
+The ribbon layer sorts the data along its primary axis
+
+## Orientation
+Ribbon layers are sorted and connected along their primary axis. The orientation can be deduced purely from the mapping since interval is mapped to the secodnary axis. To create a vertical ribbon 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