Skip to contents

Benchmark expression in multiple environments

benchInEnv.Rd

Measures the execution time for an R expression across multiple environments. The function runs the expression multiple times (controlled by `rep` parameter) and returns the execution times for each run in the specified environments.

Usage

benchInEnv(
  expr,
  envName = envList(),
  rep = 3,
  warmup = 0,
  setup = NULL,
  returnDataframe = TRUE
)

Arguments

expr

An R expression or a `character()` (deparsed R expression) to be benchmarked.

envName

A `character()` vector specifying the environment(s) name(s). If more than one environment is specified, the expression will be evaluated in each one.

rep

An `integer(1)` specifying the number of repetitions for each expression. Default is 3.

warmup

An `integer(1)` specifying how many initial repetitions to run and discard (to remove warm-up bias). Default is `0`. The total number of executions will be `warmup + rep`.

setup

An optional R expression or a `character()` (deparsed R expression) to be evaluated before the benchmarked expression. For instance, it can be used to load libraries or retrieve data.

returnDataframe

A `logical(1)` indicating whether to return the results as a data frame (`TRUE`) or as a list (`FALSE`).

Value

With `returnDataframe == TRUE` (default): A data frame with columns `envName`, `rep`, and `time`

With `returnDataframe == FALSE`: A list of execution times for each environment:

  • A numeric vector of execution times for the evaluated expression if `length(envName) == 1`.

  • A list of numeric vectors of execution times for each environment if `length(envName) > 1`.

The result contains the user time (in seconds) for each repetition of the expression.

Examples

envCreate("my_env", packages = c("jsonlite"))
#> - The project is out-of-sync -- use `renv::status()` for details.
#> # Downloading packages -------------------------------------------------------
#> - Downloading jsonlite from https://packagemanager.posit.co/cran/__linux__/noble/latest ... OK [1 Mb in 0.46s]
#> Successfully downloaded 1 package in 1.5 seconds.
#> 
#> The following package(s) will be installed:
#> - jsonlite [2.0.0]
#> These packages will be installed into "~/work/VerR/VerR/docs/reference/.envs/my_env/renv/library/linux-ubuntu-noble/R-4.5/x86_64-pc-linux-gnu".
#> 
#> # Installing packages --------------------------------------------------------
#> - Installing jsonlite ...                       OK [installed binary and cached in 0.24s]
#> Successfully installed 1 package in 0.29 seconds.
#> Installed packages in environment: /home/runner/work/VerR/VerR/docs/reference/.envs/my_env
#> - The project is out-of-sync -- use `renv::status()` for details.
#> The following package(s) will be updated in the lockfile:
#> 
#> # RSPM -----------------------------------------------------------------------
#> - jsonlite   [* -> 2.0.0]
#> - renv       [* -> 1.1.5]
#> 
#> The version of R recorded in the lockfile will be updated:
#> - R          [* -> 4.5.1]
#> 
#> - Lockfile written to "~/work/VerR/VerR/docs/reference/.envs/my_env/renv.lock".
#> Updated lockfile in environment: .envs/my_env
benchInEnv(Sys.sleep(1), "my_env",
    rep = 3,
    setup = library(jsonlite),
    returnDataframe = TRUE
)
#> 
#> Benchmarking expression in environment: my_env 
#>   envName rep  time
#> 1  my_env   1 1.001
#> 2  my_env   2 1.002
#> 3  my_env   3 1.001