updates based on review

Author: thomasp85

doc/syntax/clause/draw.qmd

@@ -97,3 +97,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 treats 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 and 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 has an orientation also has 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`) has an `orientation` setting that allows you to set the orientation explicitly.

doc/syntax/layer/type/area.qmd

@@ -22,7 +22,9 @@ 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
+* `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 sorts the data along its primary axis
@@ -77,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 x, Value AS y, Series AS colour FROM long_airquality
+DRAW area 
+  SETTING position => 'stack', center => true, orientation => 'transposed'
+```

doc/syntax/layer/type/bar.qmd

@@ -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 the secondary axis 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
 
@@ -43,7 +43,7 @@ If the secondary axis has not been mapped the layer will calculate it for you.
 * `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).
+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
 

doc/syntax/layer/type/boxplot.qmd

@@ -29,7 +29,12 @@ 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
 
@@ -77,12 +82,12 @@ Consider more observations as outliers by setting a smaller `coef`:
 
 ```{ggsql}
 VISUALISE FROM ggsql:penguins
-DRAW boxplot
+Create a horizontal boxplot by swapping `x` and `y`:
   MAPPING species AS x, bill_len AS y
   SETTING coef => 0.1
 ```
 
-Create a horizontal boxplot by swapping x and y:
+Create a horizontal boxplot by swapping `x` and `y`:
 
 ```{ggsql}
 VISUALISE FROM ggsql:penguins

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
-* Primary axis (e.g. `x`): The continuous variable to estimate density for.
+* Primary axis (e.g. `x`): The continuous variable for which to estimate density.
 
 ### Optional
 * `stroke`: The colour of the contour lines.

doc/syntax/layer/type/errorbar.qmd

@@ -11,8 +11,8 @@ The following aesthetics are recognised by the errorbar layer.
 
 ### Required
 * 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.
+* 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.
@@ -27,7 +27,7 @@ The following aesthetics are recognised by the errorbar layer.
 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).
+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
 

doc/syntax/layer/type/histogram.qmd

@@ -43,7 +43,7 @@ The histogram layer will bin the records in each group and count them. By defaul
 * `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).
+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
 
@@ -90,7 +90,7 @@ DRAW histogram
     SETTING binwidth => 100
 ```
 
-Create a horizontal histogram by changing the mapping
+Create a histogram along the y axis by changing the mapping
 
 ```{ggsql}
 VISUALISE FROM ggsql:penguins

doc/syntax/layer/type/line.qmd

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

@@ -29,13 +29,15 @@ The following aesthetics are recognised by the abline layer.
 * `linetype`: The type of the line, i.e. the dashing pattern
 
 ## 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
+* `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 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.
+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
 

doc/syntax/layer/type/path.qmd

@@ -26,7 +26,7 @@ The following aesthetics are recognised by the path layer.
 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.
+The path layer has no orientation. The axes are treated symmetrically.
 
 ## Examples