Skip to content
GitHub

Data Access - PeekbankR

The peekbankr package offers a set of wrappers that enable you to access the peekbank data in R.

Coming from the old get_ style functions?

This page shows how they translate to the client structure.

# install.packages("remotes")
remotes::install_github("peekbank/peekbankr")

You need a free Redivis account. The first data request opens a browser window asking you to authenticate.

I have an environment that cannot authenticate via browser

Use a personal API token instead. Create one in your Redivis workspace settings, give it the data.metadata scope, and put it in your .Renviron:

REDIVIS_API_TOKEN=your-token-here

Create a client for a release and read the tables from it:

library(peekbankr)
library(dplyr)

pb <- peekbank("2026.2")

data <- pb$aoi_timepoints |>
  left_join(pb$administrations)

Every table in the data schema is a field on the client.
They are downloaded on first access and cached for the session.

peekbank() requires you to specify a release:

peekbank_releases() # available releases

pb <- peekbank("2026.2")
pb$release   # "2026.2"

Alternatively, "current" gets you the most recently published version. Avoid this in contexts where reproducibility is important, as “current” might point to a different release by the time the code is rerun.

See Releases for what each release contains.

To download only part of a table, pb$subset$<table>() takes dplyr expressions and returns only the matching rows:

aoi_timepoints <- pb$subset$aoi_timepoints(dataset_name == "pomper_saffran_2016")

ps_data <- aoi_timepoints |>
  left_join(pb$administrations)

Predicates can name columns of the table and of anything a row is linked to:

pb$subset$aoi_timepoints(age >= 24, age <= 36, sex == "female")

pb$subset$aoi_timepoints(vanilla_trial, !excluded)

pb$subset$administrations(sex == "female")

pb$subset$trials(vanilla_trial)

pb$subset$aoi_timepoints(dataset_name == "pomper_saffran_2016",
                         age < 24, vanilla_trial)

For the timepoint tables specifically, the predicates are translated to remote SQL queries to limit transfer size, meaning a subset of predicates is available (the basic filter functions plus Redivis’ additions). The functions emit error messages to inform you if you try to use an untranslatable predicate.

pb$db holds a dbplyr handle on each table. dplyr verbs on it compile to SQL and run on the server; data transfer happens when you collect(). Here is an example that summarises a timepoint table without pulling it:

library(dplyr)

pb$db$aoi_timepoints |>
  count(aoi) |>
  collect()

The PeekbankR API page covers every table and method on the client, and the helper functions.