Skip to content
GitHub

PeekbankR API

An overview of the peekbankr client and helpers. For full argument lists, see the full function reference.

peekbank() returns a client pinned to one Peekbank release, through which most of peekbankr is used.

pb <- peekbank("2026.2")

peekbank_releases() lists the releases you can pass. "current" takes the most recently published one.

A client caches the data it downloads for the duration of the R session. cache_on_disk = TRUE additionally saves the data in a .pbcache folder in the working directory, which persists across sessions to prevent redownloading.

pb <- peekbank("2026.2", cache_on_disk = TRUE)

The client has one field per table in the data schema, each reachable three ways (here trials):

pb$trialsthe whole table, fetched once per session and reused after that
pb$subset$trials(...)narrowed by dplyr predicates
pb$db$trialsa dbplyr handle, transferred on collect()

In addition to the fields described in the schema, subjects, administrations, trials, trial_types and stimuli also carry a dataset_name column when returned by peekbankr.

pb$<table> returns the whole table as a tibble. It is downloaded once on first access and kept for the rest of the R session for subsequent use.

pb$datasets
pb$subjects
pb$administrations
pb$trials
pb$trial_types
pb$stimuli
pb$aoi_region_sets
pb$aoi_timepoints
pb$xy_timepoints

pb$subset$<table>(...) returns only the rows matching the dplyr predicates you pass. You can pass multiple predicates separated by comma, which are then combined with AND. A predicate can name the table’s own columns and the columns of anything a row is uniquely linked to:

datasets
subjects
administrations
trials
trial_types
stimuli
aoi_timepoints
xy_timepoints
aoi_region_sets

The result has only the table’s own columns and is cached for the session.

The timepoint tables are filtered on the server before data transfer, limiting predicates to what can be translated to SQL (the basic filter functions plus Redivis’ additions). Local variables are filled in automatically, but if you want to evaluate a function before sending it to the server (e.g. to compare some external values), you need to prefix with !!, e.g. age < !!max(local_ages), as the function would otherwise be sent to the server for translation.

All other tables are filtered locally and take any dplyr expression.

pb$db$<table> is a lazy dbplyr table on Redivis. dplyr verbs on it compile to SQL and run on the server, and the results are fetched on calling collect().

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

pb$db also holds aoi_timepoints_rle, a compressed form of aoi_timepoints: one row per run of a constant AOI, starting at t_norm and length samples long.

FieldWhat it holds
pb$releasethe Peekbank release this client is pinned to, e.g. "2026.2"
pb$redivis_tagthe Redivis version holding it, e.g. "v2.1"
pb$tablesthe names of the tables in this release

Printing the client shows the release it is pinned to and what is on it:

pb
#> <peekbank> release 2026.2 (Redivis version v2.1)
#>   code:    https://github.com/peekbank/peekbank-data-import/tree/<commit>
#>   tables:  datasets subjects administrations trials trial_types stimuli
#>            aoi_region_sets aoi_timepoints xy_timepoints
#>   methods: clear_cache() images() query() readmes()
#>   subset:  $subset$<table>(<dplyr predicates>)
#>   db:      $db$<table> for a dbplyr handle, read on collect()

Runs BigQuery Standard SQL against the pinned release and returns a tibble. String comparison is case-sensitive. Results are cached for the session.

pb$query("SELECT dataset_name, shortcite FROM datasets")

Downloads the stimulus images to <dir>/<dataset_name>/<stimulus_image_path> and returns a tibble with:

  • one row per stimulus that has an image, in the requested datasets
  • the columns of pb$stimuli, plus local_image_path: the path the image was saved to, or NA where the download failed
ArgumentDefault
datasetsall datasetsnames of the datasets to download images for
dir"stimulus_data"directory to save them to
skip_existingTRUEskip images already on disk
stimuli <- pb$images(datasets = "reflook_v4")

Downloads the per-dataset READMEs, which record import decisions and dataset quirks, to <dir>/<dataset_name>.md and returns a tibble with:

  • one row per requested dataset in the release
  • the columns of pb$datasets, plus local_readme_path: the path the README was saved to, and readme: its text (both NA where the download failed)
ArgumentDefault
datasetsall datasetsnames of the datasets to download READMEs for
dir"dataset_readmes"directory to save them to
readmes <- pb$readmes(datasets = "pomper_saffran_2016")

Drops this release’s cached tables and query results. A cache_on_disk client also deletes the saved files.

pb$clear_cache()

Returns a tibble with:

  • one row per release peekbank() can be pinned to, most recently published first
  • the columns release, redivis_tag (the Redivis version holding it) and current (TRUE for the one "current" resolves to)
peekbank_releases()

Turns one key of a table’s *_aux_data JSON into rows and returns a tibble.

E.g., for pb$subjects, a subject with three CDI scores gets three rows in the output, each with that subject’s columns plus the fields of one score. Subjects without the key are dropped. A key holding a single value, like native_language_non_iso, becomes one column named after it.

See codebook for compatible versions and keys.

ArgumentDefault
dfrequireda table with a *_aux_data column, e.g. pb$subjects
keyrequiredthe key to expand, e.g. "cdi_responses"
cdi <- pb$subjects |>
  unnest_aux("cdi_responses")
Example: Unnesting CDI JSON

This subject in pb$subjects

subject_idsexnative_languagelab_subject_iddataset_iddataset_name
1836femaleeng635625fmw_2013

has this subject_aux_data:

{
  "cdi_responses": [
    {"instrument_type": "ws", "measure": "prod", "age": 18,
     "rawscore": 138, "percentile": 61, "language": "English (American)"},
    {"instrument_type": "ws", "measure": "prod", "age": 24,
     "rawscore": 313, "percentile": 45, "language": "English (American)"}
  ]
}

Running the code example above turns it into two rows, one per CDI score (with this unnesting being repeated for all subjects):

subject_idsex…instrument_typemeasureagerawscorepercentilelanguage
1836female…wsprod1813861English (American)
1836female…wsprod2431345English (American)

Looks up where each CDI score falls in the vocabulary norms for its language, form, measure and age, and returns the scores with:

  • norm_age: the age whose norms were used (input ages are rounded to the nearest month)
  • norm_percentile: the highest norm percentile (5, 10, …, 95, 99) the score reaches, or 1 if below the 5th
  • norm_percentile_sex: the same against children of the same sex (NA for sexes other than female and male)

The norms cover English (American) only:

  • WG and WG short form, comprehension and production, 8 to 18 months
  • WS and WS short form, production, 16 to 30 months

WG and WS use the 2022 American English norms, the short forms the MB-CDI short-form norms: Level I for WG short and Level IIA for WS short.

ArgumentDefault
cdirequiredCDI scores from unnest_aux(pb$subjects, "cdi_responses")

Example usage:

cdi <- pb$subjects |>
  unnest_aux("cdi_responses") |>
  add_cdi_percentiles()

Divides each CDI score by the number of words on its form, taken from the form’s item list in Wordbank, and returns the scores along with:

  • n_items: the number of words on the form
  • proportion: the raw score divided by it

Forms without a Wordbank item list get NA.

ArgumentDefault
cdirequiredCDI scores from unnest_aux(pb$subjects, "cdi_responses")

The CDI helpers can be chained on the scores from unnest_aux():

cdi <- pb$subjects |>
  unnest_aux("cdi_responses") |>
  add_cdi_percentiles() |>
  add_cdi_proportions()

Matches each row of a table with a subject_id and an age, e.g. pb$administrations, to the child’s CDI scores closest to it in age from a provided cdi table, and returns:

  • one row per matched score, in the input table’s order
  • the columns of the input table and the columns the table supplied as the cdi input argument, with the score’s age as cdi_age

Each row gets assigned the closest score of every language, form and measure within max_age_diff months. Rows without any are dropped.

ArgumentDefault
dfrequireda table with subject_id and age, e.g. pb$administrations
cdirequiredCDI scores from unnest_aux(pb$subjects, "cdi_responses")
max_age_diffrequiredthe furthest a cdi administration’s age may be from the lwl administration’s age, in months
prefer_laterFALSEuse the later of two equally close scores instead of the earlier one
cdi <- pb$subjects |>
  unnest_aux("cdi_responses") |>
  add_cdi_percentiles()

pb$administrations |>
  nearest_cdi(cdi, max_age_diff = 3)
Example: Matching CDI scores to administrations

These two administrations in pb$administrations

administration_idsubject_idage…dataset_name
148893618…fernald_marchman_2012
149093631…fernald_marchman_2012

belong to a child with these scores in cdi:

subject_id…languageinstrument_typemeasureagerawscore
936…English (American)wgcomp1883
936…English (American)wgprod1817
936…English (American)wsprod2236
936…English (American)wsprod2485

Running the code example above turns them into two rows. The administration at 18 months gets the WG comprehension and production scores from 18 months, but no WS score, as the closest one is 4 months away. The administration at 31 months has no score within 3 months, so it is dropped:

administration_idsubject_idage…languageinstrument_typemeasurecdi_agerawscore…
148893618…English (American)wgcomp1883…
148893618…English (American)wgprod1817…