Writing R Markdown chapter.

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.
+
+<!--- ![](images/rmarkdown-wizard.png) --->
+
+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.