futureverse /progressr
三 R package: An Inclusive, Unifying API for Progress Updates
★ 299⑂ 11👁 5⑃ 8● 180▤ 0
+0
Daily
299
stars
11
forks
5
watchers
8
prs
180
issues
0
releases
README
progressr: An Inclusive, Unifying API for Progress Updates
The [progressr] package provides a minimal API for reporting
progress updates in R. 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] framework is designed
to work out-of-the-box also for parallel and distributed processing,
especially with the [futureverse] ecosystem.
Design motto:
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.
Two Minimal APIs - One For Developers and One For End-Users
Developer's API
1. Set up a progressor with a certain number of steps:
p <- progressor(nsteps)
p <- progressor(along = x)
2. Signal progress:
p() one-step progress
p(amount = 0) "still alive"
p("loading ...") pass on a message
End-user's API
1a. Subscribe to progress updates from everywhere:
handlers(global = TRUE)
y <- slow_sum_p(1:5)
y <- slow_sum_p(6:10)
1b. Subscribe to a specific expression:
with_progress({
y <- slow_sum_p(1:5)
y <- slow_sum_p(6:10)
})
2. Configure how progress is presented:
handlers("cli")
handlers("progress")
handlers("txtprogressbar", "beepr")
handlers(handler_pbcol(enable_after = 3.0))
handlers(handler_progress(complete = ""))
A simple example
Assume that we have a function slow_sum_p() 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:
r
slow_sum_p [1] 55
the default is that there will be _no_ progress updates. To get
progress updates, we need to request them to be "handled", which we do
by:
r
progressr::handlers(global = TRUE)
After this, progress will be reported:
r
y |==================== | 40%
y |======================================== | 80%
To disable reporting again, do:
r
handlers(global = FALSE)
Customizing how progress is reported
By default, [progressr] presents progress via the built-in
utils::txtProgressBar(). It presents itself as a rudimentary
ASCII-based horizontal progress bar in the R terminal. See
help("handler_txtprogressbar") for how to customize the look of
"txtprogressbar", e.g. colorization and Unicode. There are many other
ways to report on progress, including visually, auditory, and via
notification systems. You can also use a mix of these, e.g.
r
handlers(c("cli", "beepr", "ntfy"))
See the 'Customizing How Progress is Reported' vignette for examples.
AddiTop issues
#83Creating a progressor object outside `with_progress()`?12 comments · 2020-08-06#78Adding a progress bar by default in a package10 comments · 2020-05-02#13progressor(steps, props)7 comments · 2019-04-24#143Play incremental tone for audio progress bar6 comments · 2022-09-11#155Detect registered progress handler5 comments · 2023-01-31#2PERFORMANCE: Avoid progress updates if no one is listening5 comments · 2019-04-12#142Any way to inform ETA estimate with prior info?3 comments · 2022-08-25#29add_progress({ ... ])3 comments · 2019-05-09