purrrogress

Travis build status Codecov test coverage

The goal of purrrogress is to add as simply as possible progress bars to purrr mapping functions.

Installation

You can install the released version of purrrogress from CRAN with:

install.packages("purrrogress")

Using

Progress bars can be added to any map function with the with_progress() function wrapped around the function to be mapped.

library(purrrogress)
## basic example code

fun <- function(...){
    # this does nothing but take time.
    Sys.sleep(0.1)
    invisible(NULL)
}
invisible(map(1:100, with_progress(fun)))

This example doesn’t do much but illustrates the simplicity of purrrogress bars. The length of the progress bar is imputed from the variable passed to the map function as well as the title and label for the progress bar. No changes are needed to the function and all arguments are passed on as is.

Caveat

The with_progress() function can only impute the length if it is actually part of the map call. The following will not work.

# This will not work.
not_so_fun <- with_progress(fun)
invisible(map(1:100, not_so_fun))

This could be made to work by specifying the length if known a priori.

# The fix
just_less_fun <- with_progress(fun, 100)
invisible(map(1:100, just_less_fun))

Directly

The progress bars used by purrrogress are defined in a class system described in a later section. Progress bars can be created and manipulated directly through the progress_bar() function.

pb <- progress_bar(100, "A Title", "An informative label", type="none")

The type argument will determine what type of progress bar is created, windows, Tk, or none(used for testing and demonstration).

Customization

The progress bar windows can be customized to display relevant information such as the number of elements completed, or the estimated time remaining. This can be accomplished through inserting glue style keywords. These keywords are added by default:

These keywords can be used in either the title or the label of progress bars to obtain more informative messages.

pb <- progress_bar( 100
                  , title = "Test progress bar ({etr})"
                  , label = "{frac}({percent}) completed."
                  , initial = 50
                  )
pb$init()
Sys.sleep(2)
pb$title
#> Test progress bar (00:00:02)
pb$label
#> 50/100(50%) completed.
pb$term()

Adding Bindings

In addition to those provided, additional bindings can be added to show even more information.

words <- stringi::stri_rand_lipsum(1, FALSE) %>%
         stringi::stri_split(fixed = ' ') %>%
         unlist()
pb <- R6_progress$new( length(words)
                     , title = "Test Progress {current}/{total}"
                     , label = "Working on item {current}, {word}"
                     , bindings = list(word = ~words[pb$current+1])
                     )
#> Warning in ls(self, all = TRUE): partial argument match of 'all' to
#> 'all.names'
#> Warning in ls(private$bindings, all = TRUE): partial argument match of
#> 'all' to 'all.names'
pb$init()
pb$label
#> Working on item 0, Maecenas
pb$step()
pb$label
#> Working on item 1, ac
pb$step()
pb$label
#> Working on item 2, eget
pb$term()

Class System

Additional progress bars may be defined to work within the purrrogress framework, however each must inherit from the base progress class, “R6 Progress Base Class” which handles the creation and management of the active bindings for titles and labels.

Public Methods to Implement.

The following are public methods for which a derived class must implement.

Other Public Methods

The following are functions that are provided in the public interface for R6 progress bars but do not need to be implemented in child classes, or when implemented care should be taken to carry forward the default behavior.

Acknowledgements

This project was inspired by a post to R-Bloggers by Adi Sarid. Credit goes to him for the original idea on which purrrogress is built.