2  Installation

In this section, the aim is to have everyone setup with R, RStudio, the tools you need to build an R package, and git.

2.1 Overview

  • Duration 15 minutes

2.2 Questions

  • How do I install R?
  • How do I install RStudio
    • What about Positron?
  • How do I install git?
  • How do I install RTools?

2.3 Software Setup

2.3.1 Installing R

2.3.2 Installing RStudio

https://posit.co/download/rstudio-desktop/#download

2.3.3 Installing R packages for development

To ensure you are up to date, run the following script to install the packages.

install.packages(c("devtools", "roxygen2", "testthat", "knitr", "pak"))

2.3.3.1 Personalising your R Profile

This is really neat, and I think it’s actually worthwhile doing, but it does take up some time, and there are some warnings.

As you develop R packages, you’ll need to go through a cycle of restarting R, and loading things up to be ready. One of the issues with this is that you’ll find yourself writing code like:

library(devtools)

A lot. To save you time, we can edit a very special file called “The R profile”, which is saved as .RProfile. This code is special, and awesome, because it is run every time you start R. It is also dangerous, for exactly the same reason.

I recommend running the following code from devtools to help set this up:

use_devtools()

Which will bring up the following message:

☐ Include this code in .Rprofile to make devtools
  available in all interactive sessions:
  if (interactive()) {
    suppressMessages(require(devtools))
  }
  [Copied to clipboard]
☐ Modify /Users/nick/.Rprofile.
☐ Restart R for changes to take effect.

So, copy and paste the above, which I will now explain. There are three parts to this that I will break down:

require(devtools)

we usually recommend writing library(devtools), but in this instance, require is what we want, because if the package is not installed, require will throw a warning, rather than an error:

# warn
require(whatevenisthis)
Loading required package: whatevenisthis
Warning in library(package, lib.loc = lib.loc, character.only = TRUE,
logical.return = TRUE, : there is no package called 'whatevenisthis'
# error
library(whatevenisthis)
Error in library(whatevenisthis): there is no package called 'whatevenisthis'

We do not want an error when we start R, it is annoying.

suppressMessages()

This code suppresses any messages that appear from running this code, which again, we want, because we don’t (generally) want our R session to announce something upon startup.

  if (interactive()) {
    suppressMessages(require(devtools))
  }

This means that this code is only run if the R session is interactive. This always felt a bit strange to me - because I had only ever run R interactively. But you don’t want to run require(devtools) when we aren’t using R interactively, because it means we are potentially changing the state of things. Essentially, it’s good practice.

Also, here are a couple of times that you might not realise you are using R non-interactively:

  • rendering a document using quarto or rmarkdown
  • building an R package (which you’ll learn about later)

You also use R non-interactively when you are running Rscript in the command line.

Finally, another bit of useful code in your R profile is something like this:

# usethis options
options(
  usethis.full_name = "Nicholas Tierney",
  usethis.protocol = "https",
  usethis.description = list(
    `Authors@R` = '
    c(
      person(
        given = "Nicholas",
        family = "Tierney",
        role = c("aut", "cre"),
        email = "nicholas.tierney@gmail.com",
        comment = c(ORCID = "https://orcid.org/0000-0003-1460-8722")
      )
    )',
    License = "MIT + file LICENSE",
    Language = "en-GB",
    Version = "0.0.0.9000"
  ),
  # set SI to true
  reprex.session_info = TRUE
)

This helps when setting up your R package for the first time, to make sure you set up your DESCRIPTION file. It isn’t required, but it is neat, and I think worthwhile.

Because I need to set these things up on different laptops sometimes, I actually write all these files to github. They are typically called “dotfiles” - you can see mine at http://github.com/njtierney/dotfiles.

2.3.4 git and github

Very briefly, git is essentially a way of managing versions and changes. You can think of it like a product such as dropbox, but with super powers. You can go back in time, you can make copies for changing, and delicately and precisely mege them back in, or leave them where they are.

Your software needs a home. You’ll typically start with your project on your laptop or computer. GitHub is where you can store it online. The benefits to sharing your work on github are many, but my personal top reasons are:

  • Build trust in your software. If the community can see your code, they can trust it better.
  • Provides a way to log ideas and bugs via issues.
  • Provides a way for the community to contribute to your code.

My favourite book on using git and github with R is the book “happy git with R” By Jenny Bryan, Jim Hester, and the Stat 545 TAs. Honestly, it’s hard to recommend better installation instructions than their battle tested ones, so I’ll point you to this resource in case you run into troubles here.

2.3.4.1 setting up github

Getting set up on github you need an account. It’s easy enough to set up - go to https://github.com/ . When picking a username, I recommend the following:

  1. Keep it short. jsmith is better than jonathansmith.
  2. Avoid numbers and jokes. jsmith is better than jsmith123
  3. Keep it professional. jsmithisthebest
  4. Keep it lowercase DONOTSHOUT

2.3.4.2 installing git

Installing git can sometimes be a challenge. This is largely because sometimes there are small differences that arise to install windows vs mac vs linux. Or sometimes there are issues with work computers with strong permissions.

Generally, you should install git from: https://git-scm.com/downloads

But, if you encounter issues, I would advise checking out the battle-tested instructions at: https://happygitwithr.com/install-git.

Once you’ve installed git, I recommend running this:

usethis::git_vaccinate()
✔ Configuring 'core.excludesFile': '~/.gitignore'
✔ Creating the global (user-level) gitignore: '~/.gitignore'
✔ Adding ".Rproj.user", ".Rhistory", ".Rdata", ".httr-oauth", ".DS_Store", and
  ".quarto" to '/home/runner/.gitignore'.

Which ensures that you ignore specific files (specifically, Rproj.user, .Rhistory, .Rdata, .httr-oauth, .DS_Store, and .quarto). This is important because it decreases your chances of leaking credentials or other important details to GitHub.

2.3.4.3 The “git handshake”

In order for your computer to talk to git and github properly, it needs to know three things:

  1. Name
  2. Email
  3. Credentials

git needs to know your name and email - this should be the name and email you used to set up your github account. Set this up with use_git_config()

library(usethis)
use_git_config(
  user.name = "Ned Kelly", 
  user.email = "ned@example.org"
)

github needs a personal access token - this is so you can talk to github from R. This becomes really handy, and dare I say it, nearly magical later on. To get this, run:

usethis::create_github_token()

This will open up GitHub and create a Personal Access Token. If this doesn’t work, go to https://github.com/settings/tokens and click “Generate New Token”, and select the (classic).”

Generally speaking you want the following scopes selected:

  • “repo”
  • “user”
  • “workflow”.

A token will be created - keep this page open, and copy the token to your clipboard.

Then, go to R, and run:

gitcreds::gitcreds_set()

And paste this PAT code in. Then, verify all of this with:

usethis::git_sitrep()

2.3.5 Installing RTools

This is actually something that you only need to do if you want to use C or C++ with your R package, which isn’t something you need to do for this course. To read more on this, see “The R build toolchain” from the R Packages book.