Create PDF reports using R, R Markdown, LaTeX and knitr (on macOS High Sierra)

TLDR: This tutorial teaches you how to install LaTeX, R and R Markdown on macOS High Sierra. It also guides you through creating your first R Markdown file and shows how to compile it into a PDF file using knitr.

NOTE: This post builds on a post I wrote on installing RStudio on Windows a couple of years ago. If you are a Windows user, see my original post.

Introduction

If you’re using R to statistically explore data sets, and you need to write reports detailing your findings, you can benefit from using R Markdown. An R Markdown file is basically a standard Markdown file with embedded R code chunks. This tutorial teaches you how to install everything you need on a Mac running macOS High Sierra, as well as how to create R Markdown files and compile them into PDF files. It doesn’t teach you the syntax of R Markdown. Howevever, if you are familiar with R and Markdown, that should not be a problem once you have seen an example R Markdown file (which you will as part of his tutorial). If you are familiar with R and not with Markdown, follow me here on Medium or on Twitter to get notified when I post a tutorial on that. (If you’re not familar with R, I’m not quite sure why you’re reading, but of course, you’re very welcome to read along!)

Requirements

This tutorial assumes you are running macOS High Sierra. If you are running an older version of macOS you should still be able to follow along, provided you are running at least OS X El Capitan.

When writing this tutorial I used a new and 100% clean installation of macOS— no software was installed in advance and no changes had been made to the settings of the computer (except changing the color of the desktop). In other words, everything you need is explained in this tutorial.

I ran this tutorial as the default user that was created during installation of macOS. This user is an administrator. If you are running as a standard user, you may have varying degrees of success.

Having installed R and RStudio before installing MacTeX?

This guide assumes you have neither R, RStudio nor MacTeX installed before beginning the tutorial. In case you are already experienced with R but are not using LaTeX, chances are you already have R and RStudio installed but do not have MacTeX. If that’s the case for you, don’t fret. You can just skip the parts explaining how to install R and RStudio. I have tested that this works exactly the same by first installing R and RStudio and then finally installing MacTeX on a clean installation of macOS.

1. Download and Install MacTeX

You should start by installing MacTeX (pronounced mac-tech). MacTeX is a so-called LaTeX distribution (pronounced lah-tech or lay-tech). It is required for knitr to create professionally (or at least, academically) looking reports. If you haven’t heard of LaTeX before (or tried it but failed to make it work for you), don’t fret. You can write your report using RMarkdown, and knitr will automatically convert your report to a LaTeX file which it will use to create a PDF file for you. You will never have to look at the LaTeX file itself.

• Go to http://www.tug.org/mactex/mactex-download.html in your favorite web browser.
• Click the MacTeX.pkg link to download. The file is quite large, approximately 3 GB, so it may take some time.

NOTE: If you look around on the MacTeX website, you will see there’s also another installation package available, namely the BasicTeX package. I strongly recommend you pick the full installer which I linked to above. The full installer lets you install all LaTeX packages immediately while the basic installer only installs the most common ones. And just to be clear, for this tutorial, I used the full installer. If you pick the basic one, you are on the own for this part of the ride

Even if you follow my advice and use the full installer, a handful of needed packages will not be downloaded immediately. But no reason to worry — RStudio and the MacTeX package manager will make sure packages are downloaded when needed .

• When your download is complete, run the downloaded installer.
• The installation procedure is quite straightforward. You are given a few options, for example you can choose not to install some comonents. I recommend you stick with the default settings, so having accepted the license agreement, you can basically just keep clicking Continue on each screen. On the final screen of the wizard, click Install. It may ask for an administrator password. Enter the password,click Install Software and go make a cup of coffee while the installation completes.
• When the program is done installing, click Close to complete the installation.
• If asked, it’s safe to choose to move the installer package to Trash.

2. Download and Install R

Before installing RStudio we will need to download and install R itself.

• Go to https://cran.rstudio.com/ in your web browser.
• Click the Download R for (Mac) OS X link.
• Find the “Files:” section on the page. The left column contains links to installers. Clink the topmost link to download R. When I wrote this, it said R-3.4.3.pkg. By the time you read this, the version number will have most likely changed. Don’t worry about that.

• When the download is complete, run the file you just downloaded.
• Click Continue a couple of times and agree to the license.
• As when installing MacTeX, you are a given a few options to choose from during installation of R, but again I recommend you stick to the defaults, so you can just click Continue on each screen.
• Again, the installer may ask for an administrator password. Enter the password and click Install Software.
• When installation is done, click Close to close the installer. If you’re asked whether you want to remove the installer to Trash, feel free to do so.

3. Download and Install RStudio

Now is the time to install RStudio.

• Go to https://www.rstudio.com/products/rstudio/download/ in your web browser.
• The upper part of this page contains a product feature comparison chart. Just scroll down to the bottom of the page. From here, you can download various installers for RStudio. You have to choose one for macOS. At the time of this writing, it’s called RStudio 1.1.442 — Mac OS X 10.6+ (64-bit), but as usual, the version number will likely have changed when you read this.
• The RStudio installer comes in a .dmg file, a disk image. To install RStudio, double click the .dmg file to “mount” it. This should open a window showing the contents of the disk image. In this window, simply drag the blue RStudio icon to the Applications shortcut icon next to it. This will copy RStudio to your Applications folder. You should now “unmount” the disk image.

You are now ready to open RStudio! You can find it in your Applications folder or using Launchpad.

NOTE: R and RStudio are different programs, so make sure you open RStudio and not R. (It should look like the screenshot below).

When running RStudiofor the first time, you may see a popup prompting you to install command line developer tools. In case this happen, you can simply click the Install button.

Also, your Mac may warn you that it is “an application downloaded from the Internet”. If this happens, just click the “Open” button.

IMPORTANT: R may give you some warnings like the red lines ones in above screenshot. This is easily fixed by forcing R to use UTF-8 encoding. You can do this from the Terminal by running this command:
defaults write org.R-project.R force.LANG en_US.UTF-8
Relaunch RStudio, and the warnings should be gone. See also this Stackoverflow thread.

4. Preparing for Your First R Markdown Document

You are now almost ready to create your first R Markdown document. Before you can actually work with R Markdown, you will need to install a few packages, one of which is knitr itself. Luckily, RStudio will automatically detect which packages are needed if you just create new R Markdown file. All you need is to follow the steps below.

• Click File in the menu, then New File, and then R Markdown…
• RStudio will now detect that you miss some packages and ask if you want to install them now. Click Yes. RStudio will now install the required packages.

5. Your First R Markdown Document

When RStudio is done installing packages it will show the dialog window for creating a new R Markdown file. In this dialog, you can enter the title of the document, as well as the name of the author (you, I would suppose) and which type of output document you want(HTML, PDF or Word). You can change any of these later but you might as well set it up correctly now. The main goal of this post ist to show you how you can create PDF files (using R Markdown, knitr and LaTeX) so you should select PDF, and you might as well enter your name and a title for the document. You can choose other templates in the left sidebar, for example Presentation or Shiny but we are not going to use them for this tutorial. Click OK and RStudio will generate and open your first R Markdown file as shown below.

Before actually processing the R Markdown to generate a PDF, you should make sure to save the R Markdown file. When you do this for the first time, RStudio will ask what encoding you want to use when saving the file. The file encoding determines how the characters which make up your R Markdown file are stored on disk. The topic of file encodings is way too involved for the scope of this article so I will not go into any sorts of details but I should say that I absolutely recommend that you choose UTF-8 as seen below. (Feel free to check the “Set as default encoding for source files” if you want. That way you will not have to choose encoding each time you create a new R Markdown file.)

Having saved your R Markdown file, it’s time to process it and generate a PDF file. You can do this by clicking the Knit PDF button above the text. Your PDF file will be generated and opened as shown below. You’re now ready to start writing and processing your own R Markdown files and generate awesome PDF-files using knitr and LaTeX!

For more tutorials, feel free to follow me here on Medium or on Twitter.