teal_report Class

NEST CoreDev

Introduction

The teal_report class in teal.reporter provides a way to create reproducible documents step by step by adding markdown content alongside code chunks evaluation.

The teal_report class is built on top of teal_data, inheriting all its reproducibility and code-tracking capabilities while adding reporting-specific functionality through teal_card().

This vignette shows you how to build teal_report object, add and remove its content.

Creating a teal_report

A teal_report is an object where developers can add, edit and remove various content (e.g. markdown content, plots, tables), add and evaluate code chunks. It provides a framework for building reproducible reports by combining content management with automatic code tracking.

To ensure complete reproducibility, it’s recommended to start with an empty teal_report and build up your data and analysis using eval_code():

library(teal.reporter)
report <- teal_report()

Adding content to the teal_report

Adding arbitrary markdown content

Think of a teal_report as a list Rmarkdown elements built and evaluated step by step. Use teal_card(report) to access and change elements of the document. To add a new element in the teal_card one can use c method.

teal_card(report) <- c(
  teal_card(report),
  "## Document section",
  "Lorem ipsum dolor sit amet"
)

teal_card(report)

## $`06d00cf9`
## [1] "## Document section"
## 
## $`43b206d9`
## [1] "Lorem ipsum dolor sit amet"
## 
## attr(,"class")
## [1] "teal_card"
## attr(,"metadata")
## list()

Adding reproducible code chunks

teal_report inherits all methods from teal_data. The class supports within() and teal.code::eval_code(), which execute arbitrary code in its environment. Consider this as executing a code chunk in a Rmarkdown document. In the same time you can access objects created during code execution.

report <- within(report, {
  a <- 2
})
report$a

## [1] 2

teal_card(report)

## $`06d00cf9`
## [1] "## Document section"
## 
## $`43b206d9`
## [1] "Lorem ipsum dolor sit amet"
## 
## $da232800
## [1] "a <- 2"
## attr(,"params")
## list()
## attr(,"lang")
## [1] "R"
## attr(,"class")
## [1] "code_chunk"
## 
## attr(,"class")
## [1] "teal_card"
## attr(,"metadata")
## list()

In the above chunk of code a is created but nothing has been output to the console nor to the graphic devices. In case one decides to print or plot teal_report automatically captures outputs, which can be retrieved using teal.code::get_outputs().

report <- within(report, {
  head_of_iris <- head(iris)
  head_of_iris
})

teal.code::get_outputs(report) # returns a list of all outputs

## [[1]]
##   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
## 1          5.1         3.5          1.4         0.2  setosa
## 2          4.9         3.0          1.4         0.2  setosa
## 3          4.7         3.2          1.3         0.2  setosa
## 4          4.6         3.1          1.5         0.2  setosa
## 5          5.0         3.6          1.4         0.2  setosa
## 6          5.4         3.9          1.7         0.4  setosa

Modify teal_report content

teal_report allows to modify its content. Depending on the needs, one can add, remove and replace element in the same way as one modifies a list.

# adding element in the beginnning of the document
teal_card(report) <- append(teal_card(report), "# My report", after = 0)

# removing code_chunk(s)
teal_card(report) <- Filter(
  function(x) !inherits(x, "code_chunk"),
  teal_card(report)
)

# replace an element
teal_card(report)[[1]] <- "# My report (replaced)"

teal_card(report)

## $`5df7f233`
## [1] "# My report (replaced)"
## 
## $e673d433
## [1] "## Document section"
## 
## $c2499a47
## [1] "Lorem ipsum dolor sit amet"
## 
## $ca9a0503
## [[1]]
##   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
## 1          5.1         3.5          1.4         0.2  setosa
## 2          4.9         3.0          1.4         0.2  setosa
## 3          4.7         3.2          1.3         0.2  setosa
## 4          4.6         3.1          1.5         0.2  setosa
## 5          5.0         3.6          1.4         0.2  setosa
## 6          5.4         3.9          1.7         0.4  setosa
## 
## attr(,"class")
## [1] "chunk_output"
## 
## attr(,"class")
## [1] "teal_card"
## attr(,"metadata")
## list()

Document metadata

In Rmarkdown it is possible specify certain parameters as a YAML header. teal_report allows to specify metadata using metadata().

metadata(teal_card(report)) <- list(
  title = "My Document",
  author = "NEST"
)

Output teal_report

teal_report supports several output formats. render for teal_report utilizes rmarkdown::render so it supports the same output formats and arguments.

render(report, output_format = rmarkdown::pdf_document(), global_knitr = list(fig.width = 10))

Key Benefits

Using teal_report in your modules provides several advantages:

1. Reproducibility: All code is automatically captured via the underlying teal_data infrastructure
2. Consistency: Standardized way to create reports across modules
3. Flexibility: Easy to add different types of content to reports
4. Integration: Works seamlessly with the teal reporter infrastructure
5. Code Tracking: Inherited eval_code() functionality ensures all computations are reproducible

Further Reading

For more details on the underlying teal_data functionality, see the Introduction to teal.data.

For more information on the teal_report class usage in teal, see the Managing Reproducible Report Documents in teal.