Support | 0 + var for row faceting in formula syntax

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: gglite
 Title: Lightweight Data Visualization via the Grammar of Graphics
-Version: 0.0.10
+Version: 0.0.11
 Authors@R: person("Yihui", "Xie", role = c("aut", "cre"), email = "xie@yihui.name",
     comment = c(ORCID = "0000-0003-0645-5666"))
 Description: A lightweight R interface to the AntV G2 JavaScript visualization

R/utils.R

@@ -118,7 +118,8 @@ extract_terms = function(expr) {
 #' - `y ~ x` maps to `list(x = 'x', y = 'y')`
 #' - `~ x` maps to `list(x = 'x')`
 #' - `~ x1 + x2 + x3` maps to `list(position = c('x1', 'x2', 'x3'))`
-#' - `y ~ x | z` adds faceting by `z`
+#' - `y ~ x | z` adds faceting by `z` (columns)
+#' - `y ~ x | 0 + z` adds faceting by `z` (rows)
 #' - `y ~ x | z1 + z2` adds faceting by `z1` (columns) and `z2` (rows)
 #'
 #' @param f A formula object.
@@ -147,13 +148,14 @@ parse_formula = function(f) {
     aesthetics$position = rhs_terms
   }
 
-  # Build facet
+  # Build facet: | var → column; | 0 + var → row; | var1 + var2 → both
   facet = NULL
   if (length(facet_terms)) {
-    enc = list()
-    if (length(facet_terms) >= 1) enc$x = facet_terms[1]
-    if (length(facet_terms) >= 2) enc$y = facet_terms[2]
-    facet = list(type = 'facetRect', encode = enc)
+    # A leading 0 shifts terms to row (y) instead of column (x)
+    nms = if (facet_terms[1] == '0') 'y' else c('x', 'y')
+    facet_terms = facet_terms[facet_terms != '0']
+    enc = setNames(as.list(facet_terms), head(nms, length(facet_terms)))
+    if (length(enc)) facet = list(type = 'facetRect', encode = enc)
   }
 
   list(aesthetics = aesthetics, facet = facet)

tests/testit/test-utils.R

@@ -68,6 +68,20 @@ assert('parse_formula: y ~ x | z1 + z2', {
   (res$facet$encode$y %==% 'b')
 })
 
+assert('parse_formula: y ~ x | 0 + z (row facet)', {
+  res = parse_formula(hp ~ mpg | 0 + cyl)
+  (res$aesthetics$x %==% 'mpg')
+  (res$aesthetics$y %==% 'hp')
+  (res$facet$type %==% 'facetRect')
+  (is.null(res$facet$encode$x))
+  (res$facet$encode$y %==% 'cyl')
+})
+
+assert('parse_formula: y ~ x | 0 (bare 0, no facet)', {
+  res = parse_formula(hp ~ mpg | 0)
+  (is.null(res$facet))
+})
+
 assert('ts_to_df converts univariate ts', {
   res = ts_to_df(sunspot.year)
   (is.data.frame(res$data))

vignettes/gglite.Rmd

@@ -336,6 +336,24 @@ g2(iris, x = 'Sepal.Width', y = 'Sepal.Length', color = 'Species') |>
   facet_rect(x = 'Species')
 ```
 
+The formula interface supports faceting with `|`. Use `| var` for column facets,
+`| 0 + var` for row facets, and `| var1 + var2` for both:
+
+```{r}
+# Column facet: panels arranged in columns by species
+g2(penguins, bill_len ~ bill_dep | species)
+```
+
+```{r}
+# Row facet: panels arranged in rows by island
+g2(penguins, bill_len ~ bill_dep | 0 + island)
+```
+
+```{r}
+# Both: columns by species, rows by island
+g2(penguins, bill_len ~ bill_dep | species + island)
+```
+
 ## Themes
 
 Themes change the overall look. Built-in themes include `theme_classic()`