The peekbankr package allows you to access data in the
peekbank database from R. Data are hosted in the versioned peekbank dataset
on Redivis; the get_ functions retrieve tidy tables
from it without you having to write queries. This vignette shows some
examples of how to use the data loading functions and what the resulting
data look like.
There are several different get_ functions that you can
use to extract different types of data from the peekbank-db:
get_datasets()get_subjects()get_administrations()get_trials()get_stimuli()get_aoi_region_sets()get_aoi_timepoints()get_xy_timepoints()Technical note 1: peekbankr needs the
redivis client package, which is not on CRAN; install it
with
install.packages("redivis", repos = "https://langcog.r-universe.dev", type = "source").
The first request will open a browser window to authorize Redivis access
(or set a REDIVIS_API_TOKEN).
Technical note 2: Start by creating a version handle
with connect_to_peekbank() and pass it to each
get_ function. The handle pins a database version for your
whole analysis (“current” resolves to the latest release); calling
get_ functions without one works but re-resolves the
version each time and warns.
Technical note 3: We have tried to optimize the time it takes to get data from the database (the AOI timepoints transfer run-length-encoded and are expanded locally). But if you query entire timepoint tables, it will still take a while, as you are transferring 100s of MB of data.
# load the library
library(peekbankr)
# pin a database version for all the calls below
con <- connect_to_peekbank()The get_datasets function returns a table related to the
sources of the dataset, information of the tracker, information of the
method (e.g., monitor size and sample rate).
For example, you can run get_datasets without any
arguments to return all of the datasets in the database.
d_datasets <- get_datasets(connection = con)
head(d_datasets)## # A tibble: 6 × 6
## dataset_id lab_dataset_id dataset_name shortcite cite dataset_aux_data
## <int> <chr> <chr> <chr> <chr> <chr>
## 1 0 potter_remix potter_remix Potter e… Pott… NA
## 2 28 adams_marchman_2018 adams_march… Adams et… Adam… NA
## 3 32 bacon_gendercues bacon_gende… Bacon & … Baco… NA
## 4 3 baumgartner_2014 baumgartner… Baumgart… Baum… NA
## 5 27 bergelson_swingley_2… bergelson_s… Bergelso… Berg… NA
## 6 36 borovsky_2019 borovsky_20… Borovsky… Boro… NAThe get_subjects function returns information about
persistent subject identifiers for noting when subjects have
participated in multiple experiments. This includes demographic
information (currently only sex and lab-specific subject id).
d_subjects <- get_subjects(connection = con)
head(d_subjects)## # A tibble: 6 × 5
## subject_id sex native_language lab_subject_id subject_aux_data
## <int> <chr> <chr> <chr> <chr>
## 1 21 female spa, eng 32 "{\"lang_exposures\": [{\"la…
## 2 18 female spa, eng 28 "{\"lang_exposures\": [{\"la…
## 3 16 female spa, eng 25 "{\"lang_exposures\": [{\"la…
## 4 0 female spa, eng 1 "{\"lang_exposures\": [{\"la…
## 5 2 female spa, eng 3 "{\"lang_exposures\": [{\"la…
## 6 12 female spa, eng 20 "{\"lang_exposures\": [{\"la…The get_administrations function returns information
about the specific experimental administrations to subjects in the
database. This includes information about:
Again, if you run the function with no arguments, then you get all the information for all administrations in the database, but you can now also filter on a dataset name or dataset id.
d_administrations <- get_administrations(dataset_name = "pomper_saffran_2016", connection = con)
head(d_administrations)## # A tibble: 6 × 13
## administration_id age lab_age lab_age_units monitor_size_x monitor_size_y
## <int> <dbl> <dbl> <chr> <int> <int>
## 1 1936 46 46 months NA NA
## 2 1937 43 43 months NA NA
## 3 1938 47 47 months NA NA
## 4 1939 42 42 months NA NA
## 5 1940 43 43 months NA NA
## 6 1941 42 42 months NA NA
## # ℹ 7 more variables: sample_rate <dbl>, tracker <chr>, coding_method <chr>,
## # dataset_id <int>, subject_id <int>, administration_aux_data <chr>,
## # dataset_name <chr>The age argument takes a number indicating the age(s) of children (in months) that you want to analyze. you can use this argument in two ways
For example, you can get the participant information for all of the children who were tested between the ages of 24 and 36 months.
d_age_range <- get_administrations(age = c(24, 36), connection = con)
head(d_age_range)## # A tibble: 6 × 13
## administration_id age lab_age lab_age_units monitor_size_x monitor_size_y
## <int> <dbl> <dbl> <chr> <int> <int>
## 1 3 28 28 months NA NA
## 2 26 28 28 months NA NA
## 3 30 29 29 months NA NA
## 4 7 29 29 months NA NA
## 5 13 28 28 months NA NA
## 6 4 25 25 months NA NA
## # ℹ 7 more variables: sample_rate <dbl>, tracker <chr>, coding_method <chr>,
## # dataset_id <int>, subject_id <int>, administration_aux_data <chr>,
## # dataset_name <chr>The get_trials function returns a table with information
of the trials in the experiments in the database. This includes the
following information:
d_trials <- get_trials(connection = con)
head(d_trials)## # A tibble: 6 × 8
## trial_id trial_order trial_type_id excluded exclusion_reason trial_aux_data
## <int> <int> <int> <int> <chr> <chr>
## 1 550 2 0 0 NA NA
## 2 604 2 0 0 NA NA
## 3 588 2 0 0 NA NA
## 4 194 2 0 1 Only completed one… NA
## 5 383 2 0 0 NA NA
## 6 508 2 0 0 NA NA
## # ℹ 2 more variables: dataset_id <int>, dataset_name <chr>This function also takes dataset name and id filters.
The get_stimuli function returns a table with
information of the stimuli in the experiments in the database. This
includes the following information:
d_stimuli <- get_stimuli(connection = con)
head(d_stimuli)## # A tibble: 6 × 11
## stimulus_id stimulus_novelty original_stimulus_label english_stimulus_label
## <int> <chr> <chr> <chr>
## 1 11 familiar balloon balloon
## 2 3 familiar globo balloon
## 3 8 familiar galleta cookie
## 4 0 familiar cookie cookie
## 5 13 familiar perro dog
## 6 7 familiar dog dog
## # ℹ 7 more variables: stimulus_image_path <chr>, lab_stimulus_id <chr>,
## # dataset_id <int>, image_description <chr>, image_description_source <chr>,
## # stimulus_aux_data <chr>, dataset_name <chr>This function also takes dataset name and id filters.
The get_aoi_region_sets() returning a table with the
information of the region of area of interest (AOI) for experiments
using eye-trackers. It includes information of the dimensions of the x
and y, such as the minimum and maximum dimension of the xy spaces.
d_aoi_region_sets <- get_aoi_region_sets(connection = con)
head(d_aoi_region_sets)## # A tibble: 6 × 9
## aoi_region_set_id l_x_max l_x_min l_y_max l_y_min r_x_max r_x_min r_y_max
## <int> <int> <int> <int> <int> <int> <int> <int>
## 1 0 960 0 1080 0 1920 961 1080
## 2 3 395 359 754 359 1366 971 754
## 3 7 640 0 1024 0 1280 640 1024
## 4 22 533 0 900 400 1600 1067 900
## 5 4 700 0 900 0 1600 900 900
## 6 21 704 0 916 126 1674 980 920
## # ℹ 1 more variable: r_y_min <int>This function is not expected to be used commonly - this information is retained as part of the process of calculating AOIs from XY points.
The get_aoi_timepoints() function returns a table with
information of the subject’s looking behavior in each trial. For
example, you can get information about which area that the subject was
looking at in a particular trial (e.g., looking away or target or
distractor).
The t_norm field provides a trial-normalized time
variable (milliseconds) whose 0 point is the point of disambiguation on
that trial (first timestep of the onset of the first time the target
label is said).
d_aoi_timepoints <- get_aoi_timepoints(dataset_name = "pomper_saffran_2016", connection = con)
head(d_aoi_timepoints)## # A tibble: 6 × 4
## administration_id trial_id aoi t_norm
## <int> <int> <chr> <int>
## 1 1936 46339 target -1000
## 2 1936 46339 target -975
## 3 1936 46339 target -950
## 4 1936 46339 target -925
## 5 1936 46339 target -900
## 6 1936 46339 target -875For experiments using eye-trackers (as opposed to hand coding from
video), the get_xy_timepoints function returns a table
including the x and y position across time.
d_xy_timepoints <- get_xy_timepoints()