Skip to contents

Peekbank client

Source: R/client.R
PeekbankClient.Rd

Peekbank client

Peekbank client

Details

A client pins one Peekbank release, so every table read through it comes from the same version of the data. Create one with peekbank().

Every table is reachable three ways:

  • pb$administrations for the whole table, fetched once per session and reused after that

  • pb$subset$administrations() to narrow it with dplyr predicates

  • pb$db$administrations for a dbplyr handle that defers transfer until dplyr::collect().

Active bindings

release

The Peekbank release this client is pinned to

redivis_tag

The Redivis version this client is pinned to

tables

Names of the tables in this release

subset

One function per table taking dplyr predicates, e.g. pb$subset$aoi_timepoints(age < 24). A predicate can name any column of the table or of anything a row of it belongs to: an administration's dataset and subject; a trial's trial type, with its target and distractor stimuli (prefixed target_ and distractor_) and its AOI region set; a timepoint's administration and trial. The result has the table's own columns either way. For the timepoint tables the predicates run on the server to reduce transfer size.

db

dbplyr handles on this release's tables, one field each. They carry the same columns as the fields above, but they are lazy queries, so nothing is transferred until dplyr::collect().

datasets

The datasets table

subjects

The subjects table. Subjects link longitudinal administrations; administrations is usually the one you want.

administrations

The administrations table, with dataset_name joined on

trials

The trials table, with dataset_id and dataset_name joined on

trial_types

The trial types table, with dataset_name joined on

stimuli

The stimuli table, with dataset_name joined on

aoi_region_sets

The AOI region sets table

aoi_timepoints

Every AOI timepoint in the release: 36 million rows, a little over half a gigabyte once expanded. It transfers run-length encoded and is expanded locally. pb$subset$aoi_timepoints() filters on the server instead.

xy_timepoints

Every XY timepoint in the release: 10 million rows

Methods

Public methods

Method new()

Pin a database version.

Usage

PeekbankClient$new(version)

Arguments

version

A Peekbank release name such as "2025.1", or "current" for whichever was published most recently. Required: see peekbank().

Method query()

Run a BigQuery Standard SQL query against this release

Usage

PeekbankClient$query(sql)

Arguments

sql

A valid SQL query string

Method images()

Download the stimulus images of this release's stimuli

Usage

PeekbankClient$images(
  datasets = c(),
  dir = "stimulus_data",
  skip_existing = TRUE
)

Arguments

datasets

Dataset names to download for; all datasets if empty

dir

Directory to save the images to

skip_existing

Skip an image that already exists locally with the same size

Returns

The stimuli that have an image, with local_image_path added (NA where a download failed)

Method readmes()

Download the README of each of this release's datasets

Usage

PeekbankClient$readmes(datasets = c(), dir = "dataset_readmes")

Arguments

datasets

Dataset names to download for; all datasets if empty

dir

Directory to save the READMEs to, as <dataset_name>.md

Returns

The datasets table with the README's local path in local_readme_path and its text in readme (NA where a download failed)

Method clear_cache()

Drop this version's (instance's) cached tables and query results, so the next read fetches them again.

Usage

PeekbankClient$clear_cache()

Method print()

Print the pinned release and what is reachable on it

Usage

PeekbankClient$print(...)

Arguments

...

Ignored

Examples

if (FALSE) { # \dontrun{
pb <- peekbank("2026.1")

pb$administrations
pb$subset$aoi_timepoints(dataset_name == "pomper_saffran_2016")
pb$db$aoi_timepoints |> dplyr::count(aoi) |> dplyr::collect()
} # }