Creating an assignment with autogradeR • autogradeR

The autogradeR is able to generate automatic templates for more complex assignments. These templates are designed as GitHub repositories to be released using GitHub classroom. Now, let’s asumme that you’re interested in creating all the basic files that are needed for autogradeR to work for you as an instructor and your students. Note that students will have access to the autoautogradeR at any time. However, answers will be either (1) encrypted and saved in a hidden object in the environment or (2) simply saved into a hidden object (also in the environment). Instructors can decide when to encrypt answers.

1. Homework template

To create a template of the HW using autogradeR, use the assignment.template() function. This function will create two folders in a given directory, which is by default, your current working directory .. First, the data folder, where the instructor is expected to provide any external datasets to the student. Second, a tests folder, where the instructor is going to (1) develop their Homework, and (2) store correct answers.

autogradeR::assignment.template(path = "HW1")
#> Files will be saved to a new directory: /home/runner/work/autogradeR/autogradeR/vignettes/HW1

2. Modify the template

Now, it’s time for the instructor to make changes to the tests/1_answers_template.Rmd file. Note that autogradeR has already rendered the same file into 1_answers_template.html. The tests/1_answers_template.Rmd, which should be modified by the instructor, is expected to contain all the correct answers for each of the questions in the HW. The tests/0_answers_template_original.Rmd file should NEVER be modified and is used as a reference to the instructor.

Unless you know what you are doing, NEVER modify the autoautogradeR section by hand. You can change anything before those lines. Final answers MUST be saved with the structure QX =, with X representing any number. Failing to follow that structure will cause the autoautogradeR to fail. Both the autoautogradeR section and the QX = structure in final answers are the only two aspects that should NOT be modified.

You can render your tests/1_answers_template.Rmd file as many times as you need and troubleshoot with it until it renders appropriately and all the answers are shown as correct.

Finally, note that a README.rmd file was created in the root of your working direct. The README.rmd should be used to present basic information to the students in the GitHub repo. Please make all the changes you need in the README.rmd. Do not modify lines of code below the autoautogradeR in the same file.

Up to this point, the files in the repo are the following:

#> HW1
#> ├── README.Rmd
#> ├── data
#> │   └── sample_dataset.csv
#> └── tests
#>     ├── 0_answers_template_original.Rmd
#>     ├── 1_answers_template.Rmd
#>     ├── 1_answers_template.html
#>     └── reference_answers.RData

3. Generate the student’s markdown

Once your HW template is ready, you’ll need to generate the relevant files for your students using the assignment.expand() function. This function will create a 0_Homework.Rmd file, a blank template for your students to answer the questions. The autoautogradeR will be tested in a newly rendered 0_Homework.html that was generated from 0_Homework.Rmd. Finally, rendering the 0_Homework.Rmd will always render the README.Rmd, which in turns create the README.md file.

autogradeR::assignment.expand(path = "HW1")

The following are the files and folders that are created:

#> HW1
#> ├── 0_Homework.Rmd
#> ├── 0_Homework.html
#> ├── README.Rmd
#> ├── README.md
#> ├── data
#> │   └── sample_dataset.csv
#> └── tests
#>     ├── 0_answers_template_original.Rmd
#>     ├── 1_answers_template.Rmd
#>     ├── 1_answers_template.html
#>     ├── reference_answers.RData
#>     └── student_answers.RData

4. Release the HW

Create a template repo in GitHub. Use GitHub classroom. Push only the relevant files (do NOT push the answers). I will talk more about how to encrypt R files later on. You can also use ghclass but I find convenient to simply share the GitHub classroom link with my students (instead of creating the repos for them; but maybe I’m missing something).

Personal trick: I create a single organization per class I teach. Each assignment has the assignment name plus an indication of when it was released (the term). For instance, HW1 for my INFO123 class taught in the Fall of 2022 would be part of the INFO123 organization, with the assignment labeled as Homework-1-F22 That way, I don’t have to worry about creating new organizations each term, students will have constant access to their assignments, and all the resources are hosted within the same “umbrella”.

5. Collect the assignments

For collecting the assignments submitted to GitHub classroom, you have two options. You can either clone the repositories using GitHub Classroom assistant or use the assignment.collect function in autogradeR, a wrapper for ghclass:: local_repo_clone. For instance, if you decide to use autogradeR to clone the repos, you can use the following line of code.

autogradeR::assignment.collect(organization = "INFO123", GHpattern = "homework-1-F22", path = "HW1F22")

Either of the options should work just fine. The goal is to have all the folders stored in a local folder (e.g. HW1F22 in the example above).

6. Extract grades from the local repos

Once you have cloned all the repos locally, autogradeR can help you extract the final grades from student’s submitted assignments. Grades are extracted from README.md files. If students fail to push this file, their grade will be 0. Please encourage your students to push at least the HWX.Rmd, the associated HTML file, and the README.md file.

aautogradeR::ssignment.grades(createPDFs = TRUE)