PeekbankR API
An overview of the peekbankr client and helpers. For full argument lists, see the full function reference.
Creating a Client
Section titled “Creating a Client”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)Tables
Section titled “Tables”The client has one field per table in the data schema, each reachable three ways (here trials):
pb$trials | the whole table, fetched once per session and reused after that |
pb$subset$trials(...) | narrowed by dplyr predicates |
pb$db$trials | a 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.
Whole tables
Section titled “Whole tables”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$datasetspb$subjectspb$administrationspb$trialspb$trial_typespb$stimulipb$aoi_region_setspb$aoi_timepointspb$xy_timepointsSubsets
Section titled “Subsets”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
datasets : administrations
administration_id, dataset_id, age, lab_age, lab_age_units, subject_id, monitor_size_x, monitor_size_y, sample_rate, tracker, coding_method, administration_aux_data subjects : datasets : trials
trial_types : aoi_region_set_id, dataset_id, distractor_id, target_id, full_phrase, full_phrase_language, point_of_disambiguation, target_side, condition, lab_trial_id, vanilla_trial, trial_type_aux_data stimuli (target): target_stimulus_novelty, target_original_stimulus_label, target_english_stimulus_label, target_stimulus_image_path, target_lab_stimulus_id, target_image_description, target_image_description_source, target_stimulus_aux_data stimuli (distractor): distractor_stimulus_novelty, distractor_original_stimulus_label, distractor_english_stimulus_label, distractor_stimulus_image_path, distractor_lab_stimulus_id, distractor_image_description, distractor_image_description_source, distractor_stimulus_aux_data aoi_region_sets : datasets : trial_types
trial_type_id, aoi_region_set_id, dataset_id, distractor_id, target_id, full_phrase, full_phrase_language, point_of_disambiguation, target_side, condition, lab_trial_id, vanilla_trial, trial_type_aux_data stimuli (target): target_stimulus_novelty, target_original_stimulus_label, target_english_stimulus_label, target_stimulus_image_path, target_lab_stimulus_id, target_image_description, target_image_description_source, target_stimulus_aux_data stimuli (distractor): distractor_stimulus_novelty, distractor_original_stimulus_label, distractor_english_stimulus_label, distractor_stimulus_image_path, distractor_lab_stimulus_id, distractor_image_description, distractor_image_description_source, distractor_stimulus_aux_data aoi_region_sets : datasets : stimuli
aoi_timepoints
administrations : dataset_id, age, lab_age, lab_age_units, subject_id, monitor_size_x, monitor_size_y, sample_rate, tracker, coding_method, administration_aux_data subjects : datasets : trials : trial_types : aoi_region_set_id, distractor_id, target_id, full_phrase, full_phrase_language, point_of_disambiguation, target_side, condition, lab_trial_id, vanilla_trial, trial_type_aux_data stimuli (target): target_stimulus_novelty, target_original_stimulus_label, target_english_stimulus_label, target_stimulus_image_path, target_lab_stimulus_id, target_image_description, target_image_description_source, target_stimulus_aux_data stimuli (distractor): distractor_stimulus_novelty, distractor_original_stimulus_label, distractor_english_stimulus_label, distractor_stimulus_image_path, distractor_lab_stimulus_id, distractor_image_description, distractor_image_description_source, distractor_stimulus_aux_data aoi_region_sets : xy_timepoints
administrations : dataset_id, age, lab_age, lab_age_units, subject_id, monitor_size_x, monitor_size_y, sample_rate, tracker, coding_method, administration_aux_data subjects : datasets : trials : trial_types : aoi_region_set_id, distractor_id, target_id, full_phrase, full_phrase_language, point_of_disambiguation, target_side, condition, lab_trial_id, vanilla_trial, trial_type_aux_data stimuli (target): target_stimulus_novelty, target_original_stimulus_label, target_english_stimulus_label, target_stimulus_image_path, target_lab_stimulus_id, target_image_description, target_image_description_source, target_stimulus_aux_data stimuli (distractor): distractor_stimulus_novelty, distractor_original_stimulus_label, distractor_english_stimulus_label, distractor_stimulus_image_path, distractor_lab_stimulus_id, distractor_image_description, distractor_image_description_source, distractor_stimulus_aux_data 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.
Server-side queries
Section titled “Server-side queries”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.
Client Fields
Section titled “Client Fields”| Field | What it holds |
|---|---|
pb$release | the Peekbank release this client is pinned to, e.g. "2026.2" |
pb$redivis_tag | the Redivis version holding it, e.g. "v2.1" |
pb$tables | the 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()Methods
Section titled “Methods”pb$query()
Section titled “pb$query()”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")pb$images()
Section titled “pb$images()”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, pluslocal_image_path: the path the image was saved to, orNAwhere the download failed
| Argument | Default | |
|---|---|---|
datasets | all datasets | names of the datasets to download images for |
dir | "stimulus_data" | directory to save them to |
skip_existing | TRUE | skip images already on disk |
stimuli <- pb$images(datasets = "reflook_v4")pb$readmes()
Section titled “pb$readmes()”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, pluslocal_readme_path: the path the README was saved to, andreadme: its text (bothNAwhere the download failed)
| Argument | Default | |
|---|---|---|
datasets | all datasets | names of the datasets to download READMEs for |
dir | "dataset_readmes" | directory to save them to |
readmes <- pb$readmes(datasets = "pomper_saffran_2016")pb$clear_cache()
Section titled “pb$clear_cache()”Drops this release’s cached tables and query results. A cache_on_disk client also deletes the saved files.
pb$clear_cache()Helper Functions
Section titled “Helper Functions”peekbank_releases()
Section titled “peekbank_releases()”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) andcurrent(TRUEfor the one"current"resolves to)
peekbank_releases()unnest_aux()
Section titled “unnest_aux()”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.
| Argument | Default | |
|---|---|---|
df | required | a table with a *_aux_data column, e.g. pb$subjects |
key | required | the key to expand, e.g. "cdi_responses" |
cdi <- pb$subjects |>
unnest_aux("cdi_responses")Example: Unnesting CDI JSON
This subject in pb$subjects
| subject_id | sex | native_language | lab_subject_id | dataset_id | dataset_name |
|---|---|---|---|---|---|
| 1836 | female | eng | 6356 | 25 | fmw_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_id | sex | … | instrument_type | measure | age | rawscore | percentile | language |
|---|---|---|---|---|---|---|---|---|
| 1836 | female | … | ws | prod | 18 | 138 | 61 | English (American) |
| 1836 | female | … | ws | prod | 24 | 313 | 45 | English (American) |
add_cdi_percentiles()
Section titled “add_cdi_percentiles()”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, or1if below the 5thnorm_percentile_sex: the same against children of the same sex (NAfor 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.
| Argument | Default | |
|---|---|---|
cdi | required | CDI scores from unnest_aux(pb$subjects, "cdi_responses") |
Example usage:
cdi <- pb$subjects |>
unnest_aux("cdi_responses") |>
add_cdi_percentiles()add_cdi_proportions()
Section titled “add_cdi_proportions()”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 formproportion: the raw score divided by it
Forms without a Wordbank item list get NA.
| Argument | Default | |
|---|---|---|
cdi | required | CDI 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()nearest_cdi()
Section titled “nearest_cdi()”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
cdiinput argument, with the score’s age ascdi_age
Each row gets assigned the closest score of every language, form and measure within max_age_diff months. Rows without any are dropped.
| Argument | Default | |
|---|---|---|
df | required | a table with subject_id and age, e.g. pb$administrations |
cdi | required | CDI scores from unnest_aux(pb$subjects, "cdi_responses") |
max_age_diff | required | the furthest a cdi administration’s age may be from the lwl administration’s age, in months |
prefer_later | FALSE | use 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_id | subject_id | age | … | dataset_name |
|---|---|---|---|---|
| 1488 | 936 | 18 | … | fernald_marchman_2012 |
| 1490 | 936 | 31 | … | fernald_marchman_2012 |
belong to a child with these scores in cdi:
| subject_id | … | language | instrument_type | measure | age | rawscore |
|---|---|---|---|---|---|---|
| 936 | … | English (American) | wg | comp | 18 | 83 |
| 936 | … | English (American) | wg | prod | 18 | 17 |
| 936 | … | English (American) | ws | prod | 22 | 36 |
| 936 | … | English (American) | ws | prod | 24 | 85 |
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_id | subject_id | age | … | language | instrument_type | measure | cdi_age | rawscore | … |
|---|---|---|---|---|---|---|---|---|---|
| 1488 | 936 | 18 | … | English (American) | wg | comp | 18 | 83 | … |
| 1488 | 936 | 18 | … | English (American) | wg | prod | 18 | 17 | … |