differences for PR #95

carpentries-incubator · Dec 31, 2024 · 40b1afe · 40b1afe
1 parent a382d8c
commit 40b1afe
Show file tree

Hide file tree

Showing 13 changed files with 1,225 additions and 1,494 deletions.
diff --git a/.DS_Store b/.DS_Store
diff --git a/1-intro-reproducible-examples.md b/1-intro-reproducible-examples.md
@@ -1,13 +1,15 @@
 ---
 title: "What is a reprex and why is it useful?"
 teaching: 15
-exercises: 10
+exercises: 2
 ---
 
 :::::::::::::::::::::::::::::::::::::: questions 
+
 - How is the process of getting help in R different from getting help with other things?
 - Why is a minimal reproducible example an important tool for getting help in R?
 - What will we be learning in the rest of the course?
+
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
 ::::::::::::::::::::::::::::::::::::: objectives
@@ -19,78 +21,84 @@ exercises: 10
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
 #### Welcome and introductions
-- Welcome to "RRRR, I'm Stuck!" We're glad you're here! Let's first take care of a few setup steps. You should have all followed the setup instructions on the [workshop website](kaijagahm.github.io/R-help-reprexes/), and you should have both R and RStudio installed.
+- Welcome to "RRRR, I'm Stuck!" We're glad you're here! Let's first take care of a few setup steps. You should have all followed the setup instructions on the [workshop website](https://carpentries-incubator.github.io/R-help-reprexes/), and you should have both R and RStudio installed.
 
 - You should also have the following packages installed: {**reprex**}, {**ratdat**}, {**dplyr**}, and {**ggplot2**}.
 
-- We have a range of levels of experience here. This workshop assumes that you are researcher in ecology or biology who has some prior experience working with R in RStudio.
+- We have a range of levels of experience here. This workshop assumes that you are researcher in ecology/biology who has some prior experience working with R in RStudio.
 
-- The examples in this lesson follow an example data wrangling, visualization, and analysis workflow similar to one that might be used by an ecology researcher. We will not spend much time discussing the code itself. [Reference guide?]
+- We won't be spending a lot of time going over [concepts]. Here's a handy reference guide to lessen some of the cognitive load... [to be continued.]
 
-- It's okay if you're not an R expert--but even more experienced R coders might be less familiar with how to get unstuck, so we hope this workshop will be useful to many levels of coding background.
+- You don't have to be an expert. But we also know that even more experienced R coders might be less familiar with how to get unstuck, so we hope this workshop will be useful to you too.
 
 :::::::::::::::::::::::::::::::::::::: challenge 
-## Think, pair, share: When you get stuck
+
+## Think, pair, share
 
 When you're coding in R and you get stuck, what are some things that you do to get help or get unstuck?
+
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
 
 :::::::::::::::::::::::::::::::::::::: challenge 
-## Think, pair, share: Helping someone else
+
+## Think, pair, share
 
 Think about a time that you helped someone else with their code. What information did you need to know in order to help?
-(If you have never helped someone else with their code, think about a time that someone helped you--what information did they need to know in order to help?)
-::::::::::::::::::::::::::::::::::::::::::::::::
+(If you have never helped someone else with their code, think about a time that someone helped you--what information did they  need to know in order to help?)
 
-Fixing problems can be one of the most challenging parts of learning to code. Luckily, there are many people in the R and data science communities that will be able to help when you get stuck. However, learners and potential helpers alike often run into trouble when they try to communicate about broken code. Helping someone to fix their code can feel impossible when they don't give you enough information to replicate the problem. But as a novice, figuring out how to ask a good question can feel even harder than the original problem that got you stuck in the first place!
+::::::::::::::::::::::::::::::::::::::::::::::::
 
-When you get stuck, often the first step is to try some strategies on your own to fix your code. This might include reading help resources, investigating error messages, and methodically walking through each line of your code to figure out what might have gone wrong. But it's also very common to ask for help from someone else, such as a colleague or strangers online.
 
-Asking for help with your code is a little different than asking for help with many other things. That's because it is usually not enough to describe the problem in general or theoretical terms. Most help forums (StackOverflow, the Posit Community, and the R for Data Science Slack workspace are common places to ask for help with R code!) require users to post a description of their problem along with a minimal reproducible example, or "**reprex**", of their code to make it easier for helpers to figure out what the problem is.
+:::::::::::::::::::::::::::::::::::::: callout
 
-::: callout
-A **minimal reproducible example** (MRE) is also sometimes called a **minimal working example** (MWE), or a **reprex** (which is short for "reproducible example"). We will mostly use the term **reprex** in this lesson.
+## Minimal Reproducible Example (aka "reprex")
 
-The term **reprex** was coined by Romain François in a 2014 tweet:
-![The origin of the term "reprex", as a word smash of "reproducible" and "example".](fig/romainfrancois.png)
-:::
+```
+"Your code examples should be...
+Minimal: Use as little code as possible that still produces the same problem
+Complete: Provide all parts someone else needs to reproduce your problem in the question itself
+Reproducible: Test the code you're about to provide to make sure it reproduces the problem" - [StackOverflow](https://stackoverflow.com/help/minimal-reproducible-example)
+```
 
-As the name suggests, a reprex should be:
+```
+"The goal of a reprex is to package your problematic code in such a way that other people can run it and feel your pain. Then, hopefully, they can provide a solution and put you out of your misery." - [Get help! (Tidyverse)](https://www.tidyverse.org/help/)
+```
 
-1. Minimal. It's important to strip the code and data down to their simplest parts and remove anything that is not directly relevant to the problem. This makes it easy for a helper to zero in on what might be going wrong. It also makes the helping process simpler for the helper, making them more likely to take the time to work on your problem. 
+```
+"The habit of making little, rigorous, self-contained examples also has the great side effect of making you think more clearly about your programming problems." - [Jenny Bryan](https://posit.co/resources/videos/help-me-help-you-creating-reproducible-examples/)
+```
 
-2. Reproducible. The reprex should recreate the problem you're encountering, and it needs to be runnable by someone other than you, on a different computer.
+::::::::::::::::::::::::::::::::::::::::::::::::
 
-Why is reproducibility important? In many disciplines, experts can give helpful abstract advice about problems. Coding is very hands-on. Even experts usually have to "tinker" with a problem before they can determine what is happening. Without the ability to "tinker", debugging is both difficult and frustrating, which means that you are less likely to get help.
+These steps might seem simple, but they can be challenging to put into practice. In this lesson, we will be guiding you through the process of creating a minimal reproducible example. By the end, you will have a workflow to follow next time you get stuck.
 
-The Tidyverse documentation puts it simply:
+## Overview of this lesson
 
->"The goal of a reprex is to package your problematic code in such a way that other people can run it and feel your pain. Then, hopefully, they can provide a solution and put you out of your misery." - [Get help! (Tidyverse)](https://www.tidyverse.org/help/)
+[Visual: screenshot or diagram of someone else's educational resource where they explain what a minimal reproducible example is (with appropriate credit given of course)] --> use this to motivate how we're going to be going through each step of that in this lesson.
 
-::: callout
-## The wrong ways to ask questions
-- Screenshots
-- Descriptions of the data
-- "It doesn't work"
-XXX expand on this--not sure about the best way/time to introduce these "don't"s. Maybe not at all?
-:::
+[Visual: diagram of the general process, with questions along the way]--to draw ourselves
+### Understand your code
+### Apply "first aid" debugging strategies
+### Create minimal reproducible data
+### Simplify your code and make it minimal
+### Prepare to share your reproducible example with others.
 
-As an added bonus, the process of simplifying your problem and creating a reprex often leads to a better understanding of your own code!
+----
 
-![A tweet from Dr. Sam Tyner-Monroe, describing her experience solving her own problem through the process of making a reprex (December 12, 2019)](fig/samtynermonroe.png)
+**Motivating examples**
 
-In fact, the phenomenon of solving one's own problem during the process of trying to explain it clearly to someone else is well known--it's often called "[rubber duck debugging](https://en.wikipedia.org/wiki/Rubber_duck_debugging)". Jenny Bryan, who created a great video about reprexes called "[Help me help you](https://www.youtube.com/watch?v=5gqksthQ0cM&ab_channel=PositPBC)", called reprexes "basically the rubber duck in disguise".
+[Screenshots of real requests for help]
 
-![A tweet from Jenny Bryan comparing reprexes to rubber duck debugging (January 4, 2018)](fig/jennybryan.png)
+----  
 
-Making a reprex might seem simple in theory, but it can be challenging to put into practice. In this lesson, we will walk through the process of creating a minimal reproducible example. We'll talk about each of the steps and provide a workflow that you can follow when you get stuck in the future. At the end, we'll introduce you to the `{reprex}` package, a useful tool for creating good minimal reproducible examples.
 
-## Overview of this lesson
-[XXX visual for the roadmap? or just an outline?]
 
 ::::::::::::::::::::::::::::::::::::: keypoints 
-- A helper usually needs to run your code in order to debug it.
+
+- Mentors and helpers usually need to run your code in order to help debug it.
 - Minimal reproducible examples make it possible for helpers to run your code, which lets them "feel your pain" and figure out what's wrong.
 - Making a minimal reproducible example helps you understand your own problem and often leads to finding the answer yourself!
+- You can use the {reprex} package to test whether your example is reproducible.
+
 ::::::::::::::::::::::::::::::::::::::::::::::::
diff --git a/3-minimal-reproducible-data.md b/3-minimal-reproducible-data.md
@@ -1,7 +1,7 @@
 ---
 title: "Minimal Reproducible Data"
 teaching: 90
-excercises: 6
+exercises: 6
 ---
 
 
@@ -236,7 +236,7 @@ x
 ```
 
 ``` output
- [1] 10  1  5  9  2  7  8  4  6  3
+ [1]  2  5  8  6  7  1  9  3 10  4
 ```
 
 Or you can randomly sample from a normal distribution
@@ -248,8 +248,8 @@ x
 ```
 
 ``` output
- [1] -0.98657300  1.10974854  0.93699581  1.24690724 -1.87082909  1.48664080
- [7] -0.01691745 -0.02549324  0.05642538 -0.95861351
+ [1] -0.19140721 -1.13573927 -0.14130314  0.54420418 -0.85776993  0.31818212
+ [7] -0.09901090 -0.94706326 -0.01191743 -0.40541024
 ```
 
 You can also use `letters` to create factors.
@@ -261,8 +261,8 @@ x
 ```
 
 ``` output
- [1] "c" "c" "d" "c" "c" "c" "c" "c" "d" "c" "b" "d" "a" "d" "b" "a" "c" "c" "b"
-[20] "d"
+ [1] "c" "a" "c" "a" "d" "a" "d" "d" "a" "a" "b" "c" "c" "a" "a" "b" "c" "d" "a"
+[20] "c"
 ```
 
 Remember that a data frame is just a collection of vectors. You can create a data frame using `data.frame` (or `tibble` in the `dplyr` package). You can then create a vector for each variable. 
@@ -275,13 +275,13 @@ head(data)
 ```
 
 ``` output
-  x          y
-1 b -0.2619031
-2 a -0.5924968
-3 a  1.0555866
-4 b -1.2199813
-5 b -1.0856028
-6 c -0.7476225
+  x           y
+1 a  0.10293245
+2 a  0.68861179
+3 a -0.57474735
+4 b -0.46788973
+5 a  0.03972907
+6 a  0.19568872
 ```
 
 **However**, when sampling at random you must remember to `set.seed()` before sending it to someone to make sure you both get the same numbers!
@@ -388,26 +388,26 @@ sample_data
 
 ``` output
    Day Plot Species
-1    1   P1       C
-2    2   P2       D
+1    1   P1       D
+2    2   P1       B
 3    3   P1       A
-4    4   P1       C
-5    5   P1       D
-6    6   P2       B
-7    7   P1       A
-8    8   P2       D
-9    9   P1       C
+4    4   P2       A
+5    5   P1       B
+6    6   P1       C
+7    7   P2       D
+8    8   P1       A
+9    9   P1       D
 10  10   P2       A
-11   1   P1       C
-12   2   P2       A
+11   1   P1       B
+12   2   P2       D
 13   3   P1       D
-14   4   P2       A
-15   5   P2       B
+14   4   P1       A
+15   5   P2       D
 16   6   P1       A
-17   7   P2       D
-18   8   P2       C
-19   9   P1       B
-20  10   P1       C
+17   7   P2       A
+18   8   P1       A
+19   9   P2       A
+20  10   P2       A
 ```
 
 Great!