3 Week 1 Getting Started: RStudio, RMarkdown, and Knitting a Report
In this course we will primarily use coding in R that is published as knitted RMarkdown files. If this sounds jargony, don’t worry, we will go slowly through the basics of this process to start the course.
RStudio is a user interface for R (and Python) that we will use to make our RMarkdown documents. While in practice, you may publish files to a GitHub repository or similar, we will only focus on generating PDF or HTML file reports in this course. RStudio is probably the most common way that people code in R nowadays, but you are free to use an alternative as long as the end product generates a reproducible report.
Rmarkdown is a file format (with the extension .rmd) that allows us to publish reproducible reports that can contain plain text, chunks of code that are run during the report publishing process, and our output such as analyses and figures. Markdown is a great tool to learn that can create professional looking reports and code that can go alongside a paper or your thesis. These files can be HTML web documents, PDFs, and others. These are also convenient for our class since I don’t have to run your code for grading, and you don’t have to worry if your code runs properly on my end.
3.1 Installation
Download and install both the latest version of R and RStudio. The labs in the course were designed and tested using RStudio Version: 2024.12.0+467 and R 4.4.2. Alternatively, you may opt to use Posit Cloud, which I will also test labs on in case you run into issues on your own computer. Compatibility issues with old versions aren’t uncommon, especially if you are still using R 3.x.x and will likely lead to issues with your code at some point. So, do this even if you have these programs on your computer already.
3.2 Creating a Project
Step 1: Copy all files from the D2L folder for the lab into your local folder.
Step 2: Navigate to the top menu and click File > New Project.
Step 3: In the New Project dialog box, select Existing Directory (since you will work from the lab files that are already in a folder).
Step 4: Click Browse, and navigate to the folder where you placed your downloaded files.
Step 5: Select the folder and click Open or OK. RStudio will create a new project in this directory, indicated by an .Rproj file. This file stores project settings and acts as your central save/load file for your project in RStudio.
3.3 RMarkdown file structure
1. YAML Header:
The top of each .rmd file has a YAML header (yet another markup language) enclosed by —. For each lab, you will add your name and other information here as well as specify your output format for the report (generally a PDF). You can add additional info to this header but that won’t generally be needed in this course. I have included a link at the bottom of this document for more info on adding to the YAML header.
2. Plain text:
Unlike in a normal .R file, an .rmd file can include plain text that can be formatted in different ways, including headers, hyperlinks, insert images, etc. In fact, this entire book is created in RMarkdown. Anything that is not enclosed in a Code Chunk will be rendered as plain text.
The syntax here can get quite complicated but the most common ones you may want to use are:
# for headings (## for subheadings, ### for smaller headings).
**bold** for bold text.
*italic* for italic text.
- for bullet points.3. Code Chunks:
A Code Chunk in RMarkdown is a block of R code that is executed during the knitting process. The results of the code, such as computed values, tables, or plots, are automatically displayed in the final document. You can run them individually by pressing the play button for the chunk, run all chunks above by pressing the down arrow, or run the entire document by selecting ‘Run’ at the top of the .rmd file.
# This is a code chunk where code will be run and output printed (unless suppressed)
# Example: Calculating the mean of a vector
x <- c(8, 2.1, 3, 4.6, 5)
mean(x)## [1] 4.543.4 Knitting an RMarkdown file
In RStudio, knitting refers to the process of compiling an RMarkdown (.Rmd) file into a finished document in a specified format, such as HTML, PDF, or Word. In this course, we will generally be creating PDF or HTML documents which both have their pros and cons.
Rstudio should already have installed the packages you need to convert RMarkdown files to your reports for HTML (rmarkdown and knitr), but you may need to do a one time installation of tinytex for PDF rendering:
Knitting workflow:
Step 1: Specify an Output Format: In the YAML metadata at the top of the file, define the output format. For example:
Step 2: Click the Knit Button (next to the blue yarn ball) located at the top of the RStudio script editor. Choose the output format if prompted.
The knitted document opens in the Viewer pane or the default application for the format (e.g., a PDF reader for PDFs, a browser for HTML).
If the knitted file cannot be generated that means that some part of your code is not running properly! You will receive an error message in that specifies what line(s) caused the knitting to stop. This is where you should start troubleshooting.