progressr: A Unifying API for Progress Updates

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() (default) or cli::cli_progress_bar(), via the R graphical user interface (GUI) using utils::winProgressBar() or tcltk::tkProgressBar(), or via the RStudio GUI using rstudioapi::jobSetProgress(). An alternative to above visual rendering, is to report progress as audio using beepr::beep(). It is also 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 is compatible with shiny applications and knitr rendering.

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.

Progression Handlers

In the terminal:

• handler_txtprogressbar (built-in; default)

• handler_pbcol (built-in)

• handler_ascii_alert (built-in)

• handler_pbmcapply (requires the pbmcapply package)

• handler_progress (requires the progress package)

In a graphical user interface (GUI):

• handler_rstudio (only in the RStudio Console)

• handler_tkprogressbar (built-in)

• handler_winprogressbar (built-in)

As sound:

• handler_ascii_alert (built-in)

• handler_beepr (requires the beepr package)

Via the file system:

• handler_filesize (built-in)

In Shiny:

• withProgressShiny (requires the shiny package)

Via notification systems:

• handler_ntfy (requires the ntfy package)

• handler_notifier (requires the non-CRAN notifier package)

• handler_rpushbullet (requires the RPushBullet package)

Miscellaneous:

• handler_debug (built-in)

• handler_newline (built-in)

• handler_slowdown (built-in)

• handler_void (built-in)

See also

Useful links:

• https://progressr.futureverse.org

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

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

Author

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

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)
  })
})