Submission Guide

How to start and submit assignments through GitHub and Gradescope

You need to have Git installed on your computer, and have a GitHub account. You can use command line Git or RStudio itself to push, pull, etc. to/from GitHub. See Seminar 1 for an illustrated setup guide and illustration of the full workflow from accepting an assignment to submission.

Start a new assignment

1. Accept: Click on the assignment invitation link for the assignment in Canvas. Each individual assignment/deliverable will have its own link, whereas the group project will only have one link at the start of the project (all deliverables will use the same shared repository). After you accept the assignment, a GitHub repository will be automatically be generated for you.

2. Clone the repository to your local machine (see Seminar 1 for illustration of this workflow). Now you can begin working on your submission files locally. See below for more detail on repositories and organizing files.

How to “turn in” your work: Save, Commit, Push, Submit

Follow these steps carefully, and be sure they are complete before the deadline of each deliverable. Important Note: the deadline is automated, so you will not be able to perform a late submission (even by one second). Make sure to allow plenty of time for submission!

1. Please include a link to your assignment repository at the top of your main output file.

2. Save all the files associated with your solution locally (i.e. for coding assignments R Markdown, GitHub Markdown, and any associated output files - see below for more detail).

3. Commit those files to your local Git repository.

4. Push the current state of your local repo to your private repo on GitHub. Double check that this was successful, by viewing your repo on GitHub to verify that the most recent commits are visible.

5. Submit the repository on Gradescope via the link in Canvas.

That’s it! You can commit/push to update your assignment as often as you’d like before the deadline (frequent commits are actually encouraged). A snapshot of your repo at the deadline will automatically be captured for grading.

If you’re concerned that something hasn’t gone right with the submission and the deadline is imminent, send the TAs an e-mail with your assignment attached. Note: this is only a last-minute emergency back-up plan, and penalties may apply. We will work with you until you get it submitted via GitHub/Gradescope.

Files & organization

Individual assignments

• Use the repositories that are automatically generated for you when you accept each assignment (e.g., the repo with the format STAT540-UBC-2024/seminar-01-yourGitHubID will contain your Seminar 1 deliverable). Do not use additional branches or any other repositories to submit your course work.
• All your work for each deliverable should be nicely organized in its repository.
• Your repositories should include a README.md file with a clear description. These are like each assignment’s landing page.

Group project

• A shared team repository will be created for your group project; all group-level project deliverables will be submitted in this repo.
• Information on organizing this repo can be found on the Group Project Rubrics Page

Main required file types

In general for coding assignments, you need to commit and push your R Markdown, GitHub Markdown, and any associated figure/output files with your assignments (note: you should not to commit raw data to your repository - see below). Writing assignments are the exception (e.g. paper critique, project proposal): a Markdown file sufficient.

This workflow is specific to STAT 540 and may not necessarily reflect your workflow in other contexts.

R Markdown (source file)

• Write your homework in R Markdown. The file extension should be .Rmd.
• Recommendation: For coding assignments, start with the Markdown or R Markdown file that creates the assignment itself! You can take some things away (unnecessary detail) and add others (R chunks, explanatory text) to morph this into your homework solution.

GitHub Markdown (output file)

• Compile your homework to GitHub Markdown (file extension should be .md).
  • In the YAML header, specify output: github_document as shown below
  • RStudio’s “Knit” button will create the GitHub Markdown file (.md) when the output is specified in this way. The Github Markdown file is a file that can be rendered nicely on GitHub.

---
title: "Homework assignment"
author: "Your Name"
output: github_document
---

• Never ever edit the output Markdown “by hand”. Only edit the R Markdown source and then regenerate the downstream products from that.

Figure files (output files)

• By default, any figures created by your .Rmd are placed into a subdirectory titled [filename]_files where [filename] is the basename (without extension) of your .Rmd file.
• The GitHub Markdown file links to these figure files and, therefore, requires these files to be present to in order to include the figures in your full report.

Files not to commit: Data files (input files)

Locally, you may keep input data files in some logical place within the assignment’s directory. But list the names of such data files in your top-level .gitignore file, so that Git ignores it. Or better yet, include commands that download the data directly (if available and not too large). This is to reduce storage required on GitHub and when the TAs download your repositories for marking.

General tips for working on the assignments

• Start early. Even if you are already fluent with all the seminar materials, it will still take time to answer all the questions, and prepare files for submission.

• Commit early; commit often (and push). It’s helpful to have an earlier version of your work to return to (e.g. to debug if something suddenly throws an error and you can’t figure out why 🤯, or if your cat walks on your keyboard and deletes your repo 🤷).

• When you get stuck or when you run into an error, ask yourself these questions:

  • Am I in the right working directory ?
    
  • Is this material covered in one of the lectures or seminars?
  • Can I google how to do this?
  • Is there an R package that can more efficiently do what I’m attempting now?
  • Am I using the right parameters for this function? (hint, type ?function_name() where function_name is the name of the function, to check if you’re using it right)

• Your Rmarkdown can’t be knitted? Is it because you didn’t define all the variables inside your Rmarkdown? Your code chunk might run in RStudio if all the variables are all defined in the RStudio environment, but it wouldn’t run as the Rmarkdown is being knitted if the variables aren’t defined in the Rmarkdown document.

• Overall presentation and mechanics refer to the fluency, neatness, easiness to read. For example:

  • Explain what you’re doing to show your understanding, i.e. sandwiching your code and result with some explanations and interpretation. We don’t want to see just a graph or some R outputs standing alone in a question.
  • Use headings/subheadings to distinguishes different sections/questions
  • Well-structured dataframes and reusable functions can often lighten your work load and increase readability of code.
  • Use inline R code whenever you refers to the value of a variable in a block of text.
  • Comment on your code so that everyone, including yourself, can easily follow through your steps. In R, comment follows the number sign. For example # What I did here
    
  • Consider formating R output in a nice table instead of just printing it (e.g. see the kable() function from knitr package)

• You might find cheatsheets from Rstudio useful, in terms of graphing, making an awesome R markdown, etc.

• 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. Ideally, include commands to download if it is available and not too large.
  • 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!