special-symbols {data.table} R Documentation

## Special symbols

### Description

`.SD`, `.BY`, `.N`, `.I`, `.GRP`, and `.NGRP` 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`.

### Details

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 Subset of `x`'s Data 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.

• `.NGRP` is an integer, length 1, containing the number of groups.

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

### Examples

```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]                           # first row of all columns
DT[, .SD, 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, 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
```

[Package data.table version 1.13.1 Index]
{"ft_lang_label":"__label__en","ft_lang_prob":0.7619685,"math_prob":0.8773248,"size":3149,"snap":"2020-45-2020-50","text_gpt3_token_len":988,"char_repetition_ratio":0.113195546,"word_repetition_ratio":0.03125,"special_character_ratio":0.31660846,"punctuation_ratio":0.22058824,"nsfw_num_words":0,"has_unicode_error":false,"math_prob_llama3":0.9950703,"pos_list":[0],"im_url_duplicate_count":[null],"WARC_HEADER":"{\"WARC-Type\":\"response\",\"WARC-Date\":\"2020-10-27T20:37:15Z\",\"WARC-Record-ID\":\"<urn:uuid:f8dadfa5-f7ea-40be-b829-e0be9f17186e>\",\"Content-Length\":\"5451\",\"Content-Type\":\"application/http; msgtype=response\",\"WARC-Warcinfo-ID\":\"<urn:uuid:4ef09988-6d56-4335-8107-f5f9b7faa060>\",\"WARC-Concurrent-To\":\"<urn:uuid:1380d0e1-2bab-4e41-95dc-0b0466208ab1>\",\"WARC-IP-Address\":\"35.185.44.232\",\"WARC-Target-URI\":\"http://jangorecki.gitlab.io/data.table/library/data.table/html/special-symbols.html\",\"WARC-Payload-Digest\":\"sha1:7BUDSWKNEQNRHKXVX2672243ZXQ6COKK\",\"WARC-Block-Digest\":\"sha1:G526LRY2LJ4PCWKWZZVZFA6UQXSAK6YD\",\"WARC-Identified-Payload-Type\":\"application/xhtml+xml\",\"warc_filename\":\"/cc_download/warc_2020/CC-MAIN-2020-45/CC-MAIN-2020-45_segments_1603107894759.37_warc_CC-MAIN-20201027195832-20201027225832-00198.warc.gz\"}"}