Add a `progressr`-based progress bar for sampling. by josswright · Pull Request #1138 · stan-dev/cmdstanr

josswright · 2026-02-13T20:59:47Z

Submission Checklist

Run unit tests
Declare copyright holder and agree to license (see below)

Summary

As discussed in #18 , this pull request adds a progress bar to CmdStanR's sample() function via the progressr framework.

This can be enabled via two new options to model$sample(...):

show_progress_bar - boolean - default FALSE
Enables the progress bar.
suppress_iteration_messages - boolean - default FALSE if show_progress_bar is FALSE, and TRUE if show_progress_bar is TRUE.
Causes any output lines reporting an iteration (such as Chain 1 Iteration 1 / 2000 (Warmup)) to be suppressed.

For the progress bar to be displayed, a progress bar handler must be created and registered by the end user. (See: https://progressr.futureverse.org/) For ease of use, a register_default_progress_handler() function has been added. Calling register_default_progress_handler() before a model$sample(...) call will spawn a default progress bar via the cli library.

Copyright and Licensing

Please list the copyright holder for the work you are submitting
(this will be you or your assignee, such as a university or company):

Joss Wright, University of Oxford

By submitting this pull request, the copyright holder is agreeing to
license the submitted work under the following licenses:

Code: BSD 3-clause (https://opensource.org/licenses/BSD-3-Clause)
Documentation: CC-BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

This uses the [`progressr`](https://progressr.futureverse.org/index.html) framework to enable a progress bar for sampling operations. By default, this replaces standard iteration messages, but not other informative messages produced during sampling. From a user point of view, this adds two arguments to the `$sample()` method: - `show_progress_bar`: Default = FALSE If TRUE, registers a progress bar via `progressr` and signals an update for every output line that matches "Iteration:". The user is responsible for registering those progress updates with an appropriate handler. - `suppress_iteration_messages`: Defaults to the value of show_progress_bar, but can also be set directly. If TRUE, disables display of output lines matching "Iteration:", while still causing the progress bar to update. This keeps all of Stan's other informative output, but just removes the superfluous iteration messages when using a progress bar. I've tried to keep all additions to the code as non-intrusive as possible. One minor decision I made was to pass the value of `refresh` from the `$sample()` method through to the `CmdStanProcs` class so that the progress bar can report and update the number of steps in the bar to the same 'scale' as the number of iterations. (Calling `$sample()` with `iter_sampling=8000` and `refresh=100` will result in 80 'ticks' of the progress bar, each increasing the progress by 100.) By default, `progressr` doesn't register a handler to display the progress bar, as this is the responsibility of the user. Multiple packages can be used to display the progress bar. A default progress bar can be registered using the [`cli`](https://cli.r-lib.org/) library in this way: ```r library(progressr) library(cli) handlers( global=TRUE ) handlers("cli") options( cli.spinner = "moon", cli.progress_show_after = 0, cli.progress_clear = FALSE ) handlers( handler_cli( format = "{cli::pb_spin} Progress: |{cli::pb_bar}| {cli::pb_current}/{cli::pb_total} | {cli::pb_percent} | ETA: {cli::pb_eta}", clear = FALSE )) ``` A variety of alternative progress bar handlers are available, including audible and notification-based handlers, and ones that interact with RStudio's jobs pane: <https://progressr.futureverse.org/articles/progressr-11-handlers.html>

In addition to updating the progress bar on stdout lines that match "Iteration:", the CmdStanProcs object(s) now pass the current stdout line to the progress bar as a message for _every_ line, even if the number of completed iterations hasn't increased.

Added a `register_default_progress_handler()` function to `utils.R` that creates a default progress bar for sampling operations and registers it as global handler for progressr. Requires `cli` and `progressr`.

Was accidentally passing `refresh` to each informational progress bar update, rather than the calculated `progress_amount`. This caused each message line to update the progress bar, even if it didn't match an iteration message.

Moved code to close the progress bar to after the `check_finished()` function.

…essr

The nature of CmdStan's output makes pulling appropriate refresh and update values for the progress bar slightly tricky. In the original verison of the code, this led to the bar occasionally updating past the point where it was full, or terminating early due to an incorrectly calculated number of steps. This commit reworks the calculations of updates and refresh values for the progress bar, as well as adding some extra conditions to avoid the bar potentially crashing in odd scenarios.

New arguments for `iter_warmup` and `iter_sampling` were not being assigned a default value if not specified in sampling statement.

VisruthSK · 2026-02-15T04:27:10Z

Looks like some tests are failing because the lower bound for iter_sampling should be 0 instead of 1.

josswright · 2026-02-15T14:45:09Z

Looks like some tests are failing because the lower bound for iter_sampling should be 0 instead of 1.

Great. Thanks for this. (First pull request for me on a project like this, so I was a little unfamiliar with the process and running the unit tests.)

I've fixed the initial errors, and a couple of other warnings. Now running the tests and documentation generation commands locally before I push an update.

- `iter_{warmup,sampling}` arguments to MCMCProcs are allowed to be 0. - Documentation for `register_default_progress_handler` added to repository. - Ensured that calls to `progressr` functions are appropriately prefixed.

codecov-commenter · 2026-02-15T18:43:22Z

Codecov Report

❌ Patch coverage is 88.52459% with 7 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (v1.0@9f5536f). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
R/run.R	92.72%	4 Missing ⚠️
R/model.R	50.00%	3 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             v1.0    #1138   +/-   ##
=======================================
  Coverage        ?   94.04%           
=======================================
  Files           ?       19           
  Lines           ?     7538           
  Branches        ?        0           
=======================================
  Hits            ?     7089           
  Misses          ?      449           
  Partials        ?        0

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Added documentation for `show_progress_bar` and `suppress_iteration_messages` in `sample()` function. Changed `require()` calls for `progressr` and `cli` to suggested `requireNamespace()` alternatives.

josswright · 2026-02-16T18:09:07Z

Thanks for the help with the unit tests.

In the spirit of peer review, some notes and thoughts:

I'm not entirely happy with CmdStan's default iter_warmup and iter_sampling values being hard-coded into MCMCProcs default call rather than derived somehow. I imagine that the default values are fairly fixed, but I would have liked not to rely on that. Every route I could see to getting them was clunky and brought in unnecessary code.
As mentioned above, I toyed with the idea of setting refresh to 1 by default when showing the progress bar with iteration messages suppressed. In the end that seemed to introduce yet another case of a parameter depending on another parameter, as well as a potential source of fragility. I'll note, though, that refresh can safely be set to 1 for a nice, smooth progress bar without any noticeable overhead or slowdown that I saw in testing.
The code to derive the number of steps for the progress bar is more complicated than I originally imagined because of how CmdStan reports iterations.

At one stage, when the number of steps was incorrectly calculated as too low, the progress bar was crashing, which also killed the sampling run. I've now ensured that the progress bar automatically closes when it reaches its finished number of steps, which should avoid crashes and just print a warning in the case of some output oddity causing more update steps to be signalled.

I've tested as extensively as I can, but I live in fear of this killing someone's multi-day sampling run.

jgabry · 2026-02-18T01:40:01Z

Awesome, thank you for the PR! I think I have the flu right now, but I will take a look when I'm feeling better and caught up on work.

josswright · 2026-02-18T14:49:20Z

Awesome, thank you for the PR! I think I have the flu right now, but I will take a look when I'm feeling better and caught up on work.

No rush on my side! Hope you feel better soon.

jgabry · 2026-02-26T23:31:59Z

I haven't forgotten about this, just dealing with a backlog of work. In the meantime, I posted on the Stan forum to hopefully get some more people to try it out and let us know how it goes:

https://discourse.mc-stan.org/t/please-help-test-a-new-progress-bar-for-sampling-in-cmdstanr/40946

I've tested as extensively as I can, but I live in fear of this killing someone's multi-day sampling run.

Should we maybe add something to the documentation about this? At least while the progress bar is still new we'll be gathering info about whether any users suffer this fate, so we could warn users that it's an experimental feature and to be cautious using it. Then eventually we can remove the experimental caveat from the doc. What do you think @josswright @VisruthSK?

jgabry · 2026-10-07T23:46:00Z

@VisruthSK awesome, looks like this handles everything in my review comments on #1313.

Looking back on some of my old review comments on this PR from before, I think there are a couple of small things we should add to the doc because users will want to know:

why it's one bar for all chains (RStudio's terminal only supports single-line bars, so progressr doesn't do per-chain ones)
an example of picking a non-default handler, such as progressr::handlers("cli")
that refresh = 1 gives a smooth bar for slow models (can go next to the sentence about the overhead for fast ones). In other words, for fast models refresh=1 adds too much overhead, but for slow models it doesn't add much overhead (relative to sampling speed) and it improves the smoothness of the progress bar.

And then one tiny thing I noticed in the "sample can suppress CmdStan iteration messages" test. capture.output() prints the returned fit in the test output. Can you do the assignment inside, i.e. capture.output(fit <- mod$sample(...)), which stops the print?

josswright · 2026-10-09T09:35:02Z

Just to say that I'm so sorry to have dropped the ball on this after the initial activity. Some rather complicated life things happened, which are still ongoing, and it's not left me much time.

jgabry · 2026-10-09T18:48:47Z

No worries at all @josswright! I really appreciate all the work you did to get this started and I think we can finish it from here. I'm going to add you as a contributor in the DESCRIPTION file on this branch so you'll be listed whenever this merges. Might be able to get it into the upcoming v1.0 release.

VisruthSK · 2026-10-09T19:23:27Z

Just wanted to second what Jonah said, thanks for tackling this and solving all the tough parts! Hope things are going okay for you.

jgabry · 2026-10-09T20:19:44Z

@avehtari coming back to your five comments from February now that this might get into the 1.0 release candidate:

The bar is still only for $sample() and $sample_mpi() in 1.0 and is labeled experimental, so we can extend it to $laplace() and $pathfinder() once we've seen if users like it.
Global option: options(cmdstanr_progress_bar = TRUE) works now
Still works with brms
register_default_progress_handler() is gone. Instead of calling that function, the user calls progressr::handlers(global = TRUE) directly and the docs now say to do it with if (interactive()) in a notebook's setup chunk to avoid a failure while the document renders
Fixed. While the progress bar is still up the per-chain "finished in ..." lines are held back and then printed together once the bar is done, right above the summary.

finish_progress() cleared the queue of held chain ids after printing them, so when a held "finished unexpectedly" warning became an error (options(warn = 2), or a tryCatch around $sample()) the deferred call printed the same lines again.

RStudio's console pane handles cursor-up sequences since rstudio/rstudio#17786 (May 2026), and cli flips its ansi_tty capability on for those versions (r-lib/cli#823), so multi-line bars will work in current RStudio but not older releases. One bar stays the design.

progressr's intro vignette asks packages to always signal progress and leave the decision to the user's handlers. CmdStanR keeps an argument on purpose: progressr scopes reporting to the session or to one call, not to a package, and the bar also replaces CmdStan's own iteration lines, which something has to decide to hide. Decided 2026-10-09.

jgabry · 2026-10-12T15:42:20Z

Merged! Thanks again @josswright. And thanks @VisruthSK for taking over. And thanks @avehtari for your review comments (they are all addressed now).

josswright and others added 10 commits December 21, 2025 22:55

Added convenience handler for progress bar

34d001d

Added a `register_default_progress_handler()` function to `utils.R` that creates a default progress bar for sampling operations and registers it as global handler for progressr. Requires `cli` and `progressr`.

Fixed progress update bug

a083a7e

Was accidentally passing `refresh` to each informational progress bar update, rather than the calculated `progress_amount`. This caused each message line to update the progress bar, even if it didn't match an iteration message.

Merge branch 'stan-dev:master' into progressr

83a8801

Merge branch 'stan-dev:master' into progressr

868bd6e

Potential length(milestones) >0L error fix

ce20c36

Moved code to close the progress bar to after the `check_finished()` function.

Merge branch 'progressr' of github.com:josswright/cmdstanr into progr…

fd4c84e

…essr

Fixed defaults for iter_{warmup,sampling}

37931e9

New arguments for `iter_warmup` and `iter_sampling` were not being assigned a default value if not specified in sampling statement.

VisruthSK linked an issue Feb 15, 2026 that may be closed by this pull request

Progress bar #18

Closed

josswright and others added 2 commits February 15, 2026 15:46

Merge branch 'stan-dev:master' into progressr

8549ce6

Fixes for failing unit tests

6c21b5d

- `iter_{warmup,sampling}` arguments to MCMCProcs are allowed to be 0. - Documentation for `register_default_progress_handler` added to repository. - Ensured that calls to `progressr` functions are appropriately prefixed.

josswright marked this pull request as draft February 15, 2026 18:37

josswright and others added 4 commits February 15, 2026 19:13

Documented progress bar arguments. Fixed requires.

84b3ed6

Added documentation for `show_progress_bar` and `suppress_iteration_messages` in `sample()` function. Changed `require()` calls for `progressr` and `cli` to suggested `requireNamespace()` alternatives.

Imported dependencies and fixed a typo in documentation

551e8d8

Moved progressr to Suggests [ci skip]

06e2c18

Proper move progressr to Suggests

6ea01d9

josswright marked this pull request as ready for review February 16, 2026 17:44

Merge branch 'master' into pr/1138

0356350

jgabry added 3 commits February 26, 2026 18:42

minor doc edits

d0d0eb1

Error instead of warning if no progressr or cli

27b301b

Use internal %||% function

320fa9e

jgabry mentioned this pull request Oct 7, 2026

Simplify progressr #1313

Closed

2 tasks

VisruthSK added 3 commits October 7, 2026 14:52

Simplifed progressr logic

584009f

Tightened progressr code and tests

29c4efe

Merge branch 'master' into progressr

a5e7b80

Updated docs

33612db

jgabry changed the base branch from master to v1.0 October 9, 2026 18:54

jgabry added 6 commits October 9, 2026 12:57

Merge branch 'v1.0' into progressr

966d2ee

Add Joss Wright to the contributors

219b0eb

Give an example handler in the progress bar docs

ec9cb37

Check for progressr with the suggested-package helper

02be26f

Rename suppress_iteration_messages to show_iteration_messages

72d9e87

Tidy the progress bar code and document its option

0658cdb

jgabry added 4 commits October 9, 2026 13:57

Match CmdStan's full iteration line when counting progress

8b46ae9

Put the progress bar setup in one place

cbb583e

Hold the per-chain timing lines until the progress bar is done

2720c26

Guard the progressr setup in rendered documents

879cb56

jgabry added 4 commits October 9, 2026 15:06

Merge branch 'v1.0' into progressr

3b6c7bd

jgabry mentioned this pull request Oct 10, 2026

Code formatting prep #1320

Merged

2 tasks done

minor doc edits

2db7681

jgabry merged commit 237351b into stan-dev:v1.0 Oct 12, 2026

jgabry mentioned this pull request Oct 12, 2026

Progress bar #18

Closed

Navigation Menu

Repository navigation

Add a `progressr`-based progress bar for sampling. - #1138

Add a `progressr`-based progress bar for sampling.#1138
jgabry merged 45 commits into
stan-dev:v1.0from
josswright:progressr

josswright commented Feb 13, 2026 •

edited

Loading

Uh oh!

VisruthSK commented Feb 15, 2026

Uh oh!

josswright commented Feb 15, 2026

Uh oh!

codecov-commenter commented Feb 15, 2026 •

edited

Loading

Uh oh!

josswright commented Feb 16, 2026

Uh oh!

jgabry commented Feb 18, 2026

Uh oh!

josswright commented Feb 18, 2026

Uh oh!

jgabry commented Feb 26, 2026 •

edited

Loading

Uh oh!

jgabry commented Oct 7, 2026

Uh oh!

josswright commented Oct 9, 2026

Uh oh!

jgabry commented Oct 9, 2026 •

edited

Loading

Uh oh!

VisruthSK commented Oct 9, 2026

Uh oh!

jgabry commented Oct 9, 2026 •

edited

Loading

Uh oh!

jgabry commented Oct 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

josswright commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Submission Checklist

Summary

Copyright and Licensing

Uh oh!

VisruthSK commented Feb 15, 2026

Uh oh!

josswright commented Feb 15, 2026

Uh oh!

codecov-commenter commented Feb 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

josswright commented Feb 16, 2026

Uh oh!

jgabry commented Feb 18, 2026

Uh oh!

josswright commented Feb 18, 2026

Uh oh!

jgabry commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jgabry commented Oct 7, 2026

Uh oh!

josswright commented Oct 9, 2026

Uh oh!

jgabry commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

VisruthSK commented Oct 9, 2026

Uh oh!

jgabry commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jgabry commented Oct 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

josswright commented Feb 13, 2026 •

edited

Loading

codecov-commenter commented Feb 15, 2026 •

edited

Loading

jgabry commented Feb 26, 2026 •

edited

Loading

jgabry commented Oct 9, 2026 •

edited

Loading

jgabry commented Oct 9, 2026 •

edited

Loading