-
Notifications
You must be signed in to change notification settings - Fork 1
/
submission_guide.Rmd
117 lines (70 loc) · 8.74 KB
/
submission_guide.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
---
title: "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](seminars.html) 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](seminars.html) for illustration of this workflow). Now you can begin working on your submission files locally. See [below](#files-organization) 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. <span style="color: red">**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!**</span>
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](#main-required-file-types) 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](#general-tips-for-working-on-the-assignments)). 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](group_project_rubrics.html#github-repository-10-pts)
# 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](https://www.rstudio.com/resources/cheatsheets/) 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!