File: README.md

package info (click to toggle)
r-cran-purrrogress 0.1.1-3
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 224 kB
  • sloc: sh: 13; makefile: 2
file content (212 lines) | stat: -rw-r--r-- 7,742 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212

<!-- README.md is generated from README.Rmd. Please edit that file -->

# purrrogress

<!-- badges: start -->

[![Travis build
status](https://travis-ci.org/halpo/purrrogress.svg?branch=master)](https://travis-ci.org/halpo/purrrogress)
[![Codecov test
coverage](https://codecov.io/gh/halpo/purrrogress/branch/master/graph/badge.svg)](https://codecov.io/gh/halpo/purrrogress?branch=master)
<!-- badges: end -->

The goal of purrrogress is to add as simply as possible progress bars to
[`purrr`](http://purrr.tidyverse.org) mapping functions.

## Installation

You can install the released version of purrrogress from
[CRAN](https://CRAN.R-project.org) with:

``` r
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.

``` r
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.

``` r
# 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.

``` r
# 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.

``` r
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](https://glue.tidyverse.org/) style keywords. These keywords are
added by default:

  - `total` - the total number of elements.
  - `current` - the current number of elements completed.
  - `frac` - an alias for `"{current}/{total}"`, giving the nicely
    formatted fraction of completed elements.
  - `percent` - the percent completed as a whole number percent.
  - `elapsed.time` - The total time elapsed from the start to the
    completion of the last `step()` or `update()` call, typically the
    last element completion.
  - `average.time` - The average time to complete each step.
  - `estimated.total.time` - a naive estimate of the total time
    remaining. Taken as the `average.time * total`.
  - `estimated.time.remaining` - Just what is says,
    `estimated.total.time - elapsed.time`.
  - `etr` - alias for `estimated.time.remaining`

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

``` r
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.

``` r
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.

  - **`init()`** - This is called at the beginning of a loop or apply
    function. It should contain the code to actually create and show the
    progress bar window. Variables that are used to monitor and control
    the progress windows through other steps should be initialized here.
    It should additionally call `super$init()` to start timers. The
    return value should be `invisible(self)`.
  - **`term()`** - This is called to close any open windows, close
    connections and free resources. After `term()` is called the
    progress object should be unusable. There is no need to call
    `super$term()` at this time but is it provided for good practice.
    The return value is expected to be `invisible(NULL)`.
  - **`update(...)`** - This takes any number of arguments which may be
    used to update internal variables or displays. This should handle
    updating of the progress window, titles, labels, etc. The return
    value is expected to be `invisible(self)`.

#### 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.

  - **`step(n=1L, ..., keep.open=FALSE)`** - This is called to increment
    the internal progress counter, it in turn calls `update(...)`
    function the update any windows, titles and labels. The `n` argument
    is provided to allow for taking uneven steps. The `keep.open`
    argument is provided to allow for windows that stay open to show
    relevant information, such as total time or average time per step.
    If `keep.open` is false (default) when the current counter reaches
    the total `term()` will be called.
  - **`initialize(...)`** - populates the initial values of `title`,
    `label`, and `initial` count, which cannot be changed once
    specified.
  - **`add_binding()`** - adds an active binding which may be used in
    the title or label.
  - **`add_bindings(...)`** - a more convenient way to specify multiple
    bindings at once in the form of `add_bindings(name=funtion(){...})`.
  - **`expose(sym)`** - The most convenient way of binding variable to
    use in the title or label. When called the variable from the current
    scope is added to the available bindings so that it may be
    referenced in the title or label.

# Acknowledgements

This project was inspired by a post to
[R-Bloggers](https://www.r-bloggers.com/purrring-progress-bars-adding-a-progress-bar-to-purrrmap/)
by Adi Sarid. Credit goes to him for the original idea on which
`purrrogress` is built.