EVOLUTION-MANAGER
Edit File: special-symbols.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: Special symbols</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 special-symbols {data.table}"><tr><td>special-symbols {data.table}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2> Special symbols </h2> <h3>Description</h3> <p><code>.SD</code>, <code>.BY</code>, <code>.N</code>, <code>.I</code>, <code>.GRP</code>, and <code>.NGRP</code> are <em>read-only</em> symbols for use in <code>j</code>. <code>.N</code> can be used in <code>i</code> as well. See the vignettes and examples here and in <code><a href="data.table.html">data.table</a></code>. <code>.EACHI</code> is a symbol passed to <code>by</code>; i.e. <code>by=.EACHI</code>. </p> <h3>Details</h3> <p>The bindings of these variables are locked and attempting to assign to them will generate an error. If you wish to manipulate <code>.SD</code> before returning it, take a <code>copy(.SD)</code> first (see FAQ 4.5). Using <code>:=</code> in the <code>j</code> of <code>.SD</code> is reserved for future use as a (tortuously) flexible way to update <code>DT</code> by reference by group (even when groups are not contiguous in an ad hoc by). </p> <p>These symbols used in <code>j</code> are defined as follows. </p> <ul> <li><p><code>.SD</code> is a <code>data.table</code> containing the <b>S</b>ubset of <code>x</code>'s <b>D</b>ata for each group, excluding any columns used in <code>by</code> (or <code>keyby</code>). </p> </li> <li><p><code>.BY</code> is a <code>list</code> containing a length 1 vector for each item in <code>by</code>. This can be useful when <code>by</code> is not known in advance. The <code>by</code> variables are also available to <code>j</code> directly by name; useful for example for titles of graphs if <code>j</code> is a plot command, or to branch with <code>if()</code> depending on the value of a group variable. </p> </li> <li><p><code>.N</code> is an integer, length 1, containing the number of rows in the group. This may be useful when the column names are not known in advance and for convenience generally. When grouping by <code>i</code>, <code>.N</code> is the number of rows in <code>x</code> matched to, for each row of <code>i</code>, regardless of whether <code>nomatch</code> is <code>NA</code> or <code>NULL</code>. It is renamed to <code>N</code> (no dot) in the result (otherwise a column called <code>".N"</code> could conflict with the <code>.N</code> variable, see FAQ 4.6 for more details and example), unless it is explicitly named; e.g., <code>DT[,list(total=.N),by=a]</code>. </p> </li> <li><p><code>.I</code> is an integer vector equal to <code>seq_len(nrow(x))</code>. While grouping, it holds for each item in the group, its row location in <code>x</code>. This is useful to subset in <code>j</code>; e.g. <code>DT[, .I[which.max(somecol)], by=grp]</code>. </p> </li> <li><p><code>.GRP</code> is an integer, length 1, containing a simple group counter. 1 for the 1st group, 2 for the 2nd, etc. </p> </li> <li><p><code>.NGRP</code> is an integer, length 1, containing the number of groups. </p> </li></ul> <p><code>.EACHI</code> is defined as <code>NULL</code> but its value is not used. Its usage is <code>by=.EACHI</code> (or <code>keyby=.EACHI</code>) which invokes grouping-by-each-row-of-i; see <code><a href="data.table.html">data.table</a></code>'s <code>by</code> argument for more details. </p> <h3>See Also</h3> <p><code><a href="data.table.html">data.table</a></code>, <code><a href="assign.html">:=</a></code>, <code><a href="assign.html">set</a></code>, <code><a href="datatable-optimize.html">datatable-optimize</a></code> </p> <h3>Examples</h3> <pre> DT = data.table(x=rep(c("b","a","c"),each=3), v=c(1,1,1,2,2,1,1,2,2), y=c(1,3,6), a=1:9, b=9:1) DT X = data.table(x=c("c","b"), v=8:7, foo=c(4,2)) X DT[.N] # last row, only special symbol allowed in 'i' DT[, .N] # total number of rows in DT DT[, .N, by=x] # number of rows in each group DT[, .SD, .SDcols=x:y] # select columns 'x' and 'y' DT[, .SD[1]] # first row of all columns DT[, .SD[1], by=x] # first row of 'y' and 'v' for each group in 'x' DT[, c(.N, lapply(.SD, sum)), by=x] # get rows *and* sum columns 'v' and 'y' by group DT[, .I[1], by=x] # row number in DT corresponding to each group DT[, .N, by=rleid(v)] # get count of consecutive runs of 'v' DT[, c(.(y=max(y)), lapply(.SD, min)), by=rleid(v), .SDcols=v:b] # compute 'j' for each consecutive runs of 'v' DT[, grp := .GRP, by=x] # add a group counter DT[, grp_pct := .GRP/.NGRP, by=x] # add a group "progress" counter X[, DT[.BY, y, on="x"], by=x] # join within each group </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>