`special-symbols.Rd`

`.SD`

, `.BY`

, `.N`

, `.I`

, and `.GRP`

are *read-only* symbols for use in `j`

. `.N`

can be used in `i`

as well. See the vignettes and examples here and in `data.table`

.
`.EACHI`

is a symbol passed to `by`

; i.e. `by=.EACHI`

.

The bindings of these variables are locked and attempting to assign to them will generate an error. If you wish to manipulate `.SD`

before returning it, take a `copy(.SD)`

first (see FAQ 4.5). Using `:=`

in the `j`

of `.SD`

is reserved for future use as a (tortuously) flexible way to update `DT`

by reference by group (even when groups are not contiguous in an ad hoc by).

These symbols used in `j`

are defined as follows.

`.SD`

is a`data.table`

containing the**S**ubset of`x`

's**D**ata for each group, excluding any columns used in`by`

(or`keyby`

).`.BY`

is a`list`

containing a length 1 vector for each item in`by`

. This can be useful when`by`

is not known in advance. The`by`

variables are also available to`j`

directly by name; useful for example for titles of graphs if`j`

is a plot command, or to branch with`if()`

depending on the value of a group variable.`.N`

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`i`

,`.N`

is the number of rows in`x`

matched to, for each row of`i`

, regardless of whether`nomatch`

is`NA`

or`NULL`

. It is renamed to`N`

(no dot) in the result (otherwise a column called`".N"`

could conflict with the`.N`

variable, see FAQ 4.6 for more details and example), unless it is explicitly named; e.g.,`DT[,list(total=.N),by=a]`

.`.I`

is an integer vector equal to`seq_len(nrow(x))`

. While grouping, it holds for each item in the group, its row location in`x`

. This is useful to subset in`j`

; e.g.`DT[, .I[which.max(somecol)], by=grp]`

.`.GRP`

is an integer, length 1, containing a simple group counter. 1 for the 1st group, 2 for the 2nd, etc.

`.EACHI`

is defined as `NULL`

but its value is not used. Its usage is `by=.EACHI`

(or `keyby=.EACHI`

) which invokes grouping-by-each-row-of-i; see `data.table`

's `by`

argument for more details.

`data.table`

, `:=`

, `set`

, `datatable-optimize`

#> x v y a b #> 1: b 1 1 1 9 #> 2: b 1 3 2 8 #> 3: b 1 6 3 7 #> 4: a 2 1 4 6 #> 5: a 2 3 5 5 #> 6: a 1 6 6 4 #> 7: c 1 1 7 3 #> 8: c 2 3 8 2 #> 9: c 2 6 9 1#> x v foo #> 1: c 8 4 #> 2: b 7 2DT[.N] # last row, only special symbol allowed in 'i'#> x v y a b #> 1: c 2 6 9 1DT[, .N] # total number of rows in DT#> [1] 9DT[, .N, by=x] # number of rows in each group#> x N #> 1: b 3 #> 2: a 3 #> 3: c 3DT[, .SD, .SDcols=x:y] # select columns 'x' and 'y'#> x v y #> 1: b 1 1 #> 2: b 1 3 #> 3: b 1 6 #> 4: a 2 1 #> 5: a 2 3 #> 6: a 1 6 #> 7: c 1 1 #> 8: c 2 3 #> 9: c 2 6DT[, .SD[1]] # first row of all columns#> x v y a b #> 1: b 1 1 1 9DT[, .SD[1], by=x] # first row of 'y' and 'v' for each group in 'x'#> x v y a b #> 1: b 1 1 1 9 #> 2: a 2 1 4 6 #> 3: c 1 1 7 3#> x N v y a b #> 1: b 3 3 10 6 24 #> 2: a 3 5 10 15 15 #> 3: c 3 5 10 24 6DT[, .I[1], by=x] # row number in DT corresponding to each group#> x V1 #> 1: b 1 #> 2: a 4 #> 3: c 7DT[, .N, by=rleid(v)] # get count of consecutive runs of 'v'#> rleid N #> 1: 1 3 #> 2: 2 2 #> 3: 3 2 #> 4: 4 2DT[, c(.(y=max(y)), lapply(.SD, min)), by=rleid(v), .SDcols=v:b] # compute 'j' for each consecutive runs of 'v'#> rleid y v y a b #> 1: 1 6 1 1 1 7 #> 2: 2 3 2 1 4 5 #> 3: 3 6 1 1 6 3 #> 4: 4 6 2 3 8 1DT[, grp := .GRP, by=x] # add a group counter#> x v y a b grp #> 1: b 1 1 1 9 1 #> 2: b 1 3 2 8 1 #> 3: b 1 6 3 7 1 #> 4: a 2 1 4 6 2 #> 5: a 2 3 5 5 2 #> 6: a 1 6 6 4 2 #> 7: c 1 1 7 3 3 #> 8: c 2 3 8 2 3 #> 9: c 2 6 9 1 3X[, DT[.BY, y, on="x"], by=x] # join within each group#> x V1 #> 1: c 1 #> 2: c 3 #> 3: c 6 #> 4: b 1 #> 5: b 3 #> 6: b 6