106 lines
6.2 KiB
Plaintext
106 lines
6.2 KiB
Plaintext
# R Markdown
|
||
|
||
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.
|
||
|
||
```{r echo = FALSE, comment = ""}
|
||
cat(htmltools::includeText("extra/sample-rmarkdown.Rmd"))
|
||
```
|
||
|
||
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.
|
||
* Dynamic Documents
|
||
|
||
## Using R Markdown in the RStudio IDE
|
||
|
||
If you need to get started immediately...
|
||
|
||
## Write text
|
||
|
||
Markdown is easy to use.
|
||
|
||
## Embed code
|
||
|
||
Use knitr syntax to customize the output.
|
||
|
||
## Use the metadata
|
||
|
||
### Set Parameters
|
||
### Change and customize Output formats
|
||
|
||
## Extensions
|
||
|
||
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.
|
||
|
||
Learn more at rmarkdown.rstudio.com.
|