setDT {data.table} | R Documentation

## Coerce lists and data.frames to data.table by reference

### Description

In `data.table` parlance, all `set*` functions change their input by reference. That is, no copy is made at all, other than temporary working memory, which is as large as one column.. The only other `data.table` operator that modifies input by reference is `:=`. Check out the `See Also` section below for other `set*` function `data.table` provides.

`setDT` converts lists (both named and unnamed) and data.frames to data.tables by reference. This feature was requested on Stackoverflow.

### Usage

    setDT(x, keep.rownames=FALSE, key=NULL, check.names=FALSE)

### Arguments

`x` | A named or unnamed `list`, `data.frame` or `data.table`.
`keep.rownames` | For `data.frame`s, `TRUE` retains the `data.frame`'s row names under a new column `rn`.
`key` | Character vector of one or more column names which is passed to `setkeyv`. It may be a single comma separated string such as `key="x,y,z"`, or a vector of names such as `key=c("x","y","z")`.
`check.names` | Just as `check.names` in `data.frame`.

### Details

When working on large `lists` or `data.frames`, it might be both time and memory consuming to convert them to a `data.table` using `as.data.table(.)`, as this will make a complete copy of the input object before to convert it to a `data.table`. The `setDT` function takes care of this issue by allowing to convert `lists` - both named and unnamed lists and `data.frames` by reference instead. That is, the input object is modified in place, no copy is being made.

### Value

The input is modified by reference, and returned (invisibly) so it can be used in compound statements; e.g., `setDT(X)[, sum(B), by=A]`. If you require a copy, take a copy first (using `DT2 = copy(DT)`). See `?copy`.

### See Also

`data.table`, `as.data.table`, `setDF`, `copy`, `setkey`, `setcolorder`, `setattr`, `setnames`, `set`, `:=`, `setorder`

### Examples

    set.seed(45L)
    X = data.frame(A=sample(3, 10, TRUE),
             B=sample(letters[1:3], 10, TRUE),
             C=sample(10), stringsAsFactors=FALSE)

    # Convert X to data.table by reference and
    # get the frequency of each "A,B" combination
    setDT(X)[, .N, by=.(A,B)]

    # convert list to data.table
    # autofill names
    X = list(1:4, letters[1:4])
    setDT(X)
    # don't provide names
    X = list(a=1:4, letters[1:4])
    setDT(X, FALSE)

    # setkey directly
    X = list(a = 4:1, b=runif(4))
    setDT(X, key="a")[]

    # check.names argument
    X = list(a=1:5, a=6:10)
    setDT(X, check.names=TRUE)[]

[Package data.table version 1.10.4-1 Index]