RepResCourse

I'm navbar-fixed-top

Reproducible Research Course by Eric C. Anderson for (NOAA/SWFSC)

Instructions for “Trial Homework”

There are three main steps to doing this homework: I) getting the homework and preparing your R environment, II) writing in the answers, III) turning the homework in.

Since this is a course on R and git and GitHub, we will be using git and GitHub to do I and III. Detailed instructions follow. The workflow will become familiar eventually.

I. Getting the Homework and Prepping

  1. Pull down the master branch of the rep-res-course repository to get this assignment:
    • If you don’t already have a clone of the rep-res-course repository, clone the rep-res-course repository:
      1. In RStudio, Choose File->New Project
      2. When asked, choose “Create Project from Version Control”
      3. Then when asked choose “Git”
      4. For repository URL use this: https://github.com/eriqande/rep-res-course.git
      5. Don’t put anything in for the name of the project directory. It will automatically name it rep-res-course.
      6. Hit “Create Project”.
    • If you already have a clone of the rep-res-course repository
      1. Open up the RStudio project rep-res-course.Rproj
      2. If you are not on branch master in that project (check the upper right corner of the “Git” pane—if it does not say “master” in small letters you are not on the master branch), then commit any changes on whatever branch you are on (If you don’t commit changes on the branch you are on, then they will get carried back to the master branch and could cause problems pulling.), and then checkout the master branch (this can be done by clicking on the branch name in the upper right of the Git pane and choosing master. (But be sure you do not choose origin/master)).
      3. Once on the master branch click the “pull button at the top of the Git pane.
  2. Immediately checkout a new branch named ex-test:
    1. go to the “Tools” menu item in RStudio and within it choose “Shell…”. This will pop up a command prompt window (Terminal window on a mac, GitBash Window or a Command Prompt Window on PC).

    2. In the command window, type this command:

      git checkout -b ex-test
      and hit RETURN.
  3. Make sure you have the necessary packages installed. I have written an R package, rrhw, that facilitates answer submission and collation (and subsquent analysis) of homework responses. You will need that package. To get it, you will use the devtools package:

    • issue the following expression in the R console at least once this quarter:

      install.packages("devtools")

    • and do this in the R console (only one time) when you start working on a new homework set:

      devtools::install_github("eriqande/rrhw")

      This ensures that you will have the latest version of rrhw.

  4. Check that everything is working. Within RStudio, open the file exercises/trial_homework.rmd. And knit it on your computer
    • Doing this will give you a nice file with a quick table of contents to get to any of the specific exercises/problems.
    • Notice that the homework problems in the knitted html file are inside R code blocks under headings that look like: Trial Homework: #3, “problem-name”

II. Figure out the answers to the problems and write them in

  1. You will be inserting your answers into the appropriate places in the Rmarkdown file exercises/trial_homework.rmd. As stated above, each problem “lives” in an R code block which, in the knitted HTML output is below a heading that might look like Trial Homework: #3, “problem-name”. The exact heading string does not appear in the file exercises/trial_homework.rmd because it is generated by some R code. However, you can find the appropriate code chunk by searching for the name of the problem (problem-name in the above example) in the file exercises/trial_homework.rmd.

  2. Read the problem in each R-code chunk. Evaluate the lines in the R code chunk and maybe look at some objects, and read the questions in the comments and then put your answer inside the curly braces within the submit_answer function. For example, a question that looks like this:

    # x is a vector constructed like this:
x <- 1:10

# return the values of x less than 4
submit_answer({

})

    should be answered by adding x[x < 4] to the code block so that it looks like this:

    # x is a vector constructed like this:
x <- 1:10

# return the values of x less than 4
submit_answer({
x[x < 4]
})

  3. Note that you can put multi-line expressions into the submit_answer function. This is crucial when the question asks you to modify an object and also return the modified object. For example if given this question:

    # x is a vector constructed like this:
x <- 1:10

# change all the even values in x to -99 AND return x
submit_answer({

})

    You should answer like this:

    # x is a vector constructed like this:
x <- 1:10

# change all the even values in x to -99 AND return x
submit_answer({
  x[c(F,T)] <- -99
  x
})
    Notice how the last line in the entry to submit_answer is x, which returns its value to the submit_answer function.
  4. Some notes:
    • Please don’t accidentally erase the curly braces in the submit_answer function.
    • You can also evaluate all the R code in a chunk to get the objects in it loaded into your R global environment. And you can evaluate all the R code in exercises/trial_homework.rmd into your R global environment too. See the options under the menu item Code --> Run Region and get familiar with the keyboard shortcuts. This is useful for testing things.
    • If you knit the file you can see the value that your answers return in the knitted output.

III. When Done, Submit the Homework via a GitHub Pull Request

  1. After writing in all your answers, make sure that exercises/trial_homework.rmd still knits correctly. Try not to submit homework that you can’t knit without an error.
  2. Commit your completed homework file
    1. When you are finished entering your answers to your satisfaction, commit the file exercises/trial_homework.rmd. (i.e. go to the Git pane and stage the file and then hit the commit button, write a message, etc.) Don’t commit changes in any files other than exercises/trial_homework.rmd, and don’t add the html file or any other intermediates to the repository. Remember, you should be on the branch named ex-test.
  3. Push your ex-test branch up to your fork of Eric’s rep-res-course repository.
    1. If you have not already done so, create a fork of the rep-res-course repository on your own GitHub account:

    2. If you have not already done so, tell git on your computer to establish your forked version of the rep-res-course repository (on GitHub) as a remote repository that git on your computer can link to through the name my_rr_fork. Use Tools --> Shell... in RStudio to get a command prompt, then replace GITHUBNAME with your GitHub username in the following:

      git remote add my_rr_fork https://github.com/GITHUBNAME/rep-res-course.git
      You shouldn’t have to do this more than once this quarter.

    3. Push your answers up to your fork of the repository. Give this command in RStudio’s “Tools –> Shell” command shell:

      git push my_rr_fork ex-test
      You might have to provide your GitHub username and password.
    4. Go back to your GitHub page and:
      1. find the little green button at the upper left of the page.
      2. To the right of that green button is a “branch” button. Click it and make sure that you choose the ex-test branch.
      3. Now, click the little green button.
      4. Review the changes you have made (shown in the next screen) and click the large “Create Pull Request” button.
      5. This takes you to a new page where you can write some comments on your pull request, if you want. Then click the large green button (to create the pull request), and Voila! You should be done.

I’m sure this seems like a crazy sequence of things to do. Do it enough, however, and it starts to feel very natural. Stick with it!

comments powered by Disqus

Authored by Eric C. Anderson working as a Federal employee. Content on this website is a government work in the public domain in the U.S. and under the CC0 1.0 internationally. Templates and plugins to build the site are modified from Hadley Wickham's Advanced R website. Powered by jekyll, knitr, and pandoc. Source available on github.