1. Software Installation & Setup

Getting your computer ready so you can learn!

Welcome! There’s a few things we’d like everyone to try and do before the workshop starts. For this workshop and the following lessons, we need to install the following programs/software in this order (more details below for different operating systems):

  1. Install R 

  2. Install RStudio 

  3. Install R Packages & Test They Work

  4. Install Geospatial Packages and {sf}

  5. Download Data for the Workshop

Below, we provide extra details appropriate for Windows and MacOSX operating systems. For additional installation options, see here.

Step 1. Install  R 

R is the underlying statistical computing environment, or the engine we use to do things.

Windows: Download and install R

Go to CRAN and download the R installer for Windows. Make sure to choose the latest stable version (v4.1.0 as of May 2021). Download the .exe file and double click to install.

At the “Select Components” screen, you can accept the default and install both 32-bit and 64-bit versions.

At this screen, uncheck “Create a desktop icon” because non-admin users in Windows will be unable to delete it.

MacOS: Download and install R

Step 2. Install  RStudio Desktop 

Using R alone is possible, but less ideal (and less fun!). RStudio is an open-source graphical Integrated Development Environment or IDE that makes using R much easier and more interactive. In this course, we will use the free RStudio Desktop version.

Windows: Download and install RStudio Desktop (free)

macOS: Download and install RStudio Desktop (free)

Check Install!

Once installed, RStudio should be accessible from the start menu. Start up RStudio.

Step 3. Install R Packages

The core set of packages we will need are as follows. There may be a few more we need to install during the course, but this should be the majority.

We install packages available for all R users from an online repository called CRAN, by pasting the following code into the RStudio Console window and hitting ENTER.

install.packages("tidyverse")
install.packages("viridis")
install.packages("openxlsx")
install.packages("readxl")
install.packages("lubridate")

You may see a message

There are binary versions available but the source versions are later:

followed by a list of the packages you are trying to install. This is usually followed by this message:

Do you want to install from sources the package which needs compilation? (Yes/no/cancel)

Compilation means the code associated with the package needs to be translated into R and built for your operating system. Generally we can use the binary option, so after that message type “No” and hit “Enter” on the keyboard. In some cases we do need/want to compile the package to get the most recent updates. For this course, try installing from binary (type No) first!

You may see this:

That’s OK! There’s a dialog box hiding behind RStudio asking if you want to create a personal folder in your Documents folder. Click Yes. It will look something like this when done:

Step 4. Install Geospatial Packages

For some of the mapping and spatial lessons, we need a set of geospatial tools/packages. For the majority of the content we will cover, this requires installation of the {sf} package. When we run the lines below, we may get a question in the Console that is preceded by a list of package names and columns with binary, source, and needs_compilation. That’s ok!

The First Option should be to try and install without compilation. So, if you run the lines below:

And you see a message similar to below (yours will probably look different!!):

 There are binary versions available but the source versions are later:
          binary source needs_compilation
sf         1.0-1  1.0-2             FALSE
mapview   2.10.0 2.10.1              TRUE

Do you want to install from sources the packages which need compilation? (Yes/no/cancel) 

Just make sure to type “No” at the end of the line and hit Enter!


Installing from Source (with Compilation)

However, more commonly, we may need to install/update from source to have the most updated functions and options from a package (don’t worry if you have no idea what this all means yet!). This generally means the code needs to be translated and built or compiled so your computer can interpret it. To do so, we need to follow instructions below for the operating system of your choice.

Windows Geospatial Instructions (from source):

To install {sf} successfully from source, Windows users will need to install Rtools. Download the 64-bit compiler.

After installing RTools, one final step remains…adding RTools to your path. This may require administrative privileges.

Why do we need to do this?

What does this mean? Why do we need to do it? RTools is like a translator for your computer, and it helps translate code and build software (R packages). Before your computer can use it, we need to tell R (on your computer) where the RTools you just installed is actually located. Once we add this path (the location of the directory where RTools lives), the computer can use it when it is needed.

To Add RTools to your Path

Good news is we can typically do this within R/RStudio without too much trouble. Try this:

  1. Open RStudio

  2. Navigate to the Console panel

  3. Right after the > prompt, paste the following line and hit Enter or Return

    writeLines('PATH="${RTOOLS40_HOME}\\usr\\bin;${PATH}"', con = "~/.Renviron")

  4. Test that it worked. Close down RStudio, reopen it, and in the Console after the > prompt, paste the following:

    Sys.which("make")

  5. We should see something like this printed out:

    # "C:\\rtools40\\usr\\bin\\make.exe"

Now you should be able to install or “compile” packages in R in Windows. Proceed with installation instructions for additional packages!

MacOS Geospatial Instructions (from source):

For MacOS users, follow the recommended instructions on the {sf} webpage, which if possible, requires opening a Terminal window and successfully installing Homebrew with the code at this website. You can test if brew is installed by typing brew config in the Terminal and hitting Enter.

We can then install a few spatial tools (via Terminal still!) with the following code:

brew install pkg-config
# then hit enter and wait

brew install gdal
# then hit enter and wait

At this point, you should now be able to install {sf} from binary on a Mac. Proceed to the next section!

Install Spatial R Packages

After this has successfully installed, return to the RStudio “Console”, and install the following packages by typing the following into the console and pressing “return” on the keyboard:

For {sf}, try installing from binary first (so type “No” in your R Console window and hit Enter).

Success should return something like this (not an error message) when you load the library with library(sf):

library(sf)
# Linking to GEOS 3.8.1, GDAL 3.1.4, PROJ 6.3.1

As a final sanity check, copy/paste the following in the console in RStudio and press Enter. This will open an interactive map of the built-in dataset breweries in the “Viewer” pane, and will look like the map below. Click on points and pan around to celebrate a successful install!

library(mapview)
mapview(breweries)

Step 5. Download Workshop Datasets

We’ll be working with a few different datasets for this workshop (see here). We’ve zipped all these files into a single folder, which can be downloaded here. Bear in mind this .zip file is ~122 MB in size, and may take a few minutes to download depending on internet connections.

Quick Test!

Just to make sure each package installed successfully, do the following:

  1. Open up RStudio
  2. Find the “Console.” This is usually the bottom left pane in RStudio
  3. In the “Console”, find the R Prompt (the part that starts with >)
  4. Type in (or copy and paste from here will also work) the following command at the R Prompt and hit return
# check that these packages are installed successfully:
c("tidyverse", "sf", "viridis", "mapview") %in% installed.packages()
[1] TRUE TRUE TRUE TRUE

If you have successfully installed packages, you should see a list of “TRUE” repeated once for each package listed inside the c( ).


Previous module:
Introduction
Next module:
2. Getting started

Corrections

If you see mistakes or want to suggest changes, please create an issue on the source repository.

Reuse

Text and figures are licensed under Creative Commons Attribution CC BY 4.0. Source code is available at https://github.com/r4wrds/r4wrds, unless otherwise noted. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".