Coerce objects into data.trames, data.frames, data.tables, tibbles or matrices
Source:R/as_dtx.R
as_dtx.RdObjects are coerced into the desired class. For as_dtx(), the
desired class is obtained from getOption("SciViews.as_dtx"), with a default
value producing a data.trame object. If the data are grouped with
dplyr::group_by(), the resulting data frame is also dplyr::ungroup()ed
in the process.
as_dtx(x, ..., rownames = NULL, keep.key = TRUE, byref = FALSE)
as_dtrm(x, ..., rownames = NULL, keep.key = TRUE, byref = FALSE)
as_dtf(x, ..., rownames = NULL, keep.key = TRUE, byref = NULL)
as_dtt(x, ..., rownames = NULL, keep.key = TRUE, byref = FALSE)
as_dtbl(x, ..., rownames = NULL, keep.key = TRUE, byref = NULL)
default_dtx(x, ..., rownames = NULL, keep.key = TRUE, byref = FALSE)
# S3 method for class 'tbl_df'
as.matrix(x, row.names = NULL, optional = FALSE, ...)
as_matrix(x, rownames = NULL, ...)Arguments
- x
An object.
- ...
Further arguments passed to the methods (not used yet).
- rownames
The name of the column with row names. If
NULL, it is assessed fromgetOptions("SciViews.dtx.rownames").- keep.key
Do we keep the data.table key into a "key" attribute or do we restore
data.tableordata.tramekey from the attribute?- byref
If
TRUE, the object is modified by reference when converted into adata.tableor adata.trame(faster, but not conventional). This isFALSEby default, orNULLif the argument does not apply in the context.- row.names
Same as
rownames, but for base R functions.- optional
logical, If
TRUE, setting row names and converting column names to syntactically correct names is optional.
Value
The coerced object. For as_dtx(), the coercion is determined from getOption("SciViews.as_dtx") which must return one of the four other as_dt...() functions (as_dtrm by default). The default_dtx() does the same as as_dtx() if the object is a data.trame, a data.frame, a data.table, or a tibble, but it return the unmodified object for any other class (including subclassed data frames). This is a convenient function to force conversion only between those four objects classes.
Note
Use as_matrix() instead of base::as.matrix(): it has different default
arguments to better account for rownames in data.table and tibble!
Examples
# A data.frame
dtf <- dtf(
x = 1:5,
y = rnorm(5),
f = letters[1:5],
l = sample(c(TRUE, FALSE), 5, replace = TRUE))
# Convert into a tibble
(dtbl <- as_dtbl(dtf))
#> # A tibble: 5 × 4
#> x y f l
#> <int> <dbl> <chr> <lgl>
#> 1 1 -1.63 a TRUE
#> 2 2 0.512 b FALSE
#> 3 3 -1.86 c TRUE
#> 4 4 -0.522 d TRUE
#> 5 5 -0.0526 e FALSE
# Since row names are trivial (1 -> 5), a .rownames column is not added
dtf2 <- dtf
rownames(dtf2) <- letters[1:5]
dtf2
#> x y f l
#> a 1 -1.63098940 a TRUE
#> b 2 0.51242695 b FALSE
#> c 3 -1.86301149 c TRUE
#> d 4 -0.52201251 d TRUE
#> e 5 -0.05260191 e FALSE
# Now, the conversion into a tibble adds .rownames
(dtbl2 <- as_dtbl(dtf2))
#> # A tibble: 5 × 5
#> .rownames x y f l
#> <chr> <int> <dbl> <chr> <lgl>
#> 1 a 1 -1.63 a TRUE
#> 2 b 2 0.512 b FALSE
#> 3 c 3 -1.86 c TRUE
#> 4 d 4 -0.522 d TRUE
#> 5 e 5 -0.0526 e FALSE
# and data frame row names are set again when converted bock to dtf
as_dtf(dtbl2)
#> x y f l
#> a 1 -1.63098940 a TRUE
#> b 2 0.51242695 b FALSE
#> c 3 -1.86301149 c TRUE
#> d 4 -0.52201251 d TRUE
#> e 5 -0.05260191 e FALSE
# It also work for conversions data.frame <-> data.table
(dtt2 <- as_dtt(dtf2))
#> .rownames x y f l
#> <char> <int> <num> <char> <lgcl>
#> 1: a 1 -1.63098940 a TRUE
#> 2: b 2 0.51242695 b FALSE
#> 3: c 3 -1.86301149 c TRUE
#> 4: d 4 -0.52201251 d TRUE
#> 5: e 5 -0.05260191 e FALSE
as_dtf(dtt2)
#> x y f l
#> a 1 -1.63098940 a TRUE
#> b 2 0.51242695 b FALSE
#> c 3 -1.86301149 c TRUE
#> d 4 -0.52201251 d TRUE
#> e 5 -0.05260191 e FALSE
# or data.frame <-> data.trame
(dtrm2 <- as_dtrm(dtf2))
#> # A data.trame: [5 × 5]
#> .rownames x y f l
#> <chr> <int> <dbl> <chr> <lgl>
#> 1 a 1 -1.63 a TRUE
#> 2 b 2 0.512 b FALSE
#> 3 c 3 -1.86 c TRUE
#> 4 d 4 -0.522 d TRUE
#> 5 e 5 -0.0526 e FALSE
as_dtf(dtrm2)
#> x y f l
#> a 1 -1.63098940 a TRUE
#> b 2 0.51242695 b FALSE
#> c 3 -1.86301149 c TRUE
#> d 4 -0.52201251 d TRUE
#> e 5 -0.05260191 e FALSE
# It does not work when converting a tibble or a data.table into a matrix
# with as.matrix()
as.matrix(dtbl2)
#> .rownames x y f l
#> [1,] "a" "1" "-1.63098940" "a" "TRUE"
#> [2,] "b" "2" " 0.51242695" "b" "FALSE"
#> [3,] "c" "3" "-1.86301149" "c" "TRUE"
#> [4,] "d" "4" "-0.52201251" "d" "TRUE"
#> [5,] "e" "5" "-0.05260191" "e" "FALSE"
# ... but as_matrix() does the job!
as_matrix(dtbl2)
#> x y f l
#> a "1" "-1.63098940" "a" "TRUE"
#> b "2" " 0.51242695" "b" "FALSE"
#> c "3" "-1.86301149" "c" "TRUE"
#> d "4" "-0.52201251" "d" "TRUE"
#> e "5" "-0.05260191" "e" "FALSE"
# The name for row in dtrm, dtt and dtbl is in:
# (data.frame's row names are converted into a column with this name)
getOption("SciViews.dtx.rownames", default = ".rownames")
#> [1] ".rownames"
# Convert into the preferred data frame object (data.trame by default)
(dtx2 <- as_dtx(dtf2))
#> # A data.trame: [5 × 5]
#> .rownames x y f l
#> <chr> <int> <dbl> <chr> <lgl>
#> 1 a 1 -1.63 a TRUE
#> 2 b 2 0.512 b FALSE
#> 3 c 3 -1.86 c TRUE
#> 4 d 4 -0.522 d TRUE
#> 5 e 5 -0.0526 e FALSE
class(dtx2)
#> [1] "data.trame" "data.frame"
# The default data frame object used:
getOption("SciViews.as_dtx", default = as_dtrm)
#> function (x, ..., rownames = NULL, keep.key = TRUE, byref = FALSE)
#> {
#> if (is.null(rownames))
#> rownames <- getOption("SciViews.dtx.rownames", default = ".rownames")
#> if (rownames %in% names(x) || all(rownames(x) == seq_len(nrow(x))))
#> rownames <- FALSE
#> if (isTRUE(keep.key)) {
#> key <- key(x)
#> if (is.null(key))
#> key <- attr(x, "key")
#> }
#> else {
#> key <- NULL
#> }
#> if (is.list(x) && isTRUE(byref)) {
#> x <- .ungroup_dtbl(x)
#> setDT(x, keep.rownames = rownames, key = key)
#> }
#> else {
#> x <- as.data.table(.ungroup_dtbl(x), keep.rownames = rownames)
#> setkeyv(x, key)
#> }
#> setattr(x, "key", NULL)
#> rownames(x) <- NULL
#> setattr(x, "class", c("data.trame", "data.frame"))
#> x
#> }
#> <bytecode: 0x55926fed5820>
#> <environment: namespace:svBase>
# default_dtx() does the same as as_dtx(),
# but it also does not change other objects
# So, it is safe to use whatever the object you pass to it
(dtx2 <- default_dtx(dtf2))
#> # A data.trame: [5 × 5]
#> .rownames x y f l
#> <chr> <int> <dbl> <chr> <lgl>
#> 1 a 1 -1.63 a TRUE
#> 2 b 2 0.512 b FALSE
#> 3 c 3 -1.86 c TRUE
#> 4 d 4 -0.522 d TRUE
#> 5 e 5 -0.0526 e FALSE
class(dtx2)
#> [1] "data.trame" "data.frame"
# Any other object than data.trame, data.frame, data.table or tbl_df
# is not converted
res <- default_dtx(1:5)
class(res)
#> [1] "integer"
# No conversion if the data frame is subclassed
dtf3 <- dtf2
class(dtf3) <- c("subclassed", "data.frame")
class(default_dtx(dtf3))
#> [1] "subclassed" "data.frame"
# data.table keys are converted into a 'key' attribute and back
library(data.table)
setkey(dtt2, 'x')
haskey(dtt2)
#> [1] TRUE
key(dtt2)
#> [1] "x"
(dtf3 <- as_dtf(dtt2))
#> x y f l
#> a 1 -1.63098940 a TRUE
#> b 2 0.51242695 b FALSE
#> c 3 -1.86301149 c TRUE
#> d 4 -0.52201251 d TRUE
#> e 5 -0.05260191 e FALSE
attributes(dtf3)
#> $names
#> [1] "x" "y" "f" "l"
#>
#> $row.names
#> [1] "a" "b" "c" "d" "e"
#>
#> $class
#> [1] "data.frame"
#>
#> $key
#> [1] "x"
#>
# Key is restored when converted back into a data.table (also from a tibble)
(dtt3 <- as_dtt(dtf3))
#> Key: <x>
#> .rownames x y f l
#> <char> <int> <num> <char> <lgcl>
#> 1: a 1 -1.63098940 a TRUE
#> 2: b 2 0.51242695 b FALSE
#> 3: c 3 -1.86301149 c TRUE
#> 4: d 4 -0.52201251 d TRUE
#> 5: e 5 -0.05260191 e FALSE
haskey(dtt3)
#> [1] TRUE
key(dtt3)
#> [1] "x"
# Grouped tibbles are ungrouped with as_dtbl() or as_dtx()/default_dtx()!
mtcars |> dplyr::group_by(cyl) -> mtcars_grouped
class(mtcars_grouped)
#> [1] "grouped_df" "tbl_df" "tbl" "data.frame"
mtcars2 <- as_dtbl(mtcars_grouped)
class(mtcars2)
#> [1] "tbl_df" "tbl" "data.frame"