EVOLUTION-MANAGER
Edit File: datatable-optimize.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: Optimisations in 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 datatable.optimize {data.table}"><tr><td>datatable.optimize {data.table}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Optimisations in data.table</h2> <h3>Description</h3> <p><code>data.table</code> internally optimises certain expressions in order to improve performance. This section briefly summarises those optimisations. </p> <p>Note that there's no additional input needed from the user to take advantage of these optimisations. They happen automatically. </p> <p>Run the code under the <em>example</em> section to get a feel for the performance benefits from these optimisations. </p> <h3>Details</h3> <p><code>data.table</code> reads the global option <code>datatable.optimize</code> to figure out what level of optimisation is required. The default value <code>Inf</code> activates <em>all</em> available optimisations. </p> <p>At optimisation level <code>>= 1</code>, i.e., <code>getOption("datatable.optimize")</code> >= 1, these are the optimisations: </p> <ul> <li><p> The base function <code>order</code> is internally replaced with <code>data.table</code>'s <em>fast ordering</em>. That is, <code>DT[order(...)]</code> gets internally optimised to <code>DT[forder(...)]</code>. </p> </li> <li><p> The expression <code>DT[, lapply(.SD, fun), by=.]</code> gets optimised to <code>DT[, list(fun(a), fun(b), ...), by=.]</code> where <code>a,b, ...</code> are columns in <code>.SD</code>. This improves performance tremendously. </p> </li> <li><p> Similarly, the expression <code>DT[, c(.N, lapply(.SD, fun)), by=.]</code> gets optimised to <code>DT[, list(.N, fun(a), fun(b), ...)]</code>. <code>.N</code> is just for example here. </p> </li> <li> <p><code>base::mean</code> function is internally optimised to use <code>data.table</code>'s <code>fastmean</code> function. <code>mean()</code> from <code>base</code> is an S3 generic and gets slow with many groups. </p> </li></ul> <p>At optimisation level <code>>= 2</code>, i.e., <code>getOption("datatable.optimize")</code> >= 2, additional optimisations are implemented on top of the optimisations already shown above. </p> <ul> <li><p> Expressions in <code>j</code> which contain only the functions <code>min, max, mean, median, var, sd, sum, prod, first, last, head, tail</code> (for example, <code>DT[, list(mean(x), median(x), min(y), max(y)), by=z]</code>), they are very effectively optimised using what we call <em>GForce</em>. These functions are automatically replaced with a corresponding GForce version with pattern <code>g*</code>, e.g., <code>prod</code> becomes <code>gprod</code>. </p> <p>Normally, once the rows belonging to each group are identified, the values corresponding to the group are gathered and the <code>j</code>-expression is evaluated. This can be improved by computing the result directly without having to gather the values or evaluating the expression for each group (which can get costly with large number of groups) by implementing it specifically for a particular function. As a result, it is extremely fast. </p> </li> <li><p> In addition to all the functions above, '.N' is also optimised to use GForce, when used separately or when combined with the functions mentioned above. Note further that GForce-optimized functions must be used separately, i.e., code like <code>DT[ , max(x) - min(x), by=z]</code> will <em>not</em> currently be optimized to use <code>gmax, gmin</code>. </p> </li> <li><p> Expressions of the form <code>DT[i, j, by]</code> are also optimised when <code>i</code> is a <em>subset</em> operation and <code>j</code> is any/all of the functions discussed above. </p> </li></ul> <p>At optimisation level <code>>= 3</code>, i.e., <code>getOption("datatable.optimize")</code> >= 3, additional optimisations for subsets in i are implemented on top of the optimisations already shown above. Subsetting operations are - if possible - translated into joins to make use of blazing fast binary search using indices and keys. The following queries are optimized: </p> <ul> <li><p> Supported operators: <code>==</code>, <code>%in%</code>. Non-equi operators(>, <, etc.) are not supported yet because non-equi joins are slower than vector based subsets. </p> </li> <li><p> Queries on multiple columns are supported, if the connector is '<code>&</code>', e.g. <code>DT[x == 2 & y == 3]</code> is supported, but <code>DT[x == 2 | y == 3]</code> is not. </p> </li> <li><p> Optimization will currently be turned off when doing subset when cross product of elements provided to filter on exceeds > 1e4. This most likely happens if multiple <code>%in%</code>, or <code>%chin%</code> queries are combined, e.g. <code>DT[x %in% 1:100 & y %in% 1:200]</code> will not be optimized since <code>100 * 200 = 2e4 > 1e4</code>. </p> </li> <li><p> Queries with multiple criteria on one column are <em>not</em> supported, e.g. <code>DT[x == 2 & x %in% c(2,5)]</code> is not supported. </p> </li> <li><p> Queries with non-missing j are supported, e.g. <code>DT[x == 3 & y == 5, .(new = x-y)]</code> or <code>DT[x == 3 & y == 5, new := x-y]</code> are supported. Also extends to queries using <code>with = FALSE</code>. </p> </li> <li><p> "notjoin" queries, i.e. queries that start with <code>!</code>, are only supported if there are no <code>&</code> connections, e.g. <code>DT[!x==3]</code> is supported, but <code>DT[!x==3 & y == 4]</code> is not. </p> </li></ul> <p>If in doubt, whether your query benefits from optimization, call it with the <code>verbose = TRUE</code> argument. You should see "Optimized subsetting...". </p> <p><b>Auto indexing:</b> In case a query is optimized, but no appropriate key or index is found, <code>data.table</code> automatically creates an <em>index</em> on the first run. Any successive subsets on the same column then reuse this index to <em>binary search</em> (instead of <em>vector scan</em>) and is therefore fast. Auto indexing can be switched off with the global option <code>options(datatable.auto.index = FALSE)</code>. To switch off using existing indices set global option <code>options(datatable.use.index = FALSE)</code>. </p> <h3>See Also</h3> <p><code><a href="setNumericRounding.html">setNumericRounding</a></code>, <code><a href="setNumericRounding.html">getNumericRounding</a></code> </p> <h3>Examples</h3> <pre> ## Not run: # Generate a big data.table with a relatively many columns set.seed(1L) DT = lapply(1:20, function(x) sample(c(-100:100), 5e6L, TRUE)) setDT(DT)[, id := sample(1e5, 5e6, TRUE)] print(object.size(DT), units="Mb") # 400MB, not huge, but will do # 'order' optimisation options(datatable.optimize = 1L) # optimisation 'on' system.time(ans1 <- DT[order(id)]) options(datatable.optimize = 0L) # optimisation 'off' system.time(ans2 <- DT[order(id)]) identical(ans1, ans2) # optimisation of 'lapply(.SD, fun)' options(datatable.optimize = 1L) # optimisation 'on' system.time(ans1 <- DT[, lapply(.SD, min), by=id]) options(datatable.optimize = 0L) # optimisation 'off' system.time(ans2 <- DT[, lapply(.SD, min), by=id]) identical(ans1, ans2) # optimisation of 'mean' options(datatable.optimize = 1L) # optimisation 'on' system.time(ans1 <- DT[, lapply(.SD, mean), by=id]) system.time(ans2 <- DT[, lapply(.SD, base::mean), by=id]) identical(ans1, ans2) # optimisation of 'c(.N, lapply(.SD, ))' options(datatable.optimize = 1L) # optimisation 'on' system.time(ans1 <- DT[, c(.N, lapply(.SD, min)), by=id]) options(datatable.optimize = 0L) # optimisation 'off' system.time(ans2 <- DT[, c(N=.N, lapply(.SD, min)), by=id]) identical(ans1, ans2) # GForce options(datatable.optimize = 2L) # optimisation 'on' system.time(ans1 <- DT[, lapply(.SD, median), by=id]) system.time(ans2 <- DT[, lapply(.SD, function(x) as.numeric(stats::median(x))), by=id]) identical(ans1, ans2) # optimized subsets options(datatable.optimize = 2L) system.time(ans1 <- DT[id == 100L]) # vector scan system.time(ans2 <- DT[id == 100L]) # vector scan system.time(DT[id %in% 100:500]) # vector scan options(datatable.optimize = 3L) system.time(ans1 <- DT[id == 100L]) # index + binary search subset system.time(ans2 <- DT[id == 100L]) # only binary search subset system.time(DT[id %in% 100:500]) # only binary search subset again ## End(Not run)</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>