In GegznaV/knitrContainer: Collect and Print Multiple Objects in a `Knitr` R Markdown Report

knitr::opts_chunk$set(collapse = TRUE,
                      comment = "#>",
                      tidy  = TRUE,
                      fig.align = 'center')
optDEF <- knitr::opts_chunk$get()

Introduction

About knitrContainer

knitrContainer is an R package designed to collect objects and print them in knitr reports.

Why was it created?

Some objects such as pander tables and plotly plots, are not printed from inside loop in a knitr report file in a regular way.knitrContainer solves this problem by providing functions to get these objects printed and included in HTML files.

What king of objects can be collectd and printed with knitrContainer?

An object used by knitrContainer can be any object, that is includible in R list an that is printable, such as:

1. text;
2. objects printable with pander;
3. ggplot2, plotly plots;
4. etc.

How to install the package?

From Git Hub repository:

library(devtools)
install_github("GegznaV/knitrContainer")

How to use knitrContainer?

Only 4 things should be done for basic use of knitrContainer package :

1. Create a container(e.g. function knitrContainer());
2. Add objects to the container (use add_as_* family functions, e.g. function add_as_is());
3. In a R code chunk of knitr report file set option results to results='asis';
4. Print the objects appropriately: apply function print_all() in the chunk which has option results='asis'.

Example 1

library(knitrContainer)

container <- knitrContainer()
container <- add_as_text(container, "Text to be added.")
print_all(container)

Example 2

Example how to add objects using the operator %<>% from package magrittr:

container %<>% add_as_text("Text added using `%<>%` operator.")

It is the same as:

container <- add_as_text(container, "Text added using `<-` operator.")

Type the following code in R to learn more about operator %<>%:

?`%<>%`

More detailed examples are presented in the following sections.

Functions for class knitrContainer

Load packages

library(knitrContainer)

library(ggplot2)
library(plotly)

... and create necessary objects

plotly_obj <- plot_ly(economics, x = date, y = uempmed, type = "scatter",
             showlegend = FALSE)

ggplot_obj <- qplot(mpg, wt, data = mtcars, colour = cyl)

Create a knitrContainer object

container <- knitrContainer()
class(container)
container

Attach objects to the end of the container

# Section headings
container <- add_as_heading1(container, "Plots")

# Add `plotly` objects as `htmlwidgets`
container <- add_as_heading2(container, "Add `plotly` as `plotly htmlwidget`")
container <- add_as_plotly_widget(container, plotly_obj)

# Add `ggplot` objects as plotly `htmlwidgets`
container <- add_as_heading2(container, "Add `ggplot` as `plotly htmlwidget`")
container <- add_as_plotly_widget(container, ggplot_obj)

# Add `ggplot` objects as `ggplot` objects
container <- add_as_heading2(container, "Add `ggplot` as-is")
container <- add_as_is(container, ggplot_obj)

# If `plotly` objects are aded as-is, they might not be plotted
container <- add_as_heading1(container, "Attention: Not Plotted")
container <- add_as_is(container, plotly_obj)
container <- add_as_text(container, paste("As you noticed, the last",  
      "`plotly` object was not plotted as it was added with ",  
      "`add_as_is()` and not with `add_as_plotly_widget()`"))

# --- Calculations ---
SUMMARY <- summary(mtcars[1:4])

# --- Add `pander` tables ---
container <- add_as_heading1(container, "Print SUMMARY as pander table and as text")

# Add objects, printed as `pander` tables
container <- add_as_heading2(container, "As pander table")
container <- add_as_pander(container, SUMMARY)

# Add as R output text
container <- add_as_heading2(container, "As Code/ Output Text")

container <- add_as_text(container, "Not highlighted")
container <- add_as_code(container, SUMMARY)

container <- add_as_text(container, "Highlighted as R code")
container <- add_as_code_r(container, SUMMARY)

container <- add_as_text(container, "Output with default `knitr` comments")
container <- add_as_output(container, SUMMARY)

container <- add_as_text(container, "Output with custom comments")
container <- add_as_output(container, SUMMARY, comment = "#$#>")

# Add as text = Add as one paragraph
container <- add_as_heading2(container, "As text/paragraph")
container <- add_as_text(container, SUMMARY)

# Add as-is
container <- add_as_heading2(container, "As is")
container <- add_as_is(container, SUMMARY)

Explore the container

Note, that functions summary(container) and print(container) do the same action: print summary of the object

print(container)

is.knitrContainer(container) 
is.knitrContainer(ggplot_obj)

as.knitrContainer(ggplot_obj) 

class(container)

Merge several containers.

Join(container, container)   %>% length()

Convert (as is) to knitrContainer and merge.

Join(container, ggplot_obj)   %>% length()

As function uses method "as is" to convert to knitrContainer, plotly objects might not be printed from the container in some situations (e.g. from inside for loops using knitr).

Join(ggplot_obj, plotly_obj)

In these situations it is better to apply function add_as_plotly_widget first.

Print objects from the container (print_all)

In section 2 there we demonstrated how to create a knitr_nontainer. In this section we will demonstrate how to print all the objects from the container.

For this purpose a special function print_all was created. As we use knitr and R MArkdown we recommend to use separate R code chunk to apply the function. It is IMPORTANT to make sure that R chunk, in which print_all() is called, has option results set to as is ({r, results = 'asis'}). Otherwise incorrect results are expected.

The following text, section headings, figures etc. (except section "ADVANCED: ..." and "Session information") are printed from the container using the following syntax:

print_all(container)

ADVANCED: add_as_data and add_as_cmd

container2 <- knitrContainer()
# Add as data and add as code to evaluate 

# Add as data
container2 %<>% add_as_text(
    "Add `mtcars` as data (it will not be printed) and rename it to 'cars_data'.")
container2 %<>% add_as_data(mtcars, give.name = "cars_data")

# Add as code to evaluate
container2 %<>% add_as_text(
    c("Use `add_as_cmd` to add unquoted code which manipulates the dataset ",
      "'cars_data', e.g. prints its variable names or plots it."))
container2 %<>% add_as_cmd(print(names(cars_data[1:3])))
container2 %<>% add_as_cmd(plot(cars_data[1:3]))

print_all(container2)

Session information

devtools::session_info()

GegznaV/knitrContainer documentation built on April 16, 2023, 1:38 p.m.