---
title: "XX: Title"
author: "XX: Your Name"
tutorial:
  id: "XX: all lowercase id is the directory in which this tutorial is located"
output: 
  learnr::tutorial:
    df_print: default
    progressive: true
    allow_skip: true
runtime: shiny_prerendered
description: "XX ADD DESCRIPTION (a single sentence)"
---

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

# XX: Add other packages you use. Such packages should also be added
# to the student QMD. 

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

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

<!-- XX: CHECKLIST BEFORE STARTING: -->
<!-- * If you need to use the copy code button, you must load the relevant child document. -->
<!-- * Use check_current_tutorial() and make_exercise("no-answer"). Very helpful! -->
<!-- * Edit yaml at the top of this file -->
<!-- * Save the file as "tutorial.Rmd" in the correct directory under inst/tutorials/xx/, where xx is the same as the tutorial id. -->
<!-- * Load any necessary libraries for the tutorial in the first code chunk -->
<!-- * Anytime you have a student `Cmd/Ctrl + Enter`, you ask for CP/CR and then provide your code as the test code chunk -->
<!-- * Delete this and the other commented instructions below. -->
<!-- Search for, read/replace, and then delete all `XX:` entries -->

## Introduction
###

<!-- XX: Two to four sentence about the main packages/functions covered in this tutorial. -->

### Exercise 1

Create a Github repo called `XX`. Set the "Add a README file" toggle box to "On."

Connect the repo to a project on your computer using `File -> New Folder from Git ...`.  Make sure to select the "Open in a new window" box. 

You need two Positon windows: this one for running the tutorial and the one you just created for writing your code and interacting with the Console.

In the new window, select `File -> New File -> Quarto Document ...`. Provide a title -- `"XX"` -- and an author (you). Save the file as `analysis.qmd`. Render the document. 

Create a `.gitignore` file with `analysis_files` on the first line and then a blank line. Save and push.

In the Console, run:

```         
show_file(".gitignore")
```

If that fails, it is probably because you have not yet loaded `library(tutorial.helpers)` in the Console.

CP/CR.

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

### 

<!-- XX: Insert a knowledge drop related to this project. -->

<!-- XX: By default, the next two questions just mention tidyverse. If there is more than one required library, you can just add those libraries to these steps, adjusting the grammar as needed. Or, you might have separate questions for each library, thereby providing more room for knowledge drops. -->

### 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:

```         
execute: 
  echo: false
```

Using `Cmd/Ctrl + Shift + K`, render the file again. Only the title and author should appear in the HTML.

In the Console, run:

```         
show_file("analysis.qmd", chunk = "Last")
```

CP/CR.

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

### 

<!-- XX: Insert a knowledge drop related to this project. -->

### Exercise 3

Place your cursor in the QMD file on the `library(tidyverse)` line. Use `Cmd/Ctrl + Enter` to execute that line.

Note how this command causes `library(tidyverse)` to be copied down to the Console and then executed. 

CP/CR.

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

###

<!-- XX: Insert a knowledge drop related to this project. -->

### Exercise 4

<!-- XX: Delete this question if you do not make use of a `data` directory in this tutorial. Note the extra spaces after the command. These are needed to ensure separate lines for each command when students copy/paste. -->

From the Console, run these three commands:

`getwd()`  
`dir.create("data")`  
`list.files()`  

This will create a `data` directory in your project. This is a good place to store any data that you are working with.

CP/CR.

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

###

You answer should look something like this, although your path will be different.

````
> getwd()
[1] "/Users/dkane/Desktop/projects/xx"
> dir.create("data")
> list.files()
 [1] "analysis_files" "analysis.html"  "analysis.qmd"   "data"           "README.md"  
>
````

<!-- XX: You will probably have one or two Sections, in between the Introduction and Summary. We provide on example below. Before editing it, you may want to copy/paste it to create the skeleton for a second section. Any tutorial which both uses a lot of AI and is supposed to take an hour or so will probably only have two sections.  -->

## XX: First section (use sentence case)
###

<!-- XX: Mention the packages/functions which you plan on covering in this Section. Not everything mentioned here is used in the Introduction/Summary, but everything in Introduction/Summary is referenced in one of these Section intro parts, the space before Exercise 1 in each section. -->

### Exercise 1

<!-- XX: In this question, "XX" is the full name of the file, like "cars.xls". -->

We begin by downloading XX directly from GitHub to the `data` directory using `download.file()`. 

In the Console, run:

```         
download.file(
  "https://github.com/PPBDS/ai.tutorials/raw/refs/heads/main/inst/tutorials/r4ds-2/data/cheeses.xlsx",
  destfile = "data/XX"
)
```

CP/CR.

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


### Exercise 2

<!-- XX: The meat of a Section generally involves asking AI to create a pipe which accomplishes some goal. The end of a Section always finishes up with a plot. These 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. -->

### Exercise 3

Before creating a plot, we need to ensure that your data matches our data. In the QMD, replace your code from the previous exercise with our code.

In the Console, run:

```         
show_file("analysis.qmd", chunk = "Last")
```

CP/CR.

```{r xx-first-section-use-sentence-case-3}
question_text(NULL,
	answer(NULL, correct = TRUE),
	allow_retry = TRUE,
	try_again_button = "Edit Answer",
	incorrect = NULL,
	rows = 6)
```

###

<!-- XX: Insert a knowledge drop related to this project. -->

### Exercise 4

Within the latest code chunk, add the option: `#| cache: true`. Assign the result of the pipe to `x`. 

`Cmd/Ctrl + Shift + K`. By including `#| cache: true` you cause Quarto to cache the results of the chunk. The next time you render your QMD, as long as you have not changed the code, Quarto will just load up the saved object.

If you have not done so already, you should add `analysis_cache` to the `.gitginore`. The content of the cache file does not belong on GitHub.

Place your cursor on the line where the pipe is assigned to `x`, run `Cmd/Ctrl + Enter`, thus ensuring that the workspace also includes a copy of `x`.

CP/CR.

```{r xx-first-section-use-sentence-case-4}
question_text(NULL,
    answer(NULL, correct = TRUE),
    allow_retry = TRUE,
    try_again_button = "Edit Answer",
    incorrect = NULL,
    rows = 8)
```

###

Our code:

```{r, echo = TRUE}
# x <- ... where the ellipsis are replaced with the code which creates x.
```

###

<!-- XX: Insert a knowledge drop related to this project. -->

### Exercise 5

Within the Console, type `x`, which we previously assigned to a pipe and ran in the Console. Hit `Enter`.

CP/CR.

```{r xx-first-section-use-sentence-case-5}
question_text(NULL,
    answer(NULL, correct = TRUE),
    allow_retry = TRUE,
    try_again_button = "Edit Answer",
    incorrect = NULL,
    rows = 8)
```

###


Our code:

```{r, echo=TRUE}
# x
```

###

<!-- XX: Insert a knowledge drop related to this project. -->

### Exercise 6

Ask AI to generate R code that uses `x` to plot a basic graph showing XX ... Mention you want to use the data from `x` and copy/paste the `x` you ran in the Console with the resulting tibble. You only need the top 3 lines, mainly to include column names.

Within `labs()`, edit or add a proper title, subtitle, and caption. If axis labels would be useful, add them, but if unnecessary, don't bother. Don't assign the code for the plot to any variable. Put the plot code in a new code chunk. Run `Cmd/Ctrl + Shift + K` to ensure that everything works. Make your plot look nice.

In the Console, run:

```         
show_file("analysis.qmd", chunk = "Last")
```

CP/CR.

```{r xx-first-section-use-sentence-case-6}
question_text(NULL,
	answer(NULL, correct = TRUE),
	allow_retry = TRUE,
	try_again_button = "Edit Answer",
	incorrect = NULL,
	rows = 12)
```

###

Our code:

```{r, echo=TRUE}
# XX: Make sure your plotting code is good! This will take some time. You had better have a subtitle which provides the take-away message of the plot. AI sometimes gives you too much code, lots of `theme()` stuff and so on. This is no good! In most cases, we are happy with concise, straightforward code. 
```

###

<!-- XX: Insert a knowledge drop related to this project. -->

## Summary
###

<!-- XX: The exact same two to four sentences about the main packages/functions used in the Introduction, but written here in the past tense. You made a promise and you kept it.  -->

### Exercise 1

`Cmd/Ctrl + Shift + K` to ensure that everything works.  The resulting HTML page should be attractive, showing clean versions of your plot(s).

At the Console, run:

```
tutorial.helpers::show_file("analysis.qmd")
```

CP/CR.

```{r summary-1}
question_text(NULL,
	answer(NULL, correct = TRUE),
	allow_retry = TRUE,
	try_again_button = "Edit Answer",
	incorrect = NULL,
	rows = 30)
```

### 

<!-- XX: Insert a knowledge drop related to this project. -->

### Exercise 2

Publish your rendered QMD to GitHub Pages. In the Terminal --- not the Console! --- run:

````
quarto publish gh-pages analysis.qmd
````

Copy/paste the resulting URL below.

```{r summary-2}
question_text(NULL,
	answer(NULL, correct = TRUE),
	allow_retry = TRUE,
	try_again_button = "Edit Answer",
	incorrect = NULL,
	rows = 1)
```

### 

<!-- XX: Insert a knowledge drop related to this project. -->

### Exercise 3

Commit and push all your files. Copy/paste the URL to your Github repo.

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

### 

<!-- XX: The tutorial is now over. Add any necessary acknowledgements and/or provide a link to further high quality readings, ideally readings which you mentioned in at least one knowledge drop above. -->

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