EVOLUTION-MANAGER
Edit File: setattr.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Set attributes of objects by reference</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for setattr {data.table}"><tr><td>setattr {data.table}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2> Set attributes of objects by reference </h2> <h3>Description</h3> <p>In <code>data.table</code>, all <code>set*</code> functions change their input <em>by reference</em>. That is, no copy is made at all, other than temporary working memory which is as large as one column. The only other <code>data.table</code> operator that modifies input by reference is <code><a href="assign.html">:=</a></code>. Check out the <code>See Also</code> section below for other <code>set*</code> function that <code>data.table</code> provides. </p> <h3>Usage</h3> <pre> setattr(x,name,value) setnames(x,old,new,skip_absent=FALSE) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>x</code></td> <td> <p><code>setnames</code> accepts <code>data.frame</code> and <code>data.table</code>. <code>setattr</code> accepts any input; e.g, list, columns of a <code>data.frame</code> or <code>data.table</code>. </p> </td></tr> <tr valign="top"><td><code>name</code></td> <td> <p> The character attribute name. </p> </td></tr> <tr valign="top"><td><code>value</code></td> <td> <p> The value to assign to the attribute or <code>NULL</code> removes the attribute, if present. </p> </td></tr> <tr valign="top"><td><code>old</code></td> <td> <p> When <code>new</code> is provided, character names or numeric positions of column names to change. When <code>new</code> is not provided, a function or the new column names (i.e., it's implicitly treated as <code>new</code>; excluding <code>old</code> and explicitly naming <code>new</code> is equivalent). If a function, it will be called with the current column names and is supposed to return the new column names. The new column names must be the same length as the number of columns. See examples. </p> </td></tr> <tr valign="top"><td><code>new</code></td> <td> <p> Optional. It can be a function or the new column names. If a function, it will be called with <code>old</code> and expected to return the new column names. The new column names must be the same length as columns provided to <code>old</code> argument. </p> </td></tr> <tr valign="top"><td><code>skip_absent</code></td> <td> <p> Skip items in <code>old</code> that are missing (i.e. absent) in 'names(x)'. Default <code>FALSE</code> halts with error if any are missing. </p> </td></tr> </table> <h3>Details</h3> <p><code>setnames</code> operates on <code>data.table</code> and <code>data.frame</code> not other types like <code>list</code> and <code>vector</code>. It can be used to change names <em>by name</em> with built-in checks and warnings (e.g., if any old names are missing or appear more than once). </p> <p><code>setattr</code> is a more general function that allows setting of any attribute to an object <em>by reference</em>. </p> <p>A very welcome change in R 3.1+ was that 'names<-' and 'colnames<-' no longer copy the <em>entire</em> object as they used to (up to 4 times), see examples below. They now take a shallow copy. The ‘set*' functions in data.table are still useful because they don’t even take a shallow copy. This allows changing names and attributes of a (usually very large) <code>data.table</code> in the global environment <em>from within functions</em>. Like a database. </p> <h3>Value</h3> <p>The input is modified by reference, and returned (invisibly) so it can be used in compound statements; e.g., <code>setnames(DT,"V1", "Y")[, .N, by=Y]</code>. If you require a copy, take a copy first (using <code>DT2=copy(DT)</code>). See <code>?copy</code>. </p> <p>Note that <code>setattr</code> is also in package <code>bit</code>. Both packages merely expose R's internal <code>setAttrib</code> function at C level but differ in return value. <code>bit::setattr</code> returns <code>NULL</code> (invisibly) to remind you the function is used for its side effect. <code>data.table::setattr</code> returns the changed object (invisibly) for use in compound statements. </p> <h3>See Also</h3> <p><code><a href="data.table.html">data.table</a></code>, <code><a href="setkey.html">setkey</a></code>, <code><a href="setorder.html">setorder</a></code>, <code><a href="setcolorder.html">setcolorder</a></code>, <code><a href="assign.html">set</a></code>, <code><a href="assign.html">:=</a></code>, <code><a href="setDT.html">setDT</a></code>, <code><a href="setDF.html">setDF</a></code>, <code><a href="copy.html">copy</a></code> </p> <h3>Examples</h3> <pre> DT <- data.table(a = 1, b = 2, d = 3) old <- c("a", "b", "c", "d") new <- c("A", "B", "C", "D") setnames(DT, old, new, skip_absent = TRUE) # skips old[3] because "c" is not a column name of DT DF = data.frame(a=1:2,b=3:4) # base data.frame to demo copies and syntax if (capabilities()["profmem"]) # usually memory profiling is available but just in case tracemem(DF) colnames(DF)[1] <- "A" # 4 shallow copies (R >= 3.1, was 4 deep copies before) names(DF)[1] <- "A" # 3 shallow copies names(DF) <- c("A", "b") # 1 shallow copy `names<-`(DF,c("A","b")) # 1 shallow copy DT = data.table(a=1:2,b=3:4,c=5:6) # compare to data.table if (capabilities()["profmem"]) tracemem(DT) # by reference, no deep or shallow copies setnames(DT,"b","B") # by name, no match() needed (warning if "b" is missing) setnames(DT,3,"C") # by position with warning if 3 > ncol(DT) setnames(DT,2:3,c("D","E")) # multiple setnames(DT,c("a","E"),c("A","F")) # multiple by name (warning if either "a" or "E" is missing) setnames(DT,c("X","Y","Z")) # replace all (length of names must be == ncol(DT)) setnames(DT,tolower) # replace all names with their lower case setnames(DT,2:3,toupper) # replace the 2nd and 3rd names with their upper case DT <- data.table(x = 1:3, y = 4:6, z = 7:9) setnames(DT, -2, c("a", "b")) # NEW FR #1443, allows -ve indices in 'old' argument DT = data.table(a=1:3, b=4:6) f = function(...) { # ... setattr(DT,"myFlag",TRUE) # by reference # ... localDT = copy(DT) setattr(localDT,"myFlag2",TRUE) # ... invisible() } f() attr(DT,"myFlag") # TRUE attr(DT,"myFlag2") # NULL </pre> <hr /><div style="text-align: center;">[Package <em>data.table</em> version 1.14.4 <a href="00Index.html">Index</a>]</div> </body></html>