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