diff --git a/images/rmarkdown-wizard.png b/images/rmarkdown-wizard.png new file mode 100644 index 0000000..ba74619 Binary files /dev/null and b/images/rmarkdown-wizard.png differ diff --git a/reproducible-research.Rmd b/reproducible-research.Rmd index 61a4839..65063f3 100644 --- a/reproducible-research.Rmd +++ b/reproducible-research.Rmd @@ -1,7 +1,105 @@ -# Reproducible Research with R Markdown +# 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. -## What is R Markdown? ## 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 -## Set Parameters + +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.