Add bidirectionality to layers

doc/syntax/clause/project.qmd

@@ -12,7 +12,7 @@ PROJECT <aesthetic>, ... TO <coordinate-system>
     SETTING <parameter> => <value>, ...
 ```
 
-The comma-separated list of `aesthetic` names are optional but allows you to define the names of the positional aesthetics in the plot. If omitted, the default aesthetic names of the coordinate system is used. The order given matters as the first name is used for the primary aesthetic, the second name for the secondary aesthetic and so on. For instance, using `PROJECT y, x TO cartesian` will flip the plot as anything mapped to `y` will now relate to the horizontal axis, and anything mapped to `x` will relate to the vertical axis. Note that it is not allowed to use the name of already established aesthetics as positional aesthetics, e.g. `PROJECT fill, stroke TO polar` is not allowed.
+The comma-separated list of `aesthetic` names are optional but allows you to define the names of the positional aesthetics in the plot. If omitted, the default aesthetic names of the coordinate system is used. The order given matters as the first name is used for the 1st axis, the second name for the 2nd axis and so on. For instance, using `PROJECT y, x TO cartesian` will flip the plot as anything mapped to `y` will now relate to the horizontal axis, and anything mapped to `x` will relate to the vertical axis. Note that it is not allowed to use the name of already established aesthetics as positional aesthetics, e.g. `PROJECT fill, stroke TO polar` is not allowed.
 
 ### `TO`
 ```ggsql

doc/syntax/coord/cartesian.qmd

@@ -7,8 +7,8 @@ The Cartesian coordinate system is the most well-known and the default for ggsql
 ## Default aesthetics
 The Cartesian coordinate system has the following default positional aesthetics which will be used if no others have been provided:
 
-* **Primary**: `x` (horizontal position)
-* **Secondary**: `y` (vertical position)
+* **First**: `x` (horizontal position)
+* **Second**: `y` (vertical position)
 
 Users can provide their own aesthetic names if needed, e.g.
 

doc/syntax/coord/polar.qmd

@@ -7,8 +7,8 @@ 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)
+* **First**: `theta` (angular position)
+* **Second**: `radius` (distance from center)
 
 Users can provide their own aesthetic names if needed. For example, if using `x` and `y` aesthetics:
 

doc/syntax/layer/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.
@@ -25,9 +25,13 @@ The following aesthetics are recognised by the area layer.
     * `'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.
+* `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
 
@@ -69,4 +73,4 @@ When `stacking => 'fill'` we're plotting stacked proportions. These only make se
 ```{ggsql}
 VISUALISE Date AS x, Value AS y, Series AS colour FROM long_airquality
   DRAW area SETTING stacking => 'fill'
-```
+```

doc/syntax/layer/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 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 has 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
 
@@ -87,3 +90,11 @@ DRAW bar
 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
+```

doc/syntax/layer/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 categories to create boxplots for.
+* Secondary axis (e.g. `y`): The values to calculate the summary statistics for the boxplot for
 
 ### Optional
 * `stroke`: The colour of the box contours, whiskers, median line and outliers.
@@ -42,7 +42,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 using the layers secondary axis.
+
+## Orientation
+Boxplots has categories along their primary axis. The orientation can be deduced purely from the mapping. To create a boxplot with the boxplots "laying down" you map the categories to `y` instead of `x` (assuming a default Cartesian coordinate system).
 
 ### Examples
 

doc/syntax/layer/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 variable to calculate density for.
 
 ### Optional
 * `stroke`: The colour of the contour lines.
@@ -65,7 +65,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 its secondary axis.
+
+## Orientation
+Density plots has the values to calculate the density of along their primary axis. The orientation can be deduced purely from the mapping. To create a vertical density plot you map the values to `y` instead of `x` (assuming a default Cartesian coordinate system).
 
 ## Examples
 

doc/syntax/layer/histogram.qmd

@@ -10,7 +10,7 @@ Visualise the distribution of a single continuous variable by dividing the x axi
 The following aesthetics are recognised by the bar layer.
 
 ### Required
-* `x`: Position on the x-axis
+* Primary axis (e.g. `x`): The value to bin and count.
 
 ### 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
+Histograms have the values to calculate to bin and count along their primary axis. The orientation can be deduced purely from the mapping. To create a vertical histogram you map the values to `y` instead of `x` (assuming a default Cartesian coordinate system).
 
 ## Examples
 

doc/syntax/layer/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
@@ -20,10 +20,13 @@ The following aesthetics are recognised by the line layer.
 * `linetype`: The type of line, i.e. the dashing pattern
 
 ## Settings
-The line layer has no additional settings
+* `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/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
@@ -20,10 +20,10 @@ The following aesthetics are recognised by the path layer.
 * `linetype`: The type of path, i.e. the dashing pattern
 
 ## Settings
-The line layer has no additional settings
+The path layer has no additional settings
 
 ## 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
 
 ## Examples
 
@@ -76,4 +76,4 @@ Compared to polygons, paths don't close their shapes and fill their interiors.
 VISUALISE x, y FROM df
   DRAW polygon MAPPING 'Polygon' AS stroke
   DRAW path MAPPING 'Path' AS stroke
-```
+```

doc/syntax/layer/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

doc/syntax/layer/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.
@@ -62,4 +62,4 @@ Invoking a group through discrete aesthetics works as well.
 ```{ggsql}
 VISUALISE x, y FROM df
   DRAW polygon MAPPING id AS colour
-```
+```

doc/syntax/layer/ribbon.qmd

@@ -10,9 +10,8 @@ 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`): The value of the independent variable.
+* Secondary axis range (e.g. `ymin` and `ymax`): The interval of the dependent variable.
 
 ### Optional
 * `stroke`: The colour of the contour lines.
@@ -25,7 +24,10 @@ The following aesthetics are recognised by the ribbon layer.
 The ribbon layer has no additional settings.
 
 ## Data transformation
-The ribbon layer does not transform its data but passes it through unchanged.
+The line layer sorts the data along its primary position
+
+## 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
 

doc/syntax/layer/violin.qmd

@@ -11,8 +11,8 @@ The violins are mirrored kernel density estimates, similar to the [density](dens
 The following aesthetics are recognised by the violin layer.
 
 ### Required
-* `x`: Position on the x-axis (categorical).
-* `y`: Value on the y-axis for which to compute density.
+* Primary axis (e.g. `x`): The categories to create violins for.
+* Secondary axis (e.g. `y`): The values to calculate the density for the violins for
 
 ### Optional
 * `stroke`: The colour of the contour lines.
@@ -50,6 +50,9 @@ The major difference between a violin layer and a density layer is just the matt
 
 * `density AS offset`: By default the offsets around a centerline reflect the computed density.
 
+## Orientation
+Violin plots has categories along their primary axis. The orientation can be deduced purely from the mapping. To create a violin plot with the violins "laying down" you map the categories to `y` instead of `x` (assuming a default Cartesian coordinate system).
+
 ## Examples
 
 A typical violin plot.