-
Notifications
You must be signed in to change notification settings - Fork 12
/
README.Rmd
300 lines (205 loc) · 16.6 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
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = " # "
)
options(width =100)
```
`replyr` is post-maintenance, we are no longer bug-fixing or updating this package. It has been pointless to track
shifting `dplyr`/`dbplyr`/`rlang` APIs and data structures post `dplyr` `0.5`.
Most of what it does is now done better in one of our newer non-monolithic packages:
* Programming and meta-programming tools: [`wrapr`](https://CRAN.R-project.org/package=wrapr).
* Big data data manipulation: [`rquery`](https://CRAN.R-project.org/package=rquery) and [`cdata`](https://CRAN.R-project.org/package=cdata).
* Adapting \code{dplyr} to standard evaluation interfaces: [`seplyr`](https://CRAN.R-project.org/package=seplyr).
-------------------
This document describes `replyr`, an [R](https://cran.r-project.org) package available from [Github](https://github.com/WinVector/replyr) and [CRAN](https://CRAN.R-project.org/package=replyr).
## Introduction
It comes as a bit of a shock for [R](https://cran.r-project.org) [`dplyr`](https://CRAN.R-project.org/package=dplyr) users when they switch from using a `tbl` implementation based on R in-memory `data.frame`s to one based on a remote database or service. A lot of the power and convenience of the `dplyr` notation is hard to maintain with these more restricted data service providers. Things that work locally can't always be used remotely at scale. It is emphatically not yet the case that one can practice with `dplyr` in one modality and hope to move to another back-end without significant debugging and work-arounds. The [`replyr`](https://github.com/WinVector/replyr) package attempts to provide practical data manipulation affordances to make code perform similarly on local or remote (big) data.
Note: `replyr` is meant only for "tame data frames" that is data frames with non-duplicate column names that are also valid *simple* (without quotes) `R` variables names and columns that are `R` simple vector types (numbers, strings, and such).
`replyr` supplies methods to get a grip on working with remote `tbl` sources (`SQL` databases, `Spark`) through `dplyr`. The idea is to add convenience functions to make such tasks more like working with an in-memory `data.frame`. Results still do depend on which `dplyr` service you use, but with `replyr` you have fairly uniform access to some useful functions. The rule of thumb is: try `dplyr` first, and if that does not work check if `replyr` has researched a work-around.
`replyr` uniformly uses standard or parametric interfaces (names of variables as strings) in favor of name capture so that you can easily program *over* `replyr`.
Primary `replyr` services include:
* [Join Controller](https://winvector.github.io/replyr/articles/joinController.html)
* [Join Planner](https://winvector.github.io/replyr/articles/DependencySorting.html)
* [`replyr::replyr_split`](https://winvector.github.io/replyr/reference/replyr_split.html)
* [`replyr::replyr_bind_rows`](https://winvector.github.io/replyr/reference/replyr_bind_rows.html)
* [`replyr::gapply`](https://winvector.github.io/replyr/reference/gapply.html)
* [`replyr::replyr_summary`](https://winvector.github.io/replyr/reference/replyr_summary.html)
* [`replyr::replyr_apply_f_mapped`](https://winvector.github.io/replyr/reference/replyr_apply_f_mapped.html)
* [`wrapr::let`](https://winvector.github.io/wrapr/reference/let.html)
## `wrapr::let`
`wrapr::let` allows execution of arbitrary code with substituted variable names (note this is subtly different than binding values for names as with `base::substitute` or `base::with`). This allows the user to write arbitrary `dplyr` code in the case of ["parametric variable names"](http://www.win-vector.com/blog/2016/12/parametric-variable-names-and-dplyr/) (that is when variable names are not known at coding time, but will become available later at run time as values in other variables) without directly using the `dplyr` "underbar forms" (and the direct use of `lazyeval::interp`, `.dots=stats::setNames`, or `rlang`/`tidyeval`).
Example:
```{r message=FALSE,results='hide',warning=FALSE}
library('dplyr')
```
```{r letexample}
# nice parametric function we write
ComputeRatioOfColumns <- function(d,
NumeratorColumnName,
DenominatorColumnName,
ResultColumnName) {
wrapr::let(
alias=list(NumeratorColumn=NumeratorColumnName,
DenominatorColumn=DenominatorColumnName,
ResultColumn=ResultColumnName),
expr={
# (pretend) large block of code written with concrete column names.
# due to the let wrapper in this function it will behave as if it was
# using the specified paremetric column names.
d %>% mutate(ResultColumn = NumeratorColumn/DenominatorColumn)
})
}
# example data
d <- data.frame(a=1:5, b=3:7)
# example application
d %>% ComputeRatioOfColumns('a','b','c')
```
`wrapr::let` makes construction of abstract functions over `dplyr` controlled data much easier. It is designed for the case where the "`expr`" block is large sequence of statements and pipelines.
## `replyr::replyr_apply_f_mapped`
`wrapr::let` was only the secondary proposal in the original [2016 "Parametric variable names" article](http://www.win-vector.com/blog/2016/12/parametric-variable-names-and-dplyr/). What we really wanted was a stack of view so the data pretended to have names that matched the code (i.e., re-mapping the data, not the code).
With a bit of thought we can achieve this if we associate the data re-mapping with a function environment instead of with the data. So a re-mapping is active as long as a given controlling function is in control. In our case that function is `replyr::replyr_apply_f_mapped()` and works as follows:
Suppose the operation we wish to use is a rank-reducing function that has been supplied as function from somewhere else that we do not have control of (such as a package). The function could be simple such as the following, but we are going to assume we want to use it without alteration (including the without the small alteration of introducing `wrapr::let()`).
```{r rankfn}
# an external function with hard-coded column names
DecreaseRankColumnByOne <- function(d) {
d$RankColumn <- d$RankColumn - 1
d
}
```
To apply this function to `d` (which doesn't have the expected column names!) we use `replyr::replyr_apply_f_mapped()` to create a new parametrized adapter as follows:
```{r replyrmapf}
# our data
d <- data.frame(Sepal_Length = c(5.8,5.7),
Sepal_Width = c(4.0,4.4),
Species = 'setosa',
rank = c(1,2))
# a wrapper to introduce parameters
DecreaseRankColumnByOneNamed <- function(d, ColName) {
replyr::replyr_apply_f_mapped(d,
f = DecreaseRankColumnByOne,
nmap = c(RankColumn = ColName),
restrictMapIn = FALSE,
restrictMapOut = FALSE)
}
# use
dF <- DecreaseRankColumnByOneNamed(d, 'rank')
print(dF)
```
`replyr::replyr_apply_f_mapped()` renames the columns to the names expected by `DecreaseRankColumnByOne` (the mapping specified in `nmap`), applies `DecreaseRankColumnByOne`, and then inverts the mapping before returning the value.
## `replyr::replyr_split`
`replyr::replyr_split` and `replyr::replyr_bind_rows` work over many remote data types including `Spark`. This allows code like the following:
```r
suppressPackageStartupMessages(library("dplyr"))
library("replyr")
sc <- sparklyr::spark_connect(version='2.0.2',
master = "local")
diris <- copy_to(sc, iris, 'diris')
f2 <- . %>%
arrange(Sepal_Length, Sepal_Width, Petal_Length, Petal_Width) %>%
head(2)
diris %>%
replyr_split('Species') %>%
lapply(f2) %>%
replyr_bind_rows()
## Source: query [6 x 5]
## Database: spark connection master=local[4] app=sparklyr local=TRUE
##
## # A tibble: 6 x 5
## Species Sepal_Length Sepal_Width Petal_Length Petal_Width
## <chr> <dbl> <dbl> <dbl> <dbl>
## 1 versicolor 5.0 2.0 3.5 1.0
## 2 versicolor 4.9 2.4 3.3 1.0
## 3 setosa 4.3 3.0 1.1 0.1
## 4 setosa 4.4 2.9 1.4 0.2
## 5 virginica 4.9 2.5 4.5 1.7
## 6 virginica 5.6 2.8 4.9 2.0
sparklyr::spark_disconnect(sc)
```
## `replyr::gapply`
`replyr::gapply` is a "grouped ordered apply" data operation. Many calculations can be written in terms of this primitive, including per-group rank calculation (assuming your data services supports window functions), per-group summaries, and per-group selections. It is meant to be a specialization of ["The Split-Apply-Combine"](https://www.jstatsoft.org/article/view/v040i01) strategy with all three steps wrapped into a single operator.
Example:
```{r message=FALSE,results='hide',warning=FALSE}
library('dplyr')
```
```{r gapplyexample}
d <- data.frame(group=c(1,1,2,2,2),
order=c(.1,.2,.3,.4,.5))
rank_in_group <- . %>% mutate(constcol=1) %>%
mutate(rank=cumsum(constcol)) %>% select(-constcol)
d %>% replyr::gapply('group', rank_in_group, ocolumn='order', decreasing=TRUE)
```
The user supplies a function or pipeline that is meant to be applied per-group and the `replyr::gapply` wrapper orchestrates the calculation. In this example `rank_in_group` was assumed to know the column names in our data, so we directly used them instead of abstracting through `wrapr::let`. `replyr::gapply` defaults to using `dplyr::group_by` as its splitting or partitioning control, but can also perform actual splits using 'split' ('base::split') or 'extract' (sequential extraction). Semantics are slightly different between cases given how `dplyr` treats grouping columns, the issue is illustrated in the difference between the definitions of `sumgroupS` and `sumgroupG` in [this example](https://github.com/WinVector/replyr/blob/master/checks/gapply.md)).
## `replyr::replyr_*`
The `replyr::replyr_*` functions are all convenience functions supplying common functionality (such as `replyr::replyr_nrow`) that works across many data services providers. These are prefixed (instead of being `S3` or `S4` methods) so they do not interfere with common methods. Many of these functions can expensive (which is why `dplyr` does not provide them as a default), or are patching around corner cases (which is why these functions appear to duplicate `base::` and `dplyr::` capabilities). The issues `replyr::replyr_*` claim to patch around have all been filed as issues on the appropriate `R` packages and are documented [here](https://github.com/WinVector/replyr/tree/master/issues) (to confirm they are not phantoms).
Example: `replyr::replyr_summary` working on a database service (when `base::summary` does not).
```{r summaryexample}
d <- data.frame(x=rep(c(1,2,2), 5),
y=c(3,5,NA),
z=c(NA,'a','b'),
stringsAsFactors = FALSE)
my_db <- DBI::dbConnect(RSQLite::SQLite(), ":memory:")
RSQLite::initExtension(my_db) # filed as dplyr issue https://github.com/tidyverse/dplyr/issues/3150
dRemote <- replyr::replyr_copy_to(my_db,d,'d')
summary(dRemote)
glimpse(dRemote)
replyr::replyr_summary(dRemote)
cdata::qlook(my_db, 'd')
```
Data types, capabilities, and row-orders all vary a lot as we switch remote data services. But the
point of `replyr` is to provide at least some convenient version of typical functions such as:
`summary`, `nrow`, unique values, and filter rows by values in a set.
## `replyr` Data services
This is a *very* new package with no guarantees or claims of fitness for purpose. Some implemented operations are going to be slow and expensive (part of why they are not exposed in `dplyr` itself).
We will probably only ever cover:
* Native `data.frame`s (and `tbl`/`tibble`)
* `sparklyr` (`Spark` 2.0.0 or greater)
* `RPostgreSQL`
* `SQLite`
* `RMySQL` (limited support in some cases)
## Additional functions
Additional `replyr` functions include:
* `replyr::replyr_filter`
* `replyr::replyr_inTest`
These are designed to subset data based on a columns values being in a given set. These allow selection of rows by testing membership in a set (very useful for partitioning data). Example below:
```{r message=FALSE,results='hide',warning=FALSE}
library('dplyr')
```
```{r filter}
values <- c(2)
dRemote %>% replyr::replyr_filter('x', values)
```
## Commentary
There are a few goals for `replyr`:
* Providing missing convenience functions that work well over all common `dplyr` service providers. Examples include `replyr_summary`, `replyr_filter`, and `replyr_nrow`.
* Providing a basis for "row number free" data analysis. SQL back-ends don't commonly supply row number indexing (or even deterministic order of rows), so a lot of tasks you could do in memory by adjoining columns have to be done through formal key-based joins.
* Providing emulations of functionality missing from non-favored service providers (such as windowing functions, `quantile`, `sample_n`, `cumsum`; missing from `SQLite` and `RMySQL`).
* Working around corner case issues, and some variations in semantics.
* Sheer bull-headedness in emulating operations that don't quite fit into the pure `dplyr` formulation.
Good code should fill one important gap and work on a variety of `dplyr` back ends (you can test `RMySQL`, and `RPostgreSQL` using docker as mentioned [here](http://www.win-vector.com/blog/2016/11/mysql-in-a-container/) and [here](http://www.win-vector.com/blog/2016/02/databases-in-containers/); `sparklyr` can be tried in local mode as described [here](http://spark.rstudio.com)). I am especially interested in clever "you wouldn't thing this was efficiently possible, but" solutions (which give us an expanded grammar of useful operators), and replacing current hacks with more efficient general solutions. Targets of interest include `sample_n` (which isn't currently implemented for `tbl_sqlite`), `cumsum`, and `quantile` (currently we have an expensive implementation of `quantile` based on binary search: `replyr::replyr_quantile`).
`replyr` services include:
* Moving data into or out of the remote data store (including adding optional row numbers), `replyr_copy_to` and `replyr_copy_from`.
* Basic summary info: `replyr_nrow`, `replyr_dim`, and `replyr_summary`.
* Random row sampling (like `dplyr::sample_n`, but working with more service providers). Some of this functionality is provided by `replyr_filter` and `replyr_inTest`.
* Emulating [The Split-Apply-Combine Strategy](https://www.jstatsoft.org/article/view/v040i01), which is the purpose `gapply`, `replyr_split`, and `replyr_bind_rows`.
* Emulating `tidyr` gather/spread (or pivoting and anti-pivoting).
* Patching around differences in `dplyr` services providers (and documenting the reasons for the patches).
* Making use of "parameterized names" much easier (that is: writing code does not know the name of the column it is expected to work over, but instead takes the column name from a user supplied variable).
Additional desired capabilities of interest include:
* `cumsum` or row numbering (interestingly enough if you have row numbering you can implement cumulative sum in log-n rounds using joins to implement pointer chasing/jumping ideas, but that is unlikely to be practical, `lag` is enough to generate next pointers, which can be boosted to row-numberings).
* Inserting random values (or even better random unique values) in a remote column. Most service providers have a pseudo-random source you can use.
## Conclusion
`replyr` is package for speeding up reliable data manipulation using `dplyr` (especially on databases and `Spark`). It is also a good central place to collect patches and fixes needed to work around corner cases and semantic variations between versions of data sources.
## Clean up
```{r}
rm(list=ls())
gc()
```
## Note
Note: `replyr` is targeted at data with "tame column names" (column names that are valid both in databases, and as `R` unquoted variable names) and basic types (column values that are simple `R` types such as `character`, `numeric`, `logical`, and so on).
Also `replyr` tries to be a "source agnostic" package, meaning it minimizes the number of places it checks for data source and uses specialized code, this can mean some operations are slow. For example `replyr` does not (yet) use `sparklyr::sdf_pivot()`.