Unfortunately, I haven’t had as much time to make blog postsin the past year or so.I started taking classes as part ofGeorgia Tech’s Online Master of Science in Analytics (OMSA)program last summer (2018) while continuing to work full-time, so extra timeto code and write hasn’t been abundant for me.

• R Markdown Latex Table
• R Markdown Latex Equation

Pika software builder registration key. Anyways, I figured I would share one neat thing I learnedas a consequence of taking classes—writing compact“cheat sheets”with {rmarkdown}. ¹

The good news is that the fantastic new markdown LaTeX package allos you to write markdown syntax in your LaTeX documents (i.e. Simpler inputs) and still get beautifully typeset PDFs! All you need to do is load the markdown package in your document, and enclose your Markdown material within a markdown environment. 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 keeptex option. Determine whether you’re running 32-bit or 64-bit Windows. Before installing. Markdown which is a markup language that is a superset of HTML. Latex to render mathematical and scientific writing. It’s a very simple language that allows you to write HTML in a shortened way. It can be used on some websites like Stack Overflow or to write documentations (essentially on GitHub). Markdown file extension is.md.

Writing with {rmarkdown} is fairly straightforward—mostlythanks to an abundance of freely available learning resources, like theR Markdown: The Definitive Guide—and usingCSS to customize your Rmarkdown output to your likingis not too difficult either.(By the way, huge shout-out to Yihui Xieand everyone else who has contributedto the development of the {rmarkdown} package.)My objective was to make an extremely compact PDFthat minimizes all white space ².Despite my knowledge of CSS,I had a hard time getting an output that I liked purely from CSS,so I looked online to see if I could find some good LaTex templates.(After all, I would be knitting the Rmarkdown document to PDF,and LaTex would be incorporatedvia the equations on the cheat sheet.)Some templates I found worked fine but weren’t completely to my liking. ³

In my search for an “ideal” template, I stumbled upon a small tidbitin the very last portion of thePDF chapter of the R Markdown bookstating “You can also replace the underlying pandoc template using the template option”. 🤔

At first, I was a bit intimidated by the idea of writing my own template.(“I have to write my own template from scratchusing a framework (LaTeX) that I’ve hardly even touched before now! 😨”)But alas, the task became less intimidating when I realized thatI could use the tried-and-true method of copying-pasting-modifyingfrom Stack Overflow!

The Template

Using the template fromthis Stack Overflow post⁴ as a basis, I endedup creating a relatively minimal template.For the curious reader, see this GitHub repo,for the latest version of my template. It also includes an example cheat sheet.

The “gist” of my template is shown below.

The key for me was to understand how pandoc variableslike $body$ are used as placeholders for user-supplied content.(I know I haven’t mentioned pandoc up to this point,but suffice it to say thatit—along with the R package {knitr}—are what power the {rmarkdown} package.)

The multicols command shown in the snippet above is also noteworthy. ThisLaTex command provides the functionality for I wanted most for mycheat sheet—multiple columns of content!I should point out that there are in_header, before_body, and after_body YAML options for customizing PDF output with {rmarkdown}. ⁵

These options are probably sufficient for most people’s customization needs(so using a custom template would not be necessary).But for me personally, the appeal of having “complete” controlof my output by using a template convinced me to forego these options. ⁶

Usage

So, exactly how do you use a custom template with {rmarkdown}?It’s as simple as specifying the path to your template file with the templateoption in the YAML header of your Rmarkdown document. ⁷

Why This Way?

Before I was using Rstudio and {rmarkdown} to write my cheat sheets,I tried out a couple of LaTex editors ⁸.First, I tried the very popular Overleaf.It is well known and commonly used becauseit is web-based, allows the user to collaborate in real-time, andprovides real-time previewing ⁹.However, there was just something that felt “clunky” about the editor, andthe ambiguity over package versions and usage was bothersome to me. ¹⁰The other editor I tried for some time was TeXworks(with the pdftex distribution)Using the “Typset” command to generate my PDF output on an ad-hoc basis seemed to meto be a satisfactory workflow, but, among other things, I felt limited by the customizationoffered by TeXworks. ¹¹

And so I turned to Rstudio and {rmarkdown} and didn’t look back.While learning how to create a custom template was a (minor) inconvenience,it has paid off in a number of ways:

• I can use a familiar editor—Rstudio.

• I can use a familiar workflow—writing in an Rmarkdown document and knitting to create my desired output.

• Because I’m using {rmarkdown}, I can use {rmarkdown} functionality that is not available when solely writing in LaTex.

This last point is huge.The whole world of markdown syntax is valid!For example,I can add emphasis to text with markdown’s ** and __ tokens (instead of LaTex’s more “verbose” syntax);I can use # to define section headers (which I just think is super “elegant”);and I can use HTML comments to comments out multiple lines of text.(Note that native LaTex only has a single-line comment token—%. ¹²)Additionally, beyond just the markdown functionality, I can include R codethanks to added layer of functionality offered by {rmarkdown}.

The one big thing that I feel like I “sacrificed” by moving to Rstudio and {rmarkdown}is the live preview feature that comes with Overleaf (and can be emulatedwith some configuration in other LaTex editors). Nonetheless, I feel like I geta reasonable facsimile of this feature with Rstudio’s functionalityfor inline previews of equations. ¹³Below are examples of the preview capabilities for both single- andmulti-line equations.

What Works for Me May Not Work For You

Although what I’ve described in this post has been working well for me—andI’d encourage others to try it out—I don’t claim itto be the “best” solution for all of your cheat sheet needs. ¹⁴If you’ve got a workflow that works for you, that’s great! Keep using it!Be pragmatic.

1. For those unfamiliar with the concept of a cheat sheet, there’s no malice in it, despite what the moniker implies. From my experience, it is relatively common for teachers to let students use self-created note sheets (i.e. cheat sheets) for aid with taking exams. ^{^}
2. in order to maximize the amount of space used for content, of course ^{^}
3. One of the ones that I really liked was this one. However, it’s a bit more complex than I wanted. (This one implements a “structure” in which one “main” tex file references several others with the input Latex command.) ^{^}
4. which was super helpful for a LaTex noob like me because it has comments explaining what specific lines/sections are doing ^{^}
5. See the PDF chapter of the R Markdown book for some guidance with these. ^{^}
6. I’m sure I could create a perfectly fine cheat sheet using just these options, or, even re-create the output that I have achieved with my template. ^{^}
7. You can specify other options as well, such as keep_latex: true for an alternative LaTex engine with latex_engine. ^{^}
8. and there are lots of them out there^{^}
9. The live preview feature is probably my favorite of all. ^{^}
10. Others may view the hands-off approach to package management as an advantage of using Overleaf. ^{^}
11. Perhaps this is the fault of my own. Perhaps all the customization that I would like exists and I just have not discovered how to enable it. ^{^}
12. I realize that you can define custom commands or use a package to create multi-line comments in LaTex, but that ruins the point that I’m trying to make 😊. ^{^}
13. See the “Show equation and image previews” option in Tools > Global Options… > R Markdown. ^{^}
14. I wouldn’t be surprised if I find a better workflow for myself in the future. ^{^}

This article is part of the R for Researchers series. For a list of topics covered by this series, see the Introduction article. If you're new to R we highly recommend reading the articles in order.

Overview

This article will introduce you to R Markdown, a document writing program, and demonstrates using RStudio's Git diff, a tool to examine when prior changes were made to a project. These tools are part of RStudio's development environment. They help you work more efficiently.

R Markdown has two advantages that are of interest to a researcher. The first is it allows the results of R code to be directly inserted into formatted documents. The second advantage is it is incredibly easy to use. This ease is a result of R Markdown only using a small set of features and this reduces the complexity of the needed commands. This set of features supports the most commonly used formatting, resulting in the ability to create most documents. These features make R Markdown documents easy to write and the process less error prone.

Git diff allows you to look at what has changed in a file, or files, between any two saved project states. This can be very helpful in determining why results have changed.

Preliminaries

You will get the most from this article if you follow along with the examples in RStudio. Working the exercise will further enhance your skills with the material. The following steps will prepare your RStudio session to run this article's examples.

• Start RStudio and open your RFR project.
• Confirm that RFR (the name of your project) is displayed in the upper left corner of the RStudio window.
• Confirm that there is a Git tab in one of the tab panes.

Files types

RStudio is able to work with a variety of programming languages. This article series covers two of these program languages, R and R Markdown. This article provides an introduction to R Markdown files, which have a file type of .Rmd. R Programs are called R scripts, which have file type .R. The next article introduces R Scripts.

This article series will use .txt and .csv files for datasets. These are the common file types used to import text datasets. The use of these file types will be covered in the data preparation article. This article series will not make use of R's dedicated data file type for data, .RData.

Markdown and R Markdown

Markdown is a tool used to create formatted documents. Markdown source files, file type .md, contain text and formatting commands. Markdown's formatting commands are simpler than most other formatting languages, such as LaTeX or HTML, because it has a smaller number of features. This small set of features supports the most commonly used formatting. The source files are also easier to read than LaTeX or HTML. Markdown is a good choice to format most documents.

R Markdown is an extension of Markdown. R Markdown adds a few features which include R code and results in the formatted document. This allow you write documents which integrate results from your analysis. Incorporating R results directly into your documents is an important step in reproducible research. Any changes that occur in either your data set or the analysis are automatically updated in your document the next time the document is created. There is no more going back through documents trying to find every thing that needs to be fixed when an analysis is rerun. This results in not only greater efficiency, but also fewer errors in documents.

RStudio creates a document, this is called knitting, from an .Rmd file in two steps. In the first step, the R commands are run. The results of the R commands are incorporated with the text and Markdown commands from the .Rmd file. The result of the first step is a .md file. The second step uses the Markdown formatting commands to format the final document. These steps are done together for you by simply pushing the knit button in RStudio.

R Markdown files can be knit to html, pdf, or Word documents. The knitted documents should not be changed by hand. Any edits that are made by hand will be lost when the document is knit again. We do not recommend knitting to Word, because a Word document is a form that is tempting to edit. We recommend knitting to either pdf or HTML files. Programs to read .html and .pdf files are widely available at no cost. In this article series we will generate HTML files.

Writing R Markdown documents is a little different process than with 'What You See Is What You Get' (WYSIWYG) editors, such as Microsoft Word. The examples and exercises in this article series are designed to give you the practice and experience needed to be comfortable with this type of document creation process. As you start working with R Markdown, you may find it convenient to knit your document often. As you gain experience with R Markdown, you will knit much less frequently.

Creating an R Markdown file

To start a document we need to create a new R Markdown file.

• From the File menu, select New File and then R Markdown from the drop down menus.

• A New R Markdown window will open. Enter a title, here we will use 'R Markdown Examples'. This is the title which will be displayed in the document and is not the name of the file.

• Click the OK button in the New R Markdown window.

• This new R Markdown file is now open in RStudio. The file has not been named or saved. Click the save icon, which looks like a floppy disk, in the source pane.

• A Save File window will open. Since we are in a project, RStudio sets the folder to the project folder. If you want the file saved in another folder, such as a sub folder of the project, you navigate to the desired folder. We will use the default of the project folder. Enter the name of the file, here we will use 'RmdExamples'. Click the Save button.

• In the Git tab you can see that the Git status of RmdExamples.Rmd has not been established. Do i need microsoft 365 personal. That is because we have not either added this file to the Git repository or told Git to ignore it. We will commit this file after we have modified it.

Exercises

1. Open a new R Markdown file with an output format of HTML. Give the document the title 'My RFR class notes'.

2. Save the file created in exercise 1 as 'Notes' in the RFR project folder.

File tab

Notice in the Files tab that the files RmdExamples.Rmd and Notes.Rmd are now seen in the the RFR project folder.

• If the Files tab is not displayed, click on the tab labeled Files.

The File tab can be used to open and move files similarly to the Windows Explorer window in the Microsoft Windows environment. If subfolders are added to the project folder, navigating to these folders is also the same as in Windows.

Text formatting using Markdown syntax

Markdown files can be written using any plain text editor such as notepad. We will write our Markdown files using RStudio's editor.

R Markdown files start with a set of lines which begin with --- on a line and end similarly with a line containing --- . This set of lines between and including the lines with ---, is called the metadata section. Markdown commands and text will be added after the metadata section. The RmdExamples file, which is opened in the source pane, has the following metadata section.

This article series will not change or edit the metadata section. For more information on the metadata section see html metadata section and pdf metadata section.

Markdown uses #, *, blank lines, and indented lines for the most common formatting commands. This makes Markdown documents easy to type and makes it easy to read the unformatted document. We will look at a simple example as an introduction to the Markdown syntax.

• Let's say we wish to create a document with an introductory paragraph followed by a sub header, another paragraph, and finally a list.

• The following Markdown source text is one way to write this example.

• The above Markdown produces the following in the knitted document.

  Introductory paragraph text.

  Sub header text

  Another paragraph text.

  1. List item one text
     
  2. List item two text

This example uses just a few formatting commands. Blank lines indicate the end of a paragraph. Placing one to six # at the beginning of a line indicate what follows is a header with the header level being the number of # used. Starting a line with 1. starts a numbered list.

Run this example code in your RmdExample file.

• Delete all the lines which follow the metadata section in the RmdExample file.
• Copy the Markdown source text from the example above and paste the source text in the RmdExample file after the metadata section. It is best to leave at least one blank line after the metadata section before your code starts.
• Click on the knit button in the source pane.
• A viewer window will open with your example document displayed. Your viewer should display the title of the document, which is 'R Markdown Examples' here. Following the title should be the text formatted similarly to what is shown above. Note there will be some differences in formatting due to the styles associated with the web site of this article.

Now that we have made some changes to the RmdExamples file, we will do some source control work.

• Add RmdExamples.html to gitignore. Remember this is done by selecting RmdExamples.html in the Git tab and then selecting Ignore from the tools drop down menu.

• Stage RmdExamples.Rmd and gitignore. Remember this is done by clicking the staged box in front of each file in the Git tab.

• Commit the files with the commit message 'Added Markdown examples'. Remember this is done by clicking the commit icon in the Git tab and then entering the message in the Commit message box.

• Close the Git commit and RStudio Review Changes windows

Markdown syntax

R Markdown Latex Table

A paragraph is started and ended with a blank line before and after the paragraph text. There can be no blank line within the text of a paragraph. Alternately, the end of a paragraph can be indicated with two blank spaces at the end of a line of text.

There are six header levels. The number of # determines the header level. A blank line is required prior to the line which starts a header. Examples of headers one through three are shown below. Note the formatting in your document may be slightly different due to the styles applied to this web site.

• Header examples

  results in

  results in

  header 2

  results in

  header 3

There are several font modifications which can be used in your documents. The number of '*'s are used to determine italic and bold fonts. These font modifications are shown in the following example.

• Font modification examples

  results in

  italicboldbold and italicstrikethrough

There are two list types, enumerated and unordered. Unordered list items are identified with the * symbol at the beginning of a paragraph. This means there must be a blank before the list item or the prior line must end with two blank spaces. An enumerated list item is identified with an integer number followed by a period at the beginning of a paragraph. The first number of the list is the integer number provided for the first item in the list. The following items are numbered sequentially from the start number regardless of the number used to identify the subsequent enumerated items.

• Unordered list example

  results in

  • unordered item
  • another unordered item

• Enumerated list example, starting with number 1

  results in

  1. numbered item
     
  2. another numbered item

Text can be indented two ways depending on if the indent is within a list or not. Within a list, four spaces at the begin of the line indicates the text is to be indented one nesting level. Use four additional spaces for each additional nesting level. To indent text which is not in a list, use a block quote. This is done by starting a line with four spaces.

• Indented text example

  Indenting a block quote

  results in

  indented text

  Indenting a text within a list

  results in

  • List item
    indented text

Links to other documents make use of [] for the displayed text and () for the path to the document.

• link example

  results in

Information on additional Markdown formatting commands can be found at Markdown Basics.

Exercises

These exercises are to be done in the Notes.Rmd file that you created above.

3. Remove all of the document text and commands after the metadata section.

4. Add a level 2 header with the title of this article.

5. Following the header created in the exercise above, write a note to remind yourself of at least one thing about formatting using Markdown.

6. In the text you wrote for the exercise above, use a text modifier (bold, italic, etc.) to highlight a key work or phrase from the text.

7. Ignore the Notes.html file and commit the Notes.Rmd and .gitignore files with the commit message 'Added notes for R Markdown article'.

Mathematical equation formatting commands using LaTeX syntax

Mathematical expressions and equations can be formatted using LaTeX math formatting. LaTeX math formatting can be used for all three output formats, HTML, pdf, and Word documents. Information of formatting mathematics in LaTeX can be found at LaTeX/Mathematics.

HTML pages which include LaTeX formatting use mathjax and javascript for this formatting. Readers may be prompted to allow javascript to run when the webpage is opened.

The syntax to start and end LaTeX math formatting is done with either $ or $$.

• LaTeX formatting examples

  results in

  Inline LaTeX equation (y = 3 + 2x)

  results in

  LaTeX equation [y = 3 + 2x]

R code formatting commands using R Markdown syntax

R code can be included in a document as inline code or as a chunk. A code chunk is a block of code which is rendered in the document as a separate element in the document, not part of a paragraph of text. This may be a figure or a block of block of code and results. Inline R code displays only the text results of the R code in the document. The text returned by R will receive the same formatting as the text it is inline with (paragraph, header, etc.) Any graphics or other non-text results from inline code will not be included in the document.

We will look at a simple example as an introduction to including R code in R Markdown.

• As an example, lets say we have a document which is to have the value of the constant (e) and a scatter plot.

• The document text might be.

• Add the lines above to your RmdExamples file. Add these new lines at the bottom of the file, after the lines for the Markdown example from above.

• Knit RmdExamples document and you should see the following lines having been added to the HTML file.

  Example of integrated R results

  This is inline code to produce the constant (e), 2.7182818.

  This is an R chunk which produces a graph.

• Commit the changes to RmdExmples.Rmd with the commit message of 'Added R chunk example to RmdExamples'.

R code syntax

Inline code is identified with a back tick (above the tab key on a keyboard) followed by r and ends with a back tick.

• Example

  results in

  (pi) = 3.1415927

Chunks start with ```{r name, options} and end with ```. The name is an optional identifier for the chunk and options allow for control of the execution and formatting of the R chunk and it's results.

• Example

  ```{r }
  pi
  ```
  results in

Chunk options

Chunk options allow control over the display of both the source R code and R's results. The following is a list of some common chunk options. We will use most of these options in this article series.

• echo controls the display of the R source code. When set to FALSE, the R source code is not included in the document. The formatting of R's results is not affected by this option.
• comment controls what characters are displayed in front of R text results. When set to NA, no characters are displayed.
• results controls if text results are display and if they are formatted. When set to 'hide', text results are not included in the document. When set to 'asis', no formatting is done by knitr. This is useful for tables which have been formatted by R.
• message controls the display of messages. When set to FALSE, messages are not included in the document.
• warning controls the display of warning messages. When set to FALSE, warning messages are not included in the document.
• fig.show controls if graphics are displayed. When set to 'hide', graphics are not included in the document.
• fig.align controls the horizontal position of graphics. When set to 'center' results in the figure being centered. Left align is the default.
• out.height controls the height of the figure in the final document.
• out.width controls the width of the figure in the final document.
• fig.cap controls the caption which is displayed with a graphic. This is only supported for pdf documents. This is a result of RStudio using Pandoc to format the Markdown for pdf documents.

For a more complete discussion of code chunk options see Options:Chunk options.

The line which starts a chunk cannot be split into multiple lines. This results in some options list extending beyond the width of a line in your editor. This causes no issues for RStudio, though the R Markdown code is slightly less easy to read.

In most documents you will only want to see selected results from your R code. You will want the R code to run quietly in the background. Then you will use either inline or chunks to produce the selected results needed in the document. Chunk options allow for situations like this. The following example uses some made up results. We do not want to see the code which produced the results in the document. But we do want to include the results in the document.

• The following is an example of R Markdown not displaying anything other than errors from a code block.

• Produces the following two lines in a document.

  Summary

  The test of 57 subjects resulted in a p-value of 0.003.

Exercises

These exercises are to be done in the Notes.Rmd file that you created above. Add the work for these problems at the end of the file, after the work done for the previous exercises.

8. Demonstrate the use of in line R code to calculate the results of ((43 - 17)*.1)^2.

9. Demonstrate the use of a chunk to calculate the expression from the prior problem.

10. Same problem as prior problem with the addition of using chunk option(s) to prevent the R source code from being displayed.

11. Commit the Notes.Rmd file with the commit message 'Added R code examples to Notes'.

Git diff

One of the benefits of using Git for source control is its ability to display what has changed and when. This is done with a Git diff. A diff shows what has changed between any two project states. A project state is either a set of files as they were at a prior commit or the files as they are in the work directory. RStudio allows you to diff between adjacent project states. This is either the work directory to the last commit or any commit with the prior commit. To view diffs between other project states use a Git GUI such as SourceTree.

RStudio's Review Changes window is used to view the diffs. This is the same Review Changes window which we used in the Project's article when committing the .gitignore file and to view the project log. Clicking the diff icon in the Git tab opens the Review Changes window with the Changes view displayed. This view shows the diff between the work directory and the most recently committed files. This view was used in the Project's article when committing the .gitignore file. Clicking the history icon, which looks like a clock in the Git tab, opens the History view in the Review Changes window. This view shows the changes between any two adjacent commits. This view was used in the Project's article when we viewed the log. To switch between the Changes and History views use the Changes and History buttons in the upper left corner of the Review Changes window.

We have seen the diff of the work directory with each of the commit we have done. We will look at the diffs between adjacent commits for the RmdExample.Rmd file.

• Click on the History icon in the Git tab.

• The Review Changes window opens with the History view displayed.

• In the log pane, top pane, in the Review Changes window, click on the 'Added Markdown examples' commit. How do i free up storage space on my iphone.

• The 'Added Markdown examples' commit will be highlighted in log pane. In the review pane, lower pane, you will see the list of files which were committed. Below this list are the changes from the prior commit which were made to each of these files. The prior commit here is the 'Initial commit' commit.

• The changes to a particular file, for this commit, can be viewed by either clicking on the file name in the list of files or by using the scroll bar on the right.

• In the log pane click on the 'Added R chunk example to RmdExamples' commit.

• In the review pane you will see the changes made from the prior commit, here that is the 'Added Markdown examples' commit.

The log for a project can get large. Filters can be used to focus the log on what is of interest. This can make it easier to find changes that you are interested.

We will filter the log to look at changes to the RmdExamples file.

• In the RStudio: Review Changes window, click on the (all commits) menu at the top of the window.

• Select Filter by File from the menu.

• Select RmdExamples.Rmd from the menu in the Choose File window.

• Click the open button at the bottom of the Choose File window.

• The log now only shows two commits. These are the only commits which included changes to the RmdExamples.Rmd file.

LaTeX documents

RStudio can generate LaTeX source code files from R Markdown. This can be useful at times, such as for submission to publications which require LaTeX source code. LateX source can be created when the output document is pdf. The metadata option 'keep_tex: true' tells RStudio to keep a document with the LaTeX source code. The metadata section would look similar to the following.

RStudio uses the Pandoc program to knit an R Markdown file to pdf. This, as usual, is done for you and you do not need to know the details. What may be help for pdf docs is Pandoc supports all R Markdown formatting commands as well as a few others. Information on additional Markdown formatting commands can be found at Pandoc Markdown.

R Markdown verse Sweave

R Markdown does have its limitations. A key limitation is there is no support for figure and table captions or numbers. For a typical article with five to ten figures and tables, these can be done with R code. Examples of this will be provided in later articles in this series.

If you need formatting which is not supported by Markdown, LaTeX formatting commands can be used within a R Markdown file when the output type is pdf. If this is done, the document can only be knit to pdf.

For documents with many figures and tables or other special formatting needs, such as a thesis, Markdown is typically not the optimal choice. The better choice would likely be to use Sweave files with LaTeX text formatting. Sweave, like R Markdown, allows the inclusion of inline R code and chunks. The syntax is a little different for inline code and chunks, though the general approach is the same. RStudio will compile a Sweave document similarly to R Markdown files, though it does not use the knit button.

Next: R Scripts

Previous: R projects

R Markdown Latex Equation

Last Revised: 4/16/2015