发帖
雷达卡
- Overview
- Step 0: Software installation and configuration
- Step 1: Get ready to work
- Step 2: Practice with RStudio’s boilerplate R Markdown document
- Step 3: Take control of the output format
- Step 4: Swap out the “guts” of the document
- Step 5: Develop your report
- Step 6: Publish your report
- Troubleshooting
2016-06-15: I have high-jacked this for my useR! tutorial. Once I migrate content over to the happy git repo, I will put this more back to the way it was!
OverviewThis describes a hands-on activity where the goal is to 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.
Here is the official R Markdown documentation: http://rmarkdown.rstudio.com
Step 0: Software installation and configuration
We assume the following
- You’ve already installed Git and (probably) a Git client.
- You’ve already registered a free GitHub account.
- You’ve already installed R and RStudio.
- You’ve tested your installation and configuration of Git, GitHub, and RStudio
- You’ve completed Homework 01 or an equivalent exercise to truly test all of the above and to introduce you to Markdown.
Step 1: Get ready to work
Launch RStudio, probably in the Project that corresponds to the repository where you are keeping all STAT 545 coursework. Make sure the workspace is clean and you’ve launched a fresh R process. Make sure the working directory is sensible.
this should be a repo that is already syncing with a github remote
Step 2: Practice with RStudio’s boilerplate R Markdown document
I am modelling “walk before you run” here. It is best, especially for novices, to increase complexity in small increments. We will test our system’s ability to render the “hello world” of R Markdown documents before we muddy the waters with our own, probably buggy, documents.
Do this: File > New File > R Markdown …
- Give it an informative title. This will appear in the document but does not necessarily have anything to do with the file’s name. But the title and filename should be similar! The title is for human eyeballs, so it can contain spaces and punctuation. The filename is for humans and computers, so it should have similar words in it but no spaces and no punctuation.
- Accept the default Author or edit if you wish.
- Accept the default output format of HTML.
- Click OK.
Save this document to a reasonable filename and location. The filename should end in .Rmd or .rmd. Ihighly recommend saving in the top-level of the directory that is also also a Git repository for your coursework and that is also an RStudio project and that is also current working directory. Trust me on this.
commit here
Click on “Knit HTML” or do File > Knit Document. RStudio should display a preview of the resulting HTML. Also look at the file browser (which should be pointed at the directory where you saved the .Rmd file). You should see the R Markdown document, i.e. foo.Rmd AND the resulting HTML foo.html.
Congratulations, you’ve just made your first reproducible report with R Markdown.
commit here
Step 3: Take control of the output format
Do you really want HTML? Do you only want HTML? If so, you can skip this step!
The magical process that turns your R Markdown to HTML is like so: foo.Rmd --> foo.md --> foo.html. Note the intermediate markdown, foo.md. By default RStudio discards this, but you might want to hold on to that markdown.
Why? GitHub gives very special treatment to markdown files. They are rendered in an almost HTML-like way. This is great because it preserves all the charms of plain text but gives you a pseudo-webpage for free when you visit the file in the browser. In contrast, HTML is rendered as plain text on GitHub and you’ll have to take special measures to see it the way you want.
In many cases, you only want the markdown. In that case, we switch the output format to github_document. This means render will be foo.Rmd --> foo.md, where foo.md is GitHub-flavored markdown. If you still want the HTML but also the intermediate markdown, there’s a way to request that too.
Output format is one of the many things we can control in the YAML frontmatter – the text at the top of your file between leading and trailing lines of ---.
You can make some changes via the RStudio IDE: click on the “gear” in the top bar of the source editor, near the “Knit HTML” button. Select “Output options” and go to the Advanced tab and check “Keep markdown source file.” Your YAML should now look more like this:
--- title: "Something fascinating" author: "Jenny Bryan" date: "`r format(Sys.Date())`" output: html_document: keep_md: true ---You should have gained the line keep_md: true. You can also simply edit the file yourself to achieve this.
In fact this hand-edit is necessary if you want to keep only markdown and get GitHub-flavored markdown. In that case, make your YAML look like this:
--- title: "Something fascinating" author: "Jenny Bryan" date: "`r format(Sys.Date())`" output: github_document ---Save!
commit here
Render via “Knit HTML” button.
Now revisit the file browser. In addition to foo.Rmd, you should now see foo.md. If there are R chunks that make figures, the usage of markdown output formats will also cause those figure files to be left behind in a sensibly named sub-directory, foo_files.
If you commit and push foo.md and everything inside foo_files, then anyone with permission to view your GitHub repo can see a decent-looking version of your report.
If your output format is html_document, you should still see foo.html. If your output format isgithub_document and you see foo.html, that’s leftover from earlier experiments. Delete that. It will only confuse you later.
commit here
Step 4: Swap out the “guts” of the document
Select everything but the YAML frontmatter and … delete it!
Write a single English sentence.
Insert an empty R chunk, via the “Chunk” menu in upper right of source editor or with corresponding keyboard shortcut.
` ``{r}## insert your brilliant WORKING code here```Insert 1 to 3 lines of functioning code that begin the task at hand. “Walk through” and run those lines using the “Run” button or the corresponding keyboard shortcut. You MUST make sure your code actually works!
Satisfied? Save!
commit here
Now render the whole document via “Knit HTML.” Voilà!
commit here
Step 5: Develop your report
In this incremental manner, develop your report. Add code to this chunk. Refine it. Add new chunks. Go crazy! But keep running the code “manually” to make sure it works.
If it doesn’t work with you babysitting it, I can guarantee you it will fail, in a more spectacular and cryptic way, when run at arms-length via “Knit HTML” or rmarkdown::render().
Clean out your workspace and restart R and re-run everything periodically, if things get weird. There are lots of chunk menu items and keyboard shortcuts to accelerate this workflow. Render the whole document often to catch errors when they’re easy to pinpoint and fix. Save often and commit every time you reach a point that you’d like as a “fall back” position.
You’ll develop your own mojo soon, but this should give you your first successful R Markdown experience.
Step 6: Publish your report
If you’ve been making HTML, you can put that up on the web somewhere, email to your collaborator, whatever.
No matter what, technically you can publish this report merely by pushing a rendered version to GitHub. However, certain practices make this effort at publishing more satisfying for your audience.
Here are two behaviors I find very frustrating:
- “Here is my code. Behold.” This is when someone only pushes their source, i.e. R Markdown or R code AND they want other people to look at their “product”. The implicit assumption is that target audience will download code and run it. Sometimes the potential payoff simply does not justify this effort. Communication fail.
- “Here is my HTML. Behold.” This is when someone doesn’t bother to edit the default output format and accepts HTML only. What am I supposed to do with HTML on GitHub? Communication fail.
Creating, commiting, and pushing markdown is a very functional, lighweight publishing strategy. Useoutput: github_document or keep_md: true if output is html_document. In both cases, it is critical to also commit and push everything inside foo_files. Now people can visit and consume your work like any other webpage.
This is (sort of) another example of keeping things machine- and human-readable, which is bliss. By makingfoo.Rmd available, others can see and run your actual code. By sharing foo.md and/or foo.html, others can casually browse your end product and decide if they even want to run your code.
HTML on GitHubHTML files, such as foo.html, are not immediately useful on GitHub (though your local versions are easily viewable). Visit one and you’ll see the raw HTML. Yuck. But there are ways to get a preview: such ashttps://rawgit.com or http://htmlpreview.github.io. Expect some pain with HTML files inside private repos. When it becomes vital for the whole world to see proper HTML in its full glory, it’s time to use a more sophisticated web publishing strategy.
I have more general ideas about how to make a GitHub repo function as a website.
京公网安备 11010802022788号
