README.md

In caprice-j/ggbash: A Simpler Syntax for ggplot2

ggbash

ggbash provides a simpler ggplot2 syntax. It features partial match, error messages, and builtin commands such as copy or png.

The goal of ggbash is to make ggplot2 more comfortable to write for every user, from beginners to professionals.

[Note:] The development of ggbash was abandoned as I started working on other projects. This repository is just for records.

Usage

One-liner

ggbash(gg(iris) + point(Sepal.W, Sepal.L, col=Spec, sz=5) + theme(legend.txt(sz=20, face="bold")) | echo)

# The output of the above ggbash 'echo' command
ggplot(iris) +
geom_point(aes(Sepal.Width, Sepal.Length, colour = Species), size = 5) +
theme(legend.text = element_text(size = 20, face = "bold"))

Interactive

ggbash also provides a bash-like REPL environment (ggbash environment, or ggbash session).

library(ggbash)
ggbash() # start a ggbash session

One advantage of ggbash session is that parentheses and commas become optional.

gg iris + point Sepal.W Sepal.L col=Spec size=7 + theme lgnd.txt size=20 face="bold" | echo

If you prefer an extremely short code,

g iris + p Sepal.W Sepal.L c=Sp s=7 + theme l.tx s=20 f="bold"

will produce exactly the same plot, at the sacrifice of readability for beginners.

Features

1. Partial Match

Even if the unique identification of specified elements (geoms, aesthetics, column names, theme element names, etc.) is not possible, ggbash anyway tries to execute its best guess instead of bluntly returning an error.

For the above ggbash input gg iris + point Sepal.W Sepal.L c="red" sz=5, ggbash performs partial matches six times.

• ggplot function
  • gg matches ggplot2::ggplot().
    • You can also write ggplot or g.
• geom names
  • point matches geom_point.
    • You can also write geom_point (i.e. write geom_ prefix explicitly).

• column names

  • Sepal.W matches iris$Sepal.Width.

  • Sepal.L matches iris$Sepal.Length.

• aesthetics names

  • c matches colour, which is the aesthetic of geom_point.
  • sz matches size among size, shape, and stroke by fuzzy match.

Any of the following commands return exactly the same plot.

ggplot(iris)+geom_point(aes(x=Sepal.Width,y=Sepal.Length),colour="red",size=5)  # 78 characters
ggplot iris +geom_point     x=Sepal.Width y=Sepal.Length  colour="red" size=5
ggplot iris +     point       Sepal.Width   Sepal.Length  colour="red" size=5
gg     iris +     point       Sepal.W       Sepal.L       col   ="red" siz =5
gg     iris +     p           Sepal.W       Sepal.L       c     ="red" sz  =5
g      iris +     p           Sepal.W       Sepal.L       c     ="red" s   =5   # 38 characters

Users can select one of the styles which fits them best.

2. Fixit (Error Diagnostics)

ggbash(gg(diamonds, x=caret, y=price) + point + smooth)  # typo

COMPILE ERROR: No such column names

  The column name "caret" does not exist.
    maybe: carat, clarity

The built ggplot2 object is :
  ggplot(diamonds, aes( <<INVALID_TOKEN_HERE>> ) + geom_point() + geom_smooth()

ggbash has a compiler (ggbash compiler) which converts given ggbash "source code" into an "executable" ggplot2 object. During the compiling process, ggbash can detect various human errors such as element misspecifications (column names, aes names, theme element names, ...). Beginners can learn why their codes don't work from the generated diagnostics.

ggbash(gg(diamonds, x=carat, y=price) + point + smooth) # without typo

3. Builtin ggbash Commands

echo

Print the built ggplot2 object as a string. Useful for learning ggplot2 original grammar iteratively.

gg iris + point Sepal.W Sepal.L size=7 + theme lgnd.txt face="bold" | echo

# The output of ggbash 'echo' command
ggplot(iris) +
geom_point(aes(Sepal.Width, Sepal.Length), size = 7) +
theme(legend.text = element_text(face = "bold"))

copy

ggbash(gg(iris) + p(Sepal.W, Sepal.L, col=Sp, siz=4) | copy)
    copied to clipboard:
    ggplot(iris) + geom_point(aes(x=Sepal.Length,
                                  y=Sepal.Width,
                                  colour=Species,
                                  size=Petal.Width))

png and pdf

ggbash(gg(iris) + p(Sepal.W, Sepal.L, col=Sp) | png(my_image))
    saved in:
    'currentDir/my_image/iris-150/x-Sepal.Width_y-Sepal.Length-colour-Species.960x960.png'

If you would like to get a scatterplot matrix,

for( i in 1:ncol(iris) )
    for ( j in min(i+1, ncol(iris)):ncol(iris) )
        ggbash(paste("gg iris + point ",
                     colnames(iris)[i],
                     colnames(iris)[j],
                     " | png my_image"))

Order Agnostic Arguments

png and pdf arguments are order-agnostic: Any of the following notations generates the same png file "my_image/iris-150/point-my-plot.1960x1480.png".

gg mtcars | p mpg cyl | png  "my-plot"  1960*1480  my_image 
gg mtcars | p mpg cyl | png  "my-plot"  my_image   1960*1480
gg mtcars | p mpg cyl | png  my_image   1960*1480  "my-plot"
gg mtcars | p mpg cyl | png  my_image   "my-plot"  1960*1480 
gg mtcars | p mpg cyl | png  1960*1480  "my-plot"  my_image 
gg mtcars | p mpg cyl | png  1960*1480  my_image   "my-plot"

# ... or in R's normal session
ggbash(gg(mtcars) + p(mpg,cyl) | png(1960*1480, my_image, "my_plot"))

png and pdf commands interpret a single- or double-quoted token as file name ("my-plot" in the following example), a token with * infix as plot size, and otherwise directory name.

Guessing Inches or Pixels

The pdf command in ggbash recognizes both inches and pixels.

If the given width or height in (width)x(height) is less than 50 (the same limit of ggplot2::ggsave) , the numbers are interpreted as inches (1 inch = 2.54 cm).

# pdf of 15 inch width (=~ 40 cm) and 9 inch height (=~ 23 cm)
gg iris + p Sepal.W Sepal.L | pdf 16*9

# pdf of 1440 pixel (=~ 50 cm) width and height
gg iris + p Sepal.W Sepal.L | pdf 1440*1440

# the png command in ggbash also recognises inches and pixels
gg iris + p Sepal.W Sepal.L | png 16*9

Note: the default dpi (dots per inch) in ggbash is 72 (R's default) and cannot be changed. If you would like to change the dpi, you could consider ggplot2::ggsave(..., dpi=...).

Auto-generated Filenames

With iris dataset which has 150 rows, the plot of gg iris + p Sepal.W Sepal.L | png is saved in iris-150/point_x-Sepal.Width_y-Sepal.Length.960x960.png.

If you happen to have another iris dataset which has a different number of rows (say 33), the same command result is saved in iris-33/ directory.

Installation

# install.packages("devtools")
devtools::install_github("caprice-j/ggbash")

• If you get no appender.console() error, you might need install.packages('rly'). packageVersion('rly') should be at least 1.4.2.

• This package is still in its infancy, and might contain several installation bugs.

Note

Currently, I am in my school semester and suspending ggbash development. Please wait till May 2017 :)

Goals

The goal of ggbash is to make ggplot2 more comfortable to write. It can be categorized into two subgoals:

1. Better EDA experience. Provide blazingly fast way to do exploratory data anslysis.

   • less typing by Partial Match.

   • casually save plots with Pipe Operators and Auto-generated Filenames.

2. Intuitive finalization (to be implemented). Make it more intuitive to finalize your plots.

   • adjust colours or lineweights

   • rotate axis labels

   • decide tick label intervals and limits

Learning ggbash

ggbash follows original ggplot2 syntax as much as possible for reducing learning costs of current ggplot2 users.

Learning ggplot2 might be the best way to understand ggbash syntax. The document and book of ggplot2 would be helpful.

The vignette of ggbash is still in a draft.

Other Works

As far as I know, there are no previous attempts to implement a higher-level language that transcompiles to ggplot2. Reports of similar attempts are welcomed.

ggbash draws inspiration from some other higher level programming languages including Bash, CoffeeScript, Ruby, and Lisp. Fixit is inspired by Fix-It Hints in clang C++ compiler.

Limitations

ggbash has some weird specification due to parsing rule constraints:

One-liner

Interactive

Current Implementation Status

ggbash is first released on December 29, 2016.

• DONE:
  • version 0.1 : ggplot(), aes() elements, non aes() elements, ggsave
  • version 0.2 : theme()
  • version 0.3 : (no ggplot2 functions)
  • version 0.4 : (no ggplot2 functions)
• TODO:
  • stat_..., scale_..., coord_..., facet_..., labs, position_..., xlim, ylim
  • sprintf()-like formatting for filenames (like png "my-%aes%-%facet%")
• HOW:
  • auto completion (R's prompt() does not have built-in completions)
  • aes/non-aes sorting

caprice-j/ggbash documentation built on May 13, 2019, 12:11 p.m.