R: Creating Progress Bar and Setting Options

pboptions {pbapply} | R Documentation

## Creating Progress Bar and Setting Options

### Description

Creating progress bar and setting options.

### Usage

    pboptions(...)
    startpb(min = 0, max = 1)
    setpb(pb, value)
    getpb(pb)
    closepb(pb)
    dopb()

### Arguments

`...` | Arguments in `tag = value` form, or a list of tagged values. The tags must come from the parameters described below.
`pb` | A progress bar object created by `startpb`.
`min, max` | Finite numeric values for the extremes of the progress bar. Must have `min < max`.
`value` | New value for the progress bar.

### Details

`pboptions` is a convenient way of handling options related to progress bar.

Other functions can be used for conveniently adding progress bar to `for`-like loops (see Examples).

### Value

When parameters are set by `pboptions`, their former values are returned in an invisible named list. Such a list can be passed as an argument to `pboptions` to restore the parameter values. Tags are the following:

`type` | Type of the progress bar: timer (`"timer"`), text (`"txt"`), Windows (`"win"`), TclTk (`"tk"`), or none (`"none"`). Default value is `"timer"` progress bar with estimated remaining time when in interactive mode, and `"none"` otherwise.
`char` | The character (or character string) to form the progress bar. Default value is `"+"`.
`txt.width` | The width of the text based progress bar, as a multiple of the width of `char`. If `NA`, the number of characters is that which fits into `getOption("width")`. Default value is `50`.
`gui.width` | The width of the GUI based progress bar in pixels: the dialogue box will be 40 pixels wider (plus frame). Default value is `300`.
`style` | The style of the bar, see `txtProgressBar` and `timerProgressBar`. Default value is `3`.
`initial` | Initial value for the progress bar. Default value is `0`.
`title` | Character string giving the window title on the GUI dialogue box. Default value is `"R progress bar"`.
`label` | Character string giving the window label on the GUI dialogue box. Default value is `""`.
`nout` | Integer, the maximum number of times the progress bar is updated. The default value is 100. Smaller value minimizes the running time overhead related to updating the progress bar. This can be especially important for forking type parallel runs.
`min_time` | Minimum time in seconds. `timerProgressBar` output is printed only if estimated completion time is higher than this value. The default value is 0.

For `startpb` a progress bar object.

For `getpb` and `setpb`, a length-one numeric vector giving the previous value (invisibly for `setpb`). The return value is `NULL` if the progress bar is turned off by `getOption("pboptions")$type` (`"none"` or `NULL` value).

`dopb` returns a logical value if progress bar is to be shown based on the option `getOption("pboptions")$type`. It is `FALSE` if the type of progress bar is `"none"` or `NULL`.

For `closepb` closes the connection for the progress bar.

### Author(s)

Peter Solymos <solymos@ualberta.ca>

### See Also

Progress bars used in the functions: `winProgressBar`, `timerProgressBar`, `txtProgressBar`, `tkProgressBar`

### Examples

    ## for loop
    fun1 <- function() {
        pb <- startpb(0, 10)
        on.exit(closepb(pb))
        for (i in 1:10) {
            Sys.sleep(0.15)
            setpb(pb, i)
        }
        invisible(NULL)
    }
    ## while loop
    fun2 <- function() {
        pb <- startpb(0, 10-1)
        on.exit(closepb(pb))
        i <- 1
        while (i < 10) {
            Sys.sleep(0.15)
            setpb(pb, i)
            i <- i + 1
        }
        invisible(NULL)
    }
    ## using original settings
    fun1()
    ## resetting pboptions
    opb <- pboptions(style = 1, char = ">")
    ## check new settings
    getOption("pboptions")
    ## running again with new settings
    fun2()
    ## resetting original
    pboptions(opb)
    ## check reset
    getOption("pboptions")
    fun1()

    ## dealing with nested progress bars
    ## when only one the 1st one is needed
    f <- function(x) Sys.sleep(0.01)
    g <- function(x) pblapply(1:10, f)
    tmp <- lapply(1:10, g) # undesirable
    ## here is the desirable solution
    h <- function(x) {
        opb <- pboptions(type="none")
        on.exit(pboptions(opb))
        pblapply(1:10, f)
    }
    tmp <- pblapply(1:10, h)

[Package pbapply version 1.3-3 Index]