How to add pbapply to R packages

September 16, 2016 Code R pbapply progress bar R packages dependencies

As of today, there are 20 R packages that reverse depend/import/suggest (3/14/3) the pbapply package. Current and future package developers who decide to incorporate the progress bar using pbapply might want to customize the type and style of the progress bar in their packages to better suit the needs of certain functions or to create a distinctive look. Here is a quick guide to help in setting up and customizing the progress bar.

pbapply gif

Adding pbapply

The pbapply package has no extra (non r-base-core) dependencies and is lightweight, so adding it as dependency does not represent a major overhead. There are two alternative ways of adding the pbapply package to another R package: Suggests, or Depends/Imports. Here are the recommended and tested ways of adding a progress bar to other R packages (see the Writing R Extensions manual for an official guide).

1. Suggests: pbapply

The user decides whether to install pbapply and the function behavior changes accordingly. This might be preferred if there are only few functions that utilize a progress bar.

pbapply needs to be added to the Suggests field in the DESCRIPTION file and use conditional statements in the code to fall back on a base functions in case of pbapply is not being installed:

out <- if (requireNamespace("pbapply", quietly = TRUE))
   pbapply::pblapply(X, FUN, ...) else lapply(X, FUN, ...)

See a small R package here for an example (see R CMD check log on Travis CI: Build Status).

2. Depends/Imports: pbapply

In this second case, pbapply needs to be installed and called explicitly via :: or NAMESPACE. This might be preferred if many functions utilize the progress bar.

pbapply needs to be added to the Depends or Imports field in the DESCRIPTION file. Use pbapply functions either as pbapply::pblapply() or specify them in the NAMESPACE (e.g. importFrom(pbapply, pblapply)) and use it as pblapply() (without the ::).

See a small R package here for an example (see R CMD check log on Travis CI: Build Status).

Customizing the progress bar

Other than aesthetical reasons, there are cases when customizing the progress bar is truly necessary. For example, when working with a GUI, the default text based progress bar might not be appropriate and developers want a Windows or Tcl/Tk based progress bar.

In such cases, one can specify the progress bar options in the /R/zzz.R file of the package. The following example shows the default settings, but any of those list elements can be modified (see ?pboptions for acceptable values):

.onAttach <- function(libname, pkgname){
    options("pboptions" = list(
        type = if (interactive()) "timer" else "none",
        char = "-",
        txt.width = 50,
        gui.width = 300,
        style = 3,
        initial = 0,
        title = "R progress bar",
        label = "",
        nout = 100L))
    invisible(NULL)
}

Specifying the progress bar options this way will set the options before pbapply is loaded. pbapply will not override these settings. It is possible to specify a partial list of options (from pbapply version 1.3-0 and above).

Suppressing the progress bar

Suppressing the progress bar is sometimes handy. By default, progress bar is suppressed when !interactive(). This is an important feature, so that Sweave, knitr, and R markdown documents are not polluted with a really long printout of the progress bar. (Although, it is possible to turn the progress bar back on within such documents.)

In an interactive session, put this inside a function to disable the progress bar (and reset it when exiting the function):

pbo <- pboptions(type = "none")
on.exit(pboptions(pbo))

I hope that this little tutorial helps getting a progress bar where it belongs. Suggestions and feature requests are welcome. Leave a comment or visit the GitHub repo.

Update (2017-10-02): the number of R packages that reverse depend/import/suggest pbapply has more than doubled in a year (47: 5/32/10).

Statistical computing meets biodiversity conservation and natural resource management

What is new in the intrval R package?

An update (v 0.1-1) of the intrval package was recently published on CRAN. The package simplifies interval related logical operations (read more about the motivation in this post). So what is new in this version? Some of the inconsistencies in the 1st CRAN release have been cleaned up, and I have been pushed hard (see GitHub issue to implement all the 16 interval-to-interval operators. These operators define the open/closed nature of the lower/upper limits of the intervals on the left and right hand side of the o in the middle as in c(a1, b1) %[]o[]% c(a2, b2).

ABMI (6) ARU (1) C (1) CRAN (1) Hungary (1) JOSM (2) PVA (1) QPAD (1) R (15) R packages (1) bioacoustics (1) biodiversity (1) birds (2) course (2) data (1) data cloning (3) dclone (3) dependencies (1) detect (2) footprint (3) forecasting (1) functions (3) intrval (2) mefa4 (1) monitoring (2) pbapply (4) plyr (1) poster (2) processing time (1) progress bar (3) publications (1) report (1) sector effects (1) single visit (1) site (1) slides (2) special (3) species (1) trend (1) tutorials (2) video (4)