diff --git a/inst/tutorials/getting-started/images/r-tutorial-terminal.png b/inst/tutorials/getting-started/images/r-tutorial-terminal.png new file mode 100644 index 0000000..97fc481 Binary files /dev/null and b/inst/tutorials/getting-started/images/r-tutorial-terminal.png differ diff --git a/inst/tutorials/getting-started/tutorial.Rmd b/inst/tutorials/getting-started/tutorial.Rmd index bd515f0..9b781e5 100644 --- a/inst/tutorials/getting-started/tutorial.Rmd +++ b/inst/tutorials/getting-started/tutorial.Rmd @@ -40,9 +40,7 @@ After starting the tutorial, your Codespace looks something like this: include_graphics("images/cs-start-tutorial.png") ``` - - -Running a tutorial by pressing the arrow next to its name creates an HTML output file and forwards it to the port shown in the URL at the bottom. In this image, the URL is `http://127.0.0.1:7361`. If the file has not already opened, `Cmd`-click the URL to open the tutorial. Notice that the `R Tutorial` terminal is busy; other terminal windows remain available for commands. + ### @@ -140,58 +138,23 @@ Did you remember to hit the "Run Code" button above? Lots of people forget! You ### Exercise 4 -Read all of the following instructions before continuing. The purpose of this exercise is to demonstrate that your tutorial answers are saved automatically. - - - - - -* Return to your Codespace and click the "R Tutorial" terminal window. - -* Stop the tutorial by pressing `Ctrl + C` in the terminal. This is useful because it can interrupt any terminal process. A new line should appear where you can enter another command. - - - -* Return to the browser window containing the tutorial. The tutorial should now be grayed out, indicating that it is no longer connected to the running process. Close this window. - -* To restart the tutorial, either press the play button next to the "getting-started" tutorial in the sidebar or copy the following command into the terminal and press `Enter`: - - - -``` -Rscript -e "learnr::run_tutorial('getting-started', package = 'tutorial.helpers')" -``` - -* This command tells the terminal to run `Rscript`, which calls the `run_tutorial()` function from the `learnr` package. - -* Finally, open the tutorial. - - -Now that you have read all the instructions, go ahead and follow them. - -### - -Notice that all of your answers to previous questions have been saved. It is not a problem to quit a tutorial. In fact, if you leave a tutorial idle, it will eventually quit automatically. - -### Exercise 5 - -Back in your Codespace, create a new R terminal by pressing the down arrow next to the plus button in the bottom right and selecting "New R terminal." +Create a new R terminal by pressing the down arrow next to the plus button in the right side of the Panel Toolbar and selecting "New R terminal." ```{r} include_graphics("images/cs-new-R-terminal.png") ``` -In the new terminal, type `version[['version.string']]` and press `Return` (on Mac) or `Enter` (on Windows). To avoid repeating both terms in every question, we use `Enter` to mean either the `Return` or `Enter` key, as appropriate. +In the new terminal, type `version[['version.string']]` and press `return` (on Mac) or `enter` (on Windows). To avoid repeating both terms in every question, we use `enter` to mean either the `return` or `enter` key, as appropriate. - + **Do not just type the command into the answer box!** You must paste the command into the terminal and then execute the command. - + -Copy and paste both the command **and** the returned value into this box. +**C**opy and **P**aste both the **C**ommand *and* the **R**esponse from the terminal into this box. We will abbreviate this instruction in the future as **CP**/**CR**. -```{r exercises-5} +```{r exercises-4} question_text(NULL, answer(NULL, correct = TRUE), allow_retry = TRUE, @@ -215,9 +178,9 @@ Your version of R may be more recent, but it should not be older. It is OK if yo Tutorial workflow will often look like this: we tell you to run a command **in the Terminal**, you run it, and then we ask you to copy and paste both the command itself and the response it returns. 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 +### Exercise 5 -Now press the plus button in the bottom right. This opens a new bash terminal. A bash terminal is a text-based interface where you type commands to tell your computer what to do. +Now press the plus button in the bottom right. This opens a new bash terminal. A bash terminal is a text-based interface where you type commands to tell your Codespace what to do. ```{r} include_graphics("images/cs-open-bash.png") @@ -225,11 +188,11 @@ include_graphics("images/cs-open-bash.png") ### -From the terminal, run `echo $0`. (To "run" a command in the Terminal or the Console means to type the command and then press `Enter`.) +From the terminal, run `echo $0`. (To "run" a command in the Terminal or the Console means to type the command and then press `enter`.) CP/CR. -```{r exercises-6} +```{r exercises-5} question_text(NULL, answer(NULL, correct = TRUE), allow_retry = TRUE, @@ -243,20 +206,20 @@ question_text(NULL, I get: ```` -@ptweeet ➜ /workspaces/my-repo (main) $ echo $0 +@ppbds-student ➜ /workspaces/codespace-starter $ echo $0 /bin/bash -@ptweeet ➜ /workspaces/my-repo (main) $ +@ppbds-student ➜ /workspaces/codespace-starter $ ```` This means that, in the Terminal, I am using the [Bash shell](https://en.wikipedia.org/wiki/Bash_(Unix_shell)), a Unix-like shell. -### Exercise 7 +### Exercise 6 -Let us make the Terminal "sleep" by typing the command `sleep 5` in the Terminal. Hit `Enter`. The `sleep 5` command pauses execution for 5 seconds. +Let us make the Terminal "sleep" by typing the command `sleep 5` in the Terminal. Hit `enter`. The `sleep 5` command pauses execution for 5 seconds. CP/CR. -```{r exercises-7} +```{r exercises-6} question_text(NULL, answer(NULL, correct = TRUE), allow_retry = TRUE, @@ -268,21 +231,21 @@ question_text(NULL, ### ``` -@ptweeet ➜ /workspaces/my-repo (main) $ sleep 5 -@ptweeet ➜ /workspaces/my-repo (main) $ +@ppbds-student ➜ /workspaces/codespace-starter $ sleep 5 +@ppbds-student ➜ /workspaces/codespace-starter $ ``` We can change the sleep duration using this format: `sleep [number]`. The number you enter is the number of seconds for which the Terminal pauses. -### Exercise 8 +### Exercise 7 -Run `sleep 60` in the Terminal. (Again, "run" means to type the command and then press the `Enter` key.) This command makes the Terminal sleep for 60 seconds. To cancel the running `sleep` command, press `Ctrl + C` on your keyboard. Do so now, before `sleep 60` finishes. +Run `sleep 60` in the Terminal. (Again, "run" means to type the command and then press the `enter` key.) This command makes the Terminal sleep for 60 seconds. To cancel the running `sleep` command, press `Ctrl + C` on your keyboard. Do so now, before `sleep 60` finishes. When you press `Ctrl + C` while `sleep` is running, it immediately terminates the `sleep` command and returns you to the command prompt. CP/CR. -```{r exercises-8} +```{r exercises-7} question_text(NULL, answer(NULL, correct = TRUE), allow_retry = TRUE, @@ -294,25 +257,24 @@ question_text(NULL, ### ```` -@ptweeet ➜ /workspaces/my-repo (main) $ sleep 60 +@ppbds-student ➜ /workspaces/codespace-starter $ sleep 60 ^C -@ptweeet ➜ /workspaces/my-repo (main) $ +@ppbds-student ➜ /workspaces/codespace-starter $ ```` `Ctrl + C` can stop any process running in the Terminal. -### Exercise 9 - - +### Exercise 8 -It is useful to understand where the R process is currently running on your computer. + +It is useful to understand where the R process is currently running in your Codespace. In the R terminal that is not running your tutorial, run `getwd()`. This stands for **get** **w**orking **d**irectory, meaning that we want to know the directory in which the R process is currently located. CP/CR. -```{r exercises-9} +```{r exercises-8} question_text(NULL, answer(NULL, correct = TRUE), allow_retry = TRUE, @@ -327,20 +289,20 @@ Your answer should look something like: ```` R 4.5.3> getwd() -[1] "/workspaces/my-repo" -R 4.5.3> +[1] "/workspaces/codespace-starter" +R 4.5.3> ```` -In an R terminal running inside GitHub Codespaces, `getwd()` prints the current working directory—here showing that R is operating inside your project folder at `/workspaces/my-repo`. +In an R terminal running inside GitHub Codespaces, `getwd()` prints the current working directory—here showing that R is operating inside your Codespace at `/workspaces/codespace-starter`. -### Exercise 10 +### Exercise 9 Tutorials can include written responses. You have already seen several examples. Sometimes those written answers are simply copies of R commands and their results. Other times, we will ask you to write one or more sentences of prose. Copy and paste everything from the exercise header above, beginning with "Exercise 10," through the end of this sentence into the answer box below. In other words, you are copying from this tutorial, not from the Console. Press "Submit Answer." -```{r exercises-10} +```{r exercises-9} question_text(NULL, message = "We will sometimes provide an answer to written questions, as we do here. Other times, 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, @@ -350,7 +312,7 @@ question_text(NULL, rows = 6) ``` -### Exercise 11 +### Exercise 10 `show_file()` is a 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 that you have edited. @@ -364,7 +326,7 @@ tutorial.helpers::show_file(file.path(R.home(), "COPYING"), end = 7) CP/CR. -```{r exercises-11} +```{r exercises-10} question_text(NULL, answer(NULL, correct = TRUE), allow_retry = TRUE, @@ -375,13 +337,13 @@ question_text(NULL, ### -```{r exercises-11-test, include = FALSE} +```{r exercises-10-test, include = FALSE} tutorial.helpers::show_file(file.path(R.home(), "COPYING"), end = 7) ``` 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 R prompt. Those details are less important than seeing the intended usage of `show_file()`. -### Exercise 12 +### Exercise 11 We frequently ask you to `copy` content from an HTML file such as a webpage. Do not worry if what you copy appears messy or loses its formatting; that is perfectly fine. Our main concern is that what you paste contains roughly the information it is supposed to contain. @@ -391,7 +353,7 @@ Go to [the homepage](https://ppbds.github.io/tutorial.helpers/) of the **tutoria CP/CR. -```{r exercises-12} +```{r exercises-11} question_text(NULL, answer(NULL, correct = TRUE), allow_retry = TRUE, @@ -414,7 +376,40 @@ About this package tutorial.helpers provides functions and RStudio Addins to help you write R tutorials, especially if you follow my advice about the best way to do so. This approach is currently used in several packages, including r4ds.tutorials and positron.tutorials. ```` -Again, your answer never needs to match ours exactly. +Again, your answer never needs to match ours exactly. + +### Exercise 12 + +Read all of the following instructions before continuing. The purpose of this exercise is to demonstrate that your tutorial answers are saved automatically. + + + + + +* Return to your Codespace and click the tab titled "R Tutorial" in the Panel. + +```{r} +include_graphics("images/r-tutorial-terminal.png") +``` + +* Stop the tutorial by pressing `Ctrl + C` in the terminal. This is useful because it can interrupt any terminal process. A new line should appear where you can enter another command. + + + +* To restart the tutorial, either press the play button next to the "getting-started" tutorial. + + + +* This command tells the terminal to run `Rscript`, which calls the `run_tutorial()` function from the `learnr` package. + +* Finally, open the tutorial. + + +Now that you have read all the instructions, go ahead and follow them. + +### + +Notice that all of your answers to previous questions have been saved. It is not a problem to quit a tutorial. In fact, if you leave a tutorial idle, it will eventually quit automatically. ## Your answers ### @@ -427,7 +422,7 @@ After clicking the "Download" button, you will be prompted to save a file named Unless your instructor tells you otherwise, you should use the default file name, which will usually be of the form `short-name-of-tutorial` + `_answers` + `.html`. -```{r download-answers, child = system.file("child_documents/download_answers.Rmd", package = "tutorial.helpers")} +```{r your-answers-0, child = system.file("child_documents/download_answers.Rmd", package = "tutorial.helpers")} ``` ## Summary diff --git a/vignettes/ai.qmd b/vignettes/ai.qmd index b1b3e4c..5f080a8 100644 --- a/vignettes/ai.qmd +++ b/vignettes/ai.qmd @@ -36,10 +36,14 @@ Anything typed at the keyboard belongs in \`backticks\` (not "quotation marks"), Note that tutorials must be [R Markdown](https://rmarkdown.rstudio.com/) documents, meaning that their suffix is `.Rmd`. You can not (yet) use Quarto documents with tutorials. Fortunately, most of what you need which works in Quarto also works in R Markdown. The main difference is that code chunk options appear within the `{}`. Don't worry about this detail. + + AI tutorials begin with an *Introduction* which provides a summary of the key packages/functions which the tutorial will cover. The Introduction continues with a series of exercises which set up the repo/project/QMD in which most of the tutorial will be completed. After the Introduction, there are 1 or 2 sections --- the official **learnr** nomenclature is *Topics* --- which are the meat of the tutorial. + + The last section is the *Summary*. It starts with the same overview with which the Introduction began, but in the past tense. It then has a couple exercises which finish up the tutorial by using `quarto publish gh-pages analysis.qmd` to create a webpage featuring the cool plots which the student has created. The URL for this new webpage is usually the answer to the last exercise in Summary, thereby completing the tutorial. Anytime you ask a student to execute something in the Console, you confirm that they have done so with CP/CR, the abbreviation for **C**opy/**P**aste the **C**ommand/**R**esponse. @@ -48,6 +52,8 @@ Anytime you ask a student to execute something in the Console, you confirm that Students always need more practice working in a Quarto document (the QMD) and the Console at the same time. Good data scientists go back and forth between these two modes, writing something in the QMD, executing it in the Console, editing the QMD, executing again, and so on. We need to force students to do that more often. + + Tutorials are divided into *Topics* that appear on the side panel. To create these topics, we include a double hash (##) before the text for it to show up as a side panel. This is also called the *topic title*. Use [sentence case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case). On the line after the topic title, put three hashes. This ensures that students will see the introductory text before they see the first exercise. ### Questions @@ -107,6 +113,8 @@ question_text(NULL, The question will almost always instruct the student to "CP/CR," often after running `show_fle(chunk = "Last")`. Adjust the value of `rows` to match the expected length of the pasted output. If the question asks student to run some R code, we will generally include a reasonable answer in the `test` chunk. This serves two purposes. First, because `echo = TRUE`, we show the student that code (and its output) in the tutorial. This code should be excellent. We want students to learn from our example. Second, the code will be run when we test the tutorial, so we can be sure that this code (and, we hope, code like it) will work for the student. + + ### Knowledge drops The most difficult part of tutorial creation is writing the "knowledge drops," the snippets of wisdom (and the associated links) which are used at the end of each exercise. These generally come in two categories: details about R functions/packages/websites and background information about the substantive data science problem at hand. @@ -144,6 +152,8 @@ The first two commands download data and save it to an RDS file in the `data` di This code assumes that you are located in the same directory as the `tutorial.Rmd` file. You only run those commands once, and then you comment them out because you don't want them re-run each time the tutorial is created. The `read_rds()` call is never commented out because we always need the `median_age` object. + + When designing tutorials which use objects like `median_age`, we generally write two exercise code chunks. The first has the student run the same code as that which we used to create the object ourselves. This won't work if the student is not connected to the web but, with luck, in that case they will get a sensible error message. The second question informs the students that we have, behind the scenes, assigned the result of the function to an R object. We then ask the student to just print out that object. We don't have them do the assignment themselves, not least because we don't like questions which don't generate any output. We use a similar approach with models which can take awhile to fit. Example: @@ -161,6 +171,9 @@ fit_gauss <- read_rds("data/fit_gauss.rds") Again, this code only works if you are in the tutorial directory, not in the higher directory of the R project itself. Also, the first two commands are commented out, unless you are running them by hand to create the object. + + + What happens if the data is too large? See the "Arrow" tutorial in the [**r4ds.tutorials**](https://ppbds.github.io/r4ds.tutorials/) for an example. First, we generally switch away from code exercises and use written exercises. Students run the required commands and then copy/paste the command/response. Big downloads don't work well in exercise code chunks. Second, we create small versions of this big data in the global `setup` chunk. This allows us to create test code chunks for most of the exercises which follow. These tests will run much more quickly with this smaller data. Also, for any package on CRAN, we need to keep the overall size of the package as small as possible. There are two main uses for files in `data`. First, they can be used at "compile time" (when the `tutorial.Rmd` is knit to HTML) for making plots or doing anything else. Second, and more importantly, they are available to students in the exercise code blocks during "run time" (when students are doing the tutorial). @@ -183,6 +196,8 @@ Because students will complete the tutorials using screens of very different wid #### Complex text + + You sometimes want to include "complex" text in a tutorial. This is most common when trying to teach students how to use R code chunks and other strings which R markdown wants to process in certain ways. You can sometimes get away by placing such text in environments surrounded by three, or even four, backticks. The plain three or four backtick environments create a plain code block and content inside is displayed as-is. No syntax highlighting or execution is applied, and they show example code or text exactly as typed. Four backtick environments allow three backticks to be written within the block. This works often, but not always. Comment characters like `#` are especially problematic. We also use the [**parsermd**](https://rundel.github.io/parsermd/) package behind the scenes. It does not work as well as one might like. Further complexity arises because tutorials are R markdown whereas all our other work is in Quarto. In Quarto documents (like this vignette), you can use an environment started by four backticks along with `{verbatim}` and then ended with four more backticks. This won't work in R markdown. @@ -268,12 +283,14 @@ You are, obviously, responsible for adding a knowledge drop which teaches the st The second question in the Introduction is usually: + + ````{verbatim} ### Exercise 2 In your QMD, put `library(tidyverse)` in a new code chunk. Render the file using `Cmd/Ctrl + Shift + K`. -Notice that the file does not look good because the code is visible and there are annoying messages. To take care of this, add `#| message: false` to remove all the messages in this `setup` chunk. Also, add the following to the YAML header to remove all code echoes from the HTML: +Notice that the file does not look good because the code is visible and there are annoying messages. To take care of this, add `#| echo: false` to remove all the messages in this `setup` chunk. Also, add the following to the YAML header to remove all code echoes from the HTML: ``` execute: @@ -333,6 +350,8 @@ If the target audience for the tutorial is more experienced, you can be less did I recommend offering these explicit instructions in every tutorial. First, students need lots of practice. Second, each time you tell them to add something to the QMD, you give yourself an opportunity for a knowledge drop. The same applies when you tell students to execute, in the Console, a new addition to the QMD. + + ````{verbatim} ### Exercise 4 @@ -370,13 +389,14 @@ You answer should look something like this, although your path will be different > ``` - + ```` ## Tutorial Topics -You will probably have one or two Topics, in between the Introduction and Summary. Any tutorial which both uses a lot of AI and is supposed to take an hour or so will only have, at most, two Topics. + +You will probably have one or two Topics, in between the Introduction and Summary. Any tutorial which both uses a lot of AI and is supposed to take an hour or so will only have, at most, two Topics. ````{verbatim} ## XX: First topic (use sentence case) @@ -387,6 +407,8 @@ You will probably have one or two Topics, in between the Introduction and Summar If you are downloading some data, the natural place to do so is in the first exercise of a Section. + + ````{verbatim} ### Exercise 1 @@ -419,14 +441,14 @@ question_text(NULL, ```` - The meat of a Topic generally involves asking AI to create a pipe which accomplishes some goal. The end of a Topic always finishes up with a plot. The last four questions set up and then guide the student to creating that plot. If you want the student to mimic a plot, you can place it in the `images` subdirectory and then use `knitr::include_graphics("images/plot.png")` to show it to students. - To teach students about topic X, we first need to decide the final destination. What do we want students to be able to do on their own after completing the tutorial? For us, this will almost always be a plot. Having envisioned this goal, we need to create a "path" which students can use to reach that goal, first under our supervision and, second, on their own. The path will consist of several stepping stones, or stops along the way. + + To ensure that students are on the right path with their code, we need to provide them with our code that is verified to be correct. Although we should not tell students to replace their code with ours at every step, if a student is lost, they should be able to refer to our code to get back on track. We also want to include our code in test chunks, both to show students and to confirm that it works. Consider this example: @@ -476,14 +498,14 @@ In that case, the answer chunk would look like: ``` ```` - - ## Plotting Questions Plotting exercises are generally handled with a sequence of four questions. Prior to these, the tutorial will probably have the student practice gathering, organizing, and cleaning the data. The first of the three prior questions tells the student to replace the current pipe which they have in the QMD with our code. We check that they have done so with `show_file()`. The purpose of this question is to ensure that the student's data will match our data. + + ````{verbatim} ### Exercise 3 @@ -720,7 +742,7 @@ Once you are done editing a tutorial, you need to make sure it works, either on 1. Type `rmarkdown::render("file_path/tutorial.Rmd")` in the Console. This produces `tutorial.html` in the tutorial directory. Right click the file and select `Open in Browser`. It is smart to use `rmarkdown::render("file_path")` regularly since it will identify syntax errors quickly. -2. Do a full test, which means running `devtools::check()`, the shortcut key for which is `Cmd/Ctrl + Shoft + E`. This is the equivalent of `R CMD check`. It validates package structure, documentation, tests, and compliance with CRAN standards. A good result would be `0 errors ✔ | 0 warnings ✔ | 0 notes ✔`, but don't worry too much about NOTES. +2. Do a full test, which means running `devtools::check()`, the shortcut key for which is `Cmd/Ctrl + Shift + E`. This is the equivalent of `R CMD check`. It validates package structure, documentation, tests, and compliance with CRAN standards. A good result would be `0 errors ✔ | 0 warnings ✔ | 0 notes ✔`, but don't worry too much about NOTES. 3. Test your tutorial from a student's perspective after completing package checks by following this local testing workflow. You can do this without the hassle of needing to push changes to the main repository and re-download the package. Install your local package using `devtools::install()` and when prompted about updating packages, choose to update everything to ensure all dependencies are current. Once installation is complete, run your tutorial with `learnr::run_tutorial("tutorial_name", "package_name")`, replacing the placeholder names with your actual tutorial and package names. This allows you to test the tutorial in a clean environment similar to what students will experience, checking that all code chunks run without errors, instructions are clear, and there's no dependence on objects from your development environment.