diff --git a/05-foundational-skills_1.Rmd b/05-foundational-skills_1.Rmd index f55171d1..96519c3b 100644 --- a/05-foundational-skills_1.Rmd +++ b/05-foundational-skills_1.Rmd @@ -2,21 +2,21 @@ **Abstract** -This chapter is designed to provide readers with clear, concise instructions on installing all the software necessary to complete any of the subsequent walkthrough chapters. Readers who are familiar with R and RStudio, as well as how to install and load packages in R, may find this to be a helpful review or may prefer to skip the chapter entirely. This chapter also covers the basics of writing and running code in RStudio, and closes with an introduction to using the {swirl} package. It is designed to help you get started using R and RStudio, assuming no prior use of either. +This chapter provides readers with instructions on installing the software necessary to complete any of the subsequent walkthrough chapters. Readers who are familiar with R and RStudio, including installing and loading packages in R, may find this to be a helpful review or may prefer to skip the chapter entirely. This chapter also covers the basics of writing and running code in RStudio. It closes with an introduction to using the {swirl} package. It is designed to help you get started using R and RStudio, assuming no prior use of either. -This chapter, the following chapter (on [Foundational Skills](#c06)), and each of the walkthrough chapters include a broad overview of the topics emphasized and the functions introduced in the chapter. +This chapter, the following chapter (on [Foundational Skills](#c06)), and each of the walkthrough chapters include an overview of the topics emphasized and the functions introduced in the chapter. ## Topics emphasized -For all of the topics emphasized sections (like this one), we indicate topics that are unique to each chapter. Especially for the walkthrough chapters, however, there is a great deal of overlap between chapters in what is emphasized, because, for example, visualizing data is regularly used as a part of carrying out a data science project in education. Therefore, consider these topics emphasized to be the *particular* focus of the chapters they reference. +For all of the topics emphasized sections, we indicate topics that are unique to each chapter. However, there is a great deal of overlap between chapters. For example, visualizing data is regularly used as a part of carrying out a data science project in education. Therefore, consider these topics emphasized to be the particular focus of the chapters they reference. - Installing R, RStudio, and R packages ## Functions introduced -For the "functions introduced" sections, you will notice that some look a little bit different than others. For example, `pak::pak()` is different than `install.packages()`. +For the "functions introduced" sections, notice that some functions look different than others. For example, `pak::pak()` is different than `install.packages()`. -The reason is that the `pak()` function comes from a specific *package* (which we'll discuss in great depth in this and the following chapter). If you had a hunch that this function comes from the `pak` package, then you'd be correct. The `::` symbols (described more in [Chapter 6](#c06)) mean that a specific function comes from a particular package, something that we wanted to point out so that you will know which package you will need to use if you want to use the function. Not sure what some of these terms mean quite yet? Read on in this chapter to learn more about installing and using packages! +The `pak()` function comes from a specific *package* (which we'll discuss in great depth in this and the following chapter). If you had a hunch that this function comes from the `pak` package, you'd be correct. The `::` symbols (described more in [Chapter 6](#c06)) mean that the function comes from a particular package. That way, you'll know which package you will need if you want to use the function. Not sure what some of these terms mean quite yet? Read on in this chapter to learn more about installing and using packages. - `install.packages()` - `pak::pak()` @@ -39,15 +39,14 @@ We will be covering the following topics in this chapter: - Installing the {dataedu} package - Exploring R with the {swirl} package -If you already have experience using R and RStudio, you may find some of the contents of this chapter to be a refresher---or as a chance to learn a few new things about setting up and using them. If you are looking to get started with the very basics of data loading and manipulation using the {tidyverse} [@wickham2019] right now, consider reading this chapter quickly and then starting [Chapter 6](#c06), which covers foundational skills. +If you already have experience using R and RStudio, you may find some of the contents of this chapter to be a refresher---or as a chance to learn a new things about getting set up. If you are looking to get started with the basics of data loading and manipulation using the {tidyverse} [@wickham2019] right now, consider reading this chapter and then starting [Chapter 6](#c06), which covers foundational skills. ## Downloading R and RStudio -First, you will need to download the latest versions of R [@rcoreteam] and RStudio [@rstudio]. -R is a free environment for statistical computing and graphics using the programming language R. +First, you will need to download the latest versions of R [@rcoreteam] and RStudio [@rstudio]. R is a free environment for statistical computing and graphics using the programming language R. RStudio is a set of integrated tools created by [Posit](https://posit.co/) that allow for a more user-friendly experience for using R. -Although you will likely use RStudio as your main console and editor, _you must first install R_ as RStudio uses R behind the scenes. Both R and RStudio are freely available, cross-platform, and open-source. +Although you will likely use RStudio as your main console and editor, you must first install R as RStudio uses R behind the scenes. Both R and RStudio are freely available, cross-platform, and open-source. ### To download R: @@ -56,7 +55,7 @@ Although you will likely use RStudio as your main console and editor, _you must - Select the "latest release" on the page for your operating system - Download and install the application -Don't worry; you will not mess anything up if you download (or even install!) the wrong file. Once you've installed R, you can get started. +Don't worry---you won't mess anything up if you download the wrong file. ### To download RStudio: @@ -64,18 +63,17 @@ Don't worry; you will not mess anything up if you download (or even install!) th - Under the column called "RStudio Desktop", click "Download RStudio" - Click "Download RStudio" on the RStudio Desktop page, which should automatically detect your operating system -If you do have issues, consider [the Data Carpentry page](https://datacarpentry.org/R-ecology-lesson/) (https[]()://datacarpentry.org/R-ecology-lesson/) and then reach out for help. Another excellent place to get help is the [Posit Community forum](https://forum.posit.co/) (https[]()://forum.posit.co/). +If you have problems installing these, consider [the Data Carpentry page](https://datacarpentry.org/R-ecology-lesson/) (https[]()://datacarpentry.org/R-ecology-lesson/) and then reach out for help. Another excellent place to get help is the [Posit Community forum](https://forum.posit.co/) (https[]()://forum.posit.co/). ## RStudio layout and customization: getting to know R through RStudio -Now that we've installed both R and RStudio, we will be accessing R _through_ RStudio. -One of the most reliable ways to tell if you're opening R or RStudio is to look at the icons: +Now that we've installed both R and RStudio, we will be accessing R _through_ RStudio. One of the most reliable ways to tell if you're opening R or RStudio is to look at the icons: ```{r fig5-1, fig.cap = "Icons", echo = FALSE, fig.alt="R Icon and RStudio Icon"} knitr::include_graphics("./man/figures/Figure 5.1.png") ``` -Whenever we want to work with R, we'll open RStudio. RStudio interfaces directly with R, and is an **I**ntegrated **D**evelopment **E**nvironment (IDE). This means that RStudio comes with built-in features that make using R a little easier. If you'd like more information on the difference between R and RStudio, we recommend the "Getting Started" section of the _[Modern Dive](https://moderndive.com/1-getting-started.html#)_ (https[]()://moderndive.com/1-getting-started.html#) textbook [@statisticalinf]. +Whenever we want to work with R, we'll open RStudio. RStudio interfaces directly with R, and is an **I**ntegrated **D**evelopment **E**nvironment (IDE). This means that RStudio comes with built-in features that make using R easier. If you'd like more information on the difference between R and RStudio, consider reading the "Getting Started" section of the _[Modern Dive](https://moderndive.com/1-getting-started.html#)_ (https[]()://moderndive.com/1-getting-started.html#) textbook [@statisticalinf]. You do not _have_ to use RStudio to access R, and many people don't! @@ -88,9 +86,9 @@ Other IDEs that work with R include: - [IntelliJ IDEA](https://plugins.jetbrains.com/plugin/6632-r-language-for-intellij) (https[]()://plugins.jetbrains.com/plugin/6632-r-language-for-intellij) - [EMACS Speaks Statistics (ESS)](https://ess.r-project.org/) (https[]()://ess.r-project.org/) -This is a non-exhaustive list, and most of these options require a good deal of familiarity with a given IDE. +This is a non-exhaustive list and most of these options require a good deal of familiarity with a given IDE. -We bring up alternative IDEs---particularly ESS---because RStudio, as of this writing, is not fully accessible for learners who utilize screen readers. We have chosen to use RStudio in this text in order to standardize the experience, but we encourage you to choose the IDE that best suits your needs! +We bring up alternative IDEs---particularly ESS---because RStudio, as of this writing, is not fully accessible for learners who use screen readers. We have chosen to use RStudio in this text in order to standardize the experience, but we encourage you to choose the IDE that best suits your needs. ### RStudio layout @@ -106,17 +104,17 @@ The large square on the left is the Console pane, the square in the top right is As you work with R more, you'll find yourself using the tabs within each of the panes. -When we create a new file, such as an R script, an R Markdown file, or a Shiny app, RStudio will open a fourth pane, known as the "Source pane". The Source pane should show up as a square in the top left. We can open up an `.R` script in the Source pane by going to "File", selecting "New File", and then selecting "R Script": +When you create a new file, such as an R script, an R Markdown file, or a Shiny app, RStudio will open a fourth pane, known as the "Source pane". The Source pane should show up as a square in the top left. You can open an `.R` script in the Source pane by going to "File", selecting "New File", and then selecting "R Script": ```{r fig5-3, fig.cap = "Creating a New R Script in RStudio", echo = FALSE, fig.alt="Creating a New Script in RStudio by going to file then R script"} knitr::include_graphics("./man/figures/Figure 5.3.png") ``` -You do not need to do anything specific with this file, but we encourage you to experiment with it if you would like! +You do not need to do anything specific with this file, but we encourage you to experiment with it if you would like. ### Customizing RStudio -One of the balances we've tried to strike in this text is a balance between best practices in your _workflow_ (how you'll use R in your projects) and your _R code_. A best practice for your _workflow_ is to ensure that you're starting with a blank slate every time you open R (through RStudio). +One of the balances to strike in this text is a balance between best practices in your _workflow_ (how you'll use R in your projects) and your _R code_. A best practice for your _workflow_ is to ensure that you're starting with a blank slate every time you open R through RStudio. To accomplish this, go to "Tools", and select "Global Options" from the dropdown menu. @@ -124,28 +122,28 @@ To accomplish this, go to "Tools", and select "Global Options" from the dropdown knitr::include_graphics("./man/figures/Figure 5.4.png") ``` -The "General" tab will open, with several checkboxes selected and unselected. The most important thing you can do is select "Never" next to the "Save workspace to .RData on exit:" prompt. After selecting "Never", go through and check and uncheck boxes so that your General tab looks like this: +The "General" tab will open, with several checkboxes selected and unselected. It's important to select "Never" next to the "Save workspace to .RData on exit:" prompt. After selecting "Never", go through and check and uncheck boxes so that your General tab looks like this: ```{r fig5-5, fig.cap = "General Tab from Global Options", echo = FALSE, fig.alt="General tab from the Global Options in RStudio"} knitr::include_graphics("./man/figures/Figure 5.5.png") ``` -Last, but certainly not least, click on the "Appearance" tab from within Global Options. From here you can select your RStudio Font, Font Size, and Theme. Go through the options and select an appearance that works best for you, and know that you can always come back and change it! +Last, click on the "Appearance" tab from within Global Options. From here you can select your RStudio Font, Font Size, and Theme. Go through the options and select an appearance that works best for you, and know that you can always come back and change it. ### Minimized and missing panes -If, at any point, you find that one of your panes seems to have "disappeared", one of two things has likely happened: +If, at any point, you find that one of your panes has disappeared, one of two things has likely happened: - A pane has been minimized - A pane has been closed -Let's look at the Environment pane as an example. If the Environment pane has been minimized, we'll see something like this: +Look at the Environment pane as an example. If the Environment pane has been minimized, we'll see something like this: ```{r fig5-6, fig.cap = "RStudio Layout with the Environment Pane Minimized", fig.alt = "RStudio layout with a minimized Environment Pane", echo = FALSE} knitr::include_graphics("./man/figures/Figure 5.6.png") ``` -We know that the Environment pane has been minimized because although we can see the pane headers in the top right, we can't see the information _within_ the Environment pane. To fix this, we can click on the icon of two squares in the top right of the Environment pane. If you click on the icon of the large square in the top right of the Environment pane, you'll maximize the Environment pane and minimize the Files pane. We do not want to do this, since we would prefer to see all the panes at once. +You'll know that the Environment pane has been minimized because, although we can see the pane headers in the top right, you can't see the information _within_ the Environment pane. To fix this, click on the icon of two squares in the top right of the Environment pane. If you click on the icon of the large square in the top right of the Environment pane, you'll maximize the Environment pane and minimize the Files pane. This is not preferred, since in general you'll want to see all the panes at once. If the Environment pane has somehow been closed, you can recover it by going to the "View" menu, selecting "Panes", and then selecting "Pane Layout", like so: @@ -153,69 +151,68 @@ If the Environment pane has somehow been closed, you can recover it by going to knitr::include_graphics("./man/figures/Figure 5.7.png") ``` -When we select Pane Layout, we'll see this: +When you select Pane Layout, you'll see this: ```{r fig5-8, fig.cap = "Pane Layout Options within RStudio", echo = FALSE, fig.alt = "Pane Layout Options within RStudio"} knitr::include_graphics("./man/figures/Figure 5.8.png") ``` -From here, you can select which tabs you'd like to appear within each pane, and you can even change where each pane appears within RStudio. If our Environment Pane had been closed, we would select it from the Pane Layout in order to re-open it within RStudio. +From here, you can select which tabs you'd like to appear within each pane, and you can even change where each pane appears within RStudio. If the Environment Pane had been closed, select it from the Pane Layout in order to re-open it within RStudio. ## Writing and running code in RStudio -Up to this point, we've been exploring the RStudio interface and setting up our preferences. Now, we'll shift to some basic coding practices. +Up to this point, you've been exploring the RStudio interface and setting up your preferences. Now, you'll shift to basic coding practices. In order to run code in R, you need to type your code either in the Console or within an `.R` script. -We generally recommend creating an `.R` script as you're learning, as it allows you to type all of your code, add comments, and then save your `.R` script for reference. If you work entirely in the Console, anything that you type in the Console will disappear as soon as you restart or close R, and you will not be able to reference it in the future. +When possible, create an `.R` script as you're learning, as it allows you to type all of your code, add comments, and then save your `.R` script for reference. If you work entirely in the Console, anything that you type in the Console will disappear as soon as you restart or close R, and you will not be able to reference it in the future. ### Writing code in the console -To run code in the Console, you type your code next to the `>` and hit `Enter`. -We'll spend a little time practicing running code in the Console by exploring some basic properties of coding in R. +To run code in the Console, you type your code next to the `>` and hit `Enter`. Practicing running code in the Console by exploring some basic properties of coding in R. In the Console, type `3 + 4` and hit `Enter`. + You should see the following: ```{r fig5-9, fig.cap = "Using the Console as a Calculator", echo = FALSE, fig.alt = "Adding 3 and 4 on the console"} knitr::include_graphics("./man/figures/Figure 5.9.png") ``` -We've just used R to add the numbers 3 and 4. R has returned the sum of `3 + 4` on a new line, next to `[1]`. The `[1]` tells us that there is one row of data. +You've just used R to add the numbers 3 and 4. R has returned the sum of `3 + 4` on a new line, next to `[1]`. The `[1]` tells you that there is one row of data. -We can also use R to print out text. Type the following in the Console and hit `Enter`: +You can also use R to print out text. Type the following in the Console and hit `Enter`: ```{r, eval = FALSE} print("I am learning R") ``` -We should see this in the Console: +You should see this in the Console: ```{r fig5-10, fig.cap = "Printing Text to the Console", fig.alt = "Printing I am learning R on the console", echo = FALSE} knitr::include_graphics("./man/figures/Figure 5.10.png") ``` -There's one error that you're likely going to come across, both when running code in the Console as well as in an R script. Let's explore that error now by running the following code in the Console and hitting `Enter`: +There's one error that you're likely going to come across, both when running code in the Console as well as in an R script. Explore that error now by running the following code in the Console and hitting `Enter`: ```{r, eval = FALSE} print("This is going to cause a problem" ``` -Make sure that you left off the closing parenthesis! What you'll see in the Console is: +Make sure that you left off the closing parenthesis. What you'll see in the Console is: ```{r fig5-11, fig.cap = "Incomplete Parentheses Change What R Expects Next", echo = FALSE, fig.alt="Printing this is going to cause a problem with the last parantheses missing"} knitr::include_graphics("./man/figures/Figure 5.11.png") ``` -When we're missing a closing parenthesis, R is expecting us to provide more code. -We know this because instead of seeing a carat `>` in our Console, we see a `+`, and R has not returned the print statement that we were expecting. +When you're missing a closing parenthesis, R is expecting you to provide more code. You'll know this because instead of seeing a carat `>` in our Console, you see a `+`, and R has not returned the expected print statement. There are two ways to fix this problem: - Type the closing `)` in the Console and hit `Enter` - Hit the `Esc` key -Go ahead and run this intentional error, and try each of the options above. Compare the output of each, and think about how they're different. Can you think of when you might want to use one option instead of the other? +Run this intentional error, and try each of the options above. Compare the output of each, and think about how they're different. Can you think of when you might want to use one option instead of the other? ### Writing code in an R script @@ -237,20 +234,21 @@ print("Next, subtraction!") 0.65 - 1.42 ``` -Feel free to spend some more time writing and running code within your `.R` script, or move on to the next section, where we'll add comments to our code. +Feel free to spend some more time writing and running code within your `.R` script, or move on to the next section, where you'll add comments to our code. ### Commenting your code in R -It is considered good practice to comment your code when working in an `.R` script. -Even if you are the only person to ever work on your code, it can be helpful to write yourself notes about what you were trying to do with a specific piece of code. -Moreover, writing comments in your code as you work through the examples in this book is a great way to help reinforce what you're learning. -Comments are ignored by R when running a script, so they will not affect your code or analysis. +It is considered good practice to comment your code when working in an `.R` script. Even if you are the only person working on your code, it's helpful to write yourself notes about what you were trying to do with a specific piece of code. + +Moreover, writing comments in your code as you work through the examples in this book is a great way to reinforce you're learning. + +And remember, comments are ignored by R when running a script, so they will not affect your code or analysis. -To comment out a line of code, you can place a pound sign (also called an octothorpe!) `#` in front of the line of code that you want to exclude when you're running your script. -Be careful when excluding certain lines of code, especially in longer files, as it can be easy to forget where you've commented out code. -It is often better to simply start a new section of code to tinker with until you get it working as expected, rather than commenting out individual lines of code. +To comment out a line of code, place a pound sign (also called an octothorpe) `#` in front of the line of code that you want to exclude when you're running your script. -We can also write comments in line with our code, like this: +Be careful when excluding certain lines of code, especially in longer files, as it can be easy to forget where you've commented. Rather than commenting out individual lines of code, it is often better to start a new section of code to tinker with until it works as expected. + +You can also write comments in line with your code, like this: ```{r eval = FALSE} #' This will be a short code example. @@ -261,17 +259,14 @@ library(here) # Load the here package data <- read_csv(here("file_path", "file_name.csv")) # Save file_name.csv as data ``` -If you think you'll be writing more than one line of comments, you can do a pound sign followed by a single quotation mark (`#'`). -This will continue to comment out lines of text or code each time you hit `Enter`. -You can delete the `#'` on a new line where you want to write code for R to run. -This method is useful when you're writing a long description of what you're doing in R. +If you think you'll be writing more than one line of comments, you can do a pound sign followed by a single quotation mark (`#'`). This will continue to comment out lines of text or code each time you hit `Enter`. You can delete the `#'` on a new line where you want to write code for R to run. This method is useful when you're writing a long description of what you're doing in R. -_Note: when we refer to "commenting" we're referring to adding in actual text comments, whereas "commenting out" refers to using the pound sign (octothorpe) in front of a line of code so that R ignores it._ -_We will also use the phrase "uncomment code", which means you should delete (or omit when typing out) the_ `#` _or_ `#'` _in an example._ +_Note: "Commenting" refers to adding in actual text comments, whereas "commenting out" refers to using the pound sign (octothorpe) in front of a line of code so that R ignores it._ +_You'll also note the phrase "uncomment code", which means you should delete or omit the_ `#` _or_ `#'` _in an example._ ## Installing the {dataedu} package -This next section will briefly go over installing the {dataedu} package that's used throughout this book. We created this package to provide our readers with an opportunity to jump into R however they see fit. +This next section will go over installing the {dataedu} package that's used throughout this book. This package provides readers with resources for using this book. The package serves four main functions: @@ -280,8 +275,9 @@ The package serves four main functions: 3. Access to the data used in each of the walkthroughs 4. The "dataedu" theme and color palette for reuse -If you feel that you need more information before you're ready to install the package, you can skip this section. Rest assured that we'll cover packages, their installation, and how to load them into R in more depth in [Chapter 6](#c06). -However, if you're feeling a bit adventurous, go ahead and give it a shot by running the code below. *Please note that the {dataedu} package requires R version 3.6 or higher to run.* +If you feel that you need more information before you're ready to install the package, you can skip this section. You'll learn about packages, their installation, and how to load them into R in more depth in [Chapter 6](#c06). + +However, if you're feeling adventurous, give it a shot by running the code below. *Please note that the {dataedu} package requires R version 3.6 or higher to run.* ```{r, eval = FALSE} # Install {pak} @@ -294,19 +290,20 @@ pak::pak("data-edu/dataedu") One of the walkthroughs uses [{tabulapdf}](https://github.com/ropensci/tabulapdf), created by ROpenSci to read PDFs. {tabulapdf} requires the installation of [RJava](https://cran.r-project.org/web/packages/rJava/index.html), which can be a tricky process on Mac computers. -Neither {tabulapdf} nor {RJava} are included in `mass_install()` and we recommend reading through the notes on the [{tabulapdf} GitHub repository](https://github.com/ropensci/tabulapdf) if you choose to install it. +Neither {tabulapdf} nor {RJava} are included in `mass_install()`. Reading through the notes on the [{tabulapdf} GitHub repository](https://github.com/ropensci/tabulapdf) if you choose to install it. ## Exploring R with the {swirl} package -If you were able to install the {dataedu} package without any issues or concerns and you're eager to get started exploring everything that R can do, you can supplement your learning through [{swirl}](https://swirlstats.com/students.html) (https[]()://swirlstats.com/students.html). +If you were able to install the {dataedu} package without problems and you're eager to start exploring what R can do, supplement your learning through [{swirl}](https://swirlstats.com/students.html) (https[]()://swirlstats.com/students.html). -You can install {swirl} by running the following code: +Install {swirl} by running the following code: ```{r, eval = FALSE} install.packages("swirl") ``` -{swirl} is a set of packages (see more on packages in [Chapter 6](#c06)) that you can download, providing an interactive method for learning R by using R in the RStudio Console. +{swirl} is a set of packages (see more on packages in [Chapter 6](#c06)) providing an interactive method for learning R by using R in the RStudio Console. + Since you've already installed R, RStudio, and the {swirl} package, you can follow the instructions on the {swirl} webpage or run the following code _in your Console pane_ to get started with a beginner-level course in {swirl}: ```{r, eval = FALSE} @@ -316,10 +313,13 @@ swirl() ``` There are multiple courses available on {swirl}, and you can access them by installing them and then running the `swirl()` command in your console. -We are not affiliated with {swirl} in any way, nor is {swirl} required to progress through this text, but it's a great resource that we want to make sure is on your radar! + +The authors are not affiliated with {swirl} in any way, nor is {swirl} required to progress through this text. But it is a great resource to keep on your radar! ## Conclusion -Congratulations! At this point in the book, you've installed R and RStudio, explored the RStudio IDE, and even written some basic code. -At this point, you're set up to either move on to [Chapter 6](#c06), where we'll do a deeper dive into projects, packages, and functions, and how those relate to your future data tasks. We will also introduce help documentation and some skills for when you're working with new or unfamiliar information. -If that all sounds familiar to you already, you can jump ahead to a walkthrough of your choosing! \ No newline at end of file +Congratulations! At this point in the book, you've installed R and RStudio, explored the RStudio IDE, and written some basic code. + +At this point, you're set up to move on to [Chapter 6](#c06), where you'll do a deeper dive into projects, packages, and functions, and how those relate to your future data tasks. You'll also learn about documentation. + +Alternatively, if that sounds familiar to you already, feel free to jump ahead to a walkthrough of your choosing. \ No newline at end of file