Day 02: cli_progress_*()

Show progress in your code using the cli_progress_*() family of functions from the cli package.

The cli package (Csárdi 2022) provides helpers for developing attractive command line interfaces and output. It has lots of great features worth checking out, but today we’re going to talk about one of my favorites: progress bars!

Tip

This post is just a quick highlight reel, check out cli’s progress-bar vignettes for more details:

• Introduction to progress bars in cli

• Advanced cli progress bars

Progress bar basics

To lift straight from the progress-bar intro vignette, adding a progress bar is a three-step/three-function process:

1. Call cli_progress_bar() to create a progress bar.

2. Call cli_progress_update() to update it.

3. Call cli_progress_done() to terminate it.

We’ll use these three steps in our pretend cleaning function, below:

clean <- function() {
  cli_progress_bar("Cleaning data", total = 100)
  for (i in 1:100) {
    Sys.sleep(5/100)
    cli_progress_update()
  }
  cli_progress_done()
}

We created our progress bar with cli_progress_bar() on line 2, told it how often to update (after each iteration) with cli_progress_update() on line 5, and when to finish with cli_progress_done() on line 7.

If we were to run that function, we’d get the following output.

clean()

Unknown total

But what if I don’t know how many units total? Don’t worry, there’s still a way to show your progress with an unknown total number of units. You can omit the total number from the cli_progress_bar() function, and use force = TRUE inside of cli_progress_update(), as seen on line 8 of the code below.

walk_dirs <- function() {
  cli_progress_bar("Walking directories")
  while (TRUE) {
    if (runif(1) < 0.01) break
    Sys.sleep(0.01)
    cli_progress_update()
  }
  cli_progress_update(force = TRUE)
}
walk_dirs()

Naturally, the output will look different, since you don’t have a known total on which to base your progress percentage.

Progress without bars

Want to know how your code is going but don’t want or need a progress bar along the way? Check out the cli_progress_message() and cli_progress_step() functions.

cli_progress_step() makes use of cli feaatures, such as cli_alert() themes to show colored icons indicating information, success, and danger, and will show you the duration of each step after it’s completed.

f <- function() {
  cli_progress_step("Downloading data")
  Sys.sleep(2)

  cli_progress_step("Importing data")
  Sys.sleep(1)

  cli_progress_step("Cleaning data")
  Sys.sleep(2)

  cli_progress_step("Fitting model")
  Sys.sleep(3)
}
f()

Learn more

This is but a paltry sampling of what you can do with the cli_progress_*() functions, so be sure to take the time to check out cli documentation!

References

Csárdi, Gábor. 2022. cli: Helpers for Developing Command Line Interfaces. https://CRAN.R-project.org/package=cli.