Objects 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.table object. If the data are grouped with
dplyr::group_by(), the resulting data frame is also dplyr::ungroup()ed
in the process.
Usage
as_dtx(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 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.tablekey from the attribute?- byref
If
TRUE, the object is modified by reference when converted into adata.table(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 three other as_dt...() functions (as_dtt by default). The default_dtx() does the same as as_dtx() if the object is 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 three 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 -0.554 a TRUE
#> 2 2 0.629 b TRUE
#> 3 3 2.07 c FALSE
#> 4 4 -1.63 d FALSE
#> 5 5 0.512 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 -0.5536994 a TRUE
#> b 2 0.6289820 b TRUE
#> c 3 2.0650249 c FALSE
#> d 4 -1.6309894 d FALSE
#> e 5 0.5124269 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 -0.554 a TRUE
#> 2 b 2 0.629 b TRUE
#> 3 c 3 2.07 c FALSE
#> 4 d 4 -1.63 d FALSE
#> 5 e 5 0.512 e FALSE
# and data frame row names are set again when converted bock to dtf
as_dtf(dtbl2)
#> x y f l
#> a 1 -0.5536994 a TRUE
#> b 2 0.6289820 b TRUE
#> c 3 2.0650249 c FALSE
#> d 4 -1.6309894 d FALSE
#> e 5 0.5124269 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 -0.5536994 a TRUE
#> 2: b 2 0.6289820 b TRUE
#> 3: c 3 2.0650249 c FALSE
#> 4: d 4 -1.6309894 d FALSE
#> 5: e 5 0.5124269 e FALSE
as_dtf(dtt2)
#> x y f l
#> a 1 -0.5536994 a TRUE
#> b 2 0.6289820 b TRUE
#> c 3 2.0650249 c FALSE
#> d 4 -1.6309894 d FALSE
#> e 5 0.5124269 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" "-0.5536994" "a" "TRUE"
#> [2,] "b" "2" " 0.6289820" "b" "TRUE"
#> [3,] "c" "3" " 2.0650249" "c" "FALSE"
#> [4,] "d" "4" "-1.6309894" "d" "FALSE"
#> [5,] "e" "5" " 0.5124269" "e" "FALSE"
# ... but as_matrix() does the job!
as_matrix(dtbl2)
#> x y f l
#> a "1" "-0.5536994" "a" "TRUE"
#> b "2" " 0.6289820" "b" "TRUE"
#> c "3" " 2.0650249" "c" "FALSE"
#> d "4" "-1.6309894" "d" "FALSE"
#> e "5" " 0.5124269" "e" "FALSE"
# The name for row in 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.table by default)
(dtx2 <- as_dtx(dtf2))
#> .rownames x y f l
#> <char> <int> <num> <char> <lgcl>
#> 1: a 1 -0.5536994 a TRUE
#> 2: b 2 0.6289820 b TRUE
#> 3: c 3 2.0650249 c FALSE
#> 4: d 4 -1.6309894 d FALSE
#> 5: e 5 0.5124269 e FALSE
class(dtx2)
#> [1] "data.table" "data.frame"
# The default data frame object used:
getOption("SciViews.as_dtx", default = as_dtt)
#> 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 (is.data.frame(x) && isTRUE(byref)) {
#> if (isTRUE(keep.key)) {
#> key <- attr(x, "key")
#> }
#> else {
#> key <- NULL
#> }
#> x <- .ungroup_dtbl(x)
#> setDT(x, keep.rownames = rownames, key = key)
#> attr(x, "key") <- NULL
#> }
#> else {
#> key <- attr(x, "key")
#> x <- as.data.table(.ungroup_dtbl(x), keep.rownames = rownames)
#> if (isTRUE(keep.key) && !is.null(key))
#> setkeyv(x, key)
#> attr(x, "key") <- NULL
#> }
#> rownames(x) <- NULL
#> x
#> }
#> <bytecode: 0x558553e8f508>
#> <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 whaterver the object you pass to it
(dtx2 <- default_dtx(dtf2))
#> .rownames x y f l
#> <char> <int> <num> <char> <lgcl>
#> 1: a 1 -0.5536994 a TRUE
#> 2: b 2 0.6289820 b TRUE
#> 3: c 3 2.0650249 c FALSE
#> 4: d 4 -1.6309894 d FALSE
#> 5: e 5 0.5124269 e FALSE
class(dtx2)
#> [1] "data.table" "data.frame"
# Any other object than 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 -0.5536994 a TRUE
#> b 2 0.6289820 b TRUE
#> c 3 2.0650249 c FALSE
#> d 4 -1.6309894 d FALSE
#> e 5 0.5124269 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 -0.5536994 a TRUE
#> 2: b 2 0.6289820 b TRUE
#> 3: c 3 2.0650249 c FALSE
#> 4: d 4 -1.6309894 d FALSE
#> 5: e 5 0.5124269 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"