How to add pbapply to R packages?

September 6, 2016
By

(This article was first published on Peter Solymos - R related posts, and kindly contributed to R-bloggers)

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.

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"))
   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.

To leave a comment for the author, please follow the link and comment on their blog: Peter Solymos - R related posts.

R-bloggers.com offers daily e-mail updates about R news and tutorials on topics such as: Data science, Big Data, R jobs, visualization (ggplot2, Boxplots, maps, animation), programming (RStudio, Sweave, LaTeX, SQL, Eclipse, git, hadoop, Web Scraping) statistics (regression, PCA, time series, trading) and more...



If you got this far, why not subscribe for updates from the site? Choose your flavor: e-mail, twitter, RSS, or facebook...

Comments are closed.

Sponsors

Never miss an update!
Subscribe to R-bloggers to receive
e-mails with the latest R posts.
(You will not see this message again.)

Click here to close (This popup will not appear again)