--- title: "Subsetting" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{subset} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( error = TRUE, collapse = TRUE, comment = "#>" ) tibble:::set_dftbl_hooks() options( lifecycle_disable_warnings = FALSE, lifecycle_verbose_soft_deprecation = TRUE, lifecycle_repeat_warnings = TRUE ) ``` There are many, many ways to subset data frames and tibbles.
[![Alignment](alignment.png "Alignment chart"){ width=100% }](https://twitter.com/skyetetra/status/1160012260456062977)
Drawing by [Jacqueline Nolis](https://twitter.com/skyetetra/status/1160012260456062977)
This vignette is an attempt to provide a comprehensive overview over the behavior of the subsetting operators `$`, `[[` and `[`, highlighting where the tibble implementation differs from the data frame implementation. ```{r setup} library(tibble) new_df <- function() { df <- data.frame(a = 1:4) df$b <- letters[5:8] df$cd <- list(9, 10:11, 12:14, "text") df } new_tbl <- function() { as_tibble(new_df()) } ``` Results of the same code for data frames and tibbles are presented side by side: ```{r show, dftbl = TRUE, dftbl_always = TRUE} new_df() ``` 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. This allows to spot differences easier. ```{r show-compare, dftbl = TRUE} new_df() ``` Subsetting operations are read-only. The same objects are reused in all examples: ```{r ro} df <- new_df() tbl <- new_tbl() ``` ## $ With `$` subsetting, accessing a missing column gives a warning. Inexact matching is not supported: ```{r dollar, dftbl = TRUE} df$a df$"a" df$a[2:3] df$cd df$c df$d ``` ## [[ The `exact` argument is not supported by tibbles. ```{r double-bracket-col, dftbl = TRUE} df[["a"]] df[["cd", exact = TRUE]] df[["cd", exact = FALSE]] df[["c", exact = TRUE]] df[["c", exact = FALSE]] ``` With two indexes, a single element is returned. List columns are not unpacked by tibbles, the `[[` only unpacks columns. ```{r double-bracket-both, dftbl = TRUE} df[[2, "a"]] df[[2, "cd"]] df[[1:2, "cd"]] df[[2, "c"]] df[[1:2, "c"]] ``` Exotic variants like recursive indexing are deprecated for tibbles. ```{r double-bracket-exotic, dftbl = TRUE} df[[c(1, 2)]] ``` ## [ With `[` subsetting, tibbles always return a tibble. The `drop` argument is supported but has different defaults: ```{r bracket-col-one, dftbl = TRUE} df["a"] df["a", drop = FALSE] df["a", drop = TRUE] df[1] df[0] df[4] df[NA] df[NA_character_] df[NA_integer_] ``` The same examples are repeated for two-dimensional indexing when omitting the row index: ```{r bracket-col-two, dftbl = TRUE} df[, "a"] df[, "a", drop = FALSE] df[, "a", drop = TRUE] df[, 1] df[, 0] df[, 4] df[, NA] df[, NA_character_] df[, NA_integer_] ``` Multiple columns can be queried by passing a vector of column indexes (names, positions, or even a logical vector). With the latter option, tibbles are a tad stricter: ```{r bracket-col-multi-one, dftbl = TRUE} df[c("a", "b")] df[character()] df[1:2] df[1:3] df[1:4] df[0:2] df[-1:2] df[-1] df[-(1:2)] df[integer()] df[TRUE] df[FALSE] df[c(TRUE, TRUE, FALSE)] df[c(FALSE, TRUE, FALSE)] df[c(FALSE, TRUE)] df[c(FALSE, TRUE, FALSE, TRUE)] ``` The same examples are repeated for two-dimensional indexing when omitting the row index: ```{r bracket-col-multi-two, dftbl = TRUE} df[, c("a", "b")] df[, character()] df[, 1:2] df[, 1:3] df[, 1:4] df[, 0:2] df[, -1:2] df[, -1] df[, -(1:2)] df[, integer()] df[, TRUE] df[, FALSE] df[, c(TRUE, TRUE, FALSE)] df[, c(FALSE, TRUE, FALSE)] df[, c(FALSE, TRUE)] df[, c(FALSE, TRUE, FALSE, TRUE)] ``` Row subsetting with integer indexes works almost identical. Out-of-bounds subsetting is not recommended and may lead to an error in future versions. Another special case is subsetting with `[1, , drop = TRUE]` where the data frame implementation returns a list. ```{r bracket-row-integer, dftbl = TRUE} df[1, ] df[1, , drop = TRUE] df[1:2, ] df[0, ] df[integer(), ] df[5, ] df[4:5, ] df[-1, ] df[-1:2, ] df[NA, ] df[NA_integer_, ] df[c(NA, 1), ] ``` Row subsetting with logical indexes also works almost identical, the index vector must have length one or the number of rows with tibbles. ```{r bracket-row-logical, dftbl = TRUE} df[TRUE, ] df[FALSE, ] df[c(TRUE, FALSE), ] df[c(TRUE, FALSE, TRUE), ] df[c(TRUE, FALSE, TRUE, FALSE), ] df[c(TRUE, FALSE, TRUE, FALSE, TRUE), ] ``` Indexing both row and column works more or less the same, except for `drop`: ```{r bracket-both, dftbl = TRUE} df[1, "a"] df[1, "a", drop = FALSE] df[1, "a", drop = TRUE] df[1:2, "a"] df[1:2, "a", drop = FALSE] df[1:2, "a", drop = TRUE] df[1, c("a", "b")] df[1, c("a", "b"), drop = FALSE] df[1, c("a", "b"), drop = TRUE] df[1:2, c("a", "b")] ``` Indexes can be omitted altogether, no differences here: ```{r bracket-empty, dftbl = TRUE} df[] df[,] ```