Skip to content

Expand formula interface to aesthetics, facets, labels, and encode#36

Merged
yihui merged 5 commits intomainfrom
copilot/expand-formula-interface-support
Apr 8, 2026
Merged

Expand formula interface to aesthetics, facets, labels, and encode#36
yihui merged 5 commits intomainfrom
copilot/expand-formula-interface-support

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Apr 8, 2026

Summary

Expands the formula shorthand ~ var to work in all aesthetic mappings and variable-name arguments throughout the package.

What changed

Core implementation (R/utils.R, R/gglite.R, R/facet.R, R/component.R):

  • New as_var() utility converts a one-sided single-term formula ~ var to the character string "var"; all other values pass through unchanged
  • g2(): named aesthetic arguments now accept ~ var formulas (e.g., color = ~ species); the positional-formula detection is fixed to only trigger for the unnamed first argument
  • encode(): all arguments accept ~ var formulas
  • facet_rect() / facet_circle(): variable arguments accept ~ var formulas
  • labels_(): the text argument (and all options) accept ~ var formulas

Usage

# Before (still works):
g2(iris, x = 'Sepal.Width', y = 'Sepal.Length', color = 'Species') |>
  facet_rect(x = 'Species') |>
  labels_(text = 'Sepal.Length')

# After (preferred):
g2(iris, Sepal.Length ~ Sepal.Width, color = ~ Species) |>
  facet_rect(x = ~ Species) |>
  labels_(text = ~ Sepal.Length)

Documentation updates

  • All @examples in R source files updated to use the formula interface
  • All examples/*.Rmd files updated to use the formula interface
  • vignettes/gglite.Rmd updated to lead with the formula interface and document the character string interface as an alternative in a dedicated subsection

Tests added

  • g2() with all-named formula aesthetics (x = ~ mpg, y = ~ hp, color = ~ cyl)
  • g2() with mixed positional formula + formula aesthetic (hp ~ mpg, color = ~ cyl)
  • encode() with formula aesthetics
  • facet_rect() and facet_circle() with formula variables
  • labels_() with text = ~ var
  • as_var() error on multi-term formula

Copilot AI and others added 5 commits April 8, 2026 17:37
Replace character string aesthetics (x = 'col', y = 'col', color = 'col')
with the formula interface (y ~ x, color = ~ col) in all @examples sections
across R source files.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: yihui <163582+yihui@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: yihui <163582+yihui@users.noreply.github.com>
- Convert g2(data, x = 'X', y = 'Y') to g2(data, Y ~ X) in all R code chunks
- Convert g2(data, x = 'X') to g2(data, ~ X) for x-only mappings
- Convert color/size/shape/opacity = 'var' to use ~ var formula syntax
- Convert facet_rect(x = 'var') to facet_rect(x = ~ var)
- Convert facet_circle(position = 'var') to facet_circle(position = ~ var)
- Convert labels_(text = 'var') to labels_(text = ~ var)
- Convert encode(x = 'x', y = 'y') standalone calls to use ~ formulas
- Update vignette to lead with formula interface in Data and encodings section
- Add Character string interface subsection documenting the string API
- Keep encode = list(...) inside mark_*() calls unchanged (not aesthetic mappings)
- Keep reactive Shiny inputs (input$xvar) as string-based (formula not applicable)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: yihui <163582+yihui@users.noreply.github.com>
Copilot AI requested a review from yihui April 8, 2026 18:08
Copilot finished work on behalf of yihui April 8, 2026 18:08
@yihui yihui marked this pull request as ready for review April 8, 2026 18:26
@yihui yihui merged commit 4c18fcb into main Apr 8, 2026
8 checks passed
@yihui yihui deleted the copilot/expand-formula-interface-support branch April 8, 2026 18:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants