Accessing packages

Last updated on 2024-09-17 | Edit this page

Estimated time: 30 minutes

Overview

Questions

  • How do I use someone else’s package?
  • How do I use my own package?
  • What is the difference between installing and attaching?

Objectives

  • Install and attach packages from CRAN
  • Install and attach packages from Gitlab
  • Build, install and attach your own packages

One of the advantages of packages is that they can be installed. This allows us to use the functions contained in the package from anywhere.

There are many ways of accessing a package in order to start using it. In this section, we will look at the most common ones. It’s very likely that you already know at least one of these methods if you are a regular R user.

At the end of this episode, we’ll describe briefly some alternatives that may be useful in some cases.

Install a package from CRAN

CRAN is the official repository for R Packages. It stands for the Comprehensive R Archive Network. It is an awesome collection of high quality resources written by other R users just like you.

Installing a package from CRAN is particularly easy. Let’s imagine we need to install a package with tools for R developers. We can start by browsing to our favorite search engine, and make a search like: R developers tools. Almost certainly it will point us to a package called devtools. This package contains, among other things, functions to easily install from sources other than CRAN. It will be useful in the next section. The package can be installed by opening RStudio and browsing to the Packages tab:

Packages tab
Packages tab

After pressing Install, a window like this will appear:

Install prompt
Install prompt

We write devtools in the prompt, and press install. This operation will download and install the package and the required dependencies. Depending on the package, it may take a while, ranging from a few seconds to a few minutes.

The same, but with a command

Some people may prefer using code instead of a graphical user interface to install a package. Are you one of them? Then, you’ll like to know that all the above is equivalent to typing:

R 

install.packages("devtools")

As often happens with RStudio, you don’t have to remember this command by heart. You can keep using the graphical user interface and observe what happens in the console. RStudio will build and execute the command for you.

After installing, the new package should appear in the Packages tab.

Something went wrong?

Sometimes, an installation may fail. If that’s the case, take a look at the output message in the console. It will contain very useful information, and direct suggestions about how to fix the problem.

Can I publish my package in CRAN?

The answer is yes, and it is easier than you may think. Most developers of CRAN packages are R users just like you and me. If you have a package you are proud of, and you think it may be useful for someone else, consider submitting it.

In the sections below we’ll see how to install a package from other sources than CRAN. But first, let’s see how can we actually use our freshly installed package!

Using an installed package

If you have used packages before, you may know that installing the package is not enough to start using it immediately. In order to use an installed package, you need to load it into workspace. In R jargon this is known as attaching the package. This means that its functions and data will become available in your working session, so you can use them in your console and your scripts. Additionally, the functions in your package will be added to the search path.

The easiest way to attach an installed package is by using the Packages tab. If you click on the package’s name, the package’s help menu will open. If you click on the checkbox by the package’s name (see figure below), the package will be attached.

The figure above shows that the package testthat is installed and attached. Other packages, such as stringi, stringr or svglite, are installed but not attached.

What if we want to attach a package from the console?

How would you attach an installed R package using the console?

Tip: As always with RStudio, it is a good idea to look at the console while we are performing operations in the graphical user interface.

Use library(<package name>)

Using a function without attaching the package

In some situations it can be a good idea to load individual functions from a given package, but not the package itself. This can be done using the syntax: <package>::<function>.

For instance, if we want to use the function filter from the package dplyr we can call it directly as:

R 

dplyr::filter()

Keep in mind that for this to work, dplyr has to be installed.

To attach or not to attach?

If you are developing a package that depends on other packages, you’ll need to call functions from other packages. These functions will be used in the functions of your own package. When you do this, it is strongly recommended to call functions from the other packages using the syntax <package>::<function>. Conversely, it is strongly advised to not use library(<package>) inside a package.

Do you have any idea why?

The dependencies of a package can become tricky. A common problem is that two packages may contain two functions with the same name. The more explicit the naming, the better.

Additionally, we have to keep our potential users in mind. We want our package to do its work and leave no trace behind. Using library(<package>) inside the package will attach the package without you realizing. And when you’re finished with your function, the package will still be attached.

We’ll learn more about packages that depend on other packages in the episode Dependencies).

Install a package from GitHub

Although CRAN is the official repository for R packages, it is not the only one you can use. A very interesting alternative is GitHub, the most popular open code repository. We can use GitHub to find packages or to make our own packages publicly available. Contrary to CRAN, packages in GitHub are not reviewed. This has an advantage: you can have your package published there immediately.

Find a package on github, bitbucket, or gitlab and install it with devtools

If you have trouble finding a package, try github.com/PabRod/kinematics.

If you know how to install from GitHub already, try a package from GitLab. For instance, try gitlab.com/r-packages/psyverse.

devtools::install_github("PabRod/kinematics")
devtools::install_gitlab("r-packages/psyverse")

# or

devtools::install_git("https://gitlab.com/r-packages/psyverse")

Learning how to publish your package on GitHub is out of the scope of the present course. But, if you are interested, we encourage you to take the course on Version control with Git and GitHub (note this supplemental on Git with Rstudio), and this lesson chapter on Collaborating via Github).

Why would you want to install a package from GitHub?

Can you think of a situation where you’ll rather install from GitHub than from CRAN?

There are two common situations where you’ll want to use GitHub instead of CRAN:

The first and most obvious one is when the package you want doesn’t exist on CRAN. This can happen for many reasons. Maybe the package is still work in progress, or doesn’t pass the CRAN quality checklist. Or perhaps the authors just don’t want to publish it on CRAN.

The second situation is when you need a cutting edge version of the package. R developers usually use GitHub for their everyday work, and only apply to CRAN when they have accumulated changes enough. If you need a very particular version of the package, usually GitHub is the place to go.

Install a package from source

What if the package is only available in your computer? This is the case of the one we are building during this lesson.

The easiest way to install a package from source is by opening the package project and using the Build tab:

Build
Build

By pressing Install and restart three things will happen:

  1. The package will be, indeed, installed.
  2. The R session will be restarted.
  3. The package will be attached.

Why would you want to load a package from source

Can you think of a situation where you’ll need to install and attach a package from source?

The most common situation is while you are developing a package. Every now and then, you’ll want to re-install and re-attach it to check that everything is working as expected.

A short glossary

It is useful to keep in mind these three concepts:

  1. Build: converts a local package into an installable package.
  2. Install: adds the package to your local library, so it is ready to be attached when desired.
  3. Attach: loads the package’s functions to your workspace, making them ready to be used.

When you press Install and restart, the three events happen in sequence.

Key Points

  • To use a package you have to install and attach it
  • To use a homemade package, you also have to build it
  • The build, install and attach process is usually automated by RStudio
  • There are several ways of installing a package
  • The best way of installing packages is dependent on the developer and user needs