data.table (version 1.9.4)

setattr: Set attributes to objects 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. setnames operates only on data.frames and data.tables and is used for setting or changing column names by reference. setattr is a more general function that allows setting of any attribute to an object by reference.

Usage

setattr(x,name,value)
setnames(x,old,new)

Arguments

x

setnames accepts data.frame and data.table. setattr accepts any input; e.g, list, columns of a data.frame or data.table.

name

The character attribute name.

value

The value to assign to the attribute or NULL removes the attribute, if present.

old

When new is provided, character names or numeric positions of column names to change. When new is not provided, the new column names, which must be the same length as the number of columns. See examples.

new

Optional. New column names, the same length as old.

Value

• The input is modified by reference, and returned (invisibly) so it can be used in compound statements; e.g., setnames(DT,"V1", "Y")[, .N, by=Y]. If you require a copy, take a copy first (using DT2=copy(DT)). See ?copy.

  Note that setattr is also in package bit. Both packages merely expose R's internal setAttrib function at C level, but differ in return value. bit::setattr returns NULL (invisibly) to remind you the function is used for its side effect. data.table::setattr returns the changed object (invisibly), for use in compound statements.

Details

The <- method copies the whole table and we know of no way to avoid that copy without a change in R itself. Please use the set* functions instead, which make no copy at all. That is, please use setattr() rather than attr(x, name) <- value, setnames() rather than names(x) <- value or colnames(x) <- value and checkout other set* functions available for setting keys, reordering rows and columns of data.table, adding columns by reference. In particular, setattr() is useful in many situations to set attributes by reference and can be used on any object or part of an object, not just data.tables.

See Also

data.table, setkey, setorder, set, :=, setDT, setDF, copy html{}

Examples

DF = data.frame(a=1:2,b=3:4)       # base data.frame to demo copies, as of R 2.15.1
    try(tracemem(DF))                  # try() for R sessions opted out of memory profiling
    colnames(DF)[1] <- "A"             # 4 copies of entire object
    names(DF)[1] <- "A"                # 3 copies of entire object
    names(DF) <- c("A", "b")           # 1 copy of entire object
    `names<-`(DF,c("A","b"))           # 1 copy of entire object
    
    # What if DF is large, say 10GB in RAM. Copy 10GB, even once, just to change a column name?

    DT = data.table(a=1:2,b=3:4,c=5:6)
    try(tracemem(DT))
    setnames(DT,"b","B")               # by name; no match() needed
    setnames(DT,3,"C")                 # by position
    setnames(DT,2:3,c("D","E"))        # multiple
    setnames(DT,c("a","E"),c("A","F")) # multiple by name
    setnames(DT,c("X","Y","Z"))        # replace all
    
    # And, no copy of DT was made by 'setnames()' at all.
    
    # set attributes - ex: names to a list.
    set.seed(1L)
    ll <- lapply(1:4, function(x) sample(10))
    try(tracemem(DT))
    setattr(ll, 'names', letters[1:4])
    
    # once again, no copy of 'll' was made by 'setattr()' at all.

Run the code above in your browser using DataCamp Workspace