R Markdown is an authoring framework that does something incredibly useful, it provides a single file format that you can use to do everything from run code to publish finished reports. In other words, you can use a single R Markdown file to
* import data
* tidy it
* visualize, transform and model it
* and then communicate the results
R Markdown is also exceptionally easy to learn and based on a simple plain text file format, which means that R Markdown files are unusually easy to track with version control software like Git and Github. On top of all of this, R Markdown features are seamlessly integrated in to the RStudio IDE, turning the IDE into a type of R Markdown editor. Did I mention that R Markdown files also provide a multi-language notebook interface for R?
This chapter will show you how to use this versatile piece of technology. Section 1 provides a quick tour of all of the basic features in R Markdown. This section is all that you need to read to get started. The remainder of the chapter will show you how to customize details of the R Markdown workflow.
## Using R Markdown in the RStudio IDE
An R Markdown file is a simple plain text file saved with the extension .Rmd. You can open an R Markdown file in the RStudio IDE by going to File > New File > R Markdown. The editor will open a window that looks like this, which you can ignore. The IDE pre-populates your file with content based on what you choose in the window. If this is your first time using R Markdown, just click OK.
<!---  --->
RStudio will open a new file that contains the text below, which describes how to use R Markdown. In practice, you would simply delete this content and start writing in your file. Since this is our first R Markdown file let's take a look at the content. The content itself is a viable R Markdown document.
When you write an R Markdown file, you include everything that you would need rerun your analysis, as well as everything that you would need to write a report about your analysis.
R Markdown files contain three types of content:
1. An optional header of YAML values
These key value pairs contain metadata that R Markdown can use to generate a finished report from your file. If your file contains a header it must appear at the start of the file and it must begin and end with a line that contains three dashes, e.g. `---`.
2. Text formatted with Markdown cues
These sections of text look like plain text, but they may contain unobtrusive formatting markup written in the [Markdown](http://rmarkdown.rstudio.com/authoring_basics.html) syntax. For example, line 12 begins with two hashtags (`##`), which identify the line as a second level header.
3. Code chunks
Code chunks contain executable code, often in the R language. Each chunk begins with a line that contains three backticks, knitr::inline_expr(```), and then the name of a programming language in braces. Some chunks may contain optional chunk arguments inserted between the brackets and separated by commas. Each code chunk ends with a line of three backticks.
## The benefits of R Markdown
* Literate Data Science
* Reproducible Research.
As a data scientist, you don't run experiments, you run code. What do you need to reproduce? The whole process, this includes communication.
Here we list some extensions to the R Markdown format. Some of these extensions are so deep, like building Shiny Apps, that I can't possibly cover everything you need to know here (but I can tell you where to learn more), others are so simple to use, like flexdashboards, that this brief entry is all you will need to get started.
Since R Markdown is designed to be extended, you should expect more extensions to appear over time.
* Flexdashboards
* Bookdown
* Shiny apps
As a data scientist, you don't run experiments, you run code.
As a data scientist, you are the link between data, computers, colleagues, and human decision makers. Your many roles require many tools, but now there is a powerful authoring framework that lets you do everything with a single file. It’s called R Markdown. It‘s incredibly easy to use, and, like the rest of R, it is absolutely free.
With R Markdown, you record your work in a plain text file that contains narrative, code, and metadata. Open the file in your RStudio IDE and you have a true notebook for R. You don’t even need to write your code in R. You can use Python, JavaScript, SQL, and many more languages within your file.
To share your work, generate an html, pdf, or Microsoft Word report straight from your file. Or a beamer, ioslides, slidy, or reveal.js slideshow. Or a notebook that colleagues can view in a web browser. Or an administrative dashboard, or a book, or a website, or an interactive web app. R Markdown makes all of these and more.
In every case, R Markdown executes the code in your file and inserts the results into your finished report.
You can set output options, like a table of contents, or apply reusable templates that quickly shape the appearance of your report.
You can also set parameters each time you render a new report, which turns your file into a reusable data product that you can write once and deploy multiple times.
To go beyond the basics, enhance your R Markdown files with HTML based interactivity. Create client-side interactions with R’s htmlwidgets, like leaflet, dygraph, and other JavaScript visualizations. Or create more sophisticated interactions that are processed on the server side with Shiny.
R Markdown supports anything that you can do in R, and it creates a reproducible record of your work as you go. Build models, connect to databases, or run spark code on Big Data with the sparklyr package. R Markdown handles it all. And yet, at heart, it remains a simple plain text file.
