Skip to content

Commit

Permalink
Update chapter
Browse files Browse the repository at this point in the history
  • Loading branch information
@ivelasq
ivelasq committed Nov 11, 2024
1 parent ac1247a commit cb47c24
Showing 1 changed file with 47 additions and 51 deletions.
98 changes: 47 additions & 51 deletions 05-foundational-skills_1.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,7 @@

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.


In this chapter, and the following chapter (on [Foundational Skills](#c06)), and each of the walkthrough chapters, we 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 a broad overview of the topics emphasized and the functions introduced in the chapter.

## Topics emphasized

Expand All @@ -15,12 +14,12 @@ For all of the topics emphasized sections (like this one), we indicate topics th

## Functions introduced

For the "functions introduced" sections, you will notice that some look a little bit different than others. For example, `devtools::install_github()` is different than `install.packages()`.
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()`.

The reason is that the `install_github()` 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 `devtools` 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 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!

- `install.packages()`
- `devtools::install_github()`
- `pak::pak()`
- `library()`
- `print()`
- `readr::read_csv()`
Expand All @@ -40,13 +39,13 @@ 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 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.

## 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.
RStudio is a set of integrated tools that allow for a more user-friendly experience for using 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.

Expand All @@ -61,13 +60,11 @@ Don't worry; you will not mess anything up if you download (or even install!) th

### To download RStudio:

- Visit [RStudio's website](https://www.rstudio.com/products/rstudio/download/) (https[]()://www.rstudio.com/products/rstudio/download/) to download RStudio
- Under the column called "RStudio Desktop FREE", click "Download"
- Find your operating system (Mac, Windows, or Linux)
- Select the "latest release" on the page for your operating system
- Download and install the application
- Visit [Posit's website](https://posit.co/downloads/) (https[]()://posit.co/downloads/) to download RStudio
- 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 [RStudio Community forums](https://community.rstudio.com/) (https[]()://community.rstudio.com/).
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/).

## RStudio layout and customization: getting to know R through RStudio

Expand All @@ -84,13 +81,15 @@ You do not _have_ to use RStudio to access R, and many people don't!

Other IDEs that work with R include:

- [Jupyter notebook](https://jupyter.org/) (https[]()://jupyter.org/)
- [VisualStudio](https://visualstudio.microsoft.com/services/visual-studio-online/) (https[]()://visualstudio.microsoft.com/services/visual-studio-online/)
- [Positron](https://github.com/posit-dev/positron/releases) (https[]()://github.com/posit-dev/positron/releases)
- [Jupyter Notebook](https://jupyter.org/) (https[]()://jupyter.org/)
- [Visual Studio Code](https://code.visualstudio.com/) (https[]()://code.visualstudio.com/)
- [VIM](https://github.com/jalvesaq/Nvim-R) (https[]()://github.com/jalvesaq/Nvim-R)
- [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.

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!

### RStudio layout
Expand All @@ -101,12 +100,13 @@ When we open RStudio for the first time, we should see something similar to this
knitr::include_graphics("./man/figures/Figure 5.2.png")
```

We'll refer to these three "panes" as the "Console pane", the "Environment pane", and the "Files pane".
We'll refer to these three "panes" as the "Console pane", the "Environment pane", and the "Files pane".

The large square on the left is the Console pane, the square in the top right is the Environment pane, and the square in the bottom right is the Files pane.

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

```{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")
Expand All @@ -117,6 +117,7 @@ You do not need to do anything specific with this file, but we encourage you to
### 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).

To accomplish this, go to "Tools", and select "Global Options" from the dropdown menu.

```{r fig5-4, fig.cap = "Selecting Global Options from the Tool Dropdown Menu", echo = FALSE, fig.alt="Selecting Global Options from the Tool Dropdown Menu"}
Expand All @@ -129,7 +130,7 @@ The "General" tab will open, with several checkboxes selected and unselected. Th
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, 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!

### Minimized and missing panes

Expand All @@ -138,8 +139,7 @@ If, at any point, you find that one of your panes seems to have "disappeared", o
- 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:
Let's 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")
Expand All @@ -163,8 +163,8 @@ From here, you can select which tabs you'd like to appear within each pane, and

## 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, we've been exploring the RStudio interface and setting up our preferences. Now, we'll shift to some 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.
Expand All @@ -181,12 +181,9 @@ You should see the following:
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.
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.

We can also use R to print out text.
Type the following in the Console and hit `Enter`:
We 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")
Expand All @@ -198,34 +195,32 @@ We should see this in the Console:
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. Let's 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!
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.

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?
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?

### Writing code in an R script

There are three main ways to run code in an `.R` script:
There are three main ways to run code in an `.R` script:

- Highlight the line(s) of code you'd like to run and press `Ctrl` + `Enter`
- Highlight the line(s) of code you'd like to run and click the "Run" button in the `R script` pane
- To run _every_ line of code in your file you can press `Ctrl` + `Shift` + `Enter`
Expand All @@ -247,7 +242,7 @@ Feel free to spend some more time writing and running code within your `.R` scri
### 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.
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.

Expand All @@ -258,15 +253,14 @@ It is often better to simply start a new section of code to tinker with until yo
We can also write comments in line with our code, like this:

```{r eval = FALSE}
#' this will be a short code example.
#' you are not expected to know what this does,
#' This will be a short code example.
#' You are not expected to know what this does,
#' nor do you need to try running it on your computer.
library(readr) # load the readr package
library(here) # load the here package
data <- read_csv(here("file_path", "file_name.csv")) # save file_name.csv as data
library(readr) # Load the readr package
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.
Expand All @@ -290,22 +284,24 @@ If you feel that you need more information before you're ready to install the pa
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.*

```{r, eval = FALSE}
# install {remotes}
install.packages("remotes", repos = "http://cran.us.r-project.org")
# install the {dataedu} package (requires R version 3.6 or higher)
remotes::install_github("data-edu/dataedu")
# Install {pak}
install.packages("pak")
# Install the {dataedu} package (requires R version 3.6 or higher)
pak::pak("data-edu/dataedu")
```

*A special note on {tabulizer}:*
One of the walkthroughs uses [{tabulizer}](https://github.com/ropensci/tabulizer), created by ROpenSci to read PDFs.
{tabulizer} 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 {tabulizer} nor {RJava} are included in `mass_install()` and we recommend reading through the notes on the [{tabulizer} GitHub repository]("https://github.com/ropensci/tabulizer) if you choose to install it.

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.

## 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).

You can install {swirl} by running the following code:

```{r, eval = FALSE}
install.packages("swirl")
```
Expand All @@ -326,4 +322,4 @@ We are not affiliated with {swirl} in any way, nor is {swirl} required to progre

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!
If that all sounds familiar to you already, you can jump ahead to a walkthrough of your choosing!

0 comments on commit cb47c24

Please sign in to comment.