80 lines
2.8 KiB
Plaintext
80 lines
2.8 KiB
Plaintext
---
|
|
title: "Extending tibble"
|
|
author: "Kirill Müller, Hadley Wickham"
|
|
output: rmarkdown::html_vignette
|
|
vignette: >
|
|
%\VignetteIndexEntry{Extending tibble}
|
|
%\VignetteEngine{knitr::rmarkdown}
|
|
%\VignetteEncoding{UTF-8}
|
|
---
|
|
|
|
Tibbles are S3 objects of class `c("tbl_df", "tbl", "data.frame")`.
|
|
This means that they inherit their behavior from the `"data.frame"` class and add two subclasses `"tbl"` and `"tbl_df"`.
|
|
The pillar and tibble packages provide methods for `"tbl"` and `"tbl_df"`, respectively.
|
|
Package authors and programmers can implement subclasses that extend either `"tbl_df"` (and its subclasses) or only `"tbl"` to provide custom behavior for tibble-like objects.
|
|
In addition, vectors classes can be implemented from scratch or on top of existing classes, to be used as columns.
|
|
This article provides links to the various customization points that help you avoiding reimplement existing behavior, and describes the difference between `"tbl"` and `"tbl_df"`.
|
|
|
|
Read more in [the second edition of Advanced R](https://adv-r.hadley.nz/index.html):
|
|
|
|
- about the internal representation of data frames and tibbles in the [Lists](https://adv-r.hadley.nz/vectors-chap.html#lists) and [Data frames and tibbles](https://adv-r.hadley.nz/vectors-chap.html#tibble) sections of the [Vectors chapter](https://adv-r.hadley.nz/vectors-chap.html),
|
|
- about R's S3 object-oriented system in the [S3 chapter](https://adv-r.hadley.nz/s3.html).
|
|
|
|
## Topics documented elsewhere
|
|
|
|
- Change or tweak the way a tibble prints: `vignette("extending", package = "pillar")`
|
|
|
|
- Change or tweak the way a column type is printed in a tibble: `vignette("pillar", package = "vctrs")`
|
|
|
|
- Implement a new column data type: `vignette("s3-vector", package = "vctrs")`
|
|
|
|
- Making your tibble subclass work well with dplyr: `?dplyr::dplyr_extending`
|
|
|
|
## Data frame subclasses
|
|
|
|
```{r}
|
|
library(tibble)
|
|
```
|
|
|
|
For tibble >= 3.0.0, the `"tbl"` class is responsible for printing, while the `"tbl_df"` class adds tibble's sturdy subsetting and subset assignment behavior (see `vignette("invariants")` for details).
|
|
This means that a data frame class that would like to (mostly) print like a tibble but keep the behavior from base R's data frames can inherit from `c("tbl", "data.frame")` or just from `"tbl"`.
|
|
An example is the `"tbl_sql"` class in the dbplyr package that is used to implement lazy database tables.
|
|
|
|
### Tibble example
|
|
|
|
```{r}
|
|
my_tbl_df <- new_tibble(
|
|
list(a = 1:3, b = 2:4),
|
|
class = "my_tbl_df"
|
|
)
|
|
|
|
tbl_sum.my_tbl_df <- function(x, ...) {
|
|
c(
|
|
"My custom tibble" = "Some info about it",
|
|
NextMethod()
|
|
)
|
|
}
|
|
|
|
my_tbl_df
|
|
my_tbl_df[, "a"]
|
|
```
|
|
|
|
### Data frame example
|
|
|
|
```{r}
|
|
my_tbl <- vctrs::new_data_frame(
|
|
list(a = 1:3, b = 2:4),
|
|
class = c("my_tbl", "tbl")
|
|
)
|
|
|
|
tbl_sum.my_tbl <- function(x, ...) {
|
|
c(
|
|
"My custom data frame" = "Some info about it",
|
|
NextMethod()
|
|
)
|
|
}
|
|
|
|
my_tbl
|
|
my_tbl[, "a"]
|
|
```
|