Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/matt-dray/r2eng

:speaking_head::speaker: R package: translate R to English
https://github.com/matt-dray/r2eng

accessibility communication rstats rstats-package

Last synced: 3 months ago
JSON representation

:speaking_head::speaker: R package: translate R to English

Awesome Lists containing this project

README 

        
---

output: github_document

---






```{r, include = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#",

  fig.path = "man/figures/README-",

  out.width = "100%"

)

```



# {r2eng}



ɑː ˈtuː /eng/



[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)

[![R build status](https://github.com/matt-dray/r2eng/workflows/R-CMD-check/badge.svg)](https://github.com/matt-dray/r2eng/actions)

[![codecov](https://codecov.io/gh/matt-dray/r2eng/branch/master/graph/badge.svg)](https://codecov.io/gh/matt-dray/r2eng)

[![Launch Rstudio Binder](http://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/matt-dray/try-r2eng/master?urlpath=rstudio)



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](https://twitter.com/AmeliaMN)'s useR! 2020 talk called 'Speaking R' ([YouTube](https://www.youtube.com/watch?v=ckW9sSdIVAc), [slides](https://www.amelia.mn/SpeakingR/#1)).



This project is a work in progress and highly opinionated. Contributions are welcome, but please see the [Code of Conduct](#conduct).



## Installation



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



```{r install, eval=FALSE}

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](http://adv-r.had.co.nz/Computing-on-the-language.html), so you pass it a bare R expression like this:



```{r example-basic}

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:



```{r example-complex}

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).



```{r example-speak}

r2eng::speak(obj)

```



Use `evaluate` to evaluate the expression.



```{r example-eval}

r2eng::evaluate(obj, speak = FALSE)

hello

```



Use `print` to print the R expression and English sentence.



```{r example-print}

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`):



```{r example-map}

head(obj$translation_map)

```



### Further examples



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



```{r example-pipe-equals}

library(magrittr)

r2eng::translate(

  mtcars %>% filter(mpg > 22) %>% mutate(gear4 = gear == 4),

  speak = FALSE

)

```



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



```{r example-ggplot}

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:



```{r example-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](http://adv-r.had.co.nz/Computing-on-the-language.html). 



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



```{r example-basic-string}

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

```



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



```{r example-string-pipe}

"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](https://rstudio.github.io/rstudioaddins/).



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](https://github.com/matt-dray/r2eng/issues) if a relevant one one doesn't already exist.



Please note that the {r2eng} project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.