Version 1: Your Basic Rmd

For demonstrations sake, we’re going to start with Version1.Rmd and remodel it step by step. This very simple Rmd looks at the iris dataset, performs some data manipulation, and shows some plots.

Until very recently, every Rmd I made looked a little like Version 1. I would have some text, some code, and knit it using the default everything. The plots may look reasonably nice, and the code may work, but it’s not the best Rmd it could be. The following tips and tricks will be especially useful if you need to use the functions defined in your Rmd in other files or on other people’s computers, if you need to recompile your Rmd with different subsets of the data or with some additional pre-processing, if you need to share your results with collaborators who may or may not code, or if you’d like to publish your results publicly.

Basic Steps

1. File > New Project

2. Select a directory, then select that you want to create an R package

3. Set package name > Create Project

4. Create an R script in the R/ directory and add functions and/or constants

5. Build your package with devtools::build(), or navigate to the Build pane and More > Clean and Rebuild

Now your package is ready to use!

Version 2: Using Your R Package

Now in Version2.Rmd we can load our irispackage and use the functions from the package for the data manipulation steps. The first time you use your package, you’ll need to run install.packages, but after that is done once you’ll run update.packages to make sure you load the latest version.

install.packages(
  "./irisproject/",
  repos=NULL,
  type="source"
)

library(irisproject)

Improving Your R Package

Tips

• If you update the package source code, rebuild it.
• If you have another R session open, you need to restart R and update.packages before you can use the most recent version of the package.
• If you use functions from other packages inside your package, it needs to be noted in the NAMESPACE and DESCRIPTION files. Rather than doing this manually:
  • In the Roxygen documentation of your function that uses the package, add a line @importFrom package function1 function2 ..... This will update the NAMESPACE when documentation is updated.
  • Run usethis::use_package('package') in the console. This will update the DESCRIPTION file, which checks these dependencies upon package installation.

Version 3: Parameterize Your Rmd

In Version3.Rmd, you’ll see the first change on line 4 of the notebook: adding the params option to the YAML header. For the iris analysis example, we’ll parameterized the location of the project’s package, the option to convert inches to centimeters, and what variables to include in the pairs plot, which for just this version we’ll reduce to the three new variables and the species.

Within the code, when we want to access these parameters, we refer to them as a value within the params list with the params$ prefix:

params$package_location

If you knit the file with the Knit button, the parameters specified in the YAML will be used. Alternatively, you can specify parameters programmatically with:

rmarkdown::render(
  "Version3.Rmd",
  params = list(
    package_location = "./irisproject",
    convert_cm = FALSE,
    plot_pairs_of = c("Sepal.Length","Species")
  )
)

You can also click Knit > Knit with Parameters, and a user interface will pop up to allow you to change the standard R type parameters in a way that doesn’t require coding knowledge:

Improving Your Parameterization

Version 4: Customize Your Rmd

Moving from Version 3 to 4, we will add a new theme to make our Rmd pretty and to include a table of contents, add tabs for easier navigation of sections, use kable tables to display data in a nicer way, and make our plots interactive with as little as one added line of code.

Themes and Formats

The easiest way to make your Rmd pretty is to change its theme or format. There are lots of R packages that provide themes and formats, including rmdformats, which provides the robobook format, and prettydoc, which provides the architect, cayman, and lenoids themes, which are presented below.

To change the theme or format of your Rmd, simply update the output argument in the YAML header. For instance, to use a prettydoc theme, the header will look like this:

output:
  prettydoc::htmlpretty:
    theme: cayman

Alternatively, to use a rmdformats format, the header will look like this:

output:
  rmdformats::robobook

We use the robobook theme in Version4.Rmd. I like this one because it adds a simple sidebar table of contents.

Tabs

Subsections can be change from vertically ordered sections to tabs that a user can toggle between. This is done by adding a CSS class attribute to the section header – which is a lot easier than it sounds. Adding tabs is as simple as adding {.tabset} after your header.

# Section {.tabset}

## First Tab Name

first tab contents

## Second Tab Name

second tab contents

This markdown produces the following HTML:

In Version4.Rmd, we put the data manipulation steps into separate tabs with descriptions of each step. We also use tabs to separate the two sections of “setup”: loading packages and printing parameter inputs. For these tabs, we also add the .tabset-fade and .tabset-pills CSS classes for further customization

Kable Tables

Displaying your data or results in a visually pleasing way can make your Rmd look more professional and more interesting! knitr, the same package that lets you knit an Rmd and has functions to include images, exports the kable function that makes data tables look a lot nicer. It also allows for the option to round all numeric columns with the digits parameter.

In Version4.Rmd, we use kable to display pretty tables with values rounded to 3 decimal places.

Interactive Plots Directly from ggplot2

Interactive plots are useful because some questions can be answered more quickly with interactive results, for example:

• Which observation is that outlier?
• Can we zoom in on the section with a lot of overlapping points?
• Can we look at only a particular range of x values?

There are a lot of packages that allow interactive plotting, including plotly and leaflet. They allow a lot of options for customization and create great plots, but it can take some time to learn their syntaxes. However, if you already have a ggplot2 figure, you can very simply convert it to be interactive with the ggplotly function exported from the plotly package.

With this function, interactive plotting only adds one line of code on top of your existing ggplot call.

library(ggplot2)
library(plotly)

p <- ggplot2::ggplot(...)
plotly::ggplotly(p)

In Version4.Rmd, we make the plot at the end interactive. Below I show a simplified version that just passes the ggplot2 object to ggplotly.

p <- iris %>% ggplot(aes(
  x = Circumference, 
  y = Length.Ratio, 
  color = Species
)) +
  geom_point() +
  theme_classic() +
  theme(
    legend.position = 'top',
    legend.justification = 'left'
  )

plotly::ggplotly(p)

The more customized version shows code to add a custom tooltip with the text aesthetic in ggplot and the tooltip parameter in ggplotly. It also shows how to put the legend at the top of the plot instead of to the side, since plotly tends to cover up part of the legend.

p <- iris %>% ggplot(aes(
  x = Circumference, 
  y = Length.Ratio, 
  color = Species,
  text = paste0(
    "Species: ", Species,
    "\nCircumference: ", round(Circumference,3),
    "\nLength Ratio: ", round(Length.Ratio, 3),
    "\nWidth Ratio: ", round(Width.Ratio, 3),
    "\nPetal Width, Length: ", round(Petal.Width, 3),
        ", ", round(Petal.Length, 3),
    "\nSepal Width, Length: ", round(Sepal.Width, 3),
        ", ", round(Sepal.Length, 3)
  )
)) +
  geom_point() +
  theme_classic() +
  theme(
    legend.position = 'top',
    legend.justification = 'left'
  )

plotly::ggplotly(p, tooltip = c("text")) %>%
  plotly::layout(
    legend = list(
      orientation = "h",
      x = 0,
      yanchor = "bottom",
      y = 1.02
    )
  )