Lab Instructions

This semester the labs are built as interactive documents using R-shiny. This is intended to give you instant feedback, because with no TA it can take me a while to give you feedback on your labs! Hopefully this helps your learning experience- please let me know what you think or how you think this can be improved!

Interactive labs

The interactive labs are available via an R package called “NRES746labs” or via shinyapps.io.

To access the interactive labs using shinyapps.io, just click on the URL link and follow the instructions. For Lab 1, use:

https://kevintshoemaker.shinyapps.io/NRES746_LAB1/

To access the interactive labs using the R package, use the following steps:

Step 0: Get latest version of R and RStudio

Older versions of R and RStudio can cause issues- to prevent these potential issues please install the latest version of both R and RStudio before proceeding!

R: https://cran.r-project.org/
RStudio: https://www.rstudio.com/products/rstudio/download/#download

Step 1 (Windows users): install ‘RTools’ (first time only)

RTools is not an R package but a standalone software that enables Windows users to compile and install R packages from source code. You can install RTools from this link: https://cran.r-project.org/bin/windows/Rtools/. Binary installers are available for 64 and 32 bit machines.

I don’t think you need to do anything here if you are a Mac user- just move on to the next session.

Step 2: make sure that R can compile source code! (first time only)

For Windows users, you need to make sure that RTools is in your PATH variable.

For both Windows and Mac users, first check to see if R already knows how to compile from source. Try running the following code:

Sys.which("make")

##                        make 
## "C:\\Rtools\\bin\\make.exe"

## "C:\\rtools40\\usr\\bin\\make.exe"

If the ‘Sys.which’ command above returns something, you should be fine. If it returns nothing (an empty text string), you may need to do the following:

For Windows users, add RTools to your PATH variable. To do this, you can create a text file .Renviron in your Documents folder which appends your RTools directory onto your PATH variable. You can do this in R by running the following line:

writeLines('PATH="${RTOOLS40_HOME}\\usr\\bin;${PATH}"', con = "~/.Renviron")

Now close R and RStudio and try the ‘Sys.which’ command again (see above). If this works, you can move on to the next step

For Mac users, you may need to install Xcode or at least install a C compiler. Again, I am not completely certain how to debug this one, but we will figure it out!

Step 3: install package ‘devtools’ (first time only)

To do this, use the “Install” button on the “Packages” tab in Rstudio, or use the following command:

install.packages("devtools")

NOTE: you only have to do this once! Once you’ve installed a package on your machine it will always be there! Installing devtools for the first time can be time consuming, especially if (as they recommend) you install dependencies from source.

Step 4: install the “gradethis” package from GitHub (first time only)

One of the packages that I use in the tutorials (to give you instant feedback) is still in development and is not yet available on CRAN. So, you need to install it from GitHub. To do this, use the following code:

remotes::install_github("rstudio/gradethis")

NOTE: this can take a while the first time, and lots of messages will pop up. If you’re asked to choose packages to update, try choosing the ‘install CRAN packages only’ option. If that fails, you may want to try to update all the packages it wants you to (option 1).

Luckily, you only need to do this once!

Step 5: install the “NRES746labs” package from GitHub (every time you are about to start a new lab)

For now the R package lives on GitHub (since I’ll be updating it a lot!). You can use the following code to install the package from GitHub:

remotes::install_github("kevintshoemaker/NRES746labs")

NOTE: you should re-install the ‘NRES746labs’ package for every lab (using the ‘install_github’ function above), since I’ll be updating frequently. For example, the package currently only includes old versions of labs 2-4.

Step 6: run the lab!

Now you have everything you need to run the lab. Use the following code to start the interactive tutorial:

learnr::run_tutorial("lab1","NRES746labs")

NOTE: the system doesn’t seem to work for Microsoft Edge so make sure your default browser is Chrome or Safari.

NOTE: the shiny app will “use up” your R session, so if you want to work on your own script at the same time as you’re running the app, you’ll have to open up a second R session. I recommend you do this!

Hope this works! Good luck!

DEBUGGING

Here are some tips if things don’t work right away:

Make sure you have the most recent version of R and the most recent version of Rstudio
If R throws errors like “can not remove package […]” then close all R sessions and go into your local package directory and delete the package manually. Then go back to R and reinstall the package. To find your local package directory, enter the following in your R session:
```
  Sys.getenv('R_LIBS_USER')
```

This seems to be easier said than done on a Mac!

If you try to run the tutorial through the base R GUI and not RStudio you may have to do the following:
- Go into Rstudio and find your ‘pandoc’ directory:
```
   Sys.getenv('RSTUDIO_PANDOC')
```
- Go back to your base R session and enter the following:
```
   Sys.setenv(RSTUDIO_PANDOC=[...your directory here...])
```
If you get an error stating that GitHub’s API rate limit has been exceeded (GitHub has a rate limit of 60 requests per hour for unauthenticated requests), the easiest solution is to create a GitHub access token (PAT). You can get a PAT by entering ‘usethis::browse_github_pat()’ in your R console and following the instructions. Then, add your PAT to your .Renviron file by entering ‘usethis::edit_r_environ()’ in your R console. Finally, in the ‘.Renviron’ file (the one that just opened up in Rstudio), type the following:

GITHUB_PAT=[your PAT here]

If nothing else seems to work, try using one of the lab computers!