How is the R data.table `.BY` operator used?

Question

screw for data .table defines a special character .BYas

.BY is a list containing a length vector for each element. This can be useful when it is not known in advance. Variables are also available for j directly by name; useful, for example, for chart headers, if j is a chart command, or for branching with if () depending on the value of a group variable.

This description confuses me. How and when will I use .BY? Even for chart titles? Why was it added as a special character?

example("data.table")has no examples, and I did not find them on the wiki.table page. I don't know how to look for stack overflow for data.table and .BY. I keep getting hits that use the operator byindata.table

Answer 1

Here is a simple example showing how it .BYcan be passed to other arguments, such as the title of the plot. Using the embedded data mtcars:

mtcars <- as.data.table(mtcars)
layout(1:3)
mtcars[, plot(mpg, main=paste("Cylinders:", as.character(.BY))), by=cyl]