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
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
+
6
+
<imgsrc="incl/three_in_chinese.gif"alt="Three strokes writing three in Chinese"style="float: right; margin-right: 1ex; margin-left: 1ex;"/>
7
+
5
8
Design motto:
6
9
7
10
> The developer is responsible for providing progress updates but it's only the end user who decides if, when, and how progress should be presented. No exceptions will be allowed.
8
11
12
+
9
13
## Two Minimal APIs
10
14
11
15
| Developer's API | End-user's API |
@@ -15,6 +19,7 @@ Design motto:
15
19
||`options(progressr.*=...)`|
16
20
17
21
22
+
18
23
## A simple example
19
24
20
25
Assume that we have a function `slow_sum()` for adding up the values in a vector. It is so slow, that we like to provide progress updates to whoever might be interested in it. With the **progressr** package, this can be done as:
@@ -59,7 +64,7 @@ To get progress updates, we can call it as:
59
64
60
65
## Customizing how progress is reported
61
66
62
-
The default is to present progress via `utils::txtProgressBar()`, which is available on all R installations. To change the default, to, say, `progress_bar()` by the **[progress]** package, set the following R option(\*):
67
+
The default is to present progress via `utils::txtProgressBar()`, which is available on all R installations. To change the default, to, say, `progress_bar()` by the **[progress]** package, set:
63
68
64
69
```r
65
70
handlers("progress")
@@ -70,6 +75,9 @@ This progress handler will present itself as:
To set the default progress handler(s) in all your R sessions, call `progressr::handlers(...)` in your <code>~/.Rprofile</code> file. An alternative, which avoids loading the **progressr** package if never used, is to set `options(progressr.handlers = progress_handler)`.
79
+
80
+
73
81
74
82
### Auditory progress updates
75
83
@@ -114,7 +122,7 @@ with_progress({
114
122
115
123
### The future framework
116
124
117
-
The **[future]** framework has built-in support for the kind of progression updates produced by the **progressr** package. 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:
125
+
The **[future]** framework has built-in support for the kind of progression updates produced by the **progressr** package. 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:
118
126
119
127
```r
120
128
library(future.apply)
@@ -162,7 +170,7 @@ When using the **progressr** package, progression updates are communicated via R
162
170
163
171
164
172
165
-
_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 choosen._
173
+
_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._
166
174
167
175
168
176
### Debugging
@@ -186,10 +194,6 @@ To debug progress updates, use:
Copy file name to clipboardExpand all lines: R/options.R
+14-2Lines changed: 14 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -62,12 +62,24 @@
62
62
#'
63
63
#'
64
64
#' @seealso
65
-
#' To set \R options when \R starts (even before the \pkg{progressr} package is loaded), see the \link[base]{Startup} help page. The \href{https://cran.r-project.org/package=startup}{\pkg{startup}} package provides a friendly mechanism for configurating \R's startup process.
65
+
#' To set \R options when \R starts (even before the \pkg{progressr} package is loaded), see the \link[base]{Startup} help page. The \href{https://cran.r-project.org/package=startup}{\pkg{startup}} package provides a friendly mechanism for configuring \R at startup.
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.
6
6
7
+
8
+
<imgsrc="incl/three_in_chinese.gif"alt="Three strokes writing three in Chinese"style="float: right; margin-right: 1ex; margin-left: 1ex;"/>
9
+
7
10
Design motto:
8
11
9
12
> The developer is responsible for providing progress updates but it's only the end user who decides if, when, and how progress should be presented. No exceptions will be allowed.
10
13
14
+
11
15
## Two Minimal APIs
12
16
13
17
| Developer's API | End-user's API |
@@ -17,6 +21,7 @@ Design motto:
17
21
||`options(progressr.*=...)`|
18
22
19
23
24
+
20
25
## A simple example
21
26
22
27
Assume that we have a function `slow_sum()` for adding up the values in a vector. It is so slow, that we like to provide progress updates to whoever might be interested in it. With the **progressr** package, this can be done as:
@@ -61,7 +66,7 @@ To get progress updates, we can call it as:
61
66
62
67
## Customizing how progress is reported
63
68
64
-
The default is to present progress via `utils::txtProgressBar()`, which is available on all R installations. To change the default, to, say, `progress_bar()` by the **[progress]** package, set the following R option(\*):
69
+
The default is to present progress via `utils::txtProgressBar()`, which is available on all R installations. To change the default, to, say, `progress_bar()` by the **[progress]** package, set:
65
70
66
71
```r
67
72
handlers("progress")
@@ -72,6 +77,9 @@ This progress handler will present itself as:
To set the default progress handler(s) in all your R sessions, call `progressr::handlers(...)` in your <code>~/.Rprofile</code> file. An alternative, which avoids loading the **progressr** package if never used, is to set `options(progressr.handlers = progress_handler)`.
81
+
82
+
75
83
76
84
### Auditory progress updates
77
85
@@ -116,7 +124,7 @@ with_progress({
116
124
117
125
### The future framework
118
126
119
-
The **[future]** framework has built-in support for the kind of progression updates produced by the **progressr** package. 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:
127
+
The **[future]** framework has built-in support for the kind of progression updates produced by the **progressr** package. 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:
120
128
121
129
```r
122
130
library(future.apply)
@@ -164,7 +172,7 @@ When using the **progressr** package, progression updates are communicated via R
164
172
165
173
166
174
167
-
_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 choosen._
175
+
_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._
168
176
169
177
170
178
### Debugging
@@ -188,10 +196,6 @@ To debug progress updates, use:
0 commit comments