Unify rule and linear layers (#252)

* Fix annotation layer query generation for geoms with no required aesthetics

When annotation layers have no required aesthetics (e.g., rule geom) and only
non-positional scalar parameters, process_annotation_layer now adds a dummy
column to generate valid SQL instead of malformed empty VALUES clause.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* adopt linear layer functionality into rule layer

* repurpose linear tests for rule

* repurpose docs

* eradicate linear layer

* grammar/highlighting fixes

* remove `intercept`

* adapt docs

* create `setup_layer()` method

* fix issue with expanding scales

* cargo fmt

* account for #249

* replace orientation blurb with position blurb

* compute decisions up front

* clarifying comment

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: teunbrand

CLAUDE.md

@@ -337,7 +337,7 @@ pub enum Geom {
     // Statistical geoms
     Histogram, Density, Smooth, Boxplot, Violin,
     // Annotation geoms
-    Text, Segment, Arrow, Rule, Linear, ErrorBar,
+    Text, Segment, Arrow, Rule, ErrorBar,
 }
 
 pub enum DataSource {
@@ -1221,7 +1221,7 @@ All clauses (MAPPING, SETTING, PARTITION BY, FILTER) are optional.
 
 - **Basic**: `point`, `line`, `path`, `bar`, `col`, `area`, `rect`, `polygon`, `ribbon`
 - **Statistical**: `histogram`, `density`, `smooth`, `boxplot`, `violin`
-- **Annotation**: `text`, `label`, `segment`, `arrow`, `rule`, `linear`, `errorbar`
+- **Annotation**: `text`, `label`, `segment`, `arrow`, `rule`, `errorbar`
 
 **MAPPING Clause** (Aesthetic Mappings):
 

doc/ggsql.xml

@@ -143,7 +143,6 @@
       <item>segment</item>
       <item>arrow</item>
       <item>rule</item>
-      <item>linear</item>
       <item>errorbar</item>
     </list>
 
@@ -174,6 +173,7 @@
       <item>italic</item>
       <item>hjust</item>
       <item>vjust</item>
+      <item>slope</item>
     </list>
 
     <!-- Scale Types (only in SCALE context) -->

doc/index.qmd

@@ -44,8 +44,8 @@ WHERE island = 'Biscoe'
 -- Followed by visualization declaration
 VISUALISE bill_len AS x, bill_dep AS y, body_mass AS fill
 DRAW point
-DRAW linear 
-  MAPPING 0.4 AS coef, -1 AS intercept
+PLACE rule 
+  SETTING slope => 0.4, y => -1
 SCALE BINNED fill
 LABEL
   title => 'Relationship between bill dimensions in 3 species of penguins',

doc/syntax/index.qmd

@@ -21,7 +21,6 @@ There are many different layers to choose from when visualising your data. Some
 - [`line`](layer/type/line.qmd) is used to produce lineplots with the data sorted along the x axis.
 - [`path`](layer/type/path.qmd) is like `line` above but does not sort the data but plot it according to its own order.
 - [`segment`](layer/type/segment.qmd) connects two points with a line segment.
-- [`linear`](layer/type/linear.qmd) draws a long line parameterised by a coefficient and intercept.
 - [`rule`](layer/type/rule.qmd) draws horizontal and vertical reference lines.
 - [`area`](layer/type/area.qmd) is used to display series as an area chart.
 - [`ribbon`](layer/type/ribbon.qmd) is used to display series extrema.

doc/syntax/layer/type/linear.qmd

@@ -6,6 +6,8 @@ title: "Rule"
 
 The rule layer is used to draw reference lines perpendicular to an axis at specified values. This is useful for adding thresholds, means, medians, event markers, cutoff dates or other guides to the plot. The lines span the full width or height of the panels.
 
+Additionally, the rule layer can draw diagonal reference lines by specifying a `slope` along with a position (`x` or `y`). The position acts as the intercept term in the linear equation. This is useful for adding regression lines, diagonal guides, or mathematical functions to plots.
+
 > The rule layer doesn't have a natural extent along the secondary axis. The secondary scale range can thus not be deduced from rule layers. If the rule layer is the only layer in the visualisation, you must specify the position scale range manually.
 
 ## Aesthetics
@@ -15,19 +17,27 @@ The following aesthetics are recognised by the rule layer.
 * Primary axis (e.g. `x` or `y`): Position along the primary axis.
 
 ### Optional
+* `slope` The $\beta$ in the equations described below. Defaults to 0.
 * `colour`/`stroke`: The colour of the line
 * `opacity`: The opacity of the line
 * `linewidth`: The width of the line
 * `linetype`: The type of the line, i.e. the dashing pattern
 
 ## Settings
-The rule layer has no additional settings.
+* `position`: Position adjustment. One of `'identity'` (default), `'stack'`, `'dodge'`, or `'jitter'`
 
 ## Data transformation
-The rule layer does not transform its data but passes it through unchanged.
+
+For diagonal lines, the position aesthetic determines the intercept:
+
+* `y = a, slope = β` creates the line: $y = a + \beta x$ (line passes through $(0, a)$)
+* `x = a, slope = β` creates the line: $x = a + \beta y$ (line passes through $(a, 0)$)
+
+Note that `slope` represents $\Delta x/\Delta y$ (change in x per unit change in y) when using `x` mapping, not the traditional $\Delta y/\Delta x$.
+The default slope is 0, creating horizontal lines when `y` is given and vertical lines when `x` is given.
 
 ## Orientation
-Rules are drawn perpendicular to their primary axis. The orientation is deduced directly from the mapping. To create a horizontal rule you map the values to `y` instead of `x` (assuming a default Cartesian coordinate system).
+The orientation is deduced directly from the mapping. See the ['Data transformation'](#data-transformation) section for details.
 
 ## Examples
 
@@ -73,3 +83,31 @@ DRAW line
 DRAW rule 
   MAPPING value AS y, label AS colour FROM thresholds
 ```
+
+Add a diagnoal reference line to a scatterplot by using `slope`
+
+```{ggsql}
+VISUALISE FROM ggsql:penguins
+  DRAW point MAPPING bill_len AS x, bill_dep AS y
+  PLACE rule SETTING slope => 0.4, y => -1
+```
+
+Add multiple reference lines with different colors from a separate dataset. Note we're mapping from data here, so we use `DRAW` instead of `PLACE`.
+
+```{ggsql}
+WITH lines AS (
+    SELECT * FROM (VALUES
+        (0.4, -1, 'Line A'),
+        (0.2, 8, 'Line B'),
+        (0.8, -19, 'Line C')
+    ) AS t(slope, intercept, label)
+)
+VISUALISE FROM ggsql:penguins
+  DRAW point MAPPING bill_len AS x, bill_dep AS y
+  DRAW rule
+    MAPPING 
+      slope AS slope, 
+      intercept AS y, 
+      label AS colour
+    FROM lines
+```

doc/syntax/layer/type/rule.qmd

@@ -250,7 +250,7 @@
       "patterns": [
         {
           "name": "support.type.aesthetic.ggsql",
-          "match": "\\b(x|y|xmin|xmax|ymin|ymax|xend|yend|weight|color|colour|fill|stroke|opacity|size|shape|linetype|linewidth|width|height|label|typeface|fontweight|italic|hjust|vjust|panel|row|column)\\b"
+          "match": "\\b(x|y|xmin|xmax|ymin|ymax|xend|yend|weight|color|colour|fill|stroke|opacity|size|shape|linetype|linewidth|width|height|label|typeface|fontweight|italic|hjust|vjust|slope|panel|row|column)\\b"
         }
       ]
     },
@@ -295,7 +295,7 @@
       "patterns": [
         {
           "name": "support.type.geom.ggsql",
-          "match": "\\b(point|line|path|bar|col|area|tile|polygon|ribbon|histogram|density|smooth|boxplot|violin|text|label|segment|arrow|rule|linear|errorbar)\\b"
+          "match": "\\b(point|line|path|bar|col|area|tile|polygon|ribbon|histogram|density|smooth|boxplot|violin|text|label|segment|arrow|rule|errorbar)\\b"
         },
         { "include": "#common-clause-patterns" }
       ]
@@ -309,7 +309,7 @@
       "patterns": [
         {
           "name": "support.type.geom.ggsql",
-          "match": "\\b(point|line|path|bar|col|area|rect|polygon|ribbon|histogram|density|smooth|boxplot|violin|text|label|segment|arrow|rule|linear|errorbar)\\b"
+          "match": "\\b(point|line|path|bar|col|area|rect|polygon|ribbon|histogram|density|smooth|boxplot|violin|text|label|segment|arrow|rule|errorbar)\\b"
         },
         { "include": "#common-clause-patterns" }
       ]

ggsql-vscode/syntaxes/ggsql.tmLanguage.json

@@ -714,7 +714,15 @@ fn process_annotation_layer(layer: &mut Layer, dialect: &dyn SqlDialect) -> Resu
         }
     }
 
-    // Step 2: Determine max array length from all annotation parameters
+    // Step 2: Handle empty annotation_params by adding a dummy column
+    // This occurs when geoms have no required aesthetics and user provides only
+    // non-positional scalar parameters (e.g., PLACE rule SETTING stroke => 'red')
+    if annotation_params.is_empty() {
+        // Add a dummy column so we can generate a valid VALUES clause
+        annotation_params.push(("__ggsql_dummy__".to_string(), ParameterValue::Number(1.0)));
+    }
+
+    // Step 3: Determine max array length from all annotation parameters
     let mut max_length = 1;
 
     for (aesthetic, value) in &annotation_params {
@@ -740,7 +748,7 @@ fn process_annotation_layer(layer: &mut Layer, dialect: &dyn SqlDialect) -> Resu
         }
     }
 
-    // Step 3: Build VALUES clause and create final mappings simultaneously
+    // Step 4: Build VALUES clause and create final mappings simultaneously
     let mut columns: Vec<Vec<ArrayElement>> = Vec::new();
     let mut column_names = Vec::new();
 
@@ -763,6 +771,11 @@ fn process_annotation_layer(layer: &mut Layer, dialect: &dyn SqlDialect) -> Resu
         // the same column→aesthetic renaming pipeline as regular layers
         column_names.push(aesthetic.clone());
 
+        // Skip creating mappings for dummy columns (they're just for valid SQL)
+        if aesthetic == "__ggsql_dummy__" {
+            continue;
+        }
+
         // Create final mapping directly (no intermediate Literal step)
         let is_positional = crate::plot::aesthetic::is_positional_aesthetic(aesthetic);
         let mapping_value = if is_positional {
@@ -784,7 +797,7 @@ fn process_annotation_layer(layer: &mut Layer, dialect: &dyn SqlDialect) -> Resu
         layer.parameters.remove(aesthetic);
     }
 
-    // Step 4: Build VALUES rows
+    // Step 5: Build VALUES rows
     let values_clause = (0..max_length)
         .map(|i| {
             let row: Vec<String> = columns.iter().map(|col| col[i].to_sql(dialect)).collect();
@@ -793,7 +806,7 @@ fn process_annotation_layer(layer: &mut Layer, dialect: &dyn SqlDialect) -> Resu
         .collect::<Vec<_>>()
         .join(", ");
 
-    // Step 5: Build complete SQL query
+    // Step 6: Build complete SQL query
     let column_list = column_names
         .iter()
         .map(|c| format!("\"{}\"", c))
@@ -1105,4 +1118,60 @@ mod tests {
         );
         assert_eq!(series.len(), 2);
     }
+
+    #[test]
+    fn test_annotation_no_required_aesthetics() {
+        // Rule geom has no required aesthetics, only optional ones
+        let mut layer = Layer::new(Geom::rule());
+        layer.source = Some(DataSource::Annotation);
+        // Only non-positional, non-required scalar parameters
+        layer.parameters.insert(
+            "stroke".to_string(),
+            ParameterValue::String("red".to_string()),
+        );
+        layer
+            .parameters
+            .insert("linewidth".to_string(), ParameterValue::Number(2.0));
+
+        let result = process_annotation_layer(&mut layer, &AnsiDialect);
+
+        // Should generate valid SQL with a dummy column
+        match result {
+            Ok(sql) => {
+                // Check that SQL is valid (has VALUES with at least one column)
+                assert!(
+                    !sql.contains("(VALUES ) AS t()"),
+                    "Should not generate empty VALUES clause"
+                );
+                assert!(
+                    sql.contains("VALUES") && sql.contains("WITH __ggsql_values__"),
+                    "Should have VALUES with at least one column"
+                );
+                // Should contain the dummy column
+                assert!(
+                    sql.contains("__ggsql_dummy__"),
+                    "Should have dummy column when no data columns exist"
+                );
+            }
+            Err(e) => {
+                panic!("Unexpected error: {}", e);
+            }
+        }
+
+        // Verify that stroke and linewidth remain in parameters (not moved to mappings)
+        assert!(
+            layer.parameters.contains_key("stroke"),
+            "Non-positional, non-required parameters should stay in parameters"
+        );
+        assert!(
+            layer.parameters.contains_key("linewidth"),
+            "Non-positional, non-required parameters should stay in parameters"
+        );
+
+        // Verify dummy column is not in mappings
+        assert!(
+            !layer.mappings.contains_key("__ggsql_dummy__"),
+            "Dummy column should not be added to mappings"
+        );
+    }
 }

src/execute/layer.rs

@@ -846,6 +846,8 @@ fn collect_layer_required_columns(layer: &Layer, spec: &Plot) -> HashSet<String>
 /// Prune columns from a DataFrame to only include required columns.
 ///
 /// Columns that don't exist in the DataFrame are silently ignored.
+/// If no required columns exist in the DataFrame (e.g., annotation layers with only
+/// literal aesthetics), returns a 0-column DataFrame with the same row count.
 fn prune_dataframe(df: &DataFrame, required: &HashSet<String>) -> Result<DataFrame> {
     let columns_to_keep: Vec<String> = df
         .get_column_names()
@@ -855,10 +857,28 @@ fn prune_dataframe(df: &DataFrame, required: &HashSet<String>) -> Result<DataFra
         .collect();
 
     if columns_to_keep.is_empty() {
-        return Err(GgsqlError::InternalError(format!(
-            "No columns remain after pruning. Required columns: {:?}",
-            required
-        )));
+        // Return a 0-column DataFrame with the same row count
+        // This happens for annotation layers with only literal aesthetics (e.g., PLACE rule SETTING slope => 0.4)
+        // The row count determines how many marks to draw; aesthetics come from Literal values in mappings
+        let row_count = df.height();
+
+        if row_count > 0 {
+            // Create a 0-column DataFrame with the correct row count
+            // We do this by creating a dummy column and then dropping it
+            use polars::prelude::df;
+            let with_rows = df! {
+                "__dummy__" => vec![0i32; row_count]
+            }
+            .map_err(|e| GgsqlError::InternalError(format!("Failed to create DataFrame: {}", e)))?;
+
+            let result = with_rows.drop("__dummy__").map_err(|e| {
+                GgsqlError::InternalError(format!("Failed to drop dummy column: {}", e))
+            })?;
+            return Ok(result);
+        } else {
+            // 0 rows - just return empty DataFrame
+            return Ok(DataFrame::default());
+        }
     }
 
     df.select(&columns_to_keep)
@@ -1046,6 +1066,16 @@ pub fn prepare_data_with_reader<R: Reader>(query: &str, reader: &R) -> Result<Pr
         &specs[0].aesthetic_context,
     )?;
 
+    // Allow geoms to adjust mappings based on their specific logic
+    // (e.g., rule geom converts pos1/pos2 to AnnotationColumn when slope is present)
+    for spec in &mut specs {
+        for layer in &mut spec.layers {
+            layer
+                .geom
+                .setup_layer(&mut layer.mappings, &mut layer.parameters)?;
+        }
+    }
+
     // Create scales for all mapped aesthetics that don't have explicit SCALE clauses
     scale::create_missing_scales(&mut specs[0]);