In matt-dray/r2eng: Translate R Code To An English Sentence

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

{r2eng}

ɑː ˈtuː /eng/

Make R speakable!

The goal of {r2eng} (as in 'R to English') is to take an R expression and 'translate' it to an English sentence.

The package is intended (optimistically) to:

• improve communication between teachers and learners
• make R discussions in English more accessible to non-English speakers
• provide an extra audio evaluation tool for users who are blind or have low vision
• be of interest to any R user that's curious about how R expressions might be vocalised

The project was inspired by Amelia McNamara's useR! 2020 talk called 'Speaking R' (YouTube, slides).

This project is a work in progress and highly opinionated. Contributions are welcome, but please see the Code of Conduct.

Installation

You can install the development version of {r2eng} from GitHub with:

remotes::install_github("matt-dray/r2eng")

This package depends on {rlang}.

Examples

The main function in the package is translate(). It uses non-standard evaluation, so you pass it a bare R expression like this:

r2eng::translate(variable <- 1, speak = FALSE)

Set speak = TRUE for a system call that will read the English sentence out loud (macOS only).

A more complex example:

obj <- r2eng::translate(
  hello <- c(TRUE, FALSE, 'banana' %in% c('apple', 'orange')),
  speak = FALSE
)

obj

Methods

An r2eng object has the methods speak and evaluate.

Use speak to launch a system call that will vocalise the translated English sentence for the given R expression (macOS only).

r2eng::speak(obj)

Use evaluate to evaluate the expression.

r2eng::evaluate(obj, speak = FALSE)
hello

Use print to print the R expression and English sentence.

print(obj)

From your r2eng object you can access the original R expression (r_expression), English translation (eng_expression), quoted expression (quoted_expression). You can also access the parse tree output (translation_map):

head(obj$translation_map)

Further examples

Here's an example using the pipe (%>%) and two types of 'equals':

library(magrittr)
r2eng::translate(
  mtcars %>% filter(mpg > 22) %>% mutate(gear4 = gear == 4),
  speak = FALSE
)

This example uses the 'plus' constructor from {ggplot2}:

r2eng::translate(
  ggplot(diamonds, aes(x=carat, y=price, color=cut)) + geom_point() + geom_smooth(),
  speak = FALSE
)

This example shows what happens when you pass vectors:

r2eng::translate(
  plot(x = c(1, 2, 3), y = c(5, 6, 7)),
  speak = FALSE
)

Passing a string

The translate() function understands the meaning of = when used for assignment versus specifying arguments, but feeding an expression such as x = c(1, 2, 3) would confuse translate() that you want to pass an argument c(1, 2, 3) to the parameter x.

This is because translate() uses non-standard evaluation.

In such cases, you must use translate_string() instead:

r2eng::translate_string("x = c(1, 2, 3)", speak = FALSE)

Another exceptional case for translate_string() is when piping and expression:

"non_english <- c('ceci n est pas une pipe', 'Ich bin ein Berliner', '我其實唔識講廣東話')" %>% 
  r2eng::translate_string(speak = FALSE)

RStudio addin

Installing this package also installs an RStudio addin.

Select an R expression in the editor and then under 'Addins', go to 'Speak R Expression In English' under 'R2ENG'. The selected text will be spoken by your computer.

You could bind this addin to a keyboard shortcut in RStudio by going to 'Tools', then 'Modify Keyboard Shortcuts...'. Perhaps Cmd + Shift + V.

As with the rest of this package, vocalisation is only possible for macOS and with speakers.

Another Addin function is also available, 'Print R Expression In English', which prints a selected R expression and its English translation

Contributions and Code of Conduct {#conduct}

Contributions are welcome from everyone. Please first add an issue if a relevant one one doesn't already exist.

Please note that the {r2eng} project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

matt-dray/r2eng documentation built on April 29, 2024, 5:24 p.m.