Skip to contents

A knitr progress display that reports chunk execution times

Source: R/progress.R
knit_progress.Rd

A drop-in replacement for knitr's default progress display. Each block of the document is printed as i/total [label], exactly as knitr does, and once a code chunk finishes its elapsed wall clock time is appended to that line using an appropriate unit (see format_duration()). When the document finishes, a short summary reports the total chunk time and the slowest chunks, and a JSON record of the timings is written for editor integrations (see timeknit-record).

Usage

knit_progress(total, labels)

Arguments

total

The number of blocks (text and code) in the document.

labels

A character vector of chunk labels, with "" for text blocks.

Value

A list of functions update(i), interrupt(), and done().

Details

knitr calls this function itself with the number of blocks and their labels, then calls the returned update(), interrupt(), and done() functions as it works through the document. Register it with knitr through the knitr.progress.fun option, most conveniently by calling use_timeknit() from your .Rprofile.

Child documents get their own nested display: their lines are indented, they print no summary, and the parent chunk's line is repeated with its time once the child finishes. When a chunk errors, its time is written to the message stream so it still appears before the error.

Options

  • timeknit.slowest: how many of the slowest chunks to list in the summary. Defaults to 5, and 0 lists none.

  • timeknit.summary: whether to print the summary at all. Defaults to TRUE.

  • timeknit.text_blocks: whether to print lines for text (non-chunk) blocks as knitr does by default. Defaults to TRUE.

  • timeknit.record: whether to write the JSON timing record, or a directory to write it to. Defaults to TRUE; see timeknit-record.

  • knitr.progress.output: knitr's own option for where progress output is written. Defaults to the console.

Examples

pb = knit_progress(3, c("", "setup", "model"))
pb$update(1)
#> 1/3        
pb$update(2)
#> 
#> 2/3 [setup]
pb$update(3)
#>   1 ms
#> 3/3 [model]
pb$done()
#>   0 µs
#> Total chunk time: 1 ms (2 chunks)
#> Slowest chunks:
#>   [setup]  1 ms
#>   [model]  0 µs