tibble() constructs a data frame. It is used like base::data.frame(), but with a couple notable differences:

  • The returned data frame has the class tbl_df, in addition to data.frame. This allows so-called "tibbles" to exhibit some special behaviour, such as enhanced printing. Tibbles are fully described in tbl_df.

  • tibble() is much lazier than base::data.frame() in terms of transforming the user's input.

    • Character vectors are not coerced to factor.

    • List-columns are expressly anticipated and do not require special tricks.

    • Column names are not modified.

    • Inner names in columns are left unchanged.

  • tibble() builds columns sequentially. When defining a column, you can refer to columns created earlier in the call. Only columns of length one are recycled.

  • If a column evaluates to a data frame or tibble, it is nested or spliced. See examples.

tibble_row() constructs a data frame that is guaranteed to occupy one row. Vector columns are required to have size one, non-vector columns are wrapped in a list.

tibble(
  ...,
  .rows = NULL,
  .name_repair = c("check_unique", "unique", "universal", "minimal")
)

tibble_row(
  ...,
  .name_repair = c("check_unique", "unique", "universal", "minimal")
)

Arguments

...

<dynamic-dots> A set of name-value pairs. These arguments are processed with rlang::quos() and support unquote via !! and unquote-splice via !!!. Use := to create columns that start with a dot.

Arguments are evaluated sequentially. You can refer to previously created elements directly or using the .data pronoun. An existing .data pronoun, provided e.g. inside dplyr::mutate(), is not available.

.rows

The number of rows, useful to create a 0-column tibble or just as an additional check.

.name_repair

Treatment of problematic column names:

  • "minimal": No name repair or checks, beyond basic existence,

  • "unique": Make sure names are unique and not empty,

  • "check_unique": (default value), no name repair, but check they are unique,

  • "universal": Make the names unique and syntactic

  • a function: apply custom name repair (e.g., .name_repair = make.names for names in the style of base R).

  • A purrr-style anonymous function, see rlang::as_function()

This argument is passed on as repair to vctrs::vec_as_names(). See there for more details on these terms and the strategies used to enforce them.

Value

A tibble, which is a colloquial term for an object of class tbl_df. A tbl_df object is also a data frame, i.e. it has class data.frame.

See also

Use as_tibble() to turn an existing object into a tibble. Use enframe() to convert a named vector into a tibble. Name repair is detailed in vctrs::vec_as_names(). See quasiquotation for more details on tidy dots semantics, i.e. exactly how the ... argument is processed.

Examples

# Unnamed arguments are named with their expression:
a <- 1:5
tibble(a, a * 2)
#> # A tibble: 5 x 2
#>       a `a * 2`
#>   <int>   <dbl>
#> 1     1       2
#> 2     2       4
#> 3     3       6
#> 4     4       8
#> 5     5      10

# Scalars (vectors of length one) are recycled:
tibble(a, b = a * 2, c = 1)
#> # A tibble: 5 x 3
#>       a     b     c
#>   <int> <dbl> <dbl>
#> 1     1     2     1
#> 2     2     4     1
#> 3     3     6     1
#> 4     4     8     1
#> 5     5    10     1

# Columns are available in subsequent expressions:
tibble(x = runif(10), y = x * 2)
#> # A tibble: 10 x 2
#>         x      y
#>     <dbl>  <dbl>
#>  1 0.512  1.02  
#>  2 0.836  1.67  
#>  3 0.709  1.42  
#>  4 0.874  1.75  
#>  5 0.0115 0.0230
#>  6 0.888  1.78  
#>  7 0.996  1.99  
#>  8 0.500  1.00  
#>  9 0.359  0.718 
#> 10 0.775  1.55  

# tibble() never coerces its inputs,
str(tibble(letters))
#> tibble [26 × 1] (S3: tbl_df/tbl/data.frame)
#>  $ letters: chr [1:26] "a" "b" "c" "d" ...
str(tibble(x = list(diag(1), diag(2))))
#> tibble [2 × 1] (S3: tbl_df/tbl/data.frame)
#>  $ x:List of 2
#>   ..$ : num [1, 1] 1
#>   ..$ : num [1:2, 1:2] 1 0 0 1

# or munges column names (unless requested),
tibble(`a + b` = 1:5)
#> # A tibble: 5 x 1
#>   `a + b`
#>     <int>
#> 1       1
#> 2       2
#> 3       3
#> 4       4
#> 5       5

# but it forces you to take charge of names, if they need repair:
try(tibble(x = 1, x = 2))
#> Error : Column name `x` must not be duplicated.
#> Use .name_repair to specify repair.
tibble(x = 1, x = 2, .name_repair = "unique")
#> New names:
#> * x -> x...1
#> * x -> x...2
#> # A tibble: 1 x 2
#>   x...1 x...2
#>   <dbl> <dbl>
#> 1     1     2
tibble(x = 1, x = 2, .name_repair = "minimal")
#> # A tibble: 1 x 2
#>       x     x
#>   <dbl> <dbl>
#> 1     1     2

## By default, non-syntactic names are allowed,
df <- tibble(`a 1` = 1, `a 2` = 2)
## because you can still index by name:
df[["a 1"]]
#> [1] 1
df$`a 1`
#> [1] 1
with(df, `a 1`)
#> [1] 1

## Syntactic names are easier to work with, though, and you can request them:
df <- tibble(`a 1` = 1, `a 2` = 2, .name_repair = "universal")
#> New names:
#> * `a 1` -> a.1
#> * `a 2` -> a.2
df$a.1
#> [1] 1

## You can specify your own name repair function:
tibble(x = 1, x = 2, .name_repair = make.unique)
#> # A tibble: 1 x 2
#>       x   x.1
#>   <dbl> <dbl>
#> 1     1     2

fix_names <- function(x) gsub("\\s+", "_", x)
tibble(`year 1` = 1, `year 2` = 2, .name_repair = fix_names)
#> # A tibble: 1 x 2
#>   year_1 year_2
#>    <dbl>  <dbl>
#> 1      1      2

## purrr-style anonymous functions and constants
## are also supported
tibble(x = 1, x = 2, .name_repair = ~ make.names(., unique = TRUE))
#> # A tibble: 1 x 2
#>       x   x.1
#>   <dbl> <dbl>
#> 1     1     2

tibble(x = 1, x = 2, .name_repair = ~ c("a", "b"))
#> # A tibble: 1 x 2
#>       a     b
#>   <dbl> <dbl>
#> 1     1     2

# Tibbles can contain columns that are tibbles or matrices
# if the number of rows is compatible. Unnamed tibbled are
# spliced, i.e. the inner columns are inserted into the
# tibble under construction.
tibble(
  a = 1:3,
  tibble(
    b = 4:6,
    c = 7:9
  ),
  d = tibble(
    e = tibble(
      f = b
    )
  )
)
#> # A tibble: 3 x 4
#>       a     b     c d$e$f
#>   <int> <int> <int> <int>
#> 1     1     4     7     4
#> 2     2     5     8     5
#> 3     3     6     9     6
tibble(
  a = 1:4,
  b = diag(4),
  c = cov(iris[1:4])
)
#> # A tibble: 4 x 3
#>       a b[,1]  [,2]  [,3]  [,4] c[,"Sepal.Length"] [,"Sepal.Width"]
#>   <int> <dbl> <dbl> <dbl> <dbl>              <dbl>            <dbl>
#> 1     1     1     0     0     0             0.686           -0.0424
#> 2     2     0     1     0     0            -0.0424           0.190 
#> 3     3     0     0     1     0             1.27            -0.330 
#> 4     4     0     0     0     1             0.516           -0.122 

# data can not contain POSIXlt columns, or tibbles or matrices
# with incompatible number of rows:
try(tibble(y = strptime("2000/01/01", "%x")))
#> # A tibble: 1 x 1
#>   y                  
#>   <dttm>             
#> 1 NA                 
try(tibble(a = 1:3, b = tibble(c = 4:7)))
#> Error : Tibble columns must have compatible sizes.
#> * Size 3: Existing data.
#> * Size 4: Column `b`.
#>  Only values of size one are recycled.

# Use := to create columns with names that start with a dot:
tibble(.dotted = 3)
#> # A tibble: 1 x 1
#>   .dotted
#>     <dbl>
#> 1       3
tibble(.dotted := 3)
#> # A tibble: 1 x 1
#>   .dotted
#>     <dbl>
#> 1       3

# You can unquote an expression:
x <- 3
tibble(x = 1, y = x)
#> # A tibble: 1 x 2
#>       x     y
#>   <dbl> <dbl>
#> 1     1     1
tibble(x = 1, y = !!x)
#> # A tibble: 1 x 2
#>       x     y
#>   <dbl> <dbl>
#> 1     1     3

# You can splice-unquote a list of quosures and expressions:
tibble(!!! list(x = rlang::quo(1:10), y = quote(x * 2)))
#> # A tibble: 10 x 2
#>        x     y
#>    <int> <dbl>
#>  1     1     2
#>  2     2     4
#>  3     3     6
#>  4     4     8
#>  5     5    10
#>  6     6    12
#>  7     7    14
#>  8     8    16
#>  9     9    18
#> 10    10    20


# Use tibble_row() to construct a one-row tibble:
tibble_row(a = 1, lm = lm(Petal.Width ~ Petal.Length + Species, data = iris))
#> # A tibble: 1 x 2
#>       a lm    
#>   <dbl> <list>
#> 1     1 <lm>