Debian Codegraph @

vignettes/wip/subassign.Rmd

raw
1 ---
2 title: "Subassignment"
3 output: rmarkdown::html_vignette
4 vignette: >
5 %\VignetteIndexEntry{subassign}
6 %\VignetteEngine{knitr::rmarkdown}
7 %\VignetteEncoding{UTF-8}
8 ---
9
10 <style type="text/css">
11 .dftbl {
12 width: 100%;
13 table-layout: fixed;
14 display: inline-table;
15 }
16
17 .error pre code {
18 color: red;
19 }
20
21 .warning pre code {
22 color: violet;
23 }
24 </style>
25
26 ```{r, include = FALSE}
27 knitr::opts_chunk$set(
28 error = TRUE,
29 collapse = TRUE,
30 comment = "#>"
31 )
32
33 tibble:::set_dftbl_hooks()
34
35 options(
36 lifecycle_disable_warnings = FALSE,
37 lifecycle_verbose_soft_deprecation = TRUE,
38 lifecycle_repeat_warnings = TRUE
39 )
40 ```
41
42 This vignette is an attempt to provide a comprehensive overview over all subassignment operations, highlighting where the tibble implementation differs from the data frame implementation.
43
44 ```{r setup}
45 library(tibble)
46
47 new_df <- function() {
48 df <- data.frame(a = 1:4)
49 df$b <- letters[5:8]
50 df$cd <- list(9, 10:11, 12:14, "text")
51 df
52 }
53
54 new_tbl <- function() {
55 as_tibble(new_df())
56 }
57 ```
58
59 Results of the same code for data frames and tibbles are presented side by side:
60
61 ```{r show, dftbl = TRUE, dftbl_always = TRUE}
62 new_df()
63 ```
64
65 In the following, if the results are identical (after converting to a data frame if necessary), only the tibble result is shown, as in the example below.
66 This allows to spot differences easier.
67
68 ```{r show-compare, dftbl = TRUE}
69 new_df()
70 ```
71
72 For subassignment, we need a fresh copy of the data for each test.
73 The `with_*()` functions allow for a more concise notation
74 (`with_tbl()` omitted here for brevity):
75
76 ```{r with-df-def}
77 with_df <- function(code, verbose = FALSE) {
78 code <- rlang::enexpr(code)
79
80 full_code <- rlang::quo({
81 df <- new_df()
82 !!code
83 df
84 })
85 if (verbose) rlang::expr_print(rlang::quo_get_expr(full_code))
86 rlang::eval_tidy(full_code)
87 }
88 ```
89
90
91 ```{r with-tbl-def, include = FALSE}
92 with_tbl <- function(code, verbose = FALSE) {
93 code <- rlang::enexpr(code)
94
95 full_code <- rlang::quo({
96 tbl <- new_tbl()
97 !!code
98 tbl
99 })
100 if (verbose) rlang::expr_print(rlang::quo_get_expr(full_code))
101 rlang::eval_tidy(full_code)
102 }
103 ```
104
105 This function takes an assignment expression and executes it on a fresh copy of the data.
106 The first example prints what's really executed, further examples omit this output.
107
108 ```{r with-demo, dftbl = TRUE}
109 with_df(df$a <- rev(df$a), verbose = TRUE)
110 ```
111
112
113 ## $<-
114
115 ### Scalars and full length
116
117 Assigning a scalar or a full-length vector to a column consistently overwrites existing data or appends a new column at the end. Partial matching doesn't happen:
118
119 ```{r dollar-assign-scalar, dftbl = TRUE}
120 with_df(df$a <- 1)
121 with_df(df$b <- 1)
122 with_df(df$c <- 1)
123 with_df(df$cd <- 1)
124 ```
125
126 ```{r dollar-assign-full, dftbl = TRUE}
127 with_df(df$a <- 4:1)
128 with_df(df$b <- 4:1)
129 with_df(df$c <- 4:1)
130 with_df(df$cd <- 4:1)
131 ```
132
133 ### Recycling
134
135 Tibbles allow recycling only for vectors of length 1 or of the same length as the data.
136
137 ```{r dollar-assign-recycle, dftbl = TRUE}
138 with_df(df$a <- 1:2)
139 with_df(df$a <- 1:3)
140 with_df(df$a <- 1:5)
141 with_df(df$c <- 1:2)
142 ```
143
144
145
146 ### Subset assignment
147
148 Updating parts of a column extracted by `$` is the responsibility of the column vector.
149 Tibbles can't control what happens after `$` has returned.
150
151 ```{r dollar-assign-subset, dftbl = TRUE}
152 with_df(df$a[1:2] <- 4:3)
153 with_df(df$b[1:2] <- 4:3)
154 with_df(df$c[1:2] <- 4:3)
155 with_df(df$cd[1:2] <- 4:3)
156 with_df(df$a[1:3] <- 4:3)
157 with_df(df$a[1:4] <- 4:3)
158 ```
159
160 For columns of the stricter `"vctrs_vctr"` class, this class implements the check, which then works identically for data frames and tibbles:
161
162 ```{r vctrs}
163 with_df({ df$v = vctrs::new_vctr(1:4); df$v[1:2] <- vctrs::new_vctr(4:3)})
164 with_df({ df$v = vctrs::new_vctr(1:4); df$v[1:2] <- vctrs::new_vctr(letters[4:3])})
165 ```
166
167 ## [[<-
168
169 ### Scalars and full length
170
171 As with `$` subsetting, columns are consistently overwritten, and partial matching doesn't occur.
172 Numeric indexing is supported, but tibbles don't support creation of new numbered columns for a good reason.
173
174 ```{r double-bracket-assign-col-scalar, dftbl = TRUE}
175 with_df(df[["a"]] <- 1)
176 with_df(df[["a"]] <- "x")
177 with_df(df[["b"]] <- "x")
178 with_df(df[["c"]] <- "x")
179 with_df(df[["cd"]] <- "x")
180 with_df(df[[1]] <- "x")
181 with_df(df[[2]] <- "x")
182 with_df(df[[4]] <- "x")
183 with_df(df[[5]] <- "x")
184 ```
185
186 ```{r double-bracket-assign-col-full, dftbl = TRUE}
187 with_df(df[["a"]] <- 4:1)
188 with_df(df[["a"]] <- letters[4:1])
189 with_df(df[["b"]] <- letters[4:1])
190 with_df(df[["c"]] <- letters[4:1])
191 with_df(df[["cd"]] <- letters[4:1])
192 ```
193
194 ### Cells
195
196 Tibbles are stricter when updating single cells, the value must be coercible to the existing contents.
197 Updating a list column requires the contents to be wrapped in a list, consistently with `[[` subsetting which returns a list if a cell in a list column is accessed:
198
199 ```{r double-bracket-assign-cell, dftbl = TRUE}
200 with_df(df[[2, "a"]] <- 1)
201 with_df(df[[2, "a"]] <- 1.5)
202 with_df(df[[2, "a"]] <- "x")
203 with_df(df[[2, "b"]] <- "x")
204 with_df(df[[2, 1]] <- "x")
205 with_df(df[[2, 2]] <- "x")
206 with_df(df[[2, "cd"]] <- "x")
207 with_df(df[[2, "cd"]] <- list("x"))
208 with_df(df[[2, "c"]] <- "x")
209 with_df(df[[1:2, "cd"]] <- "x")
210 with_df(df[[1:2, "c"]] <- "x")
211 with_df(df[[2, c("cd", "d")]] <- "x")
212 ```
213
214 ## [<-
215
216 ### Scalars
217
218 ```{r bracket-assign-scalar-col, dftbl = TRUE}
219 with_df(df[2, "a"] <- 1)
220 with_df(df[2, "a"] <- 1.5)
221 with_df(df[2, "a"] <- "x")
222 with_df(df[2, "b"] <- "x")
223 with_df(df[2, "cd"] <- "x")
224 with_df(df[2, "cd"] <- list("x"))
225 with_df(df[2, "c"] <- "x")
226 with_df(df[2, 1] <- "x")
227 with_df(df[2, 2] <- "x")
228 with_df(df[2, 3] <- "x")
229 with_df(df[2, 4] <- "x")
230 ```
231
232 ### Full length columns
233
234 ```{r bracket-assign-full-col, dftbl = TRUE}
235 with_df(df[, "a"] <- 4:1)
236 with_df(df[, "b"] <- 4:1)
237 with_df(df[, "c"] <- 4:1)
238 with_df(df[, "cd"] <- 4:1)
239 with_df(df[, 1] <- 4:1)
240 with_df(df[, 2] <- 4:1)
241 with_df(df[, 3] <- 4:1)
242 with_df(df[, 4] <- 4:1)
243 with_df(df[, "a"] <- 1)
244 with_df(df[, "b"] <- 1)
245 with_df(df[, "c"] <- 1)
246 with_df(df[, "cd"] <- 1)
247 with_df(df[, 1] <- 1)
248 with_df(df[, 2] <- 1)
249 with_df(df[, 3] <- 1)
250 with_df(df[, 4] <- 1)
251 ```
252
253 ### Multiple full length columns
254
255 ```{r bracket-assign-full-multicol, dftbl = TRUE}
256 with_df(df[, c("a", "b")] <- 4:1)
257 with_df(df[, c("a", "b")] <- 1)
258 with_df(df[, c("a", "b")] <- data.frame(a = 4:1, b = letters[4:1]))
259 with_df(df[, c("a", "b")] <- data.frame(b = 4:1, a = letters[4:1]))
260 with_df(df[, c("a", "b")] <- data.frame(c = 4:1, d = letters[4:1]))
261 with_df(df[, c("a", "b")] <- data.frame(a = 4:1))
262 with_df(df[, c("a", "b")] <- data.frame(a = 4:1, b = letters[4:1], c = 1:4))
263 with_df(df[, c("a", "b")] <- data.frame(4:1, 1))
264 with_df(df[, c("a", "b", "c")] <- data.frame(4:1, letters[4:1]))
265 with_df(df[, c("a", "b", "cd")] <- data.frame(4:1, letters[4:1]))
266 ```
267
268 ### Full length rows
269
270 ```{r bracket-assign-full-row, dftbl = TRUE}
271 with_df(df[2, ] <- 1)
272 with_df(df[2, ] <- "x")
273 with_df(df[2, ] <- tibble(a = 1, b = "x"))
274 with_df(df[2, ] <- tibble(a = 1, b = "x", c = list("y")))
275 with_df(df[2, ] <- tibble(a = 1, b = "x", c = list("y"), d = "z"))
276 with_df(df[0, ] <- tibble(a = 1, b = "x", c = list("y")))
277 with_df(df[5, ] <- tibble(a = 1, b = "x", c = list("y")))
278 ```
279
280 ### Multiple full length rows
281
282 ```{r bracket-assign-full-multirow, dftbl = TRUE}
283 with_df(df[2:3, ] <- 1)
284 with_df(df[2:3, ] <- 1:2)
285 with_df(df[2:3, ] <- c("x", "y"))
286 with_df(df[2:3, ] <- tibble(a = 1:2, b = c("x", "y")))
287 with_df(df[2:3, ] <- tibble(a = 1, b = "x", c = list("y")))
288 with_df(df[2:3, ] <- tibble(a = 1:2, b = "x", c = list("y")))
289 with_df(df[2:3, ] <- tibble(a = 1, b = "x", c = list("y"), d = "z"))
290 with_df(df[-(1:2), ] <- tibble(a = 1:2, b = "x", c = list("y")))
291 with_df(df[0:1, ] <- tibble(a = 1:2, b = "x", c = list("y")))
292 with_df(df[4:5, ] <- tibble(a = 1:2, b = "x", c = list("y")))
293 ```
294
295 ### Unspecified
296
297 ```{r bracket-assign-unspecified, dftbl = TRUE}
298 with_df(df[] <- 1)
299 with_df(df[] <- 4:1)
300 with_df(df[] <- 3:1)
301 with_df(df[] <- 5:1)
302 with_df(df[] <- data.frame(1, "x"))
303 with_df(df[] <- data.frame(4:1, "x", 2))
304 with_df(df[] <- data.frame(1, "x", 2))
305 with_df(df[] <- data.frame(1, "x", 2, 3))
306 with_df(df[] <- df)
307 with_df(df[,] <- 1)
308 with_df(df[,] <- 4:1)
309 with_df(df[,] <- 3:1)
310 with_df(df[,] <- 5:1)
311 with_df(df[,] <- data.frame(1, "x"))
312 with_df(df[,] <- data.frame(4:1, "x", 2))
313 with_df(df[,] <- data.frame(1, "x", 2))
314 with_df(df[,] <- data.frame(1, "x", 2, 3))
315 with_df(df[,] <- df)
316 ```
317
318 ### Subset assignment
319
320 Due to tibble's default of `drop = FALSE`, updating a portion of a `[` subset is still safe, because tibble is still in control.
321 Only one example is given here.
322
323 ```{r bracket-assign-subset, dftbl = TRUE}
324 with_df(df["a"][1, ] <- "b")
325 ```