Version:	0.15.1
Title:	An Inclusive, Unifying API for Progress Updates
Description:	A minimal, unifying API for scripts and packages to report progress updates from anywhere including when using parallel processing. The package is designed such that the developer can to focus on what progress should be reported on without having to worry about how to present it. The end user has full control of how, where, and when to render these progress updates, e.g. in the terminal using utils::txtProgressBar(), cli::cli_progress_bar(), in a graphical user interface using utils::winProgressBar(), tcltk::tkProgressBar() or shiny::withProgress(), via the speakers using beepr::beep(), or on a file system via the size of a file. Anyone can add additional, customized, progression handlers. The 'progressr' package uses R's condition framework for signaling progress updated. Because of this, progress can be reported from almost anywhere in R, e.g. from classical for and while loops, from map-reduce API:s like the lapply() family of functions, 'purrr', 'plyr', and 'foreach'. It will also work with parallel processing via the 'future' framework, e.g. future.apply::future_lapply(), furrr::future_map(), and 'foreach' with 'doFuture'. The package is compatible with Shiny applications.
License:	GPL (≥ 3)
Depends:	R (≥ 3.5.0)
Imports:	digest, utils
Suggests:	graphics, tcltk, beepr, cli, crayon, pbmcapply, progress, purrr, foreach, plyr, doFuture, future, future.apply, furrr, ntfy, RPushbullet, rstudioapi, shiny, commonmark, base64enc, tools
VignetteBuilder:	progressr
URL:	https://progressr.futureverse.org, https://github.com/futureverse/progressr
BugReports:	https://github.com/futureverse/progressr/issues
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2024-11-21 06:18:27 UTC; henrik
Author:	Henrik Bengtsson [aut, cre, cph]
Maintainer:	Henrik Bengtsson <henrikb@braju.com>
Repository:	CRAN
Date/Publication:	2024-11-22 14:20:06 UTC

progressr: A Unifying API for Progress Updates

Description

The progressr package provides a minimal, unifying API for scripts and packages to report progress updates from anywhere including when using parallel processing.

Details

The package is designed such that the developer can to focus on what progress should be reported on without having to worry about how to present it.

The end user has full control of how, where, and when to render these progress updates. For instance, they can chose to report progress in the terminal using utils::txtProgressBar() or progress::progress_bar() or via the graphical user interface (GUI) using utils::winProgressBar() or tcltk::tkProgressBar(). An alternative to above visual rendering of progress, is to report it using beepr::beep() sounds. It is possible to use a combination of above progression handlers, e.g. a progress bar in the terminal together with audio updates. Besides the existing handlers, it is possible to develop custom progression handlers.

The progressr package uses R's condition framework for signaling progress updated. Because of this, progress can be reported from almost anywhere in R, e.g. from classical for and while loops, from map-reduce APIs like the lapply() family of functions, purrr, plyr, and foreach. The progressr package will also work with parallel processing via the future framework, e.g. future.apply::future_lapply(), furrr::future_map(), and foreach::foreach() with doFuture.

The progressr package is compatible with Shiny applications.

Progression Handlers

In the terminal:

• handler_txtprogressbar (default)

• handler_pbcol

• handler_pbmcapply

• handler_progress

• handler_ascii_alert

• handler_debug

In a graphical user interface (GUI):

• handler_rstudio

• handler_tkprogressbar

• handler_winprogressbar

As sound:

• handler_beepr

• handler_ascii_alert

Via the file system:

• handler_filesize

In Shiny:

• withProgressShiny

Via notification systems:

• handler_ntfy

• handler_notifier

• handler_rpushbullet

Author(s)

Maintainer: Henrik Bengtsson henrikb@braju.com (ORCID) [copyright holder]

See Also

Useful links:

• https://progressr.futureverse.org

• https://github.com/futureverse/progressr

• Report bugs at https://github.com/futureverse/progressr/issues

Examples

library(progressr)

xs <- 1:5

with_progress({
  p <- progressor(along = xs)
  y <- lapply(xs, function(x) {
    Sys.sleep(0.1)
    p(sprintf("x=%g", x))
    sqrt(x)
  })
})

A Global Calling Handler For 'progression':s

Description

A Global Calling Handler For 'progression':s

Usage

global_progression_handler(condition)

Arguments

Value

Nothing.

Requirements

This function requires R (>= 4.0.0) - the version in which global calling handlers where introduces.

Progression Handler: Progress Reported as ASCII BEL Symbols (Audio or Blink) in the Terminal

Description

A progression handler based on cat("\a", file=stderr()).

Usage

handler_ascii_alert(
  symbol = "\a",
  file = stderr(),
  intrusiveness = getOption("progressr.intrusiveness.audio", 5),
  target = c("terminal", "audio"),
  ...
)

Arguments

Examples

handlers("ascii_alert")
with_progress({ y <- slow_sum(1:10) })
print(y)

Progression Handler: Progress Reported as 'beepr' Sounds (Audio)

Description

A progression handler for beepr::beep().

Usage

handler_beepr(
  initiate = 2L,
  update = 10L,
  finish = 11L,
  interrupt = 9L,
  intrusiveness = getOption("progressr.intrusiveness.audio", 5),
  target = "audio",
  ...
)

Arguments

Requirements

This progression handler requires the beepr package.

Examples

if (requireNamespace("beepr", quietly = TRUE)) {

  handlers("beepr")
  with_progress({ y <- slow_sum(1:10) })
  print(y)
  
}

Progression Handler: Progress Reported via 'cli' Progress Bars (Text) in the Terminal

Description

A progression handler for cli::cli_progress_bar().

Usage

handler_cli(
  show_after = 0,
  intrusiveness = getOption("progressr.intrusiveness.terminal", 1),
  target = "terminal",
  ...
)

Arguments

Requirements

This progression handler requires the cli package.

Appearance

Below are a few examples on how to use and customize this progress handler. In all cases, we use handlers(global = TRUE).

handlers("cli")
y <- slow_sum(1:25)

handlers(handler_cli(format = "{cli::pb_spin} {cli::pb_bar} {cli::pb_current}/{cli::pb_total} {cli::pb_status}"))
y <- slow_sum(1:25)

Examples

if (requireNamespace("cli", quietly = TRUE)) {
  handlers(handler_cli(format = "{cli::pb_spin} {cli::pb_bar} {cli::pb_percent} {cli::pb_status}"))
  with_progress({ y <- slow_sum(1:10) })
  print(y)
}

Progression Handler: Progress Reported as Debug Information (Text) in the Terminal

Description

Progression Handler: Progress Reported as Debug Information (Text) in the Terminal

Usage

handler_debug(
  interval = getOption("progressr.interval", 0),
  intrusiveness = getOption("progressr.intrusiveness.debug", 0),
  target = "terminal",
  uuid = FALSE,
  ...
)

Arguments

Appearance

Below is how this progress handler renders by default at 0%, 30% and 99% progress:

With handlers(handler_debug()):

[21:27:11.236] (0.000s => +0.001s) initiate: 0/100 (+0) '' {clear=TRUE, enabled=TRUE, status=}
[21:27:11.237] (0.001s => +0.000s) update: 0/100 (+0) 'Starting' {clear=TRUE, enabled=TRUE, status=}
[21:27:14.240] (3.004s => +0.002s) update: 30/100 (+30) 'Importing' {clear=TRUE, enabled=TRUE, status=}
[21:27:16.245] (5.009s => +0.001s) update: 100/100 (+70) 'Summarizing' {clear=TRUE, enabled=TRUE, status=}
[21:27:16.246] (5.010s => +0.003s) update: 100/100 (+0) 'Summarizing' {clear=TRIE, enabled=TRUE, status=}

Examples

handlers("debug")
with_progress({ y <- slow_sum(1:10) })
print(y)

Progression Handler: Progress Reported as the Size of a File on the File System

Description

Progression Handler: Progress Reported as the Size of a File on the File System

Usage

handler_filesize(
  file = "default.progress",
  intrusiveness = getOption("progressr.intrusiveness.file", 5),
  target = "file",
  enable = getOption("progressr.enable", TRUE),
  ...
)

Arguments

Details

This progression handler reports progress by updating the size of a file on the file system. This provides a convenient way for an R script running in batch mode to report on the progress such that the user can peek at the file size (by default in 0-100 bytes) to assess the amount of the progress made, e.g. ⁠ls -l -- *.progress⁠. If the ‘*.progress’ file is accessible via for instance SSH, SFTP, FTPS, HTTPS, etc., then progress can be assessed from a remote location.

Examples

## Not run: 
handlers(handler_filesize(file = "myscript.progress"))
with_progress(y <- slow_sum(1:100))
print(y)

## End(Not run)

Progression Handler: Progress Reported as a New Line (Text) in the Terminal

Description

Progression Handler: Progress Reported as a New Line (Text) in the Terminal

Usage

handler_newline(
  symbol = "\n",
  file = stderr(),
  intrusiveness = getOption("progressr.intrusiveness.debug", 0),
  target = "terminal",
  ...
)

Arguments

Progression Handler: Progress Reported via the Operating-System Notification Framework (GUI, Text)

Description

A progression handler for notify() of the notifier package.

Usage

handler_notifier(
  intrusiveness = getOption("progressr.intrusiveness.notifier", 10),
  target = "gui",
  ...
)

Arguments

Requirements

This progression handler requires the notifier package, which is only available from https://github.com/gaborcsardi/notifier. This can be installed as remotes::install_github("gaborcsardi/notifier@62d484").

Examples

pkg <- "notifier"
if (requireNamespace(pkg, quietly = TRUE)) {

  handlers("notifier")
  with_progress({ y <- slow_sum(1:10) })
  print(y)
  
}

Progression Handler: Progress Reported via the Ntfy.sh Messaging Service

Description

A progression handler for ntfy::ntfy_send() of the ntfy package, which sends notifications via the https://ntfy.sh framework.

Usage

handler_ntfy(
  intrusiveness = getOption("progressr.intrusiveness.ntfy", 5),
  target = "gui",
  ...,
  title = "Progress update from R"
)

Arguments

Requirements

This progression handler requires the ntfy package.

Examples

pkg <- "ntfy"
if (requireNamespace(pkg, quietly = TRUE)) {
  ## We need to specify a ntfy.sh topic that progress messages
  ## should be sent to. See help("ntfy_topic", package = "ntfy")
  ## for details
  Sys.setenv(NTFY_TOPIC = "R-my-secret-topic")

  handlers("ntfy")
  with_progress({ y <- slow_sum(1:10) })
  print(y)
}

Progression Handler: Progress Reported as an ANSI Background Color in the Terminal

Description

Progression Handler: Progress Reported as an ANSI Background Color in the Terminal

Usage

handler_pbcol(
  adjust = 0,
  pad = 1L,
  complete = function(s) cli::bg_blue(cli::col_white(s)),
  incomplete = function(s) cli::bg_cyan(cli::col_white(s)),
  intrusiveness = getOption("progressr.intrusiveness.terminal", 1),
  target = "terminal",
  ...
)

Arguments

Requirements

This progression handler requires the cli package.

Appearance

Below are a few examples on how to use and customize this progress handler. In all cases, we use handlers(global = TRUE).

handlers("pbcol")
y <- slow_sum(1:25)

handlers(handler_pbcol(adjust = 0.5))
y <- slow_sum(1:25)

handlers(handler_pbcol(
  adjust = 1,
  complete = function(s) cli::bg_red(cli::col_black(s)),
  incomplete = function(s) cli::bg_cyan(cli::col_black(s))
))
y <- slow_sum(1:25)

Examples

handlers(handler_pbcol)
with_progress({ y <- slow_sum(1:10) })
print(y)

Progression Handler: Progress Reported via 'pbmcapply' Progress Bars (Text) in the Terminal

Description

A progression handler for pbmcapply::progressBar().

Usage

handler_pbmcapply(
  char = "=",
  substyle = 3L,
  style = "ETA",
  file = stderr(),
  intrusiveness = getOption("progressr.intrusiveness.terminal", 1),
  target = "terminal",
  ...
)

Arguments

Requirements

This progression handler requires the pbmcapply package.

Appearance

Below are a few examples on how to use and customize this progress handler. In all cases, we use handlers(global = TRUE). Since style = "txt" corresponds to using handler_txtprogressbar() with style = substyle, the main usage of this handler is with style = "ETA" (default) for which substyle is ignored.

handlers("pbmcapply")
y <- slow_sum(1:25)

Examples

if (requireNamespace("pbmcapply", quietly = TRUE)) {

  handlers("pbmcapply")
  with_progress({ y <- slow_sum(1:10) })
  print(y)
  
}

Progression Handler: Progress Reported via 'progress' Progress Bars (Text) in the Terminal

Description

A progression handler for progress::progress_bar().

Usage

handler_progress(
  format = ":spin [:bar] :percent :message",
  show_after = 0,
  intrusiveness = getOption("progressr.intrusiveness.terminal", 1),
  target = "terminal",
  ...
)

Arguments

Requirements

This progression handler requires the progress package.

Appearance

Below are a few examples on how to use and customize this progress handler. In all cases, we use handlers(global = TRUE).

handlers("progress")
y <- slow_sum(1:25)

handlers(handler_progress(complete = "#"))
y <- slow_sum(1:25)

handlers(handler_progress(format = ":spin [:bar] :percent :message"))
y <- slow_sum(1:25)

handlers(handler_progress(format = ":percent [:bar] :eta :message"))
y <- slow_sum(1:25)

Examples

if (requireNamespace("progress", quietly = TRUE)) {

  handlers(handler_progress(format = ":spin [:bar] :percent :message"))
  with_progress({ y <- slow_sum(1:10) })
  print(y)
  
}

Progression Handler: Progress Reported via the Pushbullet Messaging Service

Description

A progression handler for RPushbullet::pbPost() of the RPushbullet package.

Usage

handler_rpushbullet(
  intrusiveness = getOption("progressr.intrusiveness.rpushbullet", 5),
  target = "gui",
  ...,
  title = "Progress update from R",
  recipients = NULL,
  email = NULL,
  channel = NULL,
  apikey = NULL,
  devices = NULL
)

Arguments

Requirements

This progression handler requires the RPushbullet package, a Pushbullet account, and configuration according to the instructions of the RPushbullet package. It also requires internet access from the computer where this progress handler is registered.

Examples

pkg <- "RPushbullet"
if (requireNamespace(pkg, quietly = TRUE)) {

  handlers("rpushbullet")
  with_progress({ y <- slow_sum(1:10) })
  print(y)
  
}

Progression Handler: Progress Reported in the RStudio Console

Description

Progression Handler: Progress Reported in the RStudio Console

Usage

handler_rstudio(
  intrusiveness = getOption("progressr.intrusiveness.gui", 1),
  target = "gui",
  title = function() format(Sys.time(), "Console %X"),
  ...
)

Arguments

Requirements

This progression handler works only in the RStudio Console.

Use this progression handler by default

To use this handler by default whenever using the RStudio Console, add the following to your ‘~/.Rprofile’ startup file:

if (requireNamespace("progressr", quietly = TRUE)) {
  if (Sys.getenv("RSTUDIO") == "1" && !nzchar(Sys.getenv("RSTUDIO_TERM"))) {
    options(progressr.handlers = progressr::handler_rstudio)
  }
}

Examples

if (requireNamespace("rstudioapi", quietly = TRUE) && rstudioapi::isAvailable()) {

  handlers("rstudio")
  with_progress({ y <- slow_sum(1:10) })
  print(y)
  
}

Progression Handler: Progress Reported via 'shiny' Widgets (GUI) in the HTML Browser

Description

A progression handler for shiny and shiny::withProgress().

Usage

handler_shiny(
  intrusiveness = getOption("progressr.intrusiveness.gui", 1),
  target = "gui",
  inputs = list(message = NULL, detail = "message"),
  enable = getOption("progressr.enable", TRUE),
  ...
)

Arguments

Details

For most Shiny application there is little need to use this Shiny handler directly. Instead, it is sufficient to use withProgressShiny().

Requirements

This progression handler requires the shiny package.

Examples

## Not run: 
handlers(handler_shiny())
with_progress(y <- slow_sum(1:100))

## End(Not run)

Progression Handler: Progress Reported as a Tcl/Tk Progress Bars in the GUI

Description

A progression handler for tcltk::tkProgressBar().

Usage

handler_tkprogressbar(
  intrusiveness = getOption("progressr.intrusiveness.gui", 1),
  target = "terminal",
  inputs = list(title = NULL, label = "message"),
  ...
)

Arguments

Requirements

This progression handler requires the tcltk package and that the current R session supports Tcl/Tk (capabilities("tcltk")).

Examples

if (capabilities("tcltk") && requireNamespace("tcltk", quietly = TRUE)) {

  handlers("tkprogressbar")
  with_progress({ y <- slow_sum(1:10) })
  print(y)
  
}

Progression Handler: Progress Reported as Plain Progress Bars (Text) in the Terminal

Description

A progression handler for utils::txtProgressBar().

Usage

handler_txtprogressbar(
  char = "=",
  style = 3L,
  file = stderr(),
  intrusiveness = getOption("progressr.intrusiveness.terminal", 1),
  target = "terminal",
  ...
)

Arguments

Appearance

Below are a few examples on how to use and customize this progress handler. In all cases, we use handlers(global = TRUE).

handlers("txtprogressbar")
y <- slow_sum(1:25)

handlers(handler_txtprogressbar(style = 1L))
y <- slow_sum(1:25)

handlers(handler_txtprogressbar(style = 3L))
y <- slow_sum(1:25)

handlers(handler_txtprogressbar(char = "#"))
y <- slow_sum(1:25)

handlers(handler_txtprogressbar(char = "<>"))
y <- slow_sum(1:25)

handlers(handler_txtprogressbar(char = cli::col_red(cli::symbol$heart)))
y <- slow_sum(1:25)

Examples

handlers("txtprogressbar")

with_progress({ y <- slow_sum(1:10) })
print(y)

Progression Handler: No Progress Report

Description

Progression Handler: No Progress Report

Usage

handler_void(intrusiveness = 0, target = "void", enable = FALSE, ...)

Arguments

Details

This progression handler gives not output - it is invisible and silent.

Examples

## Not run: 
handlers(handler_void())
with_progress(y <- slow_sum(1:100))
print(y)

## End(Not run)

Progression Handler: Progress Reported as a MS Windows Progress Bars in the GUI

Description

A progression handler for winProgressBar() in the utils package.

Usage

handler_winprogressbar(
  intrusiveness = getOption("progressr.intrusiveness.gui", 1),
  target = "gui",
  inputs = list(title = NULL, label = "message"),
  ...
)

Arguments

Requirements

This progression handler requires MS Windows.

Examples

## Not run: 
handlers(handler_winprogressbar())
with_progress(y <- slow_sum(1:100))

## End(Not run)

Control How Progress is Reported

Description

Control How Progress is Reported

Usage

handlers(
  ...,
  append = FALSE,
  on_missing = c("error", "warning", "ignore"),
  default = handler_txtprogressbar,
  global = NULL
)

Arguments

Details

This function provides a convenient alternative for getting and setting option progressr.handlers.

Value

(invisibly) the previous list of progression handlers set. If no arguments are specified, then the current set of progression handlers is returned. If global is specified, then TRUE is returned if the global progression handlers is enabled, otherwise false.

For package developers

IMPORTANT: Setting progression handlers is a privilege that should be left to the end user. It should not be used by R packages, which only task is to signal progress updates, not to decide if, when, and how progress should be reported.

If you have to set or modify the progression handlers inside a function, please make sure to undo the settings afterward. If not, you will break whatever progression settings the user already has for other purposes used elsewhere. To undo you settings, you can do:

old_handlers <- handlers(c("beepr", "progress"))
on.exit(handlers(old_handlers), add = TRUE)

Configuring progression handling during R startup

A convenient place to configure the default progression handler and to enable global progression reporting by default is in the ‘~/.Rprofile’ startup file. For example, the following will (i) cause your interactive R session to use global progression handler by default, and (ii) report progress via the progress package when in the terminal and via the RStudio Jobs progress bar when in the RStudio Console. handler_txtprogressbar, other whenever using the RStudio Console, add the following to your ‘~/.Rprofile’ startup file:

if (interactive() && requireNamespace("progressr", quietly = TRUE)) {
  ## Enable global progression updates
  if (getRversion() >= 4) progressr::handlers(global = TRUE)

  ## In RStudio Console, or not?
  if (Sys.getenv("RSTUDIO") == "1" && !nzchar(Sys.getenv("RSTUDIO_TERM"))) {
    options(progressr.handlers = progressr::handler_rstudio)
  } else {
    options(progressr.handlers = progressr::handler_progress)
  }
}

Examples

handlers("txtprogressbar")
if (requireNamespace("beepr", quietly = TRUE))
  handlers("beepr", append = TRUE)

with_progress({ y <- slow_sum(1:5) })
print(y)


if (getRversion() >= "4.0.0") {
  
  handlers(global = TRUE)
  y <- slow_sum(1:4)
  z <- slow_sum(6:9)
  
  handlers(global = FALSE)
}

Creates a Progression Calling Handler

Description

A progression calling handler is a function that takes a base::condition as its first argument and that can be use together with base::withCallingHandlers(). This function helps creating such progression calling handler functions.

Usage

make_progression_handler(
  name,
  reporter = list(),
  handler = NULL,
  enable = getOption("progressr.enable", interactive()),
  enable_after = getOption("progressr.enable_after", 0),
  times = getOption("progressr.times", +Inf),
  interval = getOption("progressr.interval", 0),
  intrusiveness = 1,
  clear = getOption("progressr.clear", TRUE),
  target = "terminal",
  ...
)

Arguments

Details

The inner details of progression handlers and how to use this function are still to be documented. Until then, see the source code of existing handlers for how it is used, e.g. progressr::handler_txtprogressbar. Please use with care as things might change.

Value

A function of class progression_handler that takes a progression condition as its first and only argument.

Reporter functions

The reporter argument should be a named list of zero or more of the following functions:

• initiate

• update

• finish

These functions are called whenever a progression condition of type "initiate", "update", or "finish" are received, but only if the condition is for the progression that is currently handled. These functions are called with the following arguments (in order):

• config - a named list of the configuration of the progression handler: max_steps (integer), interval (numeric), enable_after (numeric), auto_finish (logical), clear (logical), target (character vector)

• state - a named list of the current progress state after accounting for the most recent progression condition: step (integer), message (character), delta (integer), enabled (logical), timestamps (POSIXct vector)

• progression - a progression condition

• ... - not used (reserved for future needs)

In addition to the above functions, the following functions:

• hide

• unhide

• reset

• interrupt

are called whenever the handler "should" hide or unhide the rendered progress, or reset it, or when an interrupt is detected. In these cases, the progression argument is of class control_progression.

See Also

base::withCallingHandlers().

Examples

## Create a progression handler that reports on the current progress
## step, the relative change, and the current progress message. This
## is only reported on positive progressions updated
my_handler <- make_progression_handler(name = "my", reporter = list(
  update = function(config, state, progression, ...) {
    if (progression$amount > 0) {
      message(sprintf("step = %d (+%g): message = %s",
                      state$step,
                      progression$amount,
                      sQuote(state$message)))
    }
  }
))

handlers(my_handler)

with_progress({
  y <- slow_sum(1:5)
})

Creates and Signals a Progression Condition

Description

WARNING: progress() is defunct - don't use.

Usage

progress(..., call = sys.call())

Arguments

Value

A base::condition of class progression.

See Also

To create a progression condition, use progression(). To signal a progression condition, use base::signalCondition().

Aggregate Progression Conditions

Description

Aggregate Progression Conditions

Usage

progress_aggregator(progress)

Arguments

Value

A function of class progress_aggregator.

Examples

library(progressr)

message("progress_aggregator() ...")

with_progress({
  progress <- progressor(steps = 4L)
  relay_progress <- progress_aggregator(progress)
  progress()
  relay_progress(slow_sum(1:3))
  relay_progress(slow_sum(1:10))
  progress()
})

message("progress_aggregator() ... done")

Use Progressr with Plyr Map-Reduce Functions

Description

A "progress bar" for plyr's .progress argument.

Usage

progress_progressr(...)

Arguments

Value

A named base::list that can be passed as argument .progress to any of plyr function accepting that argument.

Limitations

One can use use doFuture::registerDoFuture() to run plyr functions in parallel, e.g. plyr::l_ply(..., .parallel = TRUE). Unfortunately, using .parallel = TRUE disables progress updates because, internally, plyr forces .progress = "none" whenever .parallel = TRUE. Thus, despite the future ecosystem and progressr would support it, it is not possible to run dplyr in parallel and get progress updates at the same time.

Examples

if (requireNamespace("plyr", quietly=TRUE)) {

  with_progress({
    y <- plyr::llply(1:10, function(x) {
      Sys.sleep(0.1)
      sqrt(x)
    }, .progress = "progressr")
  })
  
}

A Progression Condition

Description

A progression condition represents a progress in an R program.

Usage

progression(
  message = character(0L),
  amount = 1,
  step = NULL,
  time = progression_time,
  ...,
  type = "update",
  class = NULL,
  progressor_uuid = NULL,
  progression_index = NULL,
  progression_time = Sys.time(),
  call = NULL,
  calls = sys.calls(),
  owner_session_uuid = NULL
)

Arguments

Value

A base::condition of class progression.

See Also

To signal a progression condition, use base::signalCondition().

Create a Progressor Function that Signals Progress Updates

Description

Create a Progressor Function that Signals Progress Updates

Usage

progressor(
  steps = length(along),
  along = NULL,
  offset = 0L,
  scale = 1L,
  transform = function(steps) scale * steps + offset,
  message = character(0L),
  label = NA_character_,
  trace = FALSE,
  initiate = TRUE,
  auto_finish = TRUE,
  on_exit = !identical(envir, globalenv()),
  enable = getOption("progressr.enable", TRUE),
  envir = parent.frame()
)

Arguments

Details

A progressor function can only be created inside a local environment, e.g. inside a function, within a local() call, or within a with_progress() call. Notably, it cannot be create at the top level, e.g. immediately at the R prompt or outside a local environment in an R script. If attempted, an informative error message is produced, e.g.

> p <- progressr::progressor(100)
Error in progressr::progressor(100) : 
  A progressor must not be created in the global environment unless
wrapped in a with_progress() or without_progress() call. Alternatively,
create it inside a function or in a local() environment to make sure
there is a finite life span of the progressor

Value

A function of class progressor.

Options and environment variables used by the 'progressr' packages

Description

Below are environment variables and R options that are used by the progressr package. Below are all R options that are currently used by the progressr package.

WARNING: Note that the names and the default values of these options may change in future versions of the package. Please use with care until further notice.

Options for controlling progression reporting

progressr.handlers:

(function or list of functions) Zero or more progression handlers that will report on any progression updates. If empty list, progress updates are ignored. If NULL, the default (handler_txtprogressbar) progression handlers is used. The recommended way to set this option is via handlers(). (Default: NULL)

Options for controlling progression handlers

progressr.clear:

(logical) If TRUE, any output, typically visual, produced by a reporter will be cleared/removed upon completion, if possible. (Default: TRUE)

progressr.enable:

(logical) If FALSE, then progress is not reported. (Default: TRUE in interactive mode, otherwise FALSE)

progressr.enable_after:

(numeric) Delay (in seconds) before progression updates are reported. (Default: 0.0)

progressr.times:

(numeric) The maximum number of times a handler should report progression updates. If zero, then progress is not reported. (Default: +Inf)

progressr.interval:

(numeric) The minimum time (in seconds) between successive progression updates from this handler. (Default: 0.0)

progressr.intrusiveness:

(numeric) A non-negative scalar on how intrusive (disruptive) the reporter to the user. This multiplicative scalar applies to the interval and times parameters. (Default: 1.0)

progressr.intrusiveness.audio:

(numeric) intrusiveness for auditory progress handlers (Default: 5.0)

progressr.intrusiveness.file:

(numeric) intrusiveness for file-based progress handlers (Default: 5.0)

progressr.intrusiveness.gui:

(numeric) intrusiveness for graphical-user-interface progress handlers (Default: 1.0)

progressr.intrusiveness.notifier:

(numeric) intrusiveness for progress handlers that creates notifications (Default: 10.0)

progressr.intrusiveness.terminal:

(numeric) intrusiveness for progress handlers that outputs to the terminal (Default: 1.0)

progressr.intrusiveness.debug:

(numeric) intrusiveness for "debug" progress handlers (Default: 0.0)

Options for controlling how standard output and conditions are relayed

progressr.delay_conditions:

(character vector) condition classes to be captured and relayed at the end after any captured standard output is relayed. (Default: c("condition"))

progressr.delay_stdout:

(logical) If TRUE, standard output is captured and relayed at the end just before any captured conditions are relayed. (Default: TRUE)

Options for controlling interrupts

progressr.interrupts:

(logical) Controls whether interrupts should be detected or not. If FALSE, then interrupts are not detected and progress information is generated. (Default: TRUE)

progressr.delay_stdout:

(logical) If TRUE, standard output is captured and relayed at the end just before any captured conditions are relayed. (Default: TRUE)

Options for debugging progression updates

progressr.debug:

(logical) If TRUE, extensive debug messages are generated. (Default: FALSE)

Options for progressr examples and demos

progressr.demo.delay:

(numeric) Delay (in seconds) between each iteration of slow_sum(). (Default: 1.0)

Environment variables that set R options

Some of the above R progressr.* options can be set by corresponding environment variable R_PROGRESSR_* when the progressr package is loaded. For example, if R_PROGRESSR_ENABLE = "true", then option progressr.enable is set to TRUE (logical). For example, if R_PROGRESSR_ENABLE_AFTER = "2.0", then option progressr.enable_after is set to 2.0 (numeric).

See Also

To set R options when R starts (even before the progressr package is loaded), see the Startup help page. The startup package provides a friendly mechanism for configuring R at startup.

Add or Remove a Global 'progression' Handler

Description

Add or Remove a Global 'progression' Handler

Usage

register_global_progression_handler(action = c("add", "remove", "query"))

Arguments

Value

Returns TRUE if a handler is registered, otherwise FALSE. If action = "query", the value is visible, otherwise invisible.

Requirements

This function requires R (>= 4.0.0) - the version in which global calling handlers where introduces.

Examples

handlers(global = TRUE)

## This renders progress updates for each of the three calls slow_sum()
for (ii in 1:3) {
  xs <- seq_len(ii + 3)
  message(sprintf("%d. slow_sum()", ii))
  y <- slow_sum(xs, stdout = TRUE, message = TRUE)
  print(y)
}


handlers(global = FALSE)

Slowly Calculate Sum of Elements

Description

Slowly Calculate Sum of Elements

Usage

slow_sum(
  x,
  delay = getOption("progressr.demo.delay", 1),
  stdout = FALSE,
  message = TRUE,
  sticky = TRUE
)

Arguments

Value

The sum of all elements in x.

Progress updates

This function signals progression conditions as it progresses.

Use Progressr in Shiny Apps: Plug-in Backward-Compatible Replacement for shiny::withProgress()

Description

A plug-in, backward-compatible replacement for shiny::withProgress().

Usage

withProgressShiny(
  expr,
  ...,
  message = NULL,
  detail = NULL,
  inputs = list(message = NULL, detail = "message"),
  env = parent.frame(),
  quoted = FALSE,
  handlers = c(shiny = handler_shiny, progressr::handlers(default = NULL))
)

Arguments

Value

The value of shiny::withProgress.

Requirements

This function requires the shiny package and will use the handler_shiny() progressr handler internally to report on updates.

Examples

library(shiny)
library(progressr)

app <- shinyApp(
  ui = fluidPage(
    plotOutput("plot")
  ),

  server = function(input, output) {
    output$plot <- renderPlot({
      X <- 1:15
      withProgressShiny(message = "Calculation in progress",
                        detail = "Starting ...",
                        value = 0, {
        p <- progressor(along = X)
        y <- lapply(X, FUN=function(x) {
          Sys.sleep(0.25)
          p(sprintf("x=%d", x))
        })
      })
      
      plot(cars)

      ## Terminate the Shiny app
      Sys.sleep(1.0)
      stopApp(returnValue = invisible())
    })
  }
)

local({
  oopts <- options(device.ask.default = FALSE)
  on.exit(options(oopts))
  if (interactive()) print(app)
})

Report on Progress while Evaluating an R Expression

Description

Report on Progress while Evaluating an R Expression

Usage

with_progress(
  expr,
  handlers = progressr::handlers(),
  cleanup = TRUE,
  delay_terminal = NULL,
  delay_stdout = NULL,
  delay_conditions = NULL,
  interrupts = getOption("progressr.interrupts", TRUE),
  interval = NULL,
  enable = NULL
)

without_progress(expr)

Arguments

Details

If you are writing a Shiny app, use the withProgressShiny() function instead of this one.

If the global progression handler is enabled, it is temporarily disabled while evaluating the expr expression.

IMPORTANT: This function is meant for end users only. It should not be used by R packages, which only task is to signal progress updates, not to decide if, when, and how progress should be reported.

without_progress() evaluates an expression while ignoring all progress updates.

Value

Returns the value of the expression.

Progression handler functions

Formally, progression handlers are calling handlers that are called when a progression condition is signaled. These handlers are functions that takes one argument which is the progression condition.

Progress updates in batch mode

When running R from the command line, R runs in a non-interactive mode (interactive() returns FALSE). The default behavior of with_progress() is to not report on progress in non-interactive mode. To have progress being reported on also then, set R options progressr.enable or environment variable R_PROGRESSR_ENABLE to TRUE. Alternatively, one can set argument enable=TRUE when calling with_progress(). For example,

$ Rscript -e "library(progressr)" -e "with_progress(slow_sum(1:5))"

will not report on progress, whereas:

$ export R_PROGRESSR_ENABLE=TRUE
$ Rscript -e "library(progressr)" -e "with_progress(slow_sum(1:5))"

will.

See Also

For Shiny apps, use withProgressShiny() instead of this function. Internally, this function is built around base::withCallingHandlers().

Examples

## The slow_sum() example function
slow_sum <- progressr::slow_sum
print(slow_sum)

x <- 1:10

## Without progress updates
y <- slow_sum(x)


## Progress reported via txtProgressBar (default)
handlers("txtprogressbar")  ## default
with_progress({
  y <- slow_sum(x)
})

## Progress reported via tcltk::tkProgressBar
if (capabilities("tcltk") && requireNamespace("tcltk", quietly = TRUE)) {
  handlers("tkprogressbar")
  with_progress({
    y <- slow_sum(x)
  })
}

## Progress reported via progress::progress_bar)
if (requireNamespace("progress", quietly = TRUE)) {
  handlers("progress")
  with_progress({
    y <- slow_sum(x)
  })
}

## Progress reported via txtProgressBar and beepr::beep
if (requireNamespace("beepr", quietly = TRUE)) {
  handlers("beepr", "txtprogressbar")
  with_progress({
    y <- slow_sum(x)
  })
}

## Progress reported via customized utils::txtProgressBar and beepr::beep,
## if available.
handlers(handler_txtprogressbar(style = 3L))
if (requireNamespace("beepr", quietly = TRUE)) {
  handlers("beepr", append = TRUE)
}

with_progress({
  y <- slow_sum(1:30)
})