collapse (version 1.7.6)

quick-conversion: Quick Data Conversion

Description

Fast, flexible and precise conversion of common data objects, without method dispatch and extensive checks:

• qDF, qDT and qTBL convert vectors, matrices, higher-dimensional arrays and suitable lists to data frame, data.table and tibble, respectively.

• qM converts vectors, higher-dimensional arrays, data frames and suitable lists to matrix.

• mctl and mrtl column- or row-wise convert a matrix to list, data frame or data.table. They are used internally by qDF and qDT, dapply, BY, etc…

• qF converts atomic vectors to factor (documented on a separate page).

• as_numeric_factor and as_character_factor convert factors, or all factor columns in a data frame / list, to numeric or character (by converting the levels).

Usage

# Converting between matrices, data frames / tables / tibbles
 qDF(X, row.names.col = FALSE, keep.attr = FALSE, class = "data.frame")
 qDT(X, row.names.col = FALSE, keep.attr = FALSE, class = c("data.table", "data.frame"))
qTBL(X, row.names.col = FALSE, keep.attr = FALSE, class = c("tbl_df","tbl","data.frame"))
  qM(X,                        keep.attr = FALSE, class = NULL)
# Programmer functions: matrix rows or columns to list / DF / DT - fully in C++
mctl(X, names = FALSE, return = "list")
mrtl(X, names = FALSE, return = "list")
# Converting factors or factor columns
  as_numeric_factor(X, keep.attr = TRUE)
as_character_factor(X, keep.attr = TRUE)

Arguments

X

a vector, factor, matrix, higher-dimensional array, data frame or list. mctl and mrtl only accept matrices, as_numeric_factor and as_character_factor only accept factors, data frames or lists.

row.names.col

should a column capturing names or row.names be added? i.e. when converting atomic objects to data frame or data frame to data.table. Can be logical TRUE, which will add a column "row.names" in front, or can supply a name for the column i.e. "column1".

keep.attr

logical. FALSE (default) yields a hard / thorough object conversion: All unnecessary attributes are removed from the object yielding a plain matrix / data.frame / data.table. FALSE yields a soft / minimal object conversion: Only the attributes 'names', 'row.names', 'dim', 'dimnames' and 'levels' are modified in the conversion. Other attributes are preserved. See also class.

class

if a vector of classes is passed here, the converted object will be assigned these classes. If NULL is passed, the default classes are assigned: qM assigns no class, qDF a class "data.frame", and qDT a class c("data.table", "data.frame"). If keep.attr = TRUE and class = NULL and the object already inherits the default classes, further inherited classes are preserved. See Details and the Example.

names

logical. Should the list be named using row/column names from the matrix?

return

an integer or string specifying what to return. The options are:

Int.		String		Description
1		"list"		returns a plain list
2		"data.frame"		returns a plain data.frame
3		"data.table"		returns a plain data.table

Value

qDF - returns a data.frame qDT - returns a data.table qTBL - returns a tibble qM - returns a matrix mctl, mrtl - return a list, data frame or data.table qF - returns a factor as_numeric_factor - returns X with factors converted to numeric variables as_character_factor - returns X with factors converted to character variables

Details

Object conversions using these functions are maximally efficient and involve 3 consecutive steps: (1) Converting the storage mode / dimensions / data of the object, (2) converting / modifying the attributes and (3) modifying the class of the object:

(1) is determined by the choice of function and the optional row.names.col argument to qDF and qDT. Higher-dimensional arrays are converted by expanding the second dimension (adding columns, same as as.matrix, as.data.frame, as.data.table).

(2) is determined by the keep.attr argument: keep.attr = TRUE seeks to preserve the attributes of the object. It's effect is like copying attributes(converted) <- attributes(original), and then modifying the "dim", "dimnames", "names", "row.names" and "levels" attributes as necessitated by the conversion task. keep.attr = FALSE only converts / assigns / removes these attributes and drops all others.

(3) is determined by the class argument: Setting class = "myclass" will yield a converted object of class "myclass", with any other / prior classes being removed by this replacement. Setting class = NULL does NOT mean that a class NULL is assigned (which would remove the class attribute), but rather that the default classes are assigned: qM assigns no class, qDF a class "data.frame", and qDT a class c("data.table", "data.frame"). At this point there is an interaction with keep.attr: If keep.attr = TRUE and class = NULL and the object converted already inherits the respective default classes, then any other inherited classes will also be preserved (with qM(x, keep.attr = TRUE, class = NULL) any class will be preserved if is.matrix(x) evaluated to TRUE.)

The default keep.attr = FALSE ensures hard conversions so that all unnecessary attributes are dropped. Furthermore in qDF and qDT the default classes were explicitly assigned, thus any other classes (like 'tbl_df', 'tbl', 'pdata.frame', 'sf', 'tsibble' etc.) will be removed when these objects are passed, regardless of the keep.attr setting. This is to ensure that the default methods for 'data.frame' and 'data.table' can be assumed to work, even if the user chooses to preserve further attributes. For qM a more lenient default setup was chosen to enable the full preservation of time series matrices with keep.attr = TRUE. If the user wants to keep attributes attached to a matrix but make sure that all default methods work properly, either one of qM(x, keep.attr = TRUE, class = "matrix") or unclass(qM(x, keep.attr = TRUE)) should be employed.

See Also

qF, Collapse Overview

Examples

# NOT RUN {
## Basic Examples
mtcarsM <- qM(mtcars)                   # Matrix from data.frame
mtcarsDT <- qDT(mtcarsM)                # data.table from matrix columns
mtcarsTBL <- qTBL(mtcarsM)              # tibble from matrix columns
head(mrtl(mtcarsM, TRUE, "data.frame")) # data.frame from matrix rows, etc..
head(qDF(mtcarsM, "cars"))              # Adding a row.names column when converting from matrix
head(qDT(mtcars, "cars"))               # Saving row.names when converting data frame to data.table

cylF <- qF(mtcars$cyl)                  # Factor from atomic vector
cylF

# Factor to numeric conversions
identical(mtcars,  as_numeric_factor(dapply(mtcars, qF)))

# }
# NOT RUN {
<!-- % ## Explaining the interaction of keep.attr and class. Consider the time series   EuStockMarkets -->
# }
# NOT RUN {
<!-- % plot() -->
# }