Completing and submitting practice exercises

1 Access your exercise repository

1.1 Register for an account and join the student team

  • You must sign up for a GitHub user account and share your GitHub username with me before I can create an exercise repository for you.
  • Note that you must have installed R and RStudio to complete exercises and installed GitHub Desktop to submit exercises.
  • Soon after I get your username, you should expect an email asking you to accept an invitation to the “2023_Students” Team in the class GitHub organization.
  • This is a private repository just for your exercise assignments so the repository will be named: <your first name>_<your last name> and can be accessed at: https://github.com/bldgspatialdata/<your first name>_<your last name>. Don’t forget to replace the placeholder with your first and last name in lower case. You can also go to the course repository list and, if you are logged in and have access, you should find your repository there.
What is a repository?

A repository is a collection of files where changes can be tracked and managed using a version control system. Git is a version control system. GitHub is a web service that makes it easier to manage version-controlled repositories and collaborate with others. For more background, read Ch. 1 Why Git? Why GitHub? from Happy Git and GitHub for the useR by Jenny Bryan.

1.2 Set up GitHub credentials in RStudio

If you are using RStudio instead of GitHub Desktop to update your repository, you also need to set up some local credentials so GitHub knows that RStudio is allowed to make changes to your repositories. You

The {usethis} documentation includes detailed article on connecting GitHub and R but it is more detail than you may need. First, install the {usethis} package (if you don’t have it installed already):

# pak::pkg_install("usethis")

Now, there are four steps (the first step is optional):

  1. Set up two-factor authentication. This is optional but recommended.

  2. Run usethis::create_github_token() to get a personal access token and copy the token to your clipboard. Make sure you are signed in to GitHub in your browser first! I also suggest setting the expiration to 90 days so you won’t need to refresh the token until after the end of this course.

  3. Run gitcreds::gitcreds_set() to put your PAT in your Git credential store

  4. Restart your session and run usethis::gh_token_help() to double-check that the token is saved in the right place.

If you run into any trouble, you can also run usethis::git_sitrep() for more feedback on what is set up correctly and what (if anything) might need to be fixed.

2 Download or update your exercise repository

2.1 Downloading (a.k.a “cloning”) your exercise repository

  • Clone the repository to your computer using GitHub Desktop or using the GitHub website. Review the GitHub documentation on cloning a repository with GitHub Desktop or the GitHub website for more detailed instructions.
  • Find and open folder where you downloaded the local copy of the exercise repository. By default, this folder should have the same name as the repository itself.
  • As long as you keep this folder on your computer, you should do not need to clone the repository again. If you delete your local files or switch computers, you need to repeat this step.

2.2 Updating (a.k.a “syncing”) your exercise repository

  • I will be adding new exercises to your repository each week using GitHub. You should “sync” the changes to the GitHub repository with your local copy of the project each week. Read the GitHub documentation on Syncing your branch in GitHub Desktop for more detailed instructions.

3 Complete the week’s exercise

The process for completing will be mostly the same for each week of the class.

3.1 Locating the week’s exercise file

  • Locate the <your first name>_<your last name>/exercises folder on your computer.
  • Open the exercises.RProj file in RStudio. Review the documentation on managing projects in RStudio or the R for Data Science chapter on working with projects for more background on why projects are useful.
  • Using the “Files” tab pane, locate the exercise_01.qmd file (or the number exercise file for this week) and open it. The file extension (.qmd) is short for Quarto Markdown document.
  • If you can’t find this week’s exercise file, you may have forgotten to update the repository. Go back and check Section 2.2
What is a Quarto document?

A Quarto document is a format that lets you mix blocks (also known as “chunks”) of R code with sections of text formatted using Markdown formatting. This format is similar to an older format known as RMarkdown (.Rmd). Quarto comes installed with RStudio but it is a separate command line application that can turn a qmd document into a standalone website, a formatted PDF, a presentation, and more. This course website, for example, is built with Quarto.

You can see that a front matter section at the top of each document. This front matter (also known as YAML) controls the format, appearance, and content of the rendered document.

The Hello, Quarto tutorial is a great place to learn how to render Quarto documents, run code blocks interactively, and format text using the markdown syntax.

  • Complete the project by filling in the blank spaces, fixing any “broken” code in the document, or adding new code in the code blocks that look like this:
1 + 1 # example code
[1] 2

3.2 Running code and writing responses to the exercise prompts

  • Try executing the code in each block as you work through the practice exercise. The results from the code appear right below the block. If you get an error or a warning, try to use that information as a clue to figure out what you need to change.

  • When you are done with the exercise, there should be no more blank spaces like this one: ____. The bonus exercises are optional but otherwise any code block that started empty should now have code inside.

  • Some questions require short written responses which should be completed as Markdown formatted text above or below the related code block—not as a comment inside the code block!

  • If all of your code blocks run smoothly, you should be able to “render” the .qmd document to create a new HTML document. When I review completed assignments, trying to render the document will always be my first step.

  • When you done with the exercise, please change the front matter for the document from status: Available to status: Complete.

  • Remember, you don’t need to get everything right and it is OK if your document won’t render. Just try your best with each part of the exercise.

Tips for completing exercises
  • Complete this exercise from top to bottom. Blocks of code at the end of the document may depend on blocks from the beginning or middle so avoid skipping around.
  • If you get an error message, read it. If it doesn’t make sense, try looking it up. R for Data Science reminds readers that Google is your friend.
  • Read the documentation!

4 Committing your completed exercise to the repository

You may have saved your updated document to your computer but the last step is to save or “commit” those changes to the exercise repository.

“Committing” your changes and syncing the changes with the remote version of your repository on GitHub allows me to see your completed exercise and share feedback on your work.

4.1 Commit changes with GitHub Desktop

The first and easiest way to commit changes is using GitHub Desktop.

4.2 Commit changes with RStudio

The second way to commit changes is using the Git tab within RStudio. The interface for Git within RStudio is a little less friendly but is a convenient option since you don’t need to leave RStudio to commit your changes.

Here is the step-by-step process (adapted from Connect RStudio to Git and GitHub in Happy Git and GitHub for the useR):

  • Click the “Git” tab in upper right pane.
  • Check “Staged” box for exercise_01.qmd.
  • If you’re not already in the Git pop-up, click “Commit”.
  • Type a message in “Commit message”, such as “Commit from RStudio”.
  • Click “Commit”.
  • Finally, click the green “Push” button to send your local changes to GitHub.
When should you commit your changes?

You don’t need to wait until you are 100% finished with the exercise to commit your changes. You may want to commit the changes every time you work on the exercise. Please make sure to change the “status” for the exercise from “Available” to “Complete” when your exercise is complete and ready for evaluation. I will typically evaluate the last week’s exercises on the Tuesday before each class session. Committing changes as you go can also avoid conflicts if I need to make corrections or additions to some part of the assignment after you started working on it.