Rethink the progress bar

[hadley]

I think it's time to rethink the knitr progress bar. Since the progress bar was created, we have collectively learnt a lot about how to create minimal, informative progress bars, that still show you what's happening.

For example, I think this progress output:

processing file: introduction.Rmd
 |..............                                                        |  20%
  ordinary text without R code

  |...................                                                   |  27%
label: unnamed-chunk-2 (with options) 
List of 3
 $ echo  : logi FALSE
 $ cache : logi FALSE
 $ indent: chr "    "

  |.......................                                               |  33%
  ordinary text without R code

  |............................                                          |  40%
label: unnamed-chunk-3 (with options) 
List of 3
 $ code  : symbol install
 $ eval  : logi FALSE
 $ indent: chr "    "

  |.................................                                     |  47%
  ordinary text without R code

  |.....................................                                 |  53%
label: unnamed-chunk-4 (with options) 
List of 2
 $ eval: logi FALSE
 $ echo: logi FALSE

  |..........................................                            |  60%
  ordinary text without R code

  |...............................................                       |  67%
label: unnamed-chunk-5 (with options) 
List of 3
 $ results: chr "asis"
 $ echo   : logi FALSE
 $ message: logi FALSE

  |...................................................                   |  73%
   inline R code fragments

  |........................................................              |  80%
label: unnamed-chunk-6 (with options) 
List of 2
 $ echo   : logi FALSE
 $ results: chr "asis"

  |.............................................................         |  87%
  ordinary text without R code

  |.................................................................     |  93%
label: unnamed-chunk-7 (with options) 
List of 1
 $ echo: logi FALSE

  |......................................................................| 100%
label: unnamed-chunk-8 (with options) 
List of 1
 $ include: logi FALSE

could be reduced to something like this:

processing file: introduction.Rmd

text                    |..............                        |  20%
chunk: unnamed-chunk-2  |...................                   |  27%
text                    |......................                |  33%
chunk: unnamed-chunk-3  |......................                |  40%
text                    |......................                |  47%
chunk: unnamed-chunk-4  |......................                |  53%
text                    |......................                |  60%
chunk: unnamed-chunk-5  |......................                |  67%
inline code             |......................                |  73%
chunk: unnamed-chunk-6  |........................              |  80%
text                    |.............................         |  87%
chunk: unnamed-chunk-7  |.................................     |  93%
chunk: unnamed-chunk-8  |......................................| 100%

where in most context the each line would overwrite the previous line, so that you see an interactive progress bar gradually filling up over time. I've dropped the display of options because I don't find that useful; reincorporating it into a single line display would be challenging, but definitely possible.

[maxheld83]

Perhaps as part of this, it might make sense to separate out two concerns currently addressed by the knitr(quiet=FALSE) output:

1. logging (which needs to be knitr specific, maybe include chunk options, etc.)
2. progress bar (which should be quite generic, as similar as possible to existing progress bars / reuse progress and progressr (https://github.com/yihui/knitr/issues/2077) as much as possible.

More discussion in https://github.com/yihui/knitr/pull/2035.

[cderv]

Just a note as I am seing this: VSCODE extension integrates the progress bar with the UI. https://github.com/REditorSupport/vscode-R/wiki/R-Markdown#progress-tracking

Changing the progress bar may have some impact there I believe.

[cderv]

What is the current plan ?

We plan to tackle this in two steps for now :

• First, follow suggestion to make the current progress bar less verbose with a more concise format. This would mean removing the options printed to the progress bar status by default. This should be something quick which would already offer some improvment. @rich-iannone has bandwidth to look into this.

• Second, rethink the progress bar at its design levels. What are the goals and what should be the formatting ? Sharing some notes below

Goals

From notes with @hadley , there would be 2 main goals for the progress bar in knitr:

• Know where the rendering process is at, showing the knitr is effectively working and possibly how long it will take. Usual progress bar desire.
• Help know where to look for issue if something wrong happens during the knitting.

There is also the goals shared by @maxheld83 above, related to https://github.com/yihui/knitr/issues/2077 to "be able to handle the progress information of knitr documents more flexibly."

This goes with another feedback I got about a use case that the progress bar outputs should be possible to customize by user inputs from the Rmd file, for the context of scheduled rendering on RStudio Connect. Like an interactive log report of some sort. I understand the usage, not sure if it should be a progress bar features, or another features that would be working well with the progress bar formatting.

Ex: outputting more verbose context that just the chunk name,

Like grouping code chunks and steps together or sharing some information about the processing in the knitting log.

processing file: monthly-report.Rmd

--[ Pre-Process work ] --
text                    |..............                        |  20%
chunk: unnamed-chunk-2  |...................                   |  27%
text                    |......................                |  33%
chunk: unnamed-chunk-3  |......................                |  40%
text                    |......................                |  47%
chunk: unnamed-chunk-4  |......................                |  53%
text                    |......................                |  60%
--[ Got 3 updated results - generating new report  ] --
chunk: unnamed-chunk-5  |......................                |  67%
inline code             |......................                |  73%
chunk: unnamed-chunk-6  |........................              |  80%
text                    |.............................         |  87%
--[ Updating database with new results ] --
chunk: unnamed-chunk-7  |.................................     |  93%
chunk: unnamed-chunk-8  |......................................| 100%
--[ 3 new records ] --

Formatting.

• We should leverage new features like the IDE supports for hyperlinks (related to #2153) - this would be useful when reporting errors.
• Progress bar formatting should consider the usage: Interactively a lot of overwriting can happen, which you don't want in batch mode (from notes with @hadley)
• Using cli for formatting should really be considered at some point as I think it can offer some good standard and offers features for progress bar now (https://cli.r-lib.org/articles/progress.html). it adds a dependency, but it is a low level one with no new import. it is probably the new best option rather than
• Could it be customized by the caller ? which is what progressr is about I think.

@yihui @rich-iannone please do share your thoughts.

@hadley we welcome any new feedback on this.

[hadley]

@cderv great summary! I think it would be useful to start collecting these notes in a google doc.

[pedropark99]

Displaying more info should not be the default

This issue was born with the intent to produce a more compact progress bar. So, maybe, displaying more info with the progress bar should not be the default (or the focus).

Yet, we want to give the freedom to the user to produce such infos, if they want to. I think the best way to do that is to add a chunk option (like progress_message) to allow the user to display extra messages in each chunk with the progress bar. So when this chunk option is triggered, it would pass the message to cli::cli_alert_info() for example, and would be printed with the progress bar.

We could also use a list in this chunk option, to allow the user to decide which "logging function" they want to use. Like:

start of chunk ....
# Will use `cli::cli_alert_warning()` to print the message:
#| progress_message = list(message = "A message", log_fun = "cli::cli_alert_warning()") 
end of chunk ....

[jthomasmock]

Noting a recent customer request re: knitr in the context of Posit Connect's log file (which based off Hadley's initial proposal might be solved?).

Customer wants to know if it is possible to *not have these vertical lines in the RMD log files on RSC? These lines interfere with their log analysis.

The vertical lines are like below:

2022-10-26 processing file: file.Rmd
| #<- vertical line
| #<- vertical line
| #<- vertical line
| ......                             | 0%

As part of the enhancement, it might be interesting to think about how the product teams can build off this work. Thinking of what this means for RStudio Background Jobs for reporting progress and/or on Connect what happens with it's logging.

[cderv]

@jthomasmock I wonder if this request does not add to the idea of multiple type of report due to multiple goals. I mean currently the knitr progress bar serve as an interactive progress report - it seems to me that what customer of Posit connect would like are logging for knitting process which is IMO slightly different.

In broader term we need user friendly progress report, with helpful information for debugging and we may need another mechanism for more machine-friendly logging about the knitting process to help diagnose and analyze in usual company grade logging framework.

Just thinking out loud for now.

[jthomasmock]

Agreed - I just wanted to note that there are potential downstream side effects or benefits with modification of the current knitr progress reports. A machine-friendly logging mechanism may be preferred in certain situations but is a separate issue/request as I think you're alluding to.

[hadley]

One advantage of using cli is that it already handles some of differences between interactive (e.g. running locally in RStudio) and batch environments (e.g. running on RStudio connect): https://cli.r-lib.org/articles/progress-advanced.html#non-interactive-r-sessions. This would probably require a little additional work to verify that if knitr fails in a non-interactive environment you still find out exactly where the problem occurred.

Also need to think about what happens when (e.g.) you have message = FALSE and the chunk generates messages. Those messages are currently recreated in the output. I don't think that's terribly useful (since I've explicitly said I don't want to see them), but others may disagree.

I think we could handle the need for users to add arbitrary content to the output through a new helper called knitr_message() or similar. This function would produce a emit condition (inheriting from message) that would always be recorded in the output.

[yihui]

The progress bar has been condensed in the dev version of knitr. The major changes are:

1. Chunk options are no longer printed by default. Only chunk labels are printed (at the end of the bar).
2. The text progress bar uses a single line display.

remotes::install_github('yihui/knitr')

For people who want to use their own progress bars, I'm hoping to allow for custom progress bars instead of supporting every single progress package: https://github.com/yihui/knitr/pull/2196

Feedback welcome!

Just a note as I am seeing this: VSCODE extension integrates the progress bar with the UI. https://github.com/REditorSupport/vscode-R/wiki/R-Markdown#progress-tracking

Changing the progress bar may have some impact there I believe.

@cderv Thanks for the info! I've filed an issue there for notification and discussion.

Customer wants to know if it is possible to *not have these vertical lines in the RMD log files on RSC? These lines interfere with their log analysis.

@jthomasmock Can they rmarkdown::render(quiet = TRUE)? With the PR https://github.com/yihui/knitr/pull/2196, they would be able to disable the progress bar.

Also need to think about what happens when (e.g.) you have message = FALSE and the chunk generates messages. Those messages are currently recreated in the output. I don't think that's terribly useful (since I've explicitly said I don't want to see them), but others may disagree.

@hadley I've made changes in evaluate so that message = FALSE would discard messages entirely (same for warning = FALSE).

[github-actions[bot]]

This old thread has been automatically locked. If you think you have found something related to this, please open a new issue by following the issue guide (https://yihui.org/issue/), and link to this old issue if necessary.