Introduction to Using R Markdown for Class Assignments

R Markdown is a low-overhead way of writing reports which includes R code and the code’s automatically-generated output. It also lets you include nicely-typeset math, hyperlinks, images, and some basic formatting. The goal of this document is to explain, with examples, how to use its most essential features. It is not a comprehensive reference. (See rather http://rmarkdown.rstudio.com .)

This guide assumes that you know at least some R.

This guide was adapted from http://www.stat.cmu.edu/~cshalizi/rmarkdown .

What is Markdown?

Markdown is a low-overhead mark-up language invented by John Gruber. There are now many programs for translating documents written in Markdown into documents in HTML, PDF or even Word format (among others). R Markdown is an extension of Markdown to incorporate running code, in R, and including its output in the document. This document look in turn at three aspects of R Markdown: how to include basic formatting; how to include R code and its output; and how to include mathematics.

Rendering and Editing

To write R Markdown you can use any text editor, a program which lets you read and write plain text files. You will also need R, and the package rmarkdown (and all the packages it depends on). I highly recommend using R Studio which comes with a built-in text editor, and has lots of tools for, working with R Markdown documents.

Rendering in R Studio

Assuming you have the document you’re working on open in the text editor, click the button that says “knit”.

Rendering in R without using R Studio

See the render command in the package rmarkdown .

Basic Formatting in R Markdown

For the most part, text is just text. One advantage of R Markdown is that the vast majority of your document will be stuff you just type as you ordinarily would.

Paragraph Breaks and Forced Line Breaks

To insert a break between paragraphs, include a single completely blank line.

To force a line break, put two blank spaces at the end of a line.

The character # at the beginning of a line means that the rest of the line is interpreted as a section header. The number of # s at the beginning of the line indicates whether it is treated as a section, sub-section, sub-sub-section, etc. of the document. For instance, Basic Formatting in R Markdown above is preceded by a single # , but Headers at the start of this paragraph was preceded by ### . Do not interrupt these headers by line-breaks.

Italics, Boldface

Text to be italicized goes inside a single set of underscores or asterisks . Text to be boldfaced goes inside a double set of underscores or asterisks .

Set-off quoted paragraphs are indicated by an initial > :

In fact, all epistemological value of the theory of probability is based on this: that large-scale random phenomena in their collective action create strict, nonrandom regularity. [Gnedenko and Kolmogorov, Limit Distributions for Sums of Independent Random Variables , p. 1]

Computer Type

Text to be printed in a fixed-width font, without further interpretation, goes in paired left-single-quotes, a.k.a. “back-ticks”, without line breaks in your typing. (Thus R vs. R.) If you want to display multiple lines like this, start them with three back ticks in a row on a line by themselves, and end them the same way:

Bullet Lists

  • This is a list marked where items are marked with bullet points.
  • Each item in the list should start with a * (asterisk) character, or a single dash ( - ).
  • Indent lines and begin them with + for sub-bullets.
  • Sub-sub-bullet aren’t really a thing in R Markdown.

Numbered lists

  • Lines which begin with a numeral (0–9), followed by a period, will usually be interpreted as items in a numbered list.
  • R Markdown handles the numbering in what it renders automatically.
  • Sub-lists of numbered lists, with letters for sub-items, are a thing.
  • They are however a fragile thing, which you’d better not push too hard.

Title, Author, Date, Output Format, Table of Contents

You can specify things like title, author and date in the header of your R Markdown file. This goes at the very beginning of the file, preceded and followed by lines containing three dashes. Thus the beginning of this file looks like so:

You can also use the header to tell R Markdown whether you want it to render to HTML (the default), PDF, or something else. To have this turned into PDF, for instance, I’d write

Adding a table of contents is done as an option to the output type.

  • To create PDF, a program called LaTeX (see below) has to be installed on your computer. LaTeX is already installed on RStudio Cloud.
  • Other output formats may be available. See help(render) in the rmarkdown package.
  • There are many, many other formatting options which can be given in the header; see the main R Markdown help files online.

Hyperlinks and Images

Hyperlinks anchored by URLs are easy: just type the URL, as, e.g., to get the source file for this document.

Hyperlinks anchored to text have the anchor in square brackets, then the link in parentheses .

Images begin with an exclamation mark, then the text to use if the image can’t be displayed, then either the file address of the image (in the same directory as your document) or a URL. Here are two examples, one for an image in the directory and one for a URL.

A local image

There doesn’t seem to be a way of re-sizing images using these Markdown commands. Since you are using R Markdown, however, you can use the following hack:

r markdown assignment

This calls an R command included in the knitr package, with some options about how the R is run (described below).

Including Code

The real point of R Markdown is that it lets you include your code, have the code run automatically when your document is rendered, and seemlessly include the results of that code in your document. The code comes in two varieties, code chunks and inline code.

Code Chunks and Their Results

A code chunk is simply an off-set piece of code by itself. It is preceded by ```{r} on a line by itself, and ended by a line which just says ``` . The code itself goes in between. Here, for instance, is some code which loads a data set from a library, and makes a scatter plot.

r markdown assignment

First, notice how the code is included, nicely formatted, in the document. Second, notice how the output of the code is also automatically included in the document. If your code outputs numbers or text, those can be included too:

Inline Code

Code output can also be seamlessly incorporated into the text, using inline code . This is code not set off on a line by itself, but beginning with r and ending with . Using inline code is how this document knows that the SAT_2010 data set contains 50 rows ( contains 50 rows ), and that the median SAT writing score was 511.5 ( 511.5 ).

Notice that inline code does not display the commands run, just their output.

Seen But Not Heard

Code chunks (but not inline code) can take a lot of options which modify how they are run, and how they appear in the document. These options go after the initial r and before the closing } that announces the start of a code chunk. One of the most common options turns off printing out the code, but leaves the results alone: ```{r, echo=FALSE}

Another runs the code, but includes neither the text of the code nor its output. ```{r, include=FALSE} This might seem pointless, but it can be useful for code chunks which do set-up like loading data files, or initial model estimates, etc.

Another option prints the code in the document, but does not run it: ```{r, eval=FALSE} This is useful if you want to talk about the (nicely formatted) code.

The default print-out of matrices, tables, etc. from R Markdown is frankly ugly. The knitr package contains a very basic command, kable , which will format an array or data frame more nicely for display.

— Of course, R’s defaults print out a crazy number of decimal places, but this isn’t the time to discuss significant digits, or the signif function.

“Caching” Code Chunks (Re-Running Only When Changed)

By default, R Markdown will re-run all of your code every time you render your document. If some of your code is slow, this can add up to a lot of time. You can, however, ask R Markdown to keep track of whether a chunk of code has changed, and only re-run it if it has. This is called caching the chunk.

One issue is that a chunk of code which hasn’t changed itself might call on results of earlier, modified chunks, and then we would want to re-run the downstream chunks. There are options for manually telling R Markdown “this chunk depends on this earlier chunk”, but it’s generally easier to let it take care of that, by setting the autodep=TRUE option.

  • If you load a package with the library() or require() commands, R Markdown isn’t smart enough to check whether the package has changed (or indeed been installed, if you were missing it). So that won’t trigger an automatic re-running of a cached code chunk.
  • To manually force re-running all code chunks, the easiest thing to do is to delete the directory R Markdown will create (named something like filename _cache ) which it uses to store the state of all code chunks.

Setting Defaults for All Chunks

You can tell R to set some defaults to apply to all chunks where you don’t specifically over-ride them. Here are the ones I generally use:

This sets some additional options beyond the ones I’ve discussed, like not re-running a chunk if only the comments have changed ( cache.comments = FALSE ), and leaving out messages and warnings. (I’d only recommend suppressing warnings once you’re sure your code is in good shape.) I would typically give this set-up chunk itself the option include=FALSE .

You can over-ride these defaults by setting options for individual chunks.

More Options

See [ http://yihui.name/knitr/options/ ] for a complete listing of possible chunk options.

Math in R Markdown

Since this is a statistics class, you need to be able to write out mathematical expressions, often long series of them. R Markdown gives you the syntax to render complex mathematical formulas and derivations, and have them displayed very nicely. Like code, the math can either be inline or set off ( displays ).

Inline math is marked off witha pair of dollar signs ( $ ), as \(\pi r^2\) or \(e^{i\pi}\) .

Mathematical displays are marked off with \[ and \] , as in \[ e^{i \pi} = -1 \]

Once your text has entered math mode, R Markdown turns over the job of converting your text into math to a different program, called LaTeX 1 . This is the most common system for typesetting mathematical documents throughout the sciences, and has been for decades. It is extremely powerful, stable, available on basically every computer, and completely free. It is also, in its full power, pretty complicated. Fortunately, the most useful bits, for our purposes, are actually rather straightforward.

Elements of Math Mode

  • Most letters will be rendered in italics (compare: a vs.  a vs.  \(a\) ; only the last is in math mode). The spacing between letters also follows the conventions for math, so don’t treat it as just another way of getting italics. (Compare speed , in simple italics, with \(speed\) , in math mode.)
  • Greek letters can be accessed with the slash in front of their names, as \alpha for \(\alpha\) . Making the first letter upper case gives the upper-case letter, as in \Gamma for \(\Gamma\) vs.  \gamma for \(\gamma\) . (Upper-case alpha and beta are the same as Roman A and B, so no special commands for them.)
  • \times for \(\times\)
  • \cdot for \(\cdot\)
  • \leq and \geq for \(\leq\) and \(\geq\)
  • \subset and \subseteq for \(\subset\) and \(\subseteq\)
  • \leftarrow , \rightarrow , \Leftarrow , \Rightarrow for \(\leftarrow\) , \(\rightarrow\) , \(\Leftarrow\) , \(\Rightarrow\)
  • \approx , \sim , \equiv for \(\approx\) , \(\sim\) , \(\equiv\)
  • See, e.g., http://web.ift.uib.no/Teori/KURS/WRK/TeX/symALL.html for a fuller listing of available symbols. ( http://tug.ctan.org/info/symbols/comprehensive/symbols-a4.pdf lists all symbols available in LaTeX , including many non-mathematical special chracters)
  • Subscripts go after an underscore character, _ , and superscripts go after a caret, ^ , as \beta_1 for \(\beta_1\) or a^2 for \(a^2\) .
  • Curly braces are used to create groupings that should be kept together, e.g., a_{ij} for \(a_{ij}\) (vs.  a_ij for \(a_ij\) ).
  • If you need something set in ordinary (Roman) type within math mode, use \mathrm , as t_{\mathrm{in}}^2 for \(t_{\mathrm{in}}^2\) .
  • If you’d like something set in an outline font (“blackboard bold”), use \mathbb , as \mathbb{R} for \(\mathbb{R}\) .
  • For bold face, use \mathbf , as

for \[ (\mathbf{x}^T\mathbf{x})^{-1}\mathbf{x}^T\mathbf{y} \] * Accents on characters work rather like changes of font: \vec{a} produces \(\vec{a}\) , \hat{a} produces \(\hat{a}\) . Some accents, particularly hats, work better if they space out, as with \widehat{\mathrm{Var}} producing \(\widehat{\mathrm{Var}}\) . * Function names are typically written in romans, and spaced differently: thus \(\log{x}\) , not \(log x\) . LaTeX , and therefore R Markdown , knows about a lot of such functions, and their names all begin with \ . For instance: \log , \sin , \cos , \exp , \min , etc. Follow these function names with the argument in curly braces; this helps LaTeX figure out what exactly the argument is, and keep it grouped together with the function name when it’s laying out the text. Thus \log{(x+1)} is better than \log (x+1) . * Fractions can be created with \frac , like so:

produces \[ \frac{a+b}{b} = 1 + \frac{a}{b} \] * Sums can be written like so:

will produce \[ \sum_{i=1}^{n}{x_i^2} \] The lower and upper limits of summation after the \sum are both optional. Products and integrals work similarly, only with \prod and \int : \[ n! = \prod_{i=1}^{n}{i} \] \[ \log{b} - \log{a} = \int_{x=a}^{x=b}{\frac{1}{x} dx} \] \sum , \prod and \int all automatically adjust to the size of the expression being summed, producted or integrated. * “Delimiters”, like parentheses or braces, can automatically re-size to match what they’re surrounding. To do this, you need to use \left and \right , as

renders as \[ \left( \sum_{i=1}^{n}{i} \right)^2 = \left( \frac{n(n-1)}{2}\right)^2 = \frac{n^2(n-1)^2}{4} \] + To use curly braces as delimiters, precede them with slashes, as \{ and \} for \(\{\) and \(\}\) . * Multiple equations, with their equals signs lined up, can be created using eqnarray , as follows.

\[ \begin{eqnarray} X & \sim & \mathrm{N}(0,1)\\ Y & \sim & \chi^2_{n-p}\\ R & \equiv & X/Y \sim t_{n-p} \end{eqnarray} \] Notice that & surrounds what goes in the middle on each line, and each line (except the last) is terminated with \\ . The left or right hand side of the equation can be blank, and space will be made:

\[ \begin{eqnarray} P(|X-\mu| > k) & = & P(|X-\mu|^2 > k^2)\\ & \leq & \frac{\mathbb{E}\left[|X-\mu|^2\right]}{k^2}\\ & \leq & \frac{\mathrm{Var}[X]}{k^2} \end{eqnarray} \]

(In full LaTeX , \begin{eqnarray} automatically enters math mode, but R Markdown needs the hint.)

Translating Math into LaTeX

LaTeX is designed so that every part of a mathematical expression has a reasonably straightforward counterpart in what you write. Still, it can be a bit intimidating at first. What many people find useful to to start by taking some page of printed or hand-written math and then deliberately translate that, line by line, into LaTeX , and then rendering it to see whether it came out right (and, if not, where to fix things). If you need to do any math for an assignment, it can be a good idea to write the math out by hand, and then turn it into LaTeX , whether the class requires it (like this one) or not. Eventually, with practice, the translation will become quite automatic, and some people even do new math by writing out the LaTeX .

LaTeX Does Not Check Correctness

LaTeX does not check whether your math is right ; it just checks whether it can figure out what you’re trying to say well enough to type-set it. Thus for instance it has no problem at all with the following:

\[ \begin{eqnarray} (n+1)(n-1) & = & n^2\\ n^2 -1 & = & n^2\\ -1 & = & 0\\ 1 & = & 0\\ -1 & = & 1 \end{eqnarray} \]

(There are computer programs for doing symbolic mathematics which, in effect, do check whether your math is right, at least if you’re working in the sub-area of math they’re designed to handle. So far as I know, no one has ever really combined them with LaTeX .)

Installing LaTeX

If you are producing a PDF report on RStudio Cloud then you can skip this section.

If you render your R Markdown document to HTML, you do not need to install LaTeX on your computer. This is because the HTML includes instructions to browsers, which say (as it were) “Send the funny-looking bits with all the slashes to mathjax.org , and it will send you back pretty pictures of equations”. The website actually runs the LaTeX .

If you want to produce PDF on your own computer then you need to install LaTeX . How you actually do this depends on the precise kind of computer. For Macs, I recommend using the MacTeX package, available from https://tug.org/mactex/mactex-download.html . For other systems, follow the links from http://www.tug.org/begin.html .

Putting It All Together: Writing A Report in R Markdown

  • You have installed the rmarkdown package and all its dependencies.
  • You have installed LaTeX , if you’re producing a PDF.
  • You have installed and fired up your favorite text editor.
  • You give it a title, an author, and a date.
  • One common pattern: “Introduction”, “Data and Research Questions”, “Analysis”, “Results”, “Conclusion”.
  • Another common pattern: “Problem 1”, “Problem 2”, … , “Extra Credit”.
  • You write text.
  • When you need it, you insert math into the text, or even whole mathematical displays.
  • The code runs (as needed) when you render the document.
  • Figures, tables, and other output are automatically inserted into the document, and track changes in your code.
  • When you (think you) have finished a section is a good time to do so.
  • Another good time is once you’ve made any non-trivial change to the code or the text.
  • If it did, and you like the results, congratulate yourself and cheerfully go on to your next task.
  • If it rendered but you don’t like the results, think about why and try to fix it.
  • If it didn’t render, R will tell you where it gave up, so try to debug from around there.

Troubleshooting/Stuff to Avoid

  • Do not call View or help in your document; these are interactive commands which don’t work well in scripts.
  • R Studio keeps two environments or workspaces which it uses to evaluate R expressions, look up function or variable names, etc. One is the “usual” global environment of the console, which builds cumulatively from the start of your session. (Unless you deliberately manipulate it; don’t do that unless you know what you’re doing.) Every time you knit, however, it re-runs your code in clean workspace, as though you had just started R from scratch. This means knitted code does what you say it should, and only that. If your code knits, it should work on any computer; getting something to run in the console which you can’t reproduce is just dumb luck.
  • “It works when I source it, but it won’t knit”: This is basically the same problem as “it worked in the console”.
  • Avoid attach in both the console and in your file; using it is a recipe for creating hard-to-find errors. You can still shorten expressions using with instead.
  • Do try to fix your LaTeX installation later, when you don’t have such time pressure; it’s really useful.
  • LaTeX will complain if you try to print out truly enormous things. Errors about “out of stack”, or “pandoc 43”, are often caused by this. Don’t print out enormous things. (Suppressing warnings and other messages may help.)
  • When you need to load data files or source someone else’s code, use full URLs, rather than creating local copies and loading them from your disk.

Further Reading

For more on R Markdown, see http://rmarkdown.rstudio.com , particularly the more detailed help pages (rather than the first-guides).

For LaTeX , the classic reference is the book by Leslie Lamport, LaTeX: A Document Preparation System (2nd ed., Reading, Mass.: Addison-Wesley, 1994). This is not, admittedly, the easiest read in the world. LaTeX , from Wikibooks, is more accessible, and free online in easy bite-sized chunks.

R Markdown is based on the knitr package, developed by Yihui Xie, for integrated R with LaTeX ; see http://yihui.name/knitr/ , and, for full documentation, Xie’s book Dynamic Documents with R and knitr (2nd edition, Boca Raton, Florida; CRC Press, 2016).

For an thorough, entertaining, and completely correct explanation of why “The word processor is a stupid and grossly inefficient tool for preparing text for communication with others”, see http://ricardo.ecn.wfu.edu/~cottrell/wp.html .

Acknowledgments

This document borrows heavily from Prof.  Cozma Shalizi ’s Using R Markdown for Class Reports .

R Markdown source for this page

In the 1970s, the great computer scientist Donald Knuth wrote a mark-up language, and a rendering program for that language, called TeX (pronounced “tech”), for writing complex mathematical documents. In the 1980s, the computer scientist Leslie Lamport extended TeX in ways that made it rather more user-friendly, and called the result LaTeX (pronounced “la-tech”). ↩︎

Creative Commons License

13-Factor Analysis

9 r markdown & assignments, 9.1 introduction to r markdown.

You can download the example markdown file here

This page will guide you through creating and editing R Markdown documents. This is a useful tool for reporting your analysis (e.g. for homework assignments). Of course, there is also a cheat sheet for R-Markdown and this book contains a comprehensive discussion of the format.

The following video contains a short introduction to the R Markdown format.

Creating a new R Markdown document

In addition to the video, the following text contains a short description of the most important formatting options.

Let’s start to go through the steps of creating and .Rmd file and outputting the content to an HTML file.

If an R-Markdown file was provided to you, open it with R-Studio and skip to step 4 after adding your answers.

Open R-Studio

r markdown assignment

3.1. Add your answers

3.2. Save again

r markdown assignment

Text and Equations

R-Markdown documents are plain text files that include both text and R-code. Using RStudio they can be converted (‘knitted’) to HTML or PDF files that include both the text and the results of the R-code. In fact this website is written using R-Markdown and RStudio. In order for RStudio to be able to interpret the document you have to use certain characters or combinations of characters when formatting text and including R-code to be evaluated. By default the document starts with the options for the text part. You can change the title, date, author and a few more advanced options.

r markdown assignment

First lines of an R-Markdown document

The default is text mode, meaning that lines in an Rmd document will be interpreted as text, unless specified otherwise.

Usually you want to include some kind of heading to structure your text. A heading is created using # signs. A single # creates a first level heading, two ## a second level and so on.

r markdown assignment

It is important to note here that the # symbol means something different within the code chunks as opposed to outside of them. If you continue to put a # in front of all your regular text, it will all be interpreted as a first level heading, making your text very large.

Bullet point lists are created using * , + or - . Sub-items are created by indenting the item using 4 spaces or 2 tabs.

  • first sub-sub-item
  • second sub-item

Ordered lists can be created using numbers and letters. If you need sub-sub-items use A) instead of A. on the third level.

  • Second item

Text formatting

Text can be formatted in italics ( *italics* ) or bold ( **bold** ). In addition, you can ad block quotes with >

Lorem ipsum dolor amet chillwave lomo ramps, four loko green juice messenger bag raclette forage offal shoreditch chartreuse austin. Slow-carb poutine meggings swag blog, pop-up salvia taxidermy bushwick freegan ugh poke.

R-code is contained in so called “chunks.” These chunks always start with three backticks and r in curly braces ( {r} ) and end with three backticks ( ). Optionally, parameters can be added after the r to influence how a chunk behaves. Additionally, you can also give each chunk a name. Note that these have to be unique , otherwise R will refuse to knit your document.

Global and chunk options

The first chunk always looks as follows

It is added to the document automatically and sets options for all the following chunks. These options can be overwritten on a per-chunk basis.

Keep knitr::opts_chunk$set(echo = TRUE) to print your code to the document you will hand in. Changing it to knitr::opts_chunk$set(echo = FALSE) will not print your code by default. This can be changed on a per-chunk basis.

r markdown assignment

A good overview of all available global/chunk options can be found here .

Writing well formatted mathematical formulas is done the same way as in LaTeX . Math mode is started and ended using $$ .

\[ f_1(\omega) = \frac{\sigma^2}{2 \pi},\ \omega \in[-\pi, \pi] \]

(for those interested this is the spectral density of white noise )

Including inline mathematical notation is done with a single $ symbol.

\({2\over3}\) of my code is inline.

Take a look at this wikibook on Mathematics in LaTeX and this list of Greek letters and mathematical symbols if you are not familiar with LaTeX.

In order to write multi-line equations in the same math environment, use \\ after every line. In order to insert a space use a single \ . To render text inside a math environment use \text{here is the text} . In order to align equations start with \begin{align} and place an & in each line at the point around which it should be aligned. Finally end with \end{align}

\[ \begin{align} \text{First equation: }\ Y &= X \beta + \epsilon_y,\ \forall X \\ \text{Second equation: }\ X &= Z \gamma + \epsilon_x \end{align} \]

Important symbols

The {} after _ and ^ are not strictly necessary if there is only one character in the sub-/superscript. However, in order to place multiple characters in the sub-/superscript they are necessary. e.g.

Greek letters

Greek letters are preceded by a \ followed by their name ( $\beta$ = \(\beta\) ). In order to capitalize them simply capitalize the first letter of the name ( $\Gamma$ = \(\Gamma\) ).

r markdown assignment

Foundations of Statistics with R

A an r markdown primer for doing homework.

RStudio has included a method for making higher quality documents from a combination of R code and some basic markdown formatting, which is called R Markdown.

In order to create an R Markdown file, inside RStudio you click on File , then New File and R Markdown . You will be prompted to enter a Title and an Author. For now, leave the Default Output Format as .html and leave the Document icon higlighted. When you have entered an acceptable title and author, click OK and a new tab in the Source pane should open up. (That is the top left pane in RStudio.)

You should see something that looks like this, with some more things underneath.

--- title: “Untitled” author: “Darrin Speegle” date: “1/20/2017” output: html_document ---

This part of the code is the YAML (YAML Ain’t Markup Language). At this point, you will want to delete all of the text below the YAML, starting with

```{r setup, }

Let’s suppose that you are writing up solutions to a homework one. It would be a good idea to have a centered title that indicates which homewok this is, so you would change title: “Untitled” to title: “Homework 1”. The author of the document should be your name, and the date should be the date that the homework is due. Let’s suppose that the homework is due January 25, 2017. I would change the YAML, then, to look like this:

--- title: “Homework 1” author: “Darrin Speegle” date: “1/25/2017” output: html_document ---

Just to see what that did, click on the Knit button just above the Source pane. A window should pup up that says Homework 1 in bold, followed by your name and the date that you entered. If that didn’t happen, redo the above.

For the purposes of this primer, I am assuming that you are typing up solutions to a homework. Modify your file to make it look like this, and then Knit again.

  • putting a 1. at the beginning of a line will start a numbered list.
  • Putting mtcars in single quotes will make the background shaded, so that it is clear that it is an R object of some sort.
  • The part beginning with ```{r} and ending with ``` is called an R chunk. You can create a new R chunk by using Command + Alt + I. When you knit your file, R Markdown puts the commands that used in a shaded box, to indicate that it is R code. Then, it also executes the R commands and shows the output.
  • Text should not be inside of the R chunk. You should put your text either above or below the chunk.
  • For the purposes of your homework, every problem needs to have some sort of explanation in words. Just giving the R code will not be sufficient. You will need to explain what it is you have done. (In the early homeworks, this can often be done quite quickly.)
  • If you are using a package inside R Markdown, you must load the package inside your markdown file! I recommend loading all libraries at the top of the markdown file. For example, if you need to use the data set Batting in the Lahman package, I recommend starting your homework like this

In order to finish typing up the solutions to Homework 1, you should continue with your list of problems, and insert R chunks with the R code that you need plus some explanation in words for each problem.

When you are done, you should Knit the document again, and a new .html file will appear. You should print out the pretty .html version (not the Markdown code) and hand that in. I will also want you to turn in your .Rmd file (the ugly Markdown code) separately. At this point, you are ready to go. The last thing I would say is that Markdown has a lot more typesetting that it can do than what I have indicated up to this point. There are many good resources on this, for example Grolemund and Wickham or Ismay .

r markdown assignment

R for Data Science

27 r markdown, 27.1 introduction.

R Markdown provides an unified authoring framework for data science, combining your code, its results, and your prose commentary. R Markdown documents are fully reproducible and support dozens of output formats, like PDFs, Word files, slideshows, and more.

R Markdown files are designed to be used in three ways:

For communicating to decision makers, who want to focus on the conclusions, not the code behind the analysis.

For collaborating with other data scientists (including future you!), who are interested in both your conclusions, and how you reached them (i.e. the code).

As an environment in which to do data science, as a modern day lab notebook where you can capture not only what you did, but also what you were thinking.

R Markdown integrates a number of R packages and external tools. This means that help is, by-and-large, not available through ? . Instead, as you work through this chapter, and use R Markdown in the future, keep these resources close to hand:

R Markdown Cheat Sheet: Help > Cheatsheets > R Markdown Cheat Sheet ,

R Markdown Reference Guide: Help > Cheatsheets > R Markdown Reference Guide .

Both cheatsheets are also available at https://rstudio.com/resources/cheatsheets/ .

27.1.1 Prerequisites

You need the rmarkdown package, but you don’t need to explicitly install it or load it, as RStudio automatically does both when needed.

27.2 R Markdown basics

This is an R Markdown file, a plain text file that has the extension .Rmd :

It contains three important types of content:

  • An (optional) YAML header surrounded by --- s.
  • Chunks of R code surrounded by ``` .
  • Text mixed with simple text formatting like # heading and _italics_ .

When you open an .Rmd , you get a notebook interface where code and output are interleaved. You can run each code chunk by clicking the Run icon (it looks like a play button at the top of the chunk), or by pressing Cmd/Ctrl + Shift + Enter. RStudio executes the code and displays the results inline with the code:

r markdown assignment

To produce a complete report containing all text, code, and results, click “Knit” or press Cmd/Ctrl + Shift + K. You can also do this programmatically with rmarkdown::render("1-example.Rmd") . This will display the report in the viewer pane, and create a self-contained HTML file that you can share with others.

r markdown assignment

When you knit the document, R Markdown sends the .Rmd file to knitr , http://yihui.name/knitr/ , which executes all of the code chunks and creates a new markdown (.md) document which includes the code and its output. The markdown file generated by knitr is then processed by pandoc , http://pandoc.org/ , which is responsible for creating the finished file. The advantage of this two step workflow is that you can create a very wide range of output formats, as you’ll learn about in R markdown formats .

r markdown assignment

To get started with your own .Rmd file, select File > New File > R Markdown… in the menubar. RStudio will launch a wizard that you can use to pre-populate your file with useful content that reminds you how the key features of R Markdown work.

The following sections dive into the three components of an R Markdown document in more details: the markdown text, the code chunks, and the YAML header.

27.2.1 Exercises

Create a new notebook using File > New File > R Notebook . Read the instructions. Practice running the chunks. Verify that you can modify the code, re-run it, and see modified output.

Create a new R Markdown document with File > New File > R Markdown… Knit it by clicking the appropriate button. Knit it by using the appropriate keyboard short cut. Verify that you can modify the input and see the output update.

Compare and contrast the R notebook and R markdown files you created above. How are the outputs similar? How are they different? How are the inputs similar? How are they different? What happens if you copy the YAML header from one to the other?

Create one new R Markdown document for each of the three built-in formats: HTML, PDF and Word. Knit each of the three documents. How does the output differ? How does the input differ? (You may need to install LaTeX in order to build the PDF output — RStudio will prompt you if this is necessary.)

27.3 Text formatting with Markdown

Prose in .Rmd files is written in Markdown, a lightweight set of conventions for formatting plain text files. Markdown is designed to be easy to read and easy to write. It is also very easy to learn. The guide below shows how to use Pandoc’s Markdown, a slightly extended version of Markdown that R Markdown understands.

The best way to learn these is simply to try them out. It will take a few days, but soon they will become second nature, and you won’t need to think about them. If you forget, you can get to a handy reference sheet with Help > Markdown Quick Reference .

27.3.1 Exercises

Practice what you’ve learned by creating a brief CV. The title should be your name, and you should include headings for (at least) education or employment. Each of the sections should include a bulleted list of jobs/degrees. Highlight the year in bold.

Using the R Markdown quick reference, figure out how to:

  • Add a footnote.
  • Add a horizontal rule.
  • Add a block quote.

Copy and paste the contents of diamond-sizes.Rmd from https://github.com/hadley/r4ds/tree/master/rmarkdown in to a local R markdown document. Check that you can run it, then add text after the frequency polygon that describes its most striking features.

27.4 Code chunks

To run code inside an R Markdown document, you need to insert a chunk. There are three ways to do so:

The keyboard shortcut Cmd/Ctrl + Alt + I

The “Insert” button icon in the editor toolbar.

By manually typing the chunk delimiters ```{r} and ``` .

Obviously, I’d recommend you learn the keyboard shortcut. It will save you a lot of time in the long run!

You can continue to run the code using the keyboard shortcut that by now (I hope!) you know and love: Cmd/Ctrl + Enter. However, chunks get a new keyboard shortcut: Cmd/Ctrl + Shift + Enter, which runs all the code in the chunk. Think of a chunk like a function. A chunk should be relatively self-contained, and focussed around a single task.

The following sections describe the chunk header which consists of ```{r , followed by an optional chunk name, followed by comma separated options, followed by } . Next comes your R code and the chunk end is indicated by a final ``` .

27.4.1 Chunk name

Chunks can be given an optional name: ```{r by-name} . This has three advantages:

You can more easily navigate to specific chunks using the drop-down code navigator in the bottom-left of the script editor:

r markdown assignment

Graphics produced by the chunks will have useful names that make them easier to use elsewhere. More on that in other important options .

You can set up networks of cached chunks to avoid re-performing expensive computations on every run. More on that below.

There is one chunk name that imbues special behaviour: setup . When you’re in a notebook mode, the chunk named setup will be run automatically once, before any other code is run.

27.4.2 Chunk options

Chunk output can be customised with options , arguments supplied to chunk header. Knitr provides almost 60 options that you can use to customize your code chunks. Here we’ll cover the most important chunk options that you’ll use frequently. You can see the full list at http://yihui.name/knitr/options/ .

The most important set of options controls if your code block is executed and what results are inserted in the finished report:

eval = FALSE prevents code from being evaluated. (And obviously if the code is not run, no results will be generated). This is useful for displaying example code, or for disabling a large block of code without commenting each line.

include = FALSE runs the code, but doesn’t show the code or results in the final document. Use this for setup code that you don’t want cluttering your report.

echo = FALSE prevents code, but not the results from appearing in the finished file. Use this when writing reports aimed at people who don’t want to see the underlying R code.

message = FALSE or warning = FALSE prevents messages or warnings from appearing in the finished file.

results = 'hide' hides printed output; fig.show = 'hide' hides plots.

error = TRUE causes the render to continue even if code returns an error. This is rarely something you’ll want to include in the final version of your report, but can be very useful if you need to debug exactly what is going on inside your .Rmd . It’s also useful if you’re teaching R and want to deliberately include an error. The default, error = FALSE causes knitting to fail if there is a single error in the document.

The following table summarises which types of output each option suppresses:

27.4.3 Table

By default, R Markdown prints data frames and matrices as you’d see them in the console:

If you prefer that data be displayed with additional formatting you can use the knitr::kable function. The code below generates Table 27.1 .

Read the documentation for ?knitr::kable to see the other ways in which you can customise the table. For even deeper customisation, consider the xtable , stargazer , pander , tables , and ascii packages. Each provides a set of tools for returning formatted tables from R code.

There is also a rich set of options for controlling how figures are embedded. You’ll learn about these in saving your plots .

27.4.4 Caching

Normally, each knit of a document starts from a completely clean slate. This is great for reproducibility, because it ensures that you’ve captured every important computation in code. However, it can be painful if you have some computations that take a long time. The solution is cache = TRUE . When set, this will save the output of the chunk to a specially named file on disk. On subsequent runs, knitr will check to see if the code has changed, and if it hasn’t, it will reuse the cached results.

The caching system must be used with care, because by default it is based on the code only, not its dependencies. For example, here the processed_data chunk depends on the raw_data chunk:

Caching the processed_data chunk means that it will get re-run if the dplyr pipeline is changed, but it won’t get rerun if the read_csv() call changes. You can avoid that problem with the dependson chunk option:

dependson should contain a character vector of every chunk that the cached chunk depends on. Knitr will update the results for the cached chunk whenever it detects that one of its dependencies have changed.

Note that the chunks won’t update if a_very_large_file.csv changes, because knitr caching only tracks changes within the .Rmd file. If you want to also track changes to that file you can use the cache.extra option. This is an arbitrary R expression that will invalidate the cache whenever it changes. A good function to use is file.info() : it returns a bunch of information about the file including when it was last modified. Then you can write:

As your caching strategies get progressively more complicated, it’s a good idea to regularly clear out all your caches with knitr::clean_cache() .

I’ve used the advice of David Robinson to name these chunks: each chunk is named after the primary object that it creates. This makes it easier to understand the dependson specification.

27.4.5 Global options

As you work more with knitr, you will discover that some of the default chunk options don’t fit your needs and you want to change them. You can do this by calling knitr::opts_chunk$set() in a code chunk. For example, when writing books and tutorials I set:

This uses my preferred comment formatting, and ensures that the code and output are kept closely entwined. On the other hand, if you were preparing a report, you might set:

That will hide the code by default, so only showing the chunks you deliberately choose to show (with echo = TRUE ). You might consider setting message = FALSE and warning = FALSE , but that would make it harder to debug problems because you wouldn’t see any messages in the final document.

27.4.6 Inline code

There is one other way to embed R code into an R Markdown document: directly into the text, with: `r ` . This can be very useful if you mention properties of your data in the text. For example, in the example document I used at the start of the chapter I had:

We have data about `r nrow(diamonds)` diamonds. Only `r nrow(diamonds) - nrow(smaller)` are larger than 2.5 carats. The distribution of the remainder is shown below:

When the report is knit, the results of these computations are inserted into the text:

We have data about 53940 diamonds. Only 126 are larger than 2.5 carats. The distribution of the remainder is shown below:

When inserting numbers into text, format() is your friend. It allows you to set the number of digits so you don’t print to a ridiculous degree of accuracy, and a big.mark to make numbers easier to read. I’ll often combine these into a helper function:

27.4.7 Exercises

Add a section that explores how diamond sizes vary by cut, colour, and clarity. Assume you’re writing a report for someone who doesn’t know R, and instead of setting echo = FALSE on each chunk, set a global option.

Download diamond-sizes.Rmd from https://github.com/hadley/r4ds/tree/master/rmarkdown . Add a section that describes the largest 20 diamonds, including a table that displays their most important attributes.

Modify diamonds-sizes.Rmd to use comma() to produce nicely formatted output. Also include the percentage of diamonds that are larger than 2.5 carats.

Set up a network of chunks where d depends on c and b , and both b and c depend on a . Have each chunk print lubridate::now() , set cache = TRUE , then verify your understanding of caching.

27.5 Troubleshooting

Troubleshooting R Markdown documents can be challenging because you are no longer in an interactive R environment, and you will need to learn some new tricks. The first thing you should always try is to recreate the problem in an interactive session. Restart R, then “Run all chunks” (either from Code menu, under Run region), or with the keyboard shortcut Ctrl + Alt + R. If you’re lucky, that will recreate the problem, and you can figure out what’s going on interactively.

If that doesn’t help, there must be something different between your interactive environment and the R markdown environment. You’re going to need to systematically explore the options. The most common difference is the working directory: the working directory of an R Markdown is the directory in which it lives. Check the working directory is what you expect by including getwd() in a chunk.

Next, brainstorm all the things that might cause the bug. You’ll need to systematically check that they’re the same in your R session and your R markdown session. The easiest way to do that is to set error = TRUE on the chunk causing the problem, then use print() and str() to check that settings are as you expect.

27.6 YAML header

You can control many other “whole document” settings by tweaking the parameters of the YAML header. You might wonder what YAML stands for: it’s “yet another markup language”, which is designed for representing hierarchical data in a way that’s easy for humans to read and write. R Markdown uses it to control many details of the output. Here we’ll discuss two: document parameters and bibliographies.

27.6.1 Parameters

R Markdown documents can include one or more parameters whose values can be set when you render the report. Parameters are useful when you want to re-render the same report with distinct values for various key inputs. For example, you might be producing sales reports per branch, exam results by student, or demographic summaries by country. To declare one or more parameters, use the params field.

This example uses a my_class parameter to determine which class of cars to display:

As you can see, parameters are available within the code chunks as a read-only list named params .

You can write atomic vectors directly into the YAML header. You can also run arbitrary R expressions by prefacing the parameter value with !r . This is a good way to specify date/time parameters.

In RStudio, you can click the “Knit with Parameters” option in the Knit dropdown menu to set parameters, render, and preview the report in a single user friendly step. You can customise the dialog by setting other options in the header. See http://rmarkdown.rstudio.com/developer_parameterized_reports.html#parameter_user_interfaces for more details.

Alternatively, if you need to produce many such parameterised reports, you can call rmarkdown::render() with a list of params :

This is particularly powerful in conjunction with purrr:pwalk() . The following example creates a report for each value of class found in mpg . First we create a data frame that has one row for each class, giving the filename of the report and the params :

Then we match the column names to the argument names of render() , and use purrr’s parallel walk to call render() once for each row:

27.6.2 Bibliographies and Citations

Pandoc can automatically generate citations and a bibliography in a number of styles. To use this feature, specify a bibliography file using the bibliography field in your file’s header. The field should contain a path from the directory that contains your .Rmd file to the file that contains the bibliography file:

You can use many common bibliography formats including BibLaTeX, BibTeX, endnote, medline.

To create a citation within your .Rmd file, use a key composed of ‘@’ + the citation identifier from the bibliography file. Then place the citation in square brackets. Here are some examples:

When R Markdown renders your file, it will build and append a bibliography to the end of your document. The bibliography will contain each of the cited references from your bibliography file, but it will not contain a section heading. As a result it is common practice to end your file with a section header for the bibliography, such as # References or # Bibliography .

You can change the style of your citations and bibliography by referencing a CSL (citation style language) file in the csl field:

As with the bibliography field, your csl file should contain a path to the file. Here I assume that the csl file is in the same directory as the .Rmd file. A good place to find CSL style files for common bibliography styles is http://github.com/citation-style-language/styles .

27.7 Learning more

R Markdown is still relatively young, and is still growing rapidly. The best place to stay on top of innovations is the official R Markdown website: http://rmarkdown.rstudio.com .

There are two important topics that we haven’t covered here: collaboration, and the details of accurately communicating your ideas to other humans. Collaboration is a vital part of modern data science, and you can make your life much easier by using version control tools, like Git and GitHub. We recommend two free resources that will teach you about Git:

“Happy Git with R”: a user friendly introduction to Git and GitHub from R users, by Jenny Bryan. The book is freely available online: http://happygitwithr.com

The “Git and GitHub” chapter of R Packages , by Hadley. You can also read it for free online: http://r-pkgs.had.co.nz/git.html .

I have also not touched on what you should actually write in order to clearly communicate the results of your analysis. To improve your writing, I highly recommend reading either Style: Lessons in Clarity and Grace by Joseph M. Williams & Joseph Bizup, or The Sense of Structure: Writing from the Reader’s Perspective by George Gopen. Both books will help you understand the structure of sentences and paragraphs, and give you the tools to make your writing more clear. (These books are rather expensive if purchased new, but they’re used by many English classes so there are plenty of cheap second-hand copies). George Gopen also has a number of short articles on writing at https://www.georgegopen.com/the-litigation-articles.html . They are aimed at lawyers, but almost everything applies to data scientists too.

How to write homework answers using R Markdown

This file aims to demonstrate the basics of writing up homework solutions in R markdown and output it as an html file. The html file can then be printed and turned in.

Install needed R pacakges

Assume R and R studio have been installed. Open Rstudio, the lower left corner of Rstudio is the Console window, where you can execute R commands.

Now install R packages Markdown and knitr (make sure you have internet connection since the following two commands install these packages from the online respository https://cran.r-project.org/ ) as follows:

  • install R package Markdown for formatting syntax:
  • install R package knitr for compling
  • set knitr as the compiler in Rstudio

In Rstudio, from the task menu, click on “Tools”, from the drop down menu click “Global options….” and you will get a pop up window; from the left panel of the pop up window, click “Sweave”; on the top of the right panel of the same pop up window, there is a line “Weave Rnw file using:”; click the triangle right after this line, and choose “knitr”.

You have been set to use knitr+Markdown to write up homework solutions. Note you may need to restart Rstudio for these settings to take effect.

Create a Markdown file

Note Markdown files have suffices “.Rmd”. [R markdown cheat sheet]{ https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf }.

First, choose a working directory (always a good step). You need to let Rstudio know of your working directory, so that all files for current R session will be stored there. Open Rstudio, In the console, execute command:

Once you are done editing the markdown file, the generated html file will be stored in this directory.

Secondly, create the markdown file using Rstudio. From the task menu of Rstudio, click “File”, and a drop down menu will appear; position your mouse cursor on “New File” on the menu, a pop up menu will appear; from this pop up menu, select “R Markdown” and you will see a second pop up meanu; proceed, fill in the Title and Author information, and choose HTML as the Defult Output Format . You have justed created a Markdown file. Save it somewhere.

You are ready to write up solutions …

Load data via txt file

All homework datasets as .txt files for version 6 of the text book can be downloaded from: http://www.cengage.com/cgi-wadsworth/course_products_wp.pl?fid=M63&product_isbn_issn=9780495017585&chapter_number=0&resource_id=277&altname=Datasets . I have also stored the tab delimited version of these files in txt format in: http://math.wsu.edu/faculty/xchen/stat412/data/stat412ASCII-tab/ . The naming convention for these txt file are: exA-B, where A is the Chapter number and B the exercise number; e.g., ex3-3.TXT means data set for exercise 3 of Chapter 3.

You can load a data set by the command:

Remember to use quotes for path_to_file/file_name.txt when loading a file. Please look into the help file for command “read.table”:

R codes in Markdown file

R codes are put into chunks, and each chunk is wrapped by two pairs of triple backticks. If you do not want the R codes in a chunk to be evaluated use {r, eval=FALSE} right after the beginning triple backticks. To see a R codes chunk, you need to open the .Rmd file.

Examples of answering

Question: For the data in Exercise 14 of Chapter 3, find the mean and median of sales amount and create a histogram for it.

Answer: (1) The mean and median of sale amount are 118.7 and 117.0; (2) The histogram is given below.

Answer to Exercise 2:

Your answer

Compile Rmd file into html file

Near the upper left corner of the window in which you are editing the markdown file, there is a button “Knit HTML”, click on it to generate the html file. Printe the html file …

Assignment Guidelines

  • Data Sources
  • Census Geography

Professor Noli Brazil

Assignments will be released on Canvas as a pdf and will be due approximately every two weeks. They have two components:

  • Executing data analysis tasks - for example, create a map or run a statistical model and interpret its results.
  • Answering conceptual questions - for example, interpret a concept introduced in lecture or the textbook.

You will use R Markdown to write up all R related assignments. This guide will go through the steps for answering and submitting class assignment questions using R Markdown. For a thorough rundown of R Markdown, see Chapter 27 in RDS.

Running R code using the console (bottom left in figure below) is a great place to start, but has its limitations. Each time you want to execute a set of commands, you have to re-enter them at the command line. Complex commands are potentially subject to typographical errors, necessitating that they be re-entered correctly. Repeating a set of operations requires re-entering the code stream. To give yourself more room to work, it’s a great idea to use the R script editor.

A script is simply a text file containing a set of commands and comments. The script can be saved and used later to re-execute the saved commands. The script can also be edited so you can execute a modified version of the commands.

You can open a new empty script by clicking the New File icon in the upper left of the main RStudio toolbar. This icon looks like a white square with a white plus sign in a green circle. Clicking the icon opens the New File Menu. Click the “R Script” option and the script editor will open with an empty script. Your R Studio should look similar to below (image source: R for Data Science )

r markdown assignment

R Scripts are basically text files with a .R extension that houses your code and comments. You write your code. Execute that code from your R script. Results are produced in your R console window. In this class, we won’t be using regular R Scripts for homework assignments. Instead, we’ll be using R Markdown .

R Markdown documents take script files to a new level by allowing you to mix R commands with explanatory text. Think of an R Markdown document as an R script on steroids. Your R Markdown source document is compiled into an output report evaluating the R commands in the source document to produce easily reproducible results in an aesthetically pleasing form. It combines code, results from the code, and narrative text explaining the results to produce beautiful documents and academic reports.

Still not convinced that R Markdown is useful? Check out Nikhil Kaza’s thorough description of R Markdown’s virtues .

R Markdown is a simple formatting syntax for authoring html, pdf, and Microsoft Word documents in RStudio. For each R related assignment, you will upload onto Canvas two documents:

  • An R Markdown document, which has an .Rmd extension
  • A knitted .html , .pdf or .docx file

These documents will provide us an easy-to-read document to grade; more importantly, you will get to practice (1) writing scripts, (2) keeping track of the analyses you run, and (3) organizing your output in a reader-friendly manner. When you submit these documents on Canvas, do not combine them into a zipped compressed folder . They should be two separate files.

To be clear, R is a programming language . RStudio is an application . R Markdown is a markup syntax to convert R script and text into a pdf or html document. It allows for presentation-ready documents that show commands and results in a seamless flow. When you write R code and embed it in presentation documents created using R Markdown, you are forced to explicitly state the steps you took to do your research.

In RStudio, install the packages knitr and rmarkdown using the install.packages() command. Type the following in your RConsole window after >

Once you’ve installed these packages, you don’t need to install them any more in the future. You also do not need to load them in at any time using library() .

Creating and saving an R Markdown

To create a new .Rmd file in RStudio, select File -> New File -> R Markdown. A window should pop up. Type in “Assignment 1” next to Title and your name next to Author . Leave everything else alone and click OK. A new window in the top left of your RStudio console should pop up containing your new R Markdown file.

r markdown assignment

The full RStudio interface

If you are using your personal computer for this guide, it’s best to set up a clean and efficient file management structure. File management is key to preventing R programming frustration. Here are some tips.

  • Set up a clear and understandable hierarchical file system for this class on your hard drive. For example, create a class folder (CRD 230). Within this class folder, create the folder Assignments. Within the Assignments folder, create separate folders for each Assignment (e.g. Assignment 1, Assignment 2, …). Don’t work from your Desktop. Or from the Downloads folder. Or some randomly named folder that you will have a hard time finding a month, week or day from now. You might end having a system that looks like the following (on a Mac)

This is what file organization looks like

  • Keep all your files that are related to a lab or assignment in one folder. That is, don’t have an Assignment 3 folder that contains data files specific to Assignment 1. Keep everything in one folder, including the R Markdown for that assignment or lab.

Using the basic guidelines above, save your R Markdown file into an appropriate folder on your hard drive by clicking on File and then Save from the RStudio menu.

To open an .Rmd file in RStudio, select File -> Open File and navigate to the folder you saved the assignment template in and select the file. You should see the R Markdown file pop up on the top left portion of your RStudio interface.

Authoring an R Markdown document

R Markdown documents contain 3 major components:

  • A YAML header surrounded by - - -
  • Chunks of R code surrounded by ```
  • Text mixed with simple text formatting using the Markdown syntax

YAML header

The YAML header controls how R Markdown renders your .Rmd file. A YAML header is a section of key:value pairs surrounded by - - - marks and is always located at the top of your Rmd file .

In the assignment’s YAML, add your name, assignment number, and the date. These are the only necessary items, but you can change other options, most of which are detailed here . Your YAML will generally look like the following.

R Code chunks

When answering an assignment question, you’ll have the following sequence of components in your R Markdown document: Question, R code answering the question, comment describing what the code is doing, and your text to explain the results. Let’s say you have the following question in one of your assignments.

Assignments will ask you to write R code to accomplish a data analysis task. You present and execute your R code inside R code chunks. R chunks start with ```{r} and end with ``` , and you insert your R code in between. To designate 1+1 as R code, it will look like the following in your R Markdown document.

All code inside a chunk will be executed when knitting the markdown file (i.e. the html file will show your code and its result). This means that your R code must reside inside an R code chunk in order for it to be processed as R code (otherwise R Markdown will think it is text). This also means that nothing but executable code (or comments, which we’ll get to next) should be inside a chunk.

We will ask you to annotate your R code so that we (and you) know what is being done in that line of code. You designate annotations or comments in R code using the # symbol. In programming, comments are bits of text that are not interpreted as computer instructions—they aren’t code, they’re just notes about the code! Since computer code can be opaque and difficult to understand, we use comments to help write down the meaning and purpose of our code. While a computer is able to understand the code, comments are there to help people understand it. This is particularly important when someone else will be looking at your work—whether that person is a collaborator, or is simply a future version of you (e.g., when you need to come back and fix something and so need to remember what you were even thinking).

Comments should be clear, concise, and helpful—they should provide information that is not otherwise present or “obvious” in the code itself. So, to annotate the above line of code 1+1 , you add in your R code chunk

You put your comments after the # .

The first line of the chunk has {r} which basically states that everything inside the chunk will be in R code. Next to the r , we can give the chunk a name, such as

Here, I named the chunk q1chunk1 which indicates this is question 1, chunk 1. You can name the chunk whatever you like (sally, clare, stevewheeler). The chunk name is not required; however, it is good practice to give each chunk a unique name (we’ll see its value later when we talk about knitting).

In the R Markdown you created and saved, you will notice the following R code chunk after the YAML.

The above code establishes global options for every R chunk code in your R Markdown file. These options alter the way R results are spit out in your formatted knitted document. I suggest adding the following global options in every R Markdown assignment file.

The above code hides non error messages for every single R code chunk in your file. These non error messages are unnecessary for the purposes of this class. Other chunk options can be found here .

You can also set options for individual chunks. These are local options - local to that chunk - and won’t be applied to other chunks in your file. For example, you can add the options warning=TRUE and message=TRUE to an individual R code chunk as follows to show the messages for the R code in that chunk. Notice that each argument is separated by a comma.

In addition to R code, assignments will ask you to write text to explain results. Going back to our example question from above

You would type in your R Markdown document the following

The question and text explaining the result reside outside of the R chunk. There is nothing special about the text in terms of its format or placement.

Separating code one chunk at a time

Do not put all of your code for an entire assignment or even a single question in one single chunk. For example, let’s say you see the following in your homework assignment.

Instead of including both lines of code in one chunk like as follows

Break it up and add text after each to explain the result.

Think of writing a script as similar to writing an essay. You don’t write an essay in one single paragraph. You break it up into several paragraphs, where paragraph breaks are used to separate major points and ideas. On the other end of the spectrum, do not break up every single line of code like you would not break up every single sentence into their own paragraphs in an essay. Break up your code where it makes sense.

Always test each chunk

After you write code in a chunk, you’ll need to test the code to make sure it is running properly. In other words, rather than writing all the code and then running it at the end of the assignment, run the chunks one at a time. To elaborate, let’s say the first question in an assignment asks you to add one plus one. In your R Markdown document, type in the following to answer this question.

Run that code chunk to make sure it works (you should get 2!). Then proceed to the next question. Let me emphasize: Do not write all of your code answering every question in the assignment and run it at the very end. Routinely TEST, Test, and test your code to make sure it runs properly.

r markdown assignment

Third, you can highlight partly or entirely a line of code and select Code from the R Studio menu and select (among many options) Run Selected Lines(s) . See Figure below (from a Mac OS).

r markdown assignment

Fourth, you can highlight partly or entirely a line of code and use a keyboard shortcut to run the code. As you can see in the figure above, the keyboard shortcut to run code on a Mac is command + return. See here for other shortcuts for both Mac and Windows.

Note that when you run an R code chunk for the very first time ever, its output will be embedded within your R Markdown document as shown below

r markdown assignment

Output within R Markdown document.

This will also be true when you plot graphs and maps. When you are testing your code, you might want to have the code results shown in your RStudio Console (the bottom left window) and plots/maps shown in the Plots window (bottom right window). To get RStudio to do this, select the “Tools” menu and select “Global Options”. Select “R Markdown” from the left-hand side and deselect the check box “Show output inline for all R Markdown documents”. The output from your code should now be shown in the console or Plots window.

r markdown assignment

R Markdown options.

Knitting an R Markdown document

In addition to the R Markdown Rmd file, you will need to submit its knitted result. Knitting puts an assignment’s main components - code, output, and text - in a nicely formatted document. You can create three types of knitted documents: html, Microsoft Word, and a pdf. I recommend knitting to an html file because it is the easiest of the three options. Go back to the YAML example I showed above. output: html_document tells R to produce an html document. If you want to knit to a pdf, you’ll need to do some extra package installing. See here .

r markdown assignment

When you start knitting, you will notice that a new window on the bottom left will appear in place of the console. The window will show the progress in your knitting. R is going through each R code chunk one at a time. The percentages you will see will be based on the proportion of your R Markdown file that R has successfully knitted. See Figure below.

r markdown assignment

R Markdown knitting progress window

If it has a problem knitting, R will stop at the chunk that contains the problem. You can determine the offending place in your R Markdown file two ways. First, in the R Markdown tab in the bottom left window, if you click on “Output” located at the top right corner of this window, you will see the R Markdown progress window, the error in red, and where R Markdown stopped. Carefully read the description of the error, which will contain the R code chunk name and sometimes the lines containing the problem in your R Markdown file. This is where it is useful for naming your chunks. You can go to your offending chunk and see what may be the problem. For example, the figure below shows knitting was stopped because the object xyz was not created in the R Markdown file. You can go to the chunk named q2chunk2 to remedy the issue.

r markdown assignment

R Markdown knitting stopped by an error

The other way to find where R Markdown is having trouble is by clicking on “Issues” also located at the top right corner of the R Markdown window. The error will give you something similar to what you found in the Output window, but instead of a chunk, it will tell you the specific line in your R Markdown file that this error is located. Go to that line in your R Markdown file and see what is the issue. For example the error is located in line 34.

r markdown assignment

Hopefully, the error statement reveals why you were not able to knit. If it is not illuminating (oh oh), you’ll need to figure out what you did wrong. See the Having problems knitting? section below.

Note that when you are knitting, progress and any errors will be shown not in the regular R console window, but in a special R Markdown window. To toggle back to the Console (and back to the R Markdown window), just click on the Console (or R Markdown) tab as shown below.

r markdown assignment

If you encounter no errors, a preview of your knitted document will pop up in a new window and the .html (or pdf or docx) file will be saved in the folder where your Rmd file resides. I recommend not waiting till the very end of an assignment to knit. When you finish one question, knit your document to see if everything is working properly. If it is working for that question, move on to the next question.

Let’s be clear. There are two things you’ll have to deal with: (1) Making sure the R code is working correctly to get the results you need in order to answer the question (2) Making sure the code is working correctly to knit a final document. These two issues may be related (if your R code is producing an error, R Markdown will not knit), but sometimes they are not. So, check both your R code and your knitting results often. And absolutely do not wait till the last minute to knit. Knit as often as possible .

When you’re satisfied with the end product, submit your .Rmd document and a knitted document on Canvas .

Having problems knitting?

  • A major source of error for most new R Markdown users is that they call up a data object in their R Markdown file that has not been created within the R Markdown file. Treat the R Markdown as its own separate system - even if you’ve created an object through the R Console, and you can see it sitting in your Environment window, R Markdown won’t recognize it because it was not created within the R Markdown document.

To be clear, let’s say you typed directly in the R console the following code:

You see the object myobject pop up in your Environment window in the top right window. Let’s say you write in your R Markdown file the code:

Once again, treat the R Markdown file as a self-contained, stand alone script . This is an important concept to understand because many students get tripped up on it when first starting out.

  • Are you trying to bring in a data file that is not located in the directory your R Markdown is pointed to? Remember, don’t scatter your data files for an assignment across different folders. Keep them in one folder - the folder where your R Markdown document resides. To find your current working directory, type in getwd() in your console and press enter. To set your working directory, type in setwd("folder") in your R Markdown and replace “folder”” with the entire path you want R to point to. You can also set your working directory by clicking on Session -> Set Working Directory -> Choose Directory from the top menu.
  • Do you have an install.packages() in your R Markdown script? Take it out! You only need to do it once - and never inside an R Markdown script.
  • Do you have a View() command in your R Markdown script? Take it out! Sometimes R Markdown will have problems when trying to view an R data object.
  • Are you using functions for a package that you need to load into R and haven’t loaded it in your R Markdown using library() . If so, load it in R Markdown!
  • If you change a piece of code somewhere in the middle because you caught an error, make sure that change is reflected throughout the code. For example, let’s say you decide to rename the object hisobject to herobject . There may be code later on in the document that uses hisobject . So, you’ll need to change every line of code in your R Markdown that uses hisobject to now use herobject .
  • SPELLING, Spelling, spelling. Check your spelling. You created an object named hisobject , but you use it later in the file as hsobject . R will tell you that hsobject is not found. You use the function read_cvs() as opposed to the correct function read_csv() .
  • R is case sensitive. The object Money is different from money .
  • R functions are sometimes finicky about spaces. They are also finicky about quotes. Some functions require quotes, others don’t.
  • Make sure that when you use brackets, parentheses or quotes, they should start and end with one. It is very rare that you will use a left parentheses and not close it with a right parentheses.
  • As I mentioned above, don’t wait till the last minute to knit. Knit after every question. Repeat it again: Knit after every question.
  • The first place to check when you get a knitting error is the specific chunk or line that the error is pointing to.
  • As I mentioned above, check if your R code works one chunk at a time.
  • Did you install the appropriate package?
  • Did you load in the appropriate library?
  • Are you using the right function?
  • Did you specify all the function’s arguments correctly?
  • Still having problems? Break up your code line by line or even argument by argument to find the error? For example, let’s say you have 4 lines of code that are connected together - i.e. line 4 depends on line 3, line 3 depends on line 2, and so on

If you get an error, run line 1 first. No error? Run line 1 and 2. No error? Keep going until you find the offending line.

  • If you have a Mac and you are getting an error when knitting, you may need to download the most recent version of XQuartz, which can be downloaded here
  • If you’re still stuck, more than likely someone else also had a similar problem in the past. So, ask a classmate. If your classmate is also stuck, use Google and it might help you out.

The proper workflow for each assignment will be as follows

  • Go through the week’s reading and lab guide and make sure you understand the material.
  • Create a folder on your hard drive that is specific to the assignment (e.g. Assignment 1, Assignment 2, etc.).
  • Create an R Markdown assignment file. Save it in the appropriate assignment folder on your hard drive.
  • Download any data needed for the assignment into the same folder. For most assignments, I will upload the assignment data on GitHub, which you can directly link to in R, so you won’t have to download data. Some files will be located on Canvas.
  • In the R Markdown document, answer the first assignment question.
  • Break up your code into different chunks where it makes sense. For some questions, you might include all code for a question in one single chunk. For other questions, you might break up the code into several chunks.
  • Make sure your code works. Run code one chunk at a time to make sure it is working. Note that there are multiple ways to get to an answer in R. We will not grade on how efficient your code is unless stated so in the question .
  • Most of the questions will ask you to explain your results. Write your explanations outside of the R code chunks. Please - please - take these interpretation questions seriously. This is a not a programming or Data Science course - you may have taken 40 hours to produce super elegant code to answer a question, but your results won’t be worth much to anyone if you can’t properly interpret them.
  • After you’ve completed the first question, knit to an html, pdf or docx file. Make sure it knits properly. If it does not, examine the error, and fix the problem.
  • If you’re satisfied with your code and its results for the first question, and the document properly knitted, move on to the next question. Repeat steps 5 and 6.
  • Once you’ve completed all questions and successfully knitted, submit the .Rmd and the knitted files on Canvas before the designated due time.
  • Smile, pat yourself on the back, and have some ice cream (I like these folks ).

In order to get full credit for each assignment, you will need to

  • Show the correct statistical results for a given question (e.g. map, table, statistics).
  • Show the code producing the results.
  • Provide comments explaining what the code is doing
  • Provide correct written answers.

Any response requiring a data analysis task must be supported by code you generate to produce your result. Just examining your various objects in the “Environment” section of R Studio is insufficient—you must use scripted commands. Because there are typically multiple ways to get an answer, we will not grade you on the efficiency of your code. You can ask for help from the TAs and work with other students. However, you must submit your own assignments.

Also note: all code used to produce your results must be shown in your HTML file (e.g., do not use echo=FALSE or include=FALSE as options anywhere. Well, mostly anywhere - we’ll get to some cases where they are useful to include). Other pieces of advice:

  • Answers should be correct. This is not to say that we will not take into consideration how much of your code is correct. But, if you do get the wrong answer we will take at least something off.
  • We will not grade on how efficient your code is unless stated so in the question. We will never take points off for accomplishing things differently than expected as long as it produces the correct result. However, if the answer is incorrect and your code indicates little effort (e.g. blank or a few lines of code that yield nothing) or is completely incomprehensible (e.g. 20 lines of mish mash), expect few to no points.
  • You must submit both an Rmd and its knitted (html, pdf or docx) file. If you don’t, we will take significant points off.

Other things to know

  • Please spell-check your assignment before handing it in (Edit -> Check Spelling from the top menu bar).
  • The default editor settings are to insert matching parentheses and quotes; if you find that this intrudes on your workflow, you can disable it via Tools -> Global Options -> Code then uncheck Insert matching parens/quotes.
  • We expect you to work together. Two heads are better than one, and five heads are better than two
  • We expect you to ask for help if you get stuck (and you will be stuck a lot). We can’t read minds, so if you don’t tell us that you are confused, we won’t know.
  • You should try and solve problems before you ask for help.
  • Trying includes an Internet search (a crucial skill!)
  • All homework should be submitted on Canvas.

Getting R Markdown Help

Whenever you are editing R Markdown documents in RStudio, you can display an R Markdown cheat sheet by going to Help -> Cheatsheets -> R Markdown Cheat Sheet. A basic introduction to R Markdown can also be found in Chapter 21 in R for Data Science . R Studio has a quick introduction to R Markdown. We’ve put together some additional R tips here in the likely case that you get stuck. And, of course, there is the Google machine. Use it to get help.

Creative Commons License

Website created and maintained by Noli Brazil

Assignment Guidelines

  • Eligible Communities
  • Neighborhood Data Sources
  • Big and Open Data Sources

CRD 150 - Quantitative Methods in Community Research

Winter 2024.

Assignments will be released Wednesday morning and are due 10:00 am on Canvas the following Wednesday. Assignment questions are provided at the end of each lab’s guide. Assignments have two components:

  • Executing data analysis tasks in R. For example, creating a map or running a statistical model.
  • Answering conceptual questions - for example, interpret a concept introduced in lecture or the textbook.

In order to get full credit for each assignment, you will need to

  • Show the correct statistical results for a given question (e.g. map, table, statistics).
  • Show the code producing the results.
  • Provide comments in your own words explaining what each line of code is doing
  • Provide correct written answers.
  • Submit an R Markdown Rmd file and its knitted html file on Canvas.

You will use R Markdown to write up all R related assignments. This guide will go through the steps for answering and submitting class assignment questions using R Markdown. For a thorough rundown of R Markdown, see Chapter 27 in RDS. For full explanation of how assignments will be graded, read the Grading section located later in this guide.

R Markdown is a simple formatting syntax for authoring html, pdf, and Microsoft Word documents in RStudio. For each R related assignment, you will need to upload onto Canvas two documents:

  • An R Markdown document, which has an .Rmd extension
  • A knitted .html file

These documents will provide us an easy-to-read document to grade; more importantly, you will get to practice (1) writing scripts, (2) keeping track of the analyses you run, and (3) organizing your output in a reader-friendly manner. When you submit these documents on Canvas, do not combine them into a zipped compressed folder . They should be two separate files.

To be clear, R is a programming language . RStudio is an application . R Markdown is a markup syntax to convert R script and text into a pdf or html document. It allows for presentation-ready documents that show commands and results in a seamless flow. When you write R code and embed it in presentation documents created using R Markdown, you are forced to explicitly state the steps you took to do your research.

In RStudio, install the packages knitr and rmarkdown using the install.packages() command. Type the following in your RConsole window after >

Once you’ve installed these packages, you don’t need to install them any more in the future. You also do not need to load them in at any time using library() .

Opening an R Markdown file

An .Rmd template will be provided for each assignment. Download the week’s assignment template, which will be linked at the top of every assignment, and save it into an appropriate folder on your hard drive. File management is important here. Here are some tips.

  • Set up a clear and understandable hierarchical file system for this class on your hard drive. For example, create a class folder (CRD 150). Within this class folder, create the folder Assignments. Within the Assignments folder, create separate folders for each Assignment (e.g. Assignment 1, Assignment 2, …). Save that week’s assignment template here. When you knit your Rmd (we’ll get to what knitting means below), this is where your html file will go. Don’t work from your Desktop. Or from the Downloads folder. Or some randomly named folder that you will have a hard time finding a month, week or day from now. You should have a sequence of folders that looks like the following (on a Mac)

To open an .Rmd file in RStudio, select File -> Open File and navigate to the folder you saved the assignment template in and select the file. You should see the R Markdown file pop up on the top left portion of your RStudio interface like below.

Authoring an R Markdown document

R Markdown documents contain 3 major components:

  • A YAML header surrounded by - - -
  • Chunks of R code surrounded by ```
  • Text mixed with simple text formatting using the Markdown syntax

YAML header

The YAML header controls how R Markdown renders your .Rmd file. A YAML header is a section of key:value pairs surrounded by - - - marks and is always located at the top of your Rmd file .

In the assignment template’s YAML, change your name, assignment number, lab number, and the date. Other than those items, the YAML format for each assignment is set for you in the template, so don’t change it. It will generally look like the following.

R Code chunks

When answering an assignment question, you’ll have the following sequence of components in your R Markdown document: Question, R code answering the question, and your text to explain the results. Let’s say you have the following question in one of your assignments.

Assignments will ask you to write R code to accomplish a data analysis task. You present and execute your R code inside R code chunks. R chunks start with ```{r} and end with ``` , and you insert your R code in between. To designate 1+1 as R code, it will look like the following in your R Markdown document.

All code inside a chunk will be executed when knitting the markdown file (i.e. the html file will show your code and its result). This means that your R code must reside inside an R code chunk in order for it to be processed as R code (otherwise R Markdown will think it is text). This also means that nothing but executable code (or comments, which we’ll get to next) should be inside a chunk.

We will ask you to annotate your R code so that we (and you) know what is being done in that line of code. You designate annotations or comments in R code using the # symbol. So, to annotate the above line of code 1+1 , you add in your R code chunk

You put your comments after the # .

The first line of the chunk has {r} which basically states that everything inside the chunk will be in R code. Next to the r , we can give the chunk a name, such as

Here, I named the chunk q1chunk1 which indicates this is question 1, chunk 1. You can name the chunk whatever you like (sally, mariah, proflondon). The chunk name is not required; however, it is good practice to give each chunk a unique name (we’ll see its value later when we talk about knitting).

In every R Markdown assignment template, you will notice the following R code chunk after the YAML.

Do not delete or alter this chunk, always keep it in your R Markdown. The above code establishes global options for every R chunk code in your R Markdown file. These options alter the way R results are spit out in your formatted knitted document. The above code hides non error messages for every single R code chunk in your file. These non error messages are unnecessary for the purposes of this class. Other chunk options can be found here .

You can also set options for individual chunks. These are local options - local to that chunk - and won’t be applied to other chunks in your file. For example, you can add the options warning=TRUE and message=TRUE to an individual R code chunk as follows to show the messages for the R code in that chunk. Notice that each argument is separated by a comma.

In addition to R code, assignments will ask you to write text to explain results. Going back to our example question from above

You would type in your R Markdown document the following

The question and text explaining the result reside outside of the R chunk. There is nothing special about the text in terms of its format or placement.

Separating code one chunk at a time

Do not put all of your code for an entire assignment or even a single question in one single chunk. For example, let’s say you see the following in your homework assignment.

Instead of including both lines of code in one chunk like as follows

Break it up and add text after each to explain the result.

Think of writing a script as similar to writing an essay. You don’t write an essay in one single paragraph. You break it up into several paragraphs, where paragraph breaks are used to separate major points and ideas. On the other end of the spectrum, do not break up every single line of code like you would not break up every single sentence into its own paragraph in an essay. Break up your code where it makes sense.

Always test each chunk

After you write code in a chunk, you’ll need to test the code to make sure it is running properly. In other words, rather than writing all the code and then running it at the end of the assignment, run the chunks one at a time. To elaborate, let’s say the first question in an assignment asks you to add one plus one. In your R Markdown document, type in the following to answer this question.

Run that code chunk to make sure it works (you should get 2!). Then proceed to the next question. Let me emphasize: Do not write all of your code answering every question in the assignment and run it at the very end. Routinely TEST, Test, and test your code to make sure it runs properly.

There are a number of ways to run code in R Markdown. First, you can click your mouse in the R code chunk you want to run and click on located at the top of the R Markdown window and select Run Current Chunk .

Second, you can place your mouse cursor in the R code chunk and click on located on the right corner of the chunk. See Figure below.

In each R chunk, pressing the button will run all previous R chunks. See Figure below.

Third, you can highlight partly or entirely a line of code and select Code from the R Studio menu and select (among many options) Run Selected Lines(s) . See Figure below (from a Mac OS).

Fourth, you can highlight partly or entirely a line of code and use a keyboard shortcut to run the code. As you can see in the figure above, the keyboard shortcut to run code on a Mac is command + return. See here for other shortcuts for both Mac and Windows.

Note that when you run an R code chunk for the very first time ever, its output will be embedded within your R Markdown document as shown below

This will also be true when you plot graphs and maps. When you are testing your code, you might want to have the code results shown in your RStudio Console (the bottom left window) and plots/maps shown in the Plots window (bottom right window). To get RStudio to do this, select the “Tools” menu and select “Global Options”. Select “R Markdown” from the left-hand side and deselect the check box “Show output inline for all R Markdown documents”. The output from your code should now be shown in the console or Plots window.

Knitting an R Markdown document

In addition to the R Markdown Rmd file, you will need to submit its knitted result. Knitting puts an assignment’s main components - code, output, and text - in a nicely formatted document. You can create three types of knitted documents: html, Microsoft Word, and a pdf. In this class, we will be knitting always to an html file because it is the easiest of the three options. Go back to the YAML example I showed above. output: html_document tells R to produce an html document.

To Knit your document click , which will be located at the top of the upper center of the R Markdown window. Note that you can select your document type when knitting by clicking the pull down menu next to and selecting your document choice (default is html). When you start knitting, you will notice that a new window on the bottom left named “Render” will appear in place of the console. The window will show the progress in your knitting. R is going through each R code chunk one at a time. The percentages you will see will be based on the proportion of your R Markdown file that R has successfully knitted. See Figure below.

If you have successfully knitted the RMarkdown file, the resulting html file will appear in the same folder as where your RMarkdown file resides.

If it has a problem knitting, R will stop at the chunk that contains the problem. You can determine the offending error and where it is located in your RMarkwdown in the Render pane. You will see the R Markdown progress window, the error in red, and where R Markdown stopped. Carefully read the description of the error, which will contain the R code chunk name and the lines containing the problem in your R Markdown file. This is where it is useful for naming your chunks. You can directly go to your offending chunk and lines of code and see what may be the problem. For example, the figure below shows knitting was stopped because the column tpopr does not exist. You can go to the chunk named q3chunk2 , lines 55-56 to remedy the issue.

Hopefully, the error statement reveals why you were not able to knit. If it is not illuminating, you’ll need to figure out what you did wrong. See the Having problems knitting? section below.

Note that when you are knitting, progress and any errors will be shown not in the regular R console window, but in the Render window. To toggle back to the Console (and back to the Render window), just click on the Console (or R Markdown) tab as shown below.

If you encounter no errors, a preview of your knitted document will pop up in a new window and the .html file will be saved in the folder where your Rmd file resides. I recommend not waiting till the very end of an assignment to knit. When you finish one question, knit your document to see if everything is working properly. If it is working for that question, move on to the next question.

Let’s be clear: There are two things you’ll have to deal with: (1) Making sure the R code is working correctly to get the results you need in order to answer the question and (2) Making sure the code is working correctly to knit a final document. These two issues may be related (if your R code is producing an error, R Markdown will not knit), but sometimes they are not. So, check both your R code and your knitting results often. And absolutely do not wait till the last minute to knit. Knit as often as possible .

When you’re satisfied with the end product, submit your .Rmd document and a knitted .html document on Canvas .

Having problems knitting?

  • A major source of error for most new R Markdown users is that they call up a data object in their R Markdown file that has not been created within the R Markdown file. Treat the R Markdown as its own separate system - even if you’ve created an object through the R Console, and you can see it sitting in your Environment window, R Markdown won’t recognize it because it was not created within the R Markdown document.

To be clear, let’s say you typed directly in the R console the following code:

You see the object myobject pop up in your Environment window in the top right window. Let’s say you write in your R Markdown file the code:

You then click on to knit. You will get an error because R will not be able to knit because myobject was not created within the R Markdown . Both lines of code should be in the R Markdown file as follows:

Once again, treat the R Markdown file as a self-contained, stand alone script . This is an important concept to understand because many students get tripped up on it when first starting out.

  • Are you trying to bring in a data file that is not located in the directory your R Markdown is pointed to? Remember, don’t scatter your data files for an assignment across different folders. Keep them in one folder - the folder where your R Markdown document resides. To find your current working directory, type in getwd() in your console and press enter. To set your working directory, type in setwd("folder") in your console, replace folder with the entire path you want R to point to, and press enter/return. You can also set your working directory by clicking on Session -> Set Working Directory -> Choose Directory from the top menu.
  • Do you have an install.packages() in your R Markdown script? Take it out! You only need to do it once - and never inside an R Markdown script.
  • Do you have a View() command in your R Markdown script? Take it out! Sometimes R Markdown will have problems when trying to view an R data object.
  • Are you using functions for a package that you need to load into R and haven’t loaded it in your R Markdown using library() . If so, load it in R Markdown!
  • If you change a piece of code somewhere in the middle because you caught an error, make sure that change is reflected throughout the code. For example, let’s say you decide to rename the object hisobject to herobject . There may be code later on in the document that uses hisobject . So, you’ll need to change every line of code in your R Markdown that uses hisobject to now use herobject .
  • SPELLING, Spelling, spelling. Check your spelling. You created an object named hisobject , but you use it later in the file as hsobject . R will tell you that hsobject is not found. Another example: you used the function read_cvs() as opposed to the correct function read_csv() .
  • R is case sensitive. The object Money is different from money .
  • R functions are sometimes finicky about spaces. They are also finicky about quotes. Some functions require quotes, others don’t.
  • Make sure that when you use brackets, parentheses or quotes, they should start and end with one. It is very rare that you will use a left parentheses and not close it with a right parentheses.
  • As I mentioned above, don’t wait till the last minute to knit. Knit after every question. Repeat it again: Knit after every question.
  • The first place to check when you get a knitting error is the specific chunk or line that the error is pointing to.
  • As I mentioned above, check if your R code works one chunk at a time.
  • Did you install the appropriate package?
  • Did you load in the appropriate library?
  • Are you using the right function?
  • Did you specify all the function’s arguments correctly?
  • Still having problems? Break up your code line by line or even argument by argument to find the error? For example, let’s say you have 4 lines of code that are connected together - i.e. line 4 depends on line 3, line 3 depends on line 2, and so on

If you get an error, run line 1 first. No error? Run line 1 and 2. No error? Keep going until you find the offending line.

  • If you have a Mac and you are getting an error when knitting, you may need to download the most recent version of XQuartz, which can be downloaded here
  • If you’re still stuck, more than likely someone else also had a similar problem in the past. So, ask a classmate. If your classmate is also stuck, use Google and it might help you out.

The proper workflow for each assignment will be as follows

  • Go through the week’s reading and lab guide and make sure you understand the material.
  • Create a folder on your hard drive that is specific to the assignment (e.g. Assignment 1, Assignment 2, etc.).
  • Save the R Markdown assignment template linked to each assignment in the appropriate assignment folder on your hard drive.
  • Download any data needed for the assignment into the same folder. For most assignments, I will upload the assignment data on Canvas or GitHub.
  • Open the R Markdown assignment file in RStudio.
  • In the R Markdown document, answer the first assignment question.
  • Break up your code into different chunks where it makes sense. For some questions, you might include all code for a question in one single chunk. For other questions, you might break up the code into several chunks.
  • Make sure your code works. Run code one chunk at a time to make sure it is working. Note that there are multiple ways to get to an answer in R. We will not grade on how efficient your code is unless stated so in the question .
  • Most of the questions will ask you to explain your results. Write your explanations outside of the R code chunks. Please - please - take these interpretation questions seriously. This is a not a programming or Data Science course - you may have taken 40 hours to produce super elegant code to answer a question, but your results won’t be worth much to anyone if you can’t properly interpret them.
  • After you’ve completed the first question, knit to an html file. Make sure it knits properly. If it does not, examine the error, and fix the problem.
  • If you’re satisfied with your code and its results for the first question, and the document properly knitted, move on to the next question. Repeat steps 6 and 7.
  • Once you’ve completed all questions and successfully knitted, submit the .Rmd and .html files on Canvas before the designated due time.
  • Smile, pat yourself on the back, and have some ice cream (I like these folks ).

Any response requiring a data analysis task must be supported by code you generate to produce your result. Just examining your various objects in the “Environment” section of R Studio is insufficient—you must use scripted commands. Because there are typically multiple ways to get an answer, we will not grade you on the efficiency of your code. You can ask for help from the TAs and work with other students. However, you must submit your own assignments.

You must include in your own words comments that explain each line of code in your R Markdown. It does not have to be extensive, but should be concise and clear enough to let us know that you understand what the code is doing. You should indicate not just the what , but also the why . For example

Comments are important for demonstrating that you understand what your code is doing. Furthermore, by writing in basic English what each piece of code is doing and why you are doing it, you will be able to strengthen your understanding of how R works. Furthermore, comments will help clear up any confusion when future you goes back to your code.

Our grading will be more lenient at the beginning of the quarter as you learn the nuances of R, but will get progressively more stringent on aspects of your submission that have already been covered in prior assignments. For example, we fully expect you to have proper axis labels on all graphs, and appropriate legends on all maps, topics that we will cover early in the quarter, later in the quarter.

Also note: all code used to produce your results must be shown in your HTML file (e.g., do not use echo=FALSE or include=FALSE as options anywhere). Other pieces of advice:

  • Answers should be correct. This is not to say that we will not take into consideration how much of your code is correct. But, if you do get the wrong answer we will take at least something off.
  • We will not grade on how efficient your code is unless stated so in the question. We will never take points off for accomplishing things differently than expected as long as it produces the correct result. However, if the answer is incorrect and your code indicates little effort (e.g. blank or a few lines of code that yield nothing) or is completely incomprehensible (e.g. 20 lines of mish mash), expect few to no points.
  • You must submit both an Rmd and html file. If you don’t, we will take significant points off.

Other things to know

  • Please spell-check your assignment before handing it in (Edit -> Check Spelling from the top menu bar).
  • The default editor settings are to insert matching parentheses and quotes; if you find that this intrudes on your workflow, you can disable it via Tools -> Global Options -> Code then uncheck Insert matching parens/quotes.
  • We expect you to work together. Two heads are better than one, and five heads are better than two
  • We expect you to ask for help if you get stuck (and you will be stuck a lot). We can’t read minds, so if you don’t tell us that you are confused, we won’t know.
  • You should try and solve problems before you ask for help.
  • Trying includes an Internet search (a crucial skill!)
  • All homework should be submitted on Canvas.

Getting R Markdown Help

Whenever you are editing R Markdown documents in RStudio, you can display an R Markdown cheat sheet by going to Help -> Cheatsheets -> R Markdown Cheat Sheet. A basic introduction to R Markdown can also be found in Chapter 27 in R for Data Science . R Studio has a quick introduction to R Markdown. We’ve put together some additional R tips here in the likely case that you get stuck. And, of course, there is the Google machine. Use it to get help.

Creative Commons License

Website created and maintained by Noli Brazil

  • Get started
  • About Lua filters
  • Version 2.7
  • Version 2.6

Render R Markdown

Render the input file to the specified output format using pandoc. If the input requires knitting then knit is called prior to pandoc.

The input file to be rendered. This can be an R script (.R), an R Markdown document (.Rmd), or a plain markdown document.

The R Markdown output format to convert to. The option "all" will render all formats defined within the file. The option can be the name of a format (e.g. "html_document" ) and that will render the document to that single format. One can also use a vector of format names to render to multiple formats. Alternatively, you can pass an output format object (e.g. html_document() ). If using NULL then the output format is the first one defined in the YAML frontmatter in the input file (this defaults to HTML if no format is specified there). If you pass an output format object to output_format , the options specified in the YAML header or _output.yml will be ignored and you must explicitly set all the options you want when you construct the object. If you pass a string, the output format will use the output parameters in the YAML header or _output.yml .

The name of the output file. If using NULL then the output filename will be based on filename for the input file. If a filename is provided, a path to the output file can also be provided. Note that the output_dir option allows for specifying the output file path as well, however, if also specifying the path, the directory must exist. If output_file is specified but does not have a file extension, an extension will be automatically added according to the output format. To avoid the automatic file extension, put the output_file value in I () , e.g., I('my-output') .

The output directory for the rendered output_file . This allows for a choice of an alternate directory to which the output file should be written (the default output directory of that of the input file). If a path is provided with a filename in output_file the directory specified here will take precedence. Please note that any directory path provided will create any necessary directories if they do not exist.

List of output options that can override the options specified in metadata (e.g. could be used to force self_contained or mathjax = "local" ). Note that this is only valid when the output format is read from metadata (i.e. not a custom format object passed to output_format ).

Paths to YAML files specifying output formats and their configurations. The first existing one is used. If none are found, then the function searches YAML files specified to the output_yaml top-level parameter in the YAML front matter, _output.yml or _output.yaml, and then uses the first existing one.

Intermediate files directory. If a path is specified then intermediate files will be written to that path. If NULL , intermediate files are written to the same directory as the input file.

The working directory in which to knit the document; uses knitr's root.dir knit option. If NULL then the behavior will follow the knitr default, which is to use the parent directory of the document.

The runtime target for rendering. The static option produces output intended for static files; shiny produces output suitable for use in a Shiny document (see run ). The default, auto , allows the runtime target specified in the YAML metadata to take precedence, and renders for a static runtime target otherwise.

Using TRUE will clean intermediate files that are created during rendering.

A list of named parameters that override custom params specified within the YAML front-matter (e.g. specifying a dataset to read or a date range to confine output to). Pass "ask" to start an application that helps guide parameter configuration.

(This option is reserved for expert use.) Metadata generated by knitr .

The environment in which the code chunks are to be evaluated during knitting (can use new.env () to guarantee an empty new environment).

An option for whether to run pandoc to convert Markdown output.

An option to suppress printing during rendering from knitr, pandoc command line and others. To only suppress printing of the last "Output created: " message, you can set rmarkdown.render.message to FALSE

Ignored. The encoding is always assumed to be UTF-8.

When run_pandoc = TRUE , the compiled document is written into the output file, and the path of the output file is returned. When

run_pandoc = FALSE , the path of the Markdown output file, with attributes knit_meta (the knitr meta data collected from code chunks) and intermediates (the intermediate files/directories generated by render() ).

Note that the knitr error option is set to FALSE during rendering (which is different from the knitr default value of TRUE ).

For additional details on rendering R scripts see Compiling R scripts to a notebook .

If no output_format parameter is specified then the output format is read from the YAML front-matter of the input file. For example, the following YAML would yield a PDF document:

Additional format options can also be specified in metadata. For example:

Multiple formats can be specified in metadata. If no output_format is passed to render then the first one defined will be used:

Formats specified in metadata can be any one of the built in formats (e.g. html_document , pdf_document ) or a format defined in another package (e.g. pkg::custom_format ).

If there is no format defined in the YAML then html_document will be used.

R Markdown supports all of the base pandoc markdown features as well as some optional features for compatibility with GitHub Flavored Markdown (which previous versions of R Markdown were based on). See rmarkdown_format for details.

knit , output_format , https://pandoc.org

R Markdown: The Definitive Guide

3.3 pdf document.

To create a PDF document from R Markdown, you specify the pdf_document output format in the YAML metadata:

Within R Markdown documents that generate PDF output, you can use raw LaTeX, and even define LaTeX macros. See Pandoc’s documentation on the raw_tex extension for details.

Note that PDF output (including Beamer slides) requires an installation of LaTeX (see Chapter 1 ).

3.3.1 Table of contents

You can add a table of contents using the toc option and specify the depth of headers that it applies to using the toc_depth option. For example:

If the TOC depth is not explicitly specified, it defaults to 2 (meaning that all level 1 and 2 headers will be included in the TOC), while it defaults to 3 in html_document .

You can add section numbering to headers using the number_sections option:

If you are familiar with LaTeX, number_sections: true means \section{} , and number_sections: false means \section*{} for sections in LaTeX (it also applies to other levels of “sections” such as \chapter{} , and \subsection{} ).

3.3.2 Figure options

There are a number of options that affect the output of figures within PDF documents:

fig_width and fig_height can be used to control the default figure width and height (6.5x4.5 is used by default).

fig_crop controls whether the pdfcrop utility, if available in your system, is automatically applied to PDF figures (this is true by default).

If you are using TinyTeX as your LaTeX distribution, we recommend that you run tinytex::tlmgr_install("pdfcrop") to install the LaTeX package pdfcrop . You also have to make sure the system package ghostscript is available in your system for pdfcrop to work. For macOS users who have installed Homebrew, ghostscript can be installed via brew install ghostscript .

If your graphics device is postscript , we recommend that you disable this feature (see more info in the knitr issue #1365 ).

fig_caption controls whether figures are rendered with captions (this is true by default).

dev controls the graphics device used to render figures (defaults to pdf ).

For example:

3.3.3 Data frame printing

You can enhance the default display of data frames via the df_print option. Valid values are presented in Table 3.3 .

3.3.4 Syntax highlighting

The highlight option specifies the syntax highlighting style. Its usage in pdf_document is the same as html_document (Section 3.1.4 ). For example:

3.3.5 LaTeX options

Many aspects of the LaTeX template used to create PDF documents can be customized using top-level YAML metadata (note that these options do not appear underneath the output section, but rather appear at the top level along with title , author , and so on). For example:

A few available metadata variables are displayed in Table 3.4 (consult the Pandoc manual for the full list ):

3.3.6 LaTeX packages for citations

By default, citations are processed through pandoc-citeproc , which works for all output formats. For PDF output, sometimes it is better to use LaTeX packages to process citations, such as natbib or biblatex . To use one of these packages, just set the option citation_package to be natbib or biblatex , e.g.

3.3.7 Advanced customization

3.3.7.1 latex engine.

By default, PDF documents are rendered using pdflatex . You can specify an alternate engine using the latex_engine option. Available engines are pdflatex , xelatex , and lualatex . For example:

The main reasons you may want to use xelatex or lualatex are: (1) They support Unicode better; (2) It is easier to make use of system fonts. See some posts on Stack Overflow for more detailed explanations, e.g., https://tex.stackexchange.com/q/3393/9128 and https://tex.stackexchange.com/q/36/9128 .

3.3.7.2 Keeping intermediate TeX

R Markdown documents are 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 keep it (e.g., for an article submission), you can specify the keep_tex option. For example:

3.3.7.3 Includes

You can do more advanced customization of PDF output by including additional LaTeX directives and/or content or by replacing the core Pandoc template entirely. To include content in the document header or before/after the document body, you use the includes option as follows:

3.3.7.4 Custom templates

You can also replace the underlying Pandoc template using the template option:

Consult the documentation on Pandoc templates for additional details on templates. You can also study the default LaTeX template as an example.

3.3.8 Other features

Similar to HTML documents, you can enable or disable certain Markdown extensions for generating PDF documents. See Section 3.1.10.4 for details. You can also pass more custom Pandoc arguments through the pandoc_args option (Section 3.1.10.5 ), and define shared options in _output.yml (Section 3.1.11 ).

IMAGES

  1. Getting Started with R Markdown

    r markdown assignment

  2. How to use R Markdown (part one)

    r markdown assignment

  3. Chapter 3 Scripts and R Markdown

    r markdown assignment

  4. Chapter 11 R Markdown

    r markdown assignment

  5. How to use R Markdown (part two): for learning R!

    r markdown assignment

  6. How to create an R Markdown File in R Studio and the R Markdown File

    r markdown assignment

VIDEO

  1. R markdown tutorial

  2. Using "rmarkdown' package to create dynamic report in R

  3. R Markdown course part 1

  4. Blacker's Markdown Mania

  5. R Markdown Part 4 (Plain Text Lists)

  6. R Markdown Tips

COMMENTS

  1. Getting Started with R Markdown

    Use the following command to install R Markdown: install.packages("rmarkdown") Now that R Markdown is installed, open a new R Markdown file in RStudio by navigating to File > New File > R Markdown…. R Markdown files have the file extension ".Rmd". 2. Default Output Format.

  2. Introduction to Using R Markdown for Class Assignments

    R Markdown is a low-overhead way of writing reports which includes R code and the code's automatically-generated output. It also lets you include nicely-typeset math, hyperlinks, images, and some basic formatting. The goal of this document is to explain, with examples, how to use its most essential features. It is not a comprehensive reference.

  3. 9 R Markdown & assignments

    9.1 Introduction to R Markdown. 9.1. Introduction to R Markdown. This page will guide you through creating and editing R Markdown documents. This is a useful tool for reporting your analysis (e.g. for homework assignments). Of course, there is also a cheat sheet for R-Markdown and this book contains a comprehensive discussion of the format. The ...

  4. A An R Markdown Primer for Doing Homework

    An R Markdown Primer for Doing Homework. RStudio has included a method for making higher quality documents from a combination of R code and some basic markdown formatting, which is called R Markdown. In order to create an R Markdown file, inside RStudio you click on File, then New File and R Markdown. You will be prompted to enter a Title and ...

  5. Introduction to R Markdown

    R Markdown. R Markdown is a file format for making dynamic documents with R. An R Markdown document is written in markdown (an easy-to-write plain text format) and contains chunks of embedded R code, like the document below. This is an R Markdown document. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents.

  6. Chapter 2 Basics

    Chapter 2 Basics. Chapter 2. Basics. R Markdown provides an authoring framework for data science. You can use a single R Markdown file to both. save and execute code, and. generate high quality reports that can be shared with an audience. R Markdown was designed for easier reproducibility, since both the computing code and narratives are in the ...

  7. Learn R Markdown • rmarkdown

    In R Markdown formats, you'll learn a little about the many other varieties of outputs you can produce using R Markdown, including dashboards, websites, and books. We'll finish up with R Markdown workflow, where you'll learn about the "analysis notebook" and how to systematically record your successes and failures so that you can ...

  8. R Markdown

    Turn your analyses into high quality documents, reports, presentations and dashboards with R Markdown. Use a productive notebook interface to weave together narrative text and code to produce elegantly formatted output. Use multiple languages including R, Python, and SQL. R Markdown supports a reproducible workflow for dozens of static and dynamic output formats including HTML, PDF, MS Word ...

  9. R Markdown Tutorial for Beginners

    With inline code, we can directly insert short pieces of code into the text of our R Markdown document—they will be executed, and their outputs will be shown embedded into the text. The syntax of inline code is r <code>. Below is a simple example of a text containing inline code: There are `r 1+6` colors of the rainbow.

  10. 27 R Markdown

    27.1 Introduction. R Markdown provides an unified authoring framework for data science, combining your code, its results, and your prose commentary. R Markdown documents are fully reproducible and support dozens of output formats, like PDFs, Word files, slideshows, and more. R Markdown files are designed to be used in three ways:

  11. 2.1 Example applications

    2.1.2 Homework assignments on RPubs. A huge number of homework assignments have been published to the website https://RPubs.com (a free publishing platform provided by RStudio), which shows that R Markdown is easy and convenient enough for students to do their homework assignments (see Figure 2.3).When I was still a student, I did most of my homework assignments using Sweave, which was a much ...

  12. How to write homework answers using R Markdown

    From the task menu of Rstudio, click "File", and a drop down menu will appear; position your mouse cursor on "New File" on the menu, a pop up menu will appear; from this pop up menu, select "R Markdown" and you will see a second pop up meanu; proceed, fill in the Title and Author information, and choose HTML as the Defult Output Format.

  13. R Markdown Quick Tour

    Turn your analyses into high quality documents, reports, presentations and dashboards with R Markdown. Use a productive notebook interface to weave together narrative text and code to produce elegantly formatted output. Use multiple languages including R, Python, and SQL. R Markdown supports a reproducible workflow for dozens of static and dynamic output formats including HTML, PDF, MS Word ...

  14. 3.2 Notebook

    3.2.1.3 Executing code. Code in the notebook is executed with the same gestures you would use to execute code in an R Markdown document: Use the green triangle button on the toolbar of a code chunk that has the tooltip "Run Current Chunk," or Ctrl + Shift + Enter (macOS: Cmd + Shift + Enter) to run the current chunk.

  15. Assignment Guidelines

    This guide will go through the steps for answering and submitting class assignment questions using R Markdown. For a thorough rundown of R Markdown, see Chapter 27 in RDS. R Scripts. Running R code using the console (bottom left in figure below) is a great place to start, but has its limitations. Each time you want to execute a set of commands ...

  16. PDF 1. Workflow R Markdown Cheat Sheet

    1. Workflow R Markdown is a format for writing reproducible, dynamic reports with R. Use it to embed R code and results into slideshows, pdfs, html documents, Word files and more. To make a report: Open - Open a file that uses the .Rmd extension. Write - Write content with the easy to use R Markdown syntax. Embed - Embed R code that creates ...

  17. 2.5 Markdown syntax

    2.5 Markdown syntax. The text in an R Markdown document is written with the Markdown syntax. Precisely speaking, it is Pandoc's Markdown. There are many flavors of Markdown invented by different people, and Pandoc's flavor is the most comprehensive one to our knowledge. You can find the full documentation of Pandoc's Markdown at https ...

  18. R Markdown: The Definitive Guide

    The first official book authored by the core R Markdown developers that provides a comprehensive and accurate reference to the R Markdown ecosystem. With R Markdown, you can easily create reproducible data analysis reports, presentations, dashboards, interactive applications, books, dissertations, websites, and journal articles, while enjoying the simplicity of Markdown and the great power of ...

  19. R Markdown

    Turn your analyses into high quality documents, reports, presentations and dashboards with R Markdown. Use a productive notebook interface to weave together narrative text and code to produce elegantly formatted output. Use multiple languages including R, Python, and SQL. R Markdown supports a reproducible workflow for dozens of static and dynamic output formats including HTML, PDF, MS Word ...

  20. Assignment Guidelines

    Save the R Markdown assignment template linked to each assignment in the appropriate assignment folder on your hard drive. Download any data needed for the assignment into the same folder. For most assignments, I will upload the assignment data on Canvas or GitHub. Open the R Markdown assignment file in RStudio.

  21. Render R Markdown

    The input file to be rendered. This can be an R script (.R), an R Markdown document (.Rmd), or a plain markdown document. output_format. The R Markdown output format to convert to. The option "all" will render all formats defined within the file. The option can be the name of a format (e.g. "html_document") and that will render the document to ...

  22. 3.3 PDF document

    3.3 PDF document. 3.3. PDF document. To create a PDF document from R Markdown, you specify the pdf_document output format in the YAML metadata: Within R Markdown documents that generate PDF output, you can use raw LaTeX, and even define LaTeX macros. See Pandoc's documentation on the raw_tex extension for details.