You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: DESCRIPTION
+6-3Lines changed: 6 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
Package: progressr
2
-
Version: 0.3.0
2
+
Version: 0.4.0
3
3
Title: A Unifying API for Progress Updates
4
-
Description: A minimal, unifying API for scripts and packages to report progress updates. By design, it allows the developer to focus on what progress that should be reported on, without having to worry about how to present it. The end user has full control on how, where, and when to render these progress updates, e.g. in the terminal using 'utils::txtProgressBar()' or 'progress::progress_bar()', in a graphical user interface using 'utils::winProgressBar()', 'tcltk::tkProgressBar()' or 'shiny::withProgress()', via the speakers using 'beep::beepr()', or on a file system via the size of a file. Anyone can add additional, customized, progression handlers. The 'progressr' package uses R's condition framework for signaling progress updated. Because of this, progress can be reported from almost anywhere in R, e.g. from classical for and while loops, from map-reduce APIs like the 'lapply()' family of functions, 'purrr', 'plyr', and 'foreach'. It will also work with parallel processing via the 'future' framework, e.g. 'future.apply::future_lapply()', 'furrr::map()', and 'foreach' with 'doFuture'.
4
+
Description: A minimal, unifying API for scripts and packages to report progress updates from anywhere including when using parallel processing. The package is designed such that the developer can to focus on what progress should be reported on without having to worry about how to present it. The end user has full control of how, where, and when to render these progress updates, e.g. in the terminal using 'utils::txtProgressBar()' or 'progress::progress_bar()', in a graphical user interface using 'utils::winProgressBar()', 'tcltk::tkProgressBar()' or 'shiny::withProgress()', via the speakers using 'beep::beepr()', or on a file system via the size of a file. Anyone can add additional, customized, progression handlers. The 'progressr' package uses R's condition framework for signaling progress updated. Because of this, progress can be reported from almost anywhere in R, e.g. from classical for and while loops, from map-reduce APIs like the 'lapply()' family of functions, 'purrr', 'plyr', and 'foreach'. It will also work with parallel processing via the 'future' framework, e.g. 'future.apply::future_lapply()', 'furrr::map()', and 'foreach' with 'doFuture'. The package is compatible with Shiny applications.
The **[progressr]** package provides a minimal API for reporting progress updates in [R](https://www.r-project.org/). The design is to separate the representation of progress updates from how they are presented. What type of progress to signal is controlled by the developer. How these progress updates are rendered is controlled by the end user. For instance, some users may prefer visual feedback such as a horizontal progress bar in the terminal, whereas others may prefer auditory feedback.
4
4
5
5
6
-
<imgsrc="incl/three_in_chinese.gif"alt="Three strokes writing three in Chinese"style="float: right; margin-right: 1ex; margin-left: 1ex;"/>
6
+
<imgsrc="imgs/three_in_chinese.gif"alt="Three strokes writing three in Chinese"style="float: right; margin-right: 1ex; margin-left: 1ex;"/>
Note that progression updates by **progressr** is designed to work out of the box for any _sequential_ iterator framework in R. Here is an set of examples for the most common ones:
108
+
Note that progression updates by **progressr** is designed to work out of the box for any _sequential_ iterator framework in R. Below is an set of examples for the most common ones.
109
+
110
+
111
+
### Base R Apply Functions
109
112
110
113
```r
111
114
library(progressr)
112
115
113
116
xs<-1:5
114
-
y_truth<- lapply(xs, slow_sqrt)
115
117
116
118
with_progress({
117
119
p<- progressor(along=xs)
@@ -121,8 +123,17 @@ with_progress({
121
123
sqrt(x)
122
124
})
123
125
})
126
+
# |===================== | 40%
127
+
```
128
+
129
+
### The foreach package
124
130
131
+
```r
125
132
library(foreach)
133
+
library(progressr)
134
+
135
+
xs<-1:5
136
+
126
137
with_progress({
127
138
p<- progressor(along=xs)
128
139
y<- foreach(x=xs) %do% {
@@ -131,8 +142,17 @@ with_progress({
131
142
sqrt(x)
132
143
}
133
144
})
145
+
# |===================== | 40%
146
+
```
134
147
148
+
### The purrr package
149
+
150
+
```r
135
151
library(purrr)
152
+
library(progressr)
153
+
154
+
xs<-1:5
155
+
136
156
with_progress({
137
157
p<- progressor(along=xs)
138
158
y<- map(xs, function(x) {
@@ -141,15 +161,34 @@ with_progress({
141
161
sqrt(x)
142
162
})
143
163
})
164
+
# |===================== | 40%
144
165
```
145
166
167
+
### The plyr package
168
+
169
+
The functions in the [**plyr**](https://cran.r-project.org/package=plyr) package take argument `.progress`, which can be used to produce progress updates. To have them generate **progressr** 'progression' updates, use `.progress = "progressr"`. For example,
170
+
```r
171
+
library(plyr)
172
+
library(progressr)
146
173
147
-
### Parallel processing and progress updates
174
+
xs<-1:5
175
+
176
+
with_progress({
177
+
y<- llply(xs, function(x, ...) {
178
+
Sys.sleep(0.1)
179
+
sqrt(x)
180
+
}, .progress="progressr")
181
+
})
182
+
# |===================== | 40%
183
+
```
184
+
185
+
186
+
## Parallel processing and progress updates
148
187
149
188
The **[future]** framework, which provides a unified API for parallel and distributed processing in R, has built-in support for the kind of progression updates produced by the **progressr** package. This means that you can use it with for instance **[future.apply]**, **[furrr]**, and **[foreach]** with **[doFuture]**.
150
189
151
190
152
-
####future_lapply() - parallel lapply()
191
+
### future_lapply() - parallel lapply()
153
192
154
193
Here is an example that uses `future_lapply()` of the **[future.apply]** package to parallelize on the local machine while at the same time signaling progression updates:
155
194
@@ -174,7 +213,7 @@ with_progress({
174
213
```
175
214
176
215
177
-
####foreach() with doFuture
216
+
### foreach() with doFuture
178
217
179
218
Here is an example that uses `foreach()` of the **[foreach]** package to parallelize on the local machine (via **[doFuture]**) while at the same time signaling progression updates:
180
219
@@ -200,7 +239,7 @@ with_progress({
200
239
```
201
240
202
241
203
-
####future_map() - parallel purrr::map()
242
+
### future_map() - parallel purrr::map()
204
243
205
244
```r
206
245
library(furrr)
@@ -225,26 +264,7 @@ with_progress({
225
264
226
265
### The plyr package
227
266
228
-
The functions in the [**plyr**](https://cran.r-project.org/package=plyr) package take argument `.progress`, which can be used to produce progress updates. To have them generate **progressr** 'progression' updates, use `.progress = "progressr"`. For example,
229
-
```r
230
-
library(plyr)
231
-
library(progressr)
232
-
233
-
xs<-1:5
234
-
235
-
with_progress({
236
-
y<- l_ply(xs, function(x, ...) {
237
-
Sys.sleep(6.0-x)
238
-
sqrt(x)
239
-
}, .progress="progressr")
240
-
})
241
-
## |===================== | 40%
242
-
```
243
-
244
-
_Comment_: This also works when using `.parallel = TRUE` with a **[foreach]** parallel-backend such as **[doParallel]** or **[doFuture]** registered.
245
-
246
-
247
-
267
+
Unfortunately, when using `.parallel = TRUE`, the **plyr** package resets `.progress` to the default `"none"` internally regardless how we set `.progress`. This prevents **progressr** progression updates from being used with _parallel_**plyr**. If it was not for this forced reset, using `doFuture::registerDoFuture()` with `.parallel = TRUE` and `.progress = "progressr"` would indeed have reported on progress updates also when **plyr** runs in parallel. See <https://github.com/HenrikBengtsson/progressr/issues/70> for a hack that works around this limitation.
248
268
249
269
250
270
## Roadmap
@@ -271,7 +291,7 @@ When using the **progressr** package, progression updates are communicated via R
271
291
272
292
273
293
274
-
294
+
275
295
276
296
_Figure: Sequence diagram illustrating how signaled progression conditions are captured by `with_progress()` and relayed to the two progression handlers 'progress' (a progress bar in the terminal) and 'beepr' (auditory) that the end user has chosen._
0 commit comments