teal_report Class

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 and add or 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), 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 within():

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

Adding content to the teal_report

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

teal_card(report)

## $`45790469`
## [1] "## Document section"
## 
## $`6e364c70`
## [1] "Lorem ipsum dolor sit amet"
## 
## attr(,"class")
## [1] "teal_card"
## attr(,"metadata")
## list()

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

## [1] 2

teal_card(report)

## $`45790469`
## [1] "## Document section"
## 
## $`6e364c70`
## [1] "Lorem ipsum dolor sit amet"
## 
## $`9160b950`
## [1] "a <- 2"
## attr(,"params")
## list()
## attr(,"lang")
## [1] "R"
## attr(,"class")
## [1] "code_chunk"
## 
## attr(,"class")
## [1] "teal_card"
## attr(,"metadata")
## list()

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 at the beginning of the document
teal_card(report) <- c(teal_card("# My report"), teal_card(report))

# 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)

## $`0798a8be`
## [1] "# My report (replaced)"
## 
## $`45790469`
## [1] "## Document section"
## 
## $`6e364c70`
## [1] "Lorem ipsum dolor sit amet"
## 
## $cf3b510e
## [[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()

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

Preview report

Report can be previewed in form of HTML markup displayed in viewer of your IDE. tools::toHTML returns browsable shiny.tag which can be used also in Shiny-application to preview a report.

tools::toHTML(report)

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 Adding support for Reproducible Report Documents in teal.