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
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
1
Package: progressr
2
-
Version: 0.1.3
2
+
Version: 0.1.3-9000
3
3
Title: A Unifying API for Progress Updates
4
4
Description: A minimal API for reporting progress updates upstream. 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.
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.
2
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
+
3
8
Design motto:
4
9
5
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.
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:
@@ -49,24 +64,27 @@ To get progress updates, we can call it as:
49
64
50
65
## Customizing how progress is reported
51
66
52
-
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:
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
+
63
81
64
82
### Auditory progress updates
65
83
66
84
Note all progress updates have to be presented visually. This can equally well be done auditory. For example, using:
67
85
68
86
```r
69
-
options(progressr.handlers=beepr_handler)
87
+
handlers("beepr")
70
88
```
71
89
will present itself as sounds played at the beginning, while progressing, and at the end (using different **[beepr]** sounds). There will be _no_ output written to the terminal;
72
90
```r
@@ -81,7 +99,7 @@ will present itself as sounds played at the beginning, while progressing, and at
81
99
82
100
It is possible to have multiple progress handlers presenting progress updates at the same time. For example, to get both visual and auditory updates, use:
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:
Because this project is under active development, the progressr API is currently kept at a very minimum. This will allow for the framework and the API to evolve while minimizing the risk for breaking code that depends on it. The roadmap for developing the API is roughly:
@@ -117,13 +159,26 @@ For a more up-to-date view on what features might be added, see <https://github.
117
159
118
160
## Appendix
119
161
162
+
### Under the hood
163
+
164
+
When using the **progressr** package, progression updates are communicated via R's condition framework, which provides methods for creating, signaling, capturing, muffling, and relaying conditions. Progression updates are of classes `progression` and `immediateCondition`(\*). The below figure gives an example how progression conditions are created, signaled, and rendered.
165
+
166
+
(\*) The `immediateCondition` class of conditions are relayed as soon as possible by the **[future]** framework, which means that progression updates produced in parallel workers are reported to the end user as soon as the main R session have received them.
167
+
168
+
169
+
170
+
171
+
172
+
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._
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.
4
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
+
5
10
Design motto:
6
11
7
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.
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:
@@ -48,26 +63,30 @@ To get progress updates, we can call it as:
48
63
|=====================|40%
49
64
```
50
65
66
+
51
67
## Customizing how progress is reported
52
68
53
-
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:
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
+
64
83
65
84
### Auditory progress updates
66
85
67
86
Note all progress updates have to be presented visually. This can equally well be done auditory. For example, using:
68
87
69
88
```r
70
-
options(progressr.handlers=beepr_handler)
89
+
handlers("beepr")
71
90
```
72
91
will present itself as sounds played at the beginning, while progressing, and at the end (using different **[beepr]** sounds). There will be _no_ output written to the terminal;
73
92
```r
@@ -82,7 +101,7 @@ will present itself as sounds played at the beginning, while progressing, and at
82
101
83
102
It is possible to have multiple progress handlers presenting progress updates at the same time. For example, to get both visual and auditory updates, use:
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:
Because this project is under active development, the progressr API is currently kept at a very minimum. This will allow for the framework and the API to evolve while minimizing the risk for breaking code that depends on it. The roadmap for developing the API is roughly:
@@ -120,16 +163,24 @@ For a more up-to-date view on what features might be added, see <https://github.
120
163
121
164
### Under the hood
122
165
166
+
When using the **progressr** package, progression updates are communicated via R's condition framework, which provides methods for creating, signaling, capturing, muffling, and relaying conditions. Progression updates are of classes `progression` and `immediateCondition`(\*). The below figure gives an example how progression conditions are created, signaled, and rendered.
167
+
168
+
(\*) The `immediateCondition` class of conditions are relayed as soon as possible by the **[future]** framework, which means that progression updates produced in parallel workers are reported to the end user as soon as the main R session have received them.
169
+
170
+
171
+
172
+
123
173
124
174
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._
0 commit comments