Author: Robert M Flight
Date: 2024-07-23

# Example Progress Bar Output

#### Robert M Flight

#### 2024-07-23

## 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