EVOLUTION-MANAGER
Edit File: melt.data.table.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: Fast melt for data.table</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 melt.data.table {data.table}"><tr><td>melt.data.table {data.table}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Fast melt for data.table</h2> <h3>Description</h3> <p><code>melt</code> is <code>data.table</code>'s wide-to-long reshaping tool. We provide an S3 method for melting <code>data.table</code>s. It is written in C for speed and memory efficiency. Since <code>v1.9.6</code>, <code>melt.data.table</code> allows melting into multiple columns simultaneously. </p> <h3>Usage</h3> <pre> ## fast melt a data.table ## S3 method for class 'data.table' melt(data, id.vars, measure.vars, variable.name = "variable", value.name = "value", ..., na.rm = FALSE, variable.factor = TRUE, value.factor = FALSE, verbose = getOption("datatable.verbose")) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>data</code></td> <td> <p> A <code>data.table</code> object to melt.</p> </td></tr> <tr valign="top"><td><code>id.vars</code></td> <td> <p>vector of id variables. Can be integer (corresponding id column numbers) or character (id column names) vector. If missing, all non-measure columns will be assigned to it. If integer, must be positive; see Details. </p> </td></tr> <tr valign="top"><td><code>measure.vars</code></td> <td> <p>Measure variables for <code>melt</code>ing. Can be missing, vector, list, or pattern-based. </p> <ul> <li><p> When missing, <code>measure.vars</code> will become all columns outside <code>id.vars</code>. </p> </li> <li><p> Vector can be <code>integer</code> (implying column numbers) or <code>character</code> (column names). </p> </li> <li> <p><code>list</code> is a generalization of the vector version – each element of the list (which should be <code>integer</code> or <code>character</code> as above) will become a <code>melt</code>ed column. </p> </li> <li><p> Pattern-based column matching can be achieved with the regular expression-based <code><a href="patterns.html">patterns</a></code> syntax; multiple patterns will produce multiple columns. </p> </li></ul> <p>For convenience/clarity in the case of multiple <code>melt</code>ed columns, resulting column names can be supplied as names to the elements <code>measure.vars</code> (in the <code>list</code> and <code>patterns</code> usages). See also <code>Examples</code>. </p> </td></tr> <tr valign="top"><td><code>variable.name</code></td> <td> <p>name for the measured variable names column. The default name is <code>'variable'</code>.</p> </td></tr> <tr valign="top"><td><code>value.name</code></td> <td> <p>name for the molten data values column(s). The default name is <code>'value'</code>. Multiple names can be provided here for the case when <code>measure.vars</code> is a <code>list</code>, though note well that the names provided in <code>measure.vars</code> take precedence. </p> </td></tr> <tr valign="top"><td><code>na.rm</code></td> <td> <p>If <code>TRUE</code>, <code>NA</code> values will be removed from the molten data.</p> </td></tr> <tr valign="top"><td><code>variable.factor</code></td> <td> <p>If <code>TRUE</code>, the <code>variable</code> column will be converted to <code>factor</code>, else it will be a <code>character</code> column.</p> </td></tr> <tr valign="top"><td><code>value.factor</code></td> <td> <p>If <code>TRUE</code>, the <code>value</code> column will be converted to <code>factor</code>, else the molten value type is left unchanged.</p> </td></tr> <tr valign="top"><td><code>verbose</code></td> <td> <p><code>TRUE</code> turns on status and information messages to the console. Turn this on by default using <code>options(datatable.verbose=TRUE)</code>. The quantity and types of verbosity may be expanded in future.</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>any other arguments to be passed to/from other methods.</p> </td></tr> </table> <h3>Details</h3> <p>If <code>id.vars</code> and <code>measure.vars</code> are both missing, all non-<code>numeric/integer/logical</code> columns are assigned as id variables and the rest as measure variables. If only one of <code>id.vars</code> or <code>measure.vars</code> is supplied, the rest of the columns will be assigned to the other. Both <code>id.vars</code> and <code>measure.vars</code> can have the same column more than once and the same column can be both as id and measure variables. </p> <p><code>melt.data.table</code> also accepts <code>list</code> columns for both id and measure variables. </p> <p>When all <code>measure.vars</code> are not of the same type, they'll be coerced according to the hierarchy <code>list</code> > <code>character</code> > <code>numeric > integer > logical</code>. For example, if any of the measure variables is a <code>list</code>, then entire value column will be coerced to a list. Note that, if the type of <code>value</code> column is a list, <code>na.rm = TRUE</code> will have no effect. </p> <p>From version <code>1.9.6</code>, <code>melt</code> gains a feature with <code>measure.vars</code> accepting a list of <code>character</code> or <code>integer</code> vectors as well to melt into multiple columns in a single function call efficiently. The function <code><a href="patterns.html">patterns</a></code> can be used to provide regular expression patterns. When used along with <code>melt</code>, if <code>cols</code> argument is not provided, the patterns will be matched against <code>names(data)</code>, for convenience. </p> <p>Attributes are preserved if all <code>value</code> columns are of the same type. By default, if any of the columns to be melted are of type <code>factor</code>, it'll be coerced to <code>character</code> type. To get a <code>factor</code> column, set <code>value.factor = TRUE</code>. <code>melt.data.table</code> also preserves <code>ordered</code> factors. </p> <p>Historical note: <code>melt.data.table</code> was originally designed as an enhancement to <code>reshape2::melt</code> in terms of computing and memory efficiency. <code>reshape2</code> has since been deprecated, and <code>melt</code> has had a generic defined within <code>data.table</code> since <code>v1.9.6</code> in 2015, at which point the dependency between the packages became more etymological than programmatic. We thank the <code>reshape2</code> authors for the inspiration. </p> <h3>Value</h3> <p>An unkeyed <code>data.table</code> containing the molten data. </p> <h3>See Also</h3> <p><code><a href="dcast.data.table.html">dcast</a></code>, <a href="https://cran.r-project.org/package=reshape">https://cran.r-project.org/package=reshape</a> </p> <h3>Examples</h3> <pre> set.seed(45) require(data.table) DT <- data.table( i_1 = c(1:5, NA), i_2 = c(NA,6,7,8,9,10), f_1 = factor(sample(c(letters[1:3], NA), 6, TRUE)), f_2 = factor(c("z", "a", "x", "c", "x", "x"), ordered=TRUE), c_1 = sample(c(letters[1:3], NA), 6, TRUE), d_1 = as.Date(c(1:3,NA,4:5), origin="2013-09-01"), d_2 = as.Date(6:1, origin="2012-01-01")) # add a couple of list cols DT[, l_1 := DT[, list(c=list(rep(i_1, sample(5,1)))), by = i_1]$c] DT[, l_2 := DT[, list(c=list(rep(c_1, sample(5,1)))), by = i_1]$c] # id, measure as character/integer/numeric vectors melt(DT, id=1:2, measure="f_1") melt(DT, id=c("i_1", "i_2"), measure=3) # same as above melt(DT, id=1:2, measure=3L, value.factor=TRUE) # same, but 'value' is factor melt(DT, id=1:2, measure=3:4, value.factor=TRUE) # 'value' is *ordered* factor # preserves attribute when types are identical, ex: Date melt(DT, id=3:4, measure=c("d_1", "d_2")) melt(DT, id=3:4, measure=c("i_1", "d_1")) # attribute not preserved # on list melt(DT, id=1, measure=c("l_1", "l_2")) # value is a list melt(DT, id=1, measure=c("c_1", "l_1")) # c1 coerced to list # on character melt(DT, id=1, measure=c("c_1", "f_1")) # value is char melt(DT, id=1, measure=c("c_1", "i_2")) # i2 coerced to char # on na.rm=TRUE. NAs are removed efficiently, from within C melt(DT, id=1, measure=c("c_1", "i_2"), na.rm=TRUE) # remove NA # measure.vars can be also a list # melt "f_1,f_2" and "d_1,d_2" simultaneously, retain 'factor' attribute # convenient way using internal function patterns() melt(DT, id=1:2, measure=patterns("^f_", "^d_"), value.factor=TRUE) # same as above, but provide list of columns directly by column names or indices melt(DT, id=1:2, measure=list(3:4, c("d_1", "d_2")), value.factor=TRUE) # same as above, but provide names directly: melt(DT, id=1:2, measure=patterns(f="^f_", d="^d_"), value.factor=TRUE) # na.rm=TRUE removes rows with NAs in any 'value' columns melt(DT, id=1:2, measure=patterns("f_", "d_"), value.factor=TRUE, na.rm=TRUE) # return 'NA' for missing columns, 'na.rm=TRUE' ignored due to list column melt(DT, id=1:2, measure=patterns("l_", "c_"), na.rm=TRUE) </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>