---
title: Tutorials in RStudio
author: David Kane
tutorial:
  id: rstudio
output:
  learnr::tutorial:
    progressive: yes
    allow_skip: yes
runtime: shiny_prerendered
description: Tutorial for introducing students who are using RStudio to tutorials in general and to some
  of the defaults from the **tutorial.helpers** package in particular.
---

```{r setup, include = FALSE}
library(learnr)
library(tutorial.helpers)
library(remotes)

knitr::opts_chunk$set(echo = FALSE)
knitr::opts_chunk$set(out.width = '90%')
options(tutorial.exercise.timelimit = 60, 
        tutorial.storage = "local") 
```

```{r copy-code-chunk, child = system.file("child_documents/copy_button.Rmd", package = "tutorial.helpers")}
```

## Introduction
### 

This tutorial is an introduction to the general use of R tutorials created with the [**learnr**](https://rstudio.github.io/learnr/) package for students using RStudio. It is meant for beginning students who have never completed a tutorial.

### 

You may complete a tutorial either on your laptop or on a cloud computing platform like [Posit Cloud](https://posit.cloud/). (See our discussion about [setting up your own computer](https://ppbds.github.io/primer/getting-started-with-rstudio.html) or about [using Posit Cloud](https://ppbds.github.io/tutorial.helpers/articles/cloud.html).) Either way, you will download a copy of your answers to the Downloads folder on your computer once you are done with a tutorial. Then, you will submit your answers to your instructor and/or keep a copy for yourself.

### 

Most tutorials begin by asking for your your name and email. (Your instructor might also request that you fill in the "ID" field so that your work can be matched to a grading database. If not, leave the "ID" field blank.) Click "Continue" and then fill in your name and email. Click the **"Submit Answer"** button each time. If you make a mistake, you can click **"Try Again"** and, uh, try again. 


```{r info-section, child = system.file("child_documents/info_section.Rmd", package = "tutorial.helpers")}
```

## Exercises 
### 

In each tutorial, there will be a set of exercises for you to complete. For non-coding questions, you write your answer and then hit the "Submit Answer" button, as you did above.

### 

Clicking **"Start Over"** --- look for small letters at the bottom of the left-hand side menu --- deletes all your work for a tutorial and allows you to begin the entire tutorial again. (If you are working on your tutorial in the Tutorial tab, the screen might not be wide enough to show the left-hand side menu. If so, just expand the Tutorial tab until it appears.)

### Exercise 1

Let's practice some simple math. Type `4 + 5` into the box below. Hit **"Run Code"** to see your results. Clicking **"Hint"** gives you a hint about what to type. 

```{r exercises-1, exercise = TRUE}

```

```{r exercises-1-hint-1, eval = FALSE}
4 + 5
```

### 

Once you click "Run Code," the answer `[1] 9` should appear below the code you entered. This is the same behavior you would see if you ran this code in the RStudio Console tab.

### 

There are two types of answers for tutorial questions: prose and code. With prose answers, you will use the "Submit Answer" button, as you did with your name and email. With code answers, you use the "Run Code" button, as you did for this question.

### 

If you don't "Run Code" (or "Submit Answer") your response, nothing is recorded.

### Exercise 2

Let's use variables to perform the same calculation. Below, we have already assigned 5 to `x` and 4 to `y`. On the line below those two provided lines of code, add the two variables by typing `x + y`. Hit "Run Code" to see your results. 

```{r exercises-2, exercise = TRUE}
x <- 5
y <- 4

```

```{r exercises-2-hint-1, eval = FALSE}
x <- 5
y <- 4
x + y
```

### 

Once you click "Run Code", the answer `[1] 9` should appear below the code you entered. 

### Exercise 3

We will often need to copy code from our previous exercises to continue working on a multi-stage problem. To make this easier, we provide a "Copy previous code" button. Below the following box, click on the "Copy previous code" button. 

```{r exercises-3, exercise = TRUE}

```

<button onclick = "transfer_code(this)">Copy previous code</button>

```{r exercises-3-hint-1, eval = FALSE}
x <- ...
y <- 10
x + ...
```

### 

This should paste all work from the previous exercise into the above exercise code area. Note that this will only copy code which has already been run in the previous exercise.

### 

Change the values to `x <- 6` and `y <- 10`. Hit "Run Code." You should get the answer `[1] 16`.

### 

Note that the assignment symbol, `<-`, is a less-than-sign followed by a dash. We often pronounce the symbol as "gets." So, we might say, when reading this code, that "x gets 6."

### 

Did you remember to hit the "Run Code" button above? Lots of people forget! You must hit the button for your answer to be recorded.

### 

If you used the hint, note how we did not provide the entire answer. This is our standard approach with hints.


### Exercise 4

<!-- Might be nice to create a screen recording of these steps. -->

Read all of the following instructions before continuing, as this tutorial will close once you take the first step.

Restart your **R session** by clicking `Session -> Restart R` from the main RStudio Menu. (Note that restarting R within this **RStudio instance** is a different thing than restarting the overall RStudio instance itself.)

You should receive the warning message shown below. (Note that this box might be "hidden" behind your tutorial.) Whenever you see this warning message, keep in mind that clicking "Terminate Jobs" will close any running tutorials. 

```{r}
knitr::include_graphics("images/terminate_jobs.png")
```

Click "Terminate Jobs." This will "grey out" the tutorial. (You might also have to close the tutorial window by hand and/or hit the "Return to home" button, the little house icon with the red roof located just below the word "Environment.") 

Re-open this tutorial by clicking "Start Tutorial" in the Tutorial tab, just as you did at the start of the tutorial. Progress will have been saved automatically.

Now that you have read all the instructions, go ahead and follow them.

### 

Note how all your answers to previous questions have been saved. It is not a problem to quit a tutorial. In fact, if you ignore a tutorial for awhile, it will quit automatically.


### Exercise 5

We often ask you to execute an R command in the R Console, the tab on the left portion of your RStudio screen. Type `version[['version.string']]` into the Console and hit the return/enter key.

**Do not just type the command into the answer box!** You must paste the command into the R Console and then execute the command.

Copy/paste the command **and** the return value into this box.

```{r exercises-5}
question_text(NULL,
	answer(NULL, correct = TRUE),
	allow_retry = TRUE,
	try_again_button = "Edit Answer",
	incorrect = NULL,
	rows = 3)
```

### 

Your answer should look something like:

````
> version[['version.string']]
[1] "R version 4.4.2 (2024-10-31)"
> 
````

Your version of R may be more recent, but it should not be older. It is OK if your formatting differs from ours. Exactness does not matter. What matters is that you prove that you have executed the command as instructed.

### 

The tutorial workflow will often look like this. We tell you to run a command **in the Console**. You run it. We then ask you to copy/paste, from the Console, both the command itself and the response returned. Because we ask you to **c**opy/**p**aste the **c**ommand/**r**esponse so often, we usually shorten this instruction to CP/CR.


### Exercise 6

RStudio and your R installation have some default settings which are not good for new users. Run this command at the Console to change them:

`
tutorial.helpers::set_rstudio_settings()
`

CP/CR.

```{r exercises-6}
question_text(NULL,
	answer(NULL, correct = TRUE),
	allow_retry = TRUE,
	try_again_button = "Edit Answer",
	incorrect = NULL,
	rows = 8)
```

### 

The output from this function will report the changes, if any, which were made. To learn more, look up the help page by running `?set_rstudio_settings` at the Console.

### 

You can generally call functions by just giving their name along with the ending parentheses, as with `set_rstudio_settings()`. However, it can be safer to preface the function name with the name of the package in which the function is found, separated by two colons. Since `set_rstudio_settings()` is in the **tutorial.helpers** package, we can also call it using the double colon notation: `tutorial.helpers::set_rstudio_settings()`.

### Exercise 7

Run this command from the R Console. 

`
rstudioapi::readRStudioPreference(name = "load_workspace", NA)
`

CP/CR.

```{r exercises-7}
question_text(NULL,
    answer(NULL, correct = TRUE),
    allow_retry = TRUE,
    try_again_button = "Edit Answer",
    incorrect = NULL,
    rows = 3)
```

### 

You should have pasted something like this in the box above:

````
> rstudioapi::readRStudioPreference(name = "load_workspace", NA)
[1] FALSE
>
````

The response should be `FALSE`. If it is not, try re-running `tutorial.helpers::set_rstudio_settings()`.

You have now selected sensible settings for using RStudio.

### Exercise 8

Tutorials can include written responses. You have already seen several examples. Sometimes those written answers are just copies of the R commands and their results. Other times, we will ask you to write one or more sentences of prose. 

Copy and paste everything from `Exercise 8` above through the end of this sentence into the answer box below. That is, you are copying from this tutorial, not from the Console. Press "Submit Answer."

```{r exercises-8}
question_text(NULL,
    message = "We will sometimes provide an answer to written questions. Other times, like here, we won't. In the former case, we will not allow you to resubmit your answer. Don't stress! Most instructors grade tutorials on pass/fail basis, so, as long as you make an honest effort, you will do fine.",          
    answer(NULL, 
           correct = TRUE),
    allow_retry = FALSE,
    incorrect = NULL,
    rows = 6)
```

### Exercise 9

`show_file()` is another commonly-used function from the **tutorial.helpers** package. It makes it easy for you to share the contents of another file with your instructor, especially a file which you have edited. 

From the R Console, run this command:

```
tutorial.helpers::show_file(file.path(R.home(), "COPYING"), end = 7)
```

CP/CR.

```{r exercises-9}
question_text(NULL,
	answer(NULL, correct = TRUE),
	allow_retry = TRUE,
	try_again_button = "Edit Answer",
	incorrect = NULL,
	rows = 3)
```

<!-- I really want a test case to ensure that this works on all OSs. -->

```{r include = FALSE}
tutorial.helpers::show_file(file.path(R.home(), "COPYING"), end = 7)
```

### 

Your answer should look something like this:

````
> tutorial.helpers::show_file(file.path(R.home(), "COPYING"), end = 7)
		    GNU GENERAL PUBLIC LICENSE
		       Version 2, June 1991

 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
                       51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.
> 
````

### 

For now, don't worry about what `R.home()` and `file.path()` are doing, although you can read about them by running `?R.home` and `?file.path` at the Console. Those details are less important than seeing the intended usage of `show_file()`. 


## Your answers
### 

At the end of every tutorial, you will save your work (and submit it, at the discretion of your instructor). We will do this in the next panel, labeled "Download answers." Follow the instructions there. 

Make sure to answer the question about how many **minutes** you spent on the tutorial and to click "Submit Answer."

After hitting the "Download" button, you will be prompted to save a file named `rstudio_answers.html`. This file will be saved in the default Downloads folder on your computer, even if you completed the tutorial on a cloud computing platform. 

Unless told otherwise by your instructor, you should use the default file name, which will usually be of the form `name-of-tutorial` + `_answers` + `.html`. 

```{r download-answers, child = system.file("child_documents/download_answers.Rmd", package = "tutorial.helpers")}
```

## Summary
You now understand how tutorials function and how to download a copy of your answers. Good luck with your data science journey!
