We assume the following
Have a decent
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!
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.
How to submit homework
- Make sure you have
- Saved all the files associated with your solution locally.
- Committed all those files to your local Git repository.
- Pushed the current state of your local repo to GitHub.
- Open an issue, link to the latest commit, and tag the staff:
- Visit your GitHub repo in a web browser.
- Just above the file list, look for “latest commit” followed by ten numbers and letters (called the revision SHA) and a clipboard icon.
- Click the clipboard icon to copy the revision SHA to your clipboard.
- Click on “Issues”, then on “New Issue”. Name the issue “Mark homework x of firstname-lastname”, where x is, 1, 2, ….
- In the issue description, tag Jenny by including the text
@jennybc, and paste the revision SHA. Include a link to exactly where you want a reviewer to go.
- Click “Submit new issue”. You’re done! Congratulations!
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 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.
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: