Summarize mark results.

Usage

# S3 method for class 'bench_mark'
summary(object, filter_gc = TRUE, relative = FALSE, time_unit = NULL, ...)

Arguments

object: bench_mark object to summarize.
filter_gc: If TRUE remove iterations that contained at least one garbage collection before summarizing. If TRUE but an expression had a garbage collection in every iteration, filtering is disabled, with a warning.
relative: If TRUE all summaries are computed relative to the minimum execution time rather than absolute time.
time_unit: If NULL the times are reported in a human readable fashion depending on each value. If one of 'ns', 'us', 'ms', 's', 'm', 'h', 'd', 'w' the time units are instead expressed as nanoseconds, microseconds, milliseconds, seconds, hours, minutes, days or weeks respectively.
...: Additional arguments ignored.

Value

A tibble with the additional summary columns. The following summary columns are computed

expression - bench_expr The deparsed expression that was evaluated (or its name if one was provided).
min - bench_time The minimum execution time.
median - bench_time The sample median of execution time.
itr/sec - double The estimated number of executions performed per second.
mem_alloc - bench_bytes Total amount of memory allocated by R while running the expression. Memory allocated outside the R heap, e.g. by malloc() or new directly is not tracked, take care to avoid misinterpreting the results if running code that may do this.
gc/sec - double The number of garbage collections per second.
n_itr - integer Total number of iterations after filtering garbage collections (if filter_gc == TRUE).
n_gc - double Total number of garbage collections performed over all iterations. This is a psudo-measure of the pressure on the garbage collector, if it varies greatly between to alternatives generally the one with fewer collections will cause fewer allocation in real usage.
total_time - bench_time The total time to perform the benchmarks.
result - list A list column of the object(s) returned by the evaluated expression(s).
memory - list A list column with results from Rprofmem().
time - list A list column of bench_time vectors for each evaluated expression.
gc - list A list column with tibbles containing the level of garbage collection (0-2, columns) for each iteration (rows).

Details

If filter_gc == TRUE (the default) runs that contain a garbage collection will be removed before summarizing. This is most useful for fast expressions when the majority of runs do not contain a gc. Call summary(filter_gc = FALSE) if you would like to compute summaries with these times, such as expressions with lots of allocations when all or most runs contain a gc.

Examples

dat <- data.frame(x = runif(10000, 1, 1000), y=runif(10000, 1, 1000))

# `bench::mark()` implicitly calls summary() automatically
results <- bench::mark(
  dat[dat$x > 500, ],
  dat[which(dat$x > 500), ],
  subset(dat, x > 500))

# However you can also do so explicitly to filter gc differently.
summary(results, filter_gc = FALSE)
#> # A tibble: 3 × 13
#>   expression           min median `itr/sec` mem_alloc `gc/sec` n_itr  n_gc
#>   <bch:expr>         <bch> <bch:>     <dbl> <bch:byt>    <dbl> <int> <dbl>
#> 1 dat[dat$x > 500, ] 140µs  155µs     3908.     375KB     32.0  1954    16
#> 2 dat[which(dat$x >… 134µs  139µs     5020.     258KB     24.0  2510    12
#> 3 subset(dat, x > 5… 201µs  214µs     2978.     493KB     26.0  1489    13
#> # ℹ 5 more variables: total_time <bch:tm>, result <list>, memory <list>,
#> #   time <list>, gc <list>

# Or output relative times
summary(results, relative = TRUE)
#> # A tibble: 3 × 13
#>   expression           min median `itr/sec` mem_alloc `gc/sec` n_itr  n_gc
#>   <bch:expr>         <dbl>  <dbl>     <dbl>     <dbl>    <dbl> <int> <dbl>
#> 1 dat[dat$x > 500, ]  1.05   1.11      1.41      1.45     1.54  1938    16
#> 2 dat[which(dat$x >…  1      1         1.57      1        1     2498    12
#> 3 subset(dat, x > 5…  1.50   1.53      1         1.91     1.17  1476    13
#> # ℹ 5 more variables: total_time <bch:tm>, result <list>, memory <list>,
#> #   time <list>, gc <list>