R: Timer Progress Bar

timerProgressBar {pbapply} | R Documentation

## Timer Progress Bar

### Description

Text progress bar with timer in the R console.

### Usage

    timerProgressBar(min = 0, max = 1, initial = 0, char = "=",
        width = NA, title, label, style = 1, file = "", min_time = 0)
    getTimerProgressBar(pb)
    setTimerProgressBar(pb, value, title = NULL, label = NULL)

### Arguments

`min, max` | (finite) numeric values for the extremes of the progress bar. Must have `min` < `max`.
`initial, value` | initial or new value for the progress bar. See Details for what happens with invalid values.
`char` | he character (or character string) to form the progress bar. If number of characters is >1, it is silently stripped to length 1 unless `style` is 5 or 6 (see Details).
`width` | the width of the progress bar, as a multiple of the width of char. If `NA`, the default, the number of characters is that which fits into `getOption("width")`.
`style` | the style taking values between 1 and 6. 1: progress bar with elapsed and remaining time, remaining percentage is indicated by spaces between pipes (default for this function), 2: throbber with elapsed and remaining time, 3: progress bar with remaining time printing elapsed time at the end, remaining percentage is indicated by spaces between pipes (default for `style` option in `pboptions`), 4: throbber with remaining time printing elapsed time at the end, 5: progress bar with elapsed and remaining time with more flexible styling (see Details and Examples), 6: progress bar with remaining time printing elapsed time at the end with more flexible styling (see Details and Examples).
`file` | an open connection object or `""` which indicates the console.
`min_time` | numeric, minimum processing time (in seconds) required to show a progress bar.
`pb` | an object of class `"timerProgressBar"`.
`title, label` | ignored, for compatibility with other progress bars.

### Details

`timerProgressBar` will display a progress bar on the R console (or a connection) via a text representation.

`setTimerProgessBar` will update the value. Missing (`NA`) and out-of-range values of value will be (silently) ignored. (Such values of `initial` cause the progress bar not to be displayed until a valid value is set.)

The progress bar should be closed when finished with: this outputs the final newline character (see `closepb`).

If `style` is 5 or 6, it is possible to define up to 4 characters for the `char` argument (as a single string) for the left end, elapsed portion, remaining portion, and right end of the progress bar (`|= |` by default). Remaining portion cannot be the same as the elapsed portion (space is used for remaining in such cases). If 1 character is defined, it is taken for the elapsed portion. If 2-4 characters are defined, those are interpreted in sequence (left and right end being the same when 2-3 characters defined), see Examples.

### Value

For `timerProgressBar` an object of class `"timerProgressBar"` inheriting from `"txtProgressBar"`.

For `getTimerProgressBar` and `setTimerProgressBar`, a length-one numeric vector giving the previous value (invisibly for `setTimerProgressBar`).

### Author(s)

Zygmunt Zawadzki <zawadzkizygmunt@gmail.com>

Peter Solymos <solymos@ualberta.ca>

### See Also

The `timerProgressBar` implementation follows closely the code of `txtProgressBar`.

### Examples

    ## increase sluggishness to admire the progress bar longer
    sluggishness <- 0.02

    test_fun <- function(...)
    {
        pb <- timerProgressBar(...)
        on.exit(close(pb))
        for(i in seq(0, 1, 0.05)) {
            Sys.sleep(sluggishness)
            setTimerProgressBar(pb, i)
        }
        invisible(NULL)
    }

    ## check the different styles
    test_fun(width = 35, char = "+", style = 1)
    test_fun(style = 2)
    test_fun(width = 50, char = ".", style = 3)
    test_fun(style = 4)
    test_fun(width = 35, char = "[=-]", style = 5)
    test_fun(width = 50, char = "{*.}", style = 6)

    ## no bar only percent and elapsed
    test_fun(width = 0, char = "    ", style = 6)

    ## this should produce a progress bar based on min_time
    (elapsed <- system.time(test_fun(width = 35, min_time = 0))["elapsed"])
    ## this should not produce a progress bar based on min_time
    system.time(test_fun(min_time = 2 * elapsed))["elapsed"]

[Package pbapply version 1.3-3 Index]