Advanced R Markdown

Overview

With the Certara.ModelResults package, you can generate the raw R Markdown .Rmd file used to generate the output report for your tagged model diagnostics. This guide focuses on specific R Markdown options applicable to pharmacometric output generated from the Certara.ModelResults package. Click here for a comprehensive guide to R Markdown.

Download R Markdown from resultsUI()

To begin, we’ll launch Certara.ModelResults with our example data xpdb_NLME. Let’s also assign a return value to our function resultsUI(), which will return our tagged diagnostics to our R environment after exiting the Shiny GUI.

library(Certara.ModelResults)

tagged_diagnostics <- resultsUI(xpdb = xpdb_NLME)

After tagging various model diagnostics plots and tables of interest from the Shiny GUI, navigate to the Report tab, then, drag one or more model diagnostic plots and/or tables from the Tagged container to the Report Output container. We’ll name our report Two Compartment IV Bolus Covariate Model, then, select Download R Markdown.

Open R Markdown file in R Studio

Next, we’ll open the file we downloaded Two Compartment IV Bolus Covariate Model.Rmd in R Studio.

Since we are not rendering the R Markdown file inside the Shiny GUI (which occurs when we select “Download Report”), but rather, downloading the raw R Markdown file and rendering from R, we don’t have to worry about the resulting output file type quite yet. However, changing the file type in the Shiny GUI (e.g. html, pdf, docx), then downloading the raw .Rmd, will place the selected output type first in the YAML metadata of your document. Since we selected docx file type in the Shiny GUI, our YAML metadata has word_document: first in the output: section.

---
title: "Two Compartment IV Bolus Covariate Model"
date: '11-17-23'
output:
  word_document:
    toc: true
    toc_depth: 4
    keep_md: true
    reference_docx:
  html_document:
    toc: true
    toc_depth: 4
    keep_md: true
  pdf_document:
    toc: true
    number_sections: true
    fig_caption: true
params:
  inputs: NA
geometry: left=3cm,right=3cm,top=2cm,bottom=2cm
---

Why does this matter? When we render our R Markdown file in R using the function render() from the rmarkdown package, the resulting file output will default to the first output option specified in the YAML metadata. There are of course many options available inside the render() function to control specific output options. More on this in the next section.

At this time, we’ll make any additional changes to our .Rmd file, including changing any headings, or adding any additional paragraphs. Furthermore, we could add any descriptive statistics tables we’ve generated in R to this .Rmd file, or, if the models were fit using the Certara.RsNLME package, we may add in the code used to build and execute our models.

render() R Markdown file

After we’re done editing our .Rmd file, we can easily select the “knit” button in R Studio to create our file output.

knit-button

Or alternatively, use the render() function from the rmarkdown package.

When we execute the render() function, all of the code chunks are executed inside our .Rmd file and a new markdown (.md) document which includes the code and its output is generated by knitr.

Then, the markdown file generated by knitr is processed by pandoc which is responsible for creating the final output format e.g. (html, pdf, docx).

While the “Knit” button from the R Studio GUI is simpler to use, the render() function gives us more robust options.

Since I do not specify the output format in the function shown below, the render() function will automatically output the first output type defined in our above YAML metadata word_document:


library(rmarkdown)

render("~/Documents/Two Compartment IV Bolus Covariate Model.Rmd")

Note: The resulting file Two Compartment IV Bolus Covariate Model.docx will be saved in your current working directory.

Figure dpi, width, and height

We can add the following chunk inside our .Rmd file to globally control all plot dpi, width, and height options.

knitr::opts_chunk$set(dpi = 300, fig.width = 8, fig.height = 5)

Alternatively, if we want to set dimensions for a specific plot, we can define the dimensions inside the {} of the code chunk for our plot.

{r, dpi = 96, fig.width = 9, fig.height = 6}

Specify different output formats

We can control different output types using the output_format argument of the render() function.

If we want to render all output types specified in our YAML metadata (word_document:, html_document: and pdf_document:) we can set output_format = "all".


library(rmarkdown)
render("~/Documents/Two Compartment IV Bolus Covariate Model.Rmd", output_format = "all")

Output to pdf and keep LaTeX

We can render our R markdown to a specific format by passing the name of the format to our output_format argument. To render our R Markdown to pdf, we use the following command.

render("~/Documents/Two Compartment IV Bolus Covariate Model.Rmd", output_format = "pdf_document")

The .Rmd file is converted to PDF by first converting to a TeX file and then calling the LaTeX engine to convert to PDF. By default, this TeX file is removed, however if you want to retain it (e.g., for a submission), you can specify the keep_tex option.


render("~/Documents/Two Compartment IV Bolus Covariate Model.Rmd", output_format = pdf_document(keep_tex = TRUE))

A few final notes about the output_format argument to the render() function. You’ll see in the previous two examples, I first supplied the character string "pdf_document" then, in the second example, I supplied the function pdf_document(). When we specify the character string, the render() function will look to the contents inside our YAML metadata for output options. Since we specified pdf_document, the output options in our YAML metadata are the following:

  pdf_document:
    toc: true
    number_sections: true
    fig_caption: true

Additionally, we could add keep_tex: true to our YAML metadata instead.

  pdf_document:
    toc: true
    number_sections: true
    fig_caption: true
    keep_tex: true

Using the function pdf_document() instead of the character string "pdf_document" allows us to supply additional output options directly inside the render() function, rather than specifying the options in our YAML metadata (e.g., pdf_document(keep_tex = TRUE, toc = TRUE, toc_depth = 2, numbered_sections = TRUE))).

Use MS Word docx style template

Looking at the word_output: section in our YAML metadata, we can see a field named reference_docx:.

  word_document:
    toc: true
    toc_depth: 4
    keep_md: true
    reference_docx:

We can use this field to supply a path to a Microsoft Word document style template. This will allow you to customize things such as margins and other document formatting styles.

Create base style template

Let’s use the word document that we create from our render() function as the basis of our style template.

First, we’ll need to render our .Rmd file to .docx.

library(rmarkdown)
render("~/Documents/Two Compartment IV Bolus Covariate Model.Rmd", output_format = "word_document")

Next, open the resulting output file Two-Compartment-IV-Bolus-Covariate-Model.docx in MS Word.

word-output

Navigate to the View tab and select Draft from the Views section. We can see the various styles associated with our document in the left pane.

word-styles

Navigate back to the Home tab and select a document style attribute that you would like to edit. Let’s select our title and edit the “Title” style from the Styles section.

word-styles

Right click the Title style, then click Modify. You will see the following window, where you can edit various styling options, such as changing the font type, size, face, and color. After making changes, make sure the radio button New documents based on this template is selected, then click OK.

word-modify-styles

Our title has now been changed for this document. Now let’s make sure that all new documents created from render(output_format = "word_document") automatically include the new style formatting we set for our title.

word-title-changed

Save style template

We’ll rename our document with the updated title styling from Two-Compartment-IV-Bolus-Covariate-Model.docx to something generic, such as style_template.docx, then save in a directory of our choice.

Note: It’s OK that we have existing plots/tables saved inside our style template, new documents based on this template will use only the style rules applied to the document elements, and the diagnostics in the style template will not get copied to the new file.

Specify reference_docx: in YAML

Now, let’s return to our .Rmd file in R and add the file path where we saved our style_template.docx to the field reference_docx: in our YAML metadata.

Note: Since I have saved style_template.docx in my current working directory in R (getwd()), I can simply supply the name of the file here. If this file is saved in a location other than your current working directory, please specify the full path.

---
title: "Two Compartment IV Bolus Covariate Model"
date: '11-17-23'
output:
  word_document:
    toc: true
    toc_depth: 4
    keep_md: true
    reference_docx: "style_template.docx"
  html_document:
    toc: true
    toc_depth: 4
    keep_md: true
  pdf_document:
    toc: true
    number_sections: true
    fig_caption: true
params:
  inputs: NA
geometry: left=3cm,right=3cm,top=2cm,bottom=2cm
---

render() R Markdown file

Finally, after saving our .Rmd file, we can once again render() our R Markdown file to word_output, and the resulting .docx file will now be initialized with our updated document title styling.

library(rmarkdown)
render("~/Documents/Two Compartment IV Bolus Covariate Model.Rmd", output_format = "word_document")

The same customizations can be applied across all document styling elements, including the table of contents, headers, body, captions, and more.

See the article from R Studio with additional instructions about how to use reference docs files.