GitHub pre-requisites

We assume the following

Have a decent README.md

In the first homework you created a top-level README.md for your repository. Keep it in good shape! You are allowed to edit it!

Authoring Markdown files

Throughout this course, any basic text document should be written in Markdown and should always have a filename that ends in .md. These files are pleasant to write and read, but are also easily converted into HTML and other output formats. GitHub provides an attractive HTML-like preview for Markdown documents. RStudio’s “Preview HTML” button will compile the open document to actual HTML and open a preview.

Whenever you are editing Markdown documents in RStudio, you can display a Markdown cheatsheet by clicking the question Mark ? at the top of the editor pane.

Authoring R Markdown files

If your document is describing a data analysis, author it in R Markdown, which is like Markdown, but with the addition of R “code chunks” that are runnable. The filename should end in .Rmd or .rmd. RStudio’s “Knit HTML” button will compile the open document to actual HTML and open a preview.

Whenever you are editing R Markdown documents in RStudio, click the question Mark ? at the top of the editor pane to display a Markdown cheatsheet or visit RStudio’s R Markdown website.

Here is our introductory tutorial on rendering R Markdown.

Organization of your coursework repository

As the course goes on, you will accumulate many files in your repository. In due course, we will discuss the of use sub-directories to organize things.

BTW we truly mean directories or “folders” – NOT a Git branch or anything fancy like that!

You have a top-level README.md for your repository. Once you create sub-directories, you may also want to have a README.md file in each sub-directory to serve as a landing pages for, e.g., a homework assignment or a data directory.

As you get more advanced, here is more advice about making your GitHub repo very browsable.

Which files to commit

How to submit homework

Make your work shine!

Here are some minor tweaks that can make a big difference in how awesome your product is.

Make it easy for people to access your work

Reduce the friction for TAs and profs to get the hard-working source code (the R markdown) and the front-facing report (HTML).

  • Create a README.md in the homework’s subdirectory to serve as the landing page for your submission. Whenever anyone visits this subdirectory of your repo, this will be automatically rendered nicely! In particular, hyperlinks will work.
  • With this README.md file, create annotated links to the documents TAs and profs will need to access. Such as:
    • Your main R markdown document.
    • The intermediate Markdown product that comes from knitting your main R markdown document. Remember GitHub will render this into pseudo-HTML automagically. Remember the figures in figures/ need to be available in the repo in order appear here.
    • The final pretty HTML report. Read instructions below on how access the pretty, not the ugly source.

If you want to see an example of a README.md that links to and explains a bunch of files in the same repo + subdirectory, you can look at this example from STAT 545A 2013.

Make it easy for others to run your code

  • In exactly one, very early R chunk, load any necessary packages, so your dependencies are obvious.
  • In exactly one, very early R chunk, import anything coming from an external file. This will make it easy for someone to see which data files are required, edit to reflect their locals paths if necessary, etc. There are situations where you might not keep data in the repo itself.
  • Pretend you are someone else. Clone a fresh copy of your own repo from GitHub, fire up a new RStudio session and try to knit your R markdown file. Does it “just work”? It should!

Make pretty tables

Instead of just printing an object with R, you could format the info in an attractive table. Some leads:

This work is licensed under the CC BY-NC 3.0 Creative Commons License.