From e93979c25eabc5a3b5c8ec91ae6822fbfff222ad Mon Sep 17 00:00:00 2001 From: jennybc Date: Wed, 13 Jul 2016 10:47:46 +0200 Subject: [PATCH] create a part for workflows --- 20_usage-new-project-github-first.Rmd | 2 +- ...> 30_workflow-first-use-rmd-and-github.Rmd | 2 + ...workflow-first-use-r-script-and-github.Rmd | 0 32_workflow-make-github-repo-browsable.Rmd | 110 ++++++++++++++++++ ...mmands.Rmd => 38_workflow-git-commands.Rmd | 0 _bookdown.yml | 7 +- 6 files changed, 117 insertions(+), 4 deletions(-) rename 30_usage-first-use-rmd-and-github.Rmd => 30_workflow-first-use-rmd-and-github.Rmd (99%) rename 31_usage-first-use-r-script-and-github.Rmd => 31_workflow-first-use-r-script-and-github.Rmd (100%) create mode 100644 32_workflow-make-github-repo-browsable.Rmd rename 38_usage-git-commands.Rmd => 38_workflow-git-commands.Rmd (100%) diff --git a/20_usage-new-project-github-first.Rmd b/20_usage-new-project-github-first.Rmd index c3f8ad77..8c63864f 100644 --- a/20_usage-new-project-github-first.Rmd +++ b/20_usage-new-project-github-first.Rmd @@ -1,4 +1,4 @@ -# (PART) Early Usage {-} +# (PART) Early GitHub Usage {-} # New project, GitHub first {#new-github-first} diff --git a/30_usage-first-use-rmd-and-github.Rmd b/30_workflow-first-use-rmd-and-github.Rmd similarity index 99% rename from 30_usage-first-use-rmd-and-github.Rmd rename to 30_workflow-first-use-rmd-and-github.Rmd index c5d96eee..288cfd7c 100644 --- a/30_usage-first-use-rmd-and-github.Rmd +++ b/30_workflow-first-use-rmd-and-github.Rmd @@ -1,3 +1,5 @@ +# (PART) Workflows {-} + # Test drive R Markdown {#rmd-test-drive} We will author an R Markdown document and render it to HTML. We discuss how to keep the intermediate Markdown file, the figures, and what to commit to Git and push to GitHub. If GitHub is the primary venue, we render directly to GitHub-flavored markdown and never create HTML. diff --git a/31_usage-first-use-r-script-and-github.Rmd b/31_workflow-first-use-r-script-and-github.Rmd similarity index 100% rename from 31_usage-first-use-r-script-and-github.Rmd rename to 31_workflow-first-use-r-script-and-github.Rmd diff --git a/32_workflow-make-github-repo-browsable.Rmd b/32_workflow-make-github-repo-browsable.Rmd new file mode 100644 index 00000000..5d454519 --- /dev/null +++ b/32_workflow-make-github-repo-browsable.Rmd @@ -0,0 +1,110 @@ +# Render an R script {#r-test-drive} + +An underappreciated fact is that much of what you can do with R Markdown, you can also do with an R script. + +If you're in analysis mode and want a report as a side effect, write an R script. If you're writing a report with a lot of R code in it, write Rmd. In either case, render to markdown and/or HTML to communicate with other humans beings. + + * In R markdown, prose is top-level and code is tucked into chunks. + * In R scripts, code is top-level and prose is tucked into comments. You will use `#'` to request that certain comments appear as top-level prose in the rendered output. + +You will continue to specify things like the output format via YAML at the top of the file. This will need to be commented with `#'`. + +## Morph R Markdown into a renderable R script + +Get yourself a working R Markdown file, such as the one you made in your [Rmd test drive](#rmd-test-drive). Or use the boilerplate Rmd document RStudio makes with *File > New File > R Markdown ...*. + +Save the file as `foo.R`, as opposed to `foo.Rmd`. Yes, for a brief moment, you will have R Markdown saved as an R script, but that won't be true for long. + +Transform the Rmd to R: + + * Anything that's not R code? Like the YAML and the English prose? Protect it with roxygen-style comments: start each line with `#'`. + * Anything that's R code? Let it exist "as is" as top-level code. That means you'll need to change the syntax of R chunk headers like so: + + Before: ` ```{r setup, include = FALSE}` + After: `#+ r setup, include = FALSE` + + Replace the leading backticks and opening curly brace with `#+`. + Delete the trailing curly brace. + Delete the 3 backticks that end each chunk. + +Render the R script through one of these methods: + + * Click on the "notebook" icon in RStudio to "Compile Report". + * In RStudio, do *File > Knit Document*. + * In R, do `rmarkdown::render("foo.R")`. + +You'll get a markdown and/or HTML report, just as with R Markdown. + +If you're having trouble making all the necessary changes and you're frustrated, see below for an example you can copy and paste. + +All the workflow tips from the [Rmd test drive](#rmd-test-drive) apply here: when you script an analysis, render it to markdown, commit the `.R`, the `.md`, any associated figures, and push to GitHub. Collaborators can see your code but also browse the result without running it. This makes the current state of your analysis accessible to someone who does not even run R or who wants to take a quick look at things from a cell phone or while on vacation. + +## Write a render-ready R script + +Instead of morphing an R Markdown file, let's create a render-ready R script directly. + +Create a new R script and copy/paste this code into it. + +```{r define-demo-code, include = FALSE} +demo_code <- c( + "#' Here's some prose in a very special comment. Let's summarize the built-in", + "#' dataset `VADeaths`.", + "## here is a regular code comment, that will remain as such", + "summary(VADeaths)", + "", + "#' Here's some more prose. I can use usual markdown syntax to make things", + "#' **bold** or *italics*. Let's use an example from the `dotchart()` help to", + "#' make a Cleveland dot plot from the `VADeaths` data. I even bother to name", + "#' this chunk, so the resulting PNG has a decent name.", + "#+ dotchart", + "dotchart(VADeaths, main = \"Death Rates in Virginia - 1940\")" +) +writeLines(demo_code, "render-r-script-demo.R") +``` + +```{r eval = FALSE, code = demo_code} +``` + +Render the R script through one of these methods: + + * Click on the "notebook" icon in RStudio to "Compile Report". + * In RStudio, do *File > Knit Document*. + * In R, do `rmarkdown::render("YOURSCRIPT.R")`. + +Revel in your attractive looking report with almost zero effort! Seriously, all you had to do was think about when to use special comments `#'` in order to promote that to nicely rendered text. + +Drawing on the workflow tips in [Rmd test drive](#rmd-test-drive), let's add some YAML frontmatter, properly commented with `#'`, and request the `github_document`. Here's the whole script again: + +```{r augment-demo-code, include = FALSE} +demo_code <- c( + "#' ---", + "#' title: \"R scripts can be rendered!\"", + "#' author: \"Jenny Bryan\"", + "#' date: \"`r format(Sys.Date())`\"", + "#' output: github_document", + "#' ---", + "#'", + demo_code +) +writeLines(demo_code, "render-r-script-demo.R") +``` + +```{r eval = FALSE, code = demo_code} +``` + +Behind the scenes here we have used `rmarkdown::render()` to render this script and you can go [visit it on GitHub](https://github.com/jennybc/happy-git-with-r/blob/master/render-r-script-demo.md). + +```{r render-demo-code, include = FALSE} +rmarkdown::render("render-r-script-demo.R", output_format = "github_document") +## for some reason I am +## [a] having to specify output_format in render(); why YAML not working? +## [b] having to do this "by hand" in R Console in order to actually get the +## figure left behind +``` + +```{r clean-up, include = FALSE, eval = FALSE} +## for now, I'm just letting the files created here persist +## but maybe I will regret that one day, so this is ready to activate +leftovers <- list.files(pattern = "render-r-script", ignore.case = TRUE) +if (length(leftovers)) file.remove(leftovers) +``` diff --git a/38_usage-git-commands.Rmd b/38_workflow-git-commands.Rmd similarity index 100% rename from 38_usage-git-commands.Rmd rename to 38_workflow-git-commands.Rmd diff --git a/_bookdown.yml b/_bookdown.yml index eb24524d..2babbf34 100644 --- a/_bookdown.yml +++ b/_bookdown.yml @@ -25,9 +25,10 @@ rmd_files: [ "21_usage-existing-project-github-first.Rmd", "22_usage-existing-project-github-last.Rmd", - "30_usage-first-use-rmd-and-github.Rmd", - "31_usage-first-use-r-script-and-github.Rmd", - "38_usage-git-commands.Rmd", + "30_workflow-first-use-rmd-and-github.Rmd", + "31_workflow-first-use-r-script-and-github.Rmd", + "32_workflow-make-github-repo-browsable.Rmd", + "38_workflow-git-commands.Rmd", "40_prompt-clone.Rmd", "41_prompt-fork.Rmd",