R: Quick Data Conversion

quick-conversion {collapse} | R Documentation

## 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

### 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.

### 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

### See Also

`qF`, Collapse Overview

### Examples

    ## 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)))

[Package collapse version 1.7.6 Index]