Example Progress Bar Output

Robert M Flight

2024-07-23

Source: vignettes/example_progress_bars.Rmd

Motivation

rmarkdown & knitr capture everything written to stdout, which includes all output from document chunks, including progress bars, such as those supplied by dplyr.

To enable progress reporting even when using rmarkdown documents, the progress bar supplied here can write output to any connection, including stdout, stderr, and any opened file.

Setup

Load the package, and define the function that will use the progress bar. This particular example is courtesy of Bob Rudis.

library(knitrProgressBar)

arduously_long_nchar <- function(input_var, .pb=NULL) {
  
  update_progress(.pb) # this is a function provided by the package
  
  Sys.sleep(0.1)
  
  nchar(input_var)
  
}

Choosing Output Locations

There are two ways to choose the output:

  1. Using make_kpb_output_decisions()
  2. Directly, by passing a connection (or NULL for no output)

Using make_kpb_output_decisions()

Defaults 

# not run
pb <- progress_estimated(length(letters))

purrr::map_int(letters, arduously_long_nchar, .pb = pb)

In the terminal, this should push results to stdout, in knitr / rmarkdown it will get pushed to stderr.

Suppressing Output

If you want the progress to appear when in the terminal, but not when running via the RStudio Knit button or Rscript, then you can supply an option to suppress progress output in non-interactive running:

options(kpb.suppress_noninteractive = TRUE)

Log Files

If you want log-files displaying progress, you can use the following options:

options(kpb.use_logfile = TRUE)

This will push all progress to a log-file, by default to kpb_output.log.

Adding more options will provide finer control:

options(kpb.use_logfile = TRUE)
options(kpb.log_file = "my_logfile.log")

Now progress will be saved in my_logfile.log.

If you are using rmarkdown and want to make log-files based on the chunk labels, then you would use the kpb.log_pattern option:

options(kpb.use_logfile = TRUE)
options(kpb.log_pattern = "pb_out_")

This will generate a log-file for each rmarkdown chunk, and prepend each one with pb_out_.

Note: kpb.log_file and kpb.log_pattern should not both be set in a single run, and kpb.log_file trumps kpb.log_pattern.

Setting Save Locations Directly

In this case, you can simply pass a connection directly into progress_estimated:

# to terminal, or print in a knitr chunk
pb <- progress_estimated(length(letters), progress_location = stdout())

# to stderr, so visible from knitr
pb <- progress_estimated(length(letters), progress_location = stderr())

# to a file, visible using tailf
pb <- progress_estimated(length(letters), progress_location = file("progress.log", open = "w"))

No Progress Bar

If you decide that you don’t want any progress displayed, just pass a NULL connection.

pb <- progress_estimated(length(letters), progress_location = NULL)

purrr::map_int(letters, arduously_long_nchar, .pb = pb)
#>  [1] 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1