forked from matt-dray/r2eng
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
169 lines (113 loc) · 5.97 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
<img src="https://raw.githubusercontent.com/matt-dray/stickers/master/output/r2eng_hex.png" width="150" align="right">
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# {r2eng}
ɑː ˈtuː /eng/
<!-- badges: start -->
[{target='_blank'}](https://www.repostatus.org/#wip)
[{target='_blank'}](https://github.com/matt-dray/r2eng/actions)
[{target='_blank'}](https://codecov.io/gh/matt-dray/r2eng)
[](https://mybinder.org/v2/gh/matt-dray/try-r2eng/master?urlpath=rstudio)
<!-- badges: end -->
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 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){target='_blank'}'s useR! 2020 talk called 'Speaking R' ([YouTube](https://www.youtube.com/watch?v=ckW9sSdIVAc){target='_blank'}, [slides](https://www.amelia.mn/SpeakingR/#1){target='_blank'}).
This project is a work in progress and highly opinionated. Contributions are welcome, but please see the [Code of Conduct](#conduct){target='_blank'}.
## 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 {lintr}, {purrr} and {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){target='_blank'}, so you pass it a bare R expression like this:
```{r example-basic}
r2eng::translate(variable <- 1, speak = TRUE)
```
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 via {lintr} (`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){target='_blank'}.
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/){target='_blank'}.
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 <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd>.
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){target='_blank'} 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){target='_blank'}. By contributing to this project, you agree to abide by its terms.