| Title: | Tidy 'Gorilla' Experiment Builder Exports |
|---|---|
| Description: | Reads the data files downloaded from the 'Gorilla' Experiment Builder <https://gorilla.sc/> and turns them into tidy tibbles. Files from Task Builder 1 and 2 and from Questionnaire Builder 1 and 2 can be read together, whether they were downloaded as one file per node or as combined files, as CSV or Excel files, and from several versions of an experiment. Task data are reduced to one row per response with the same columns for both task builders. Questionnaire answers are returned with one row per participant, and participant information such as status, device, randomiser outcomes and stored values is collected in one table. Recordings of the eye tracking and mouse tracking components are read with each sample assigned to a zone of the screen. A summary and a set of checks point out incomplete or repeated participation and unusual response patterns before the analysis. The tables can be saved as CSV files for use in other software. |
| Authors: | Massimiliano Canzi [aut, cre, cph] (ORCID: <https://orcid.org/0000-0001-6124-0321>) |
| Maintainer: | Massimiliano Canzi <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-11-17 07:38:04 UTC |
| Source: | https://github.com/mcanzi/silverback |
Replaces the public identifiers that can link participants to a
recruitment platform, such as Prolific or SONA IDs, with codes such as
P001.
The same participant gets the same code in all tables. The private
identifiers assigned by 'Gorilla' are kept, because they do not identify
anyone outside 'Gorilla'. Answers that participants typed in, such as an
ID entered in a questionnaire, are not changed.
blind_ids( x, columns = c("participant_public_id", "participant_external_session_id", "participant_completion_code") )blind_ids( x, columns = c("participant_public_id", "participant_external_session_id", "participant_completion_code") )
x |
A |
columns |
Columns to replace. By default the public ID, the external session ID and the completion code. |
x with the identifiers replaced. Participants without a value
keep NA.
g <- read_gorilla(gorilla_example()) gorilla_participants(blind_ids(g))g <- read_gorilla(gorilla_example()) gorilla_participants(blind_ids(g))
Lists participants and tasks that may need a closer look before the analysis. Each row describes one finding. The function removes nothing, so you decide what to exclude.
gorilla_checks( x, fast = 200, max_fast = 0.1, max_same = 0.9, min_responses = 10, balance = 1.5 )gorilla_checks( x, fast = 200, max_fast = 0.1, max_same = 0.9, min_responses = 10, balance = 1.5 )
x |
A |
fast |
Reaction time in milliseconds below which a response counts as fast. |
max_fast |
Largest acceptable proportion of fast responses. |
max_same |
Largest acceptable proportion of identical responses. |
min_responses |
Fewest responses in a task for the |
balance |
Largest acceptable ratio between the largest and the smallest group of a randomiser node. |
The checks are
Participants whose status is not complete, such as live
or rejected participants included by hand. Skipped if the export has
no status column.
Data from more than one version of the experiment.
The same public ID under several private IDs, which usually means that someone took part more than once.
Participants who did not do a task that most participants with the same outcomes of randomiser, branch, order, counterbalance and allocator nodes did.
Randomiser nodes whose groups differ in size by more
than the ratio balance.
Participants who used a different type of device from most participants.
Participants with more than the proportion max_fast of
responses in a task faster than fast milliseconds.
Participants who gave the same response in more
than the proportion max_same of at least min_responses responses in
a task where other responses were possible. For components that
recorded no response values, the object clicked or chosen counts as the
response.
A tibble with columns check, participant_private_id,
task_name and detail, with no rows if nothing was found.
summary.gorilla_data() for an overview of each task.
g <- read_gorilla(gorilla_example(), quiet = TRUE) gorilla_checks(g)g <- read_gorilla(gorilla_example(), quiet = TRUE) gorilla_checks(g)
The package includes a small invented experiment downloaded in the one-file-per-node format: a lexical decision task made with Task Builder 2, a rhyme judgement task made with Task Builder 1, a consent form made with Questionnaire Builder 1 and a background questionnaire made with Questionnaire Builder 2. One participant stopped during the lexical decision task, and one node was never reached, so its file is empty. The data were simulated and the identifiers are made up.
gorilla_example(file = NULL)gorilla_example(file = NULL)
file |
Name of one file. If |
A path.
gorilla_example() list.files(gorilla_example())gorilla_example() list.files(gorilla_example())
One row per participant, with the identifiers, the status, the device,
operating system and browser, and the times of the first and last
recorded event. tasks counts the tasks and questionnaires the
participant has data for. The outcome of each randomiser, branch and
checkpoint node follows, and then the last value of each store field.
Columns that are empty for all participants are dropped.
gorilla_participants(x, status = NULL)gorilla_participants(x, status = NULL)
x |
A |
status |
Keep only participants with these values of
|
A tibble. start and end are in UTC; minutes is the time
between them.
g <- read_gorilla(gorilla_example()) gorilla_participants(g)g <- read_gorilla(gorilla_example()) gorilla_participants(g)
Keeps the rows of the task data that hold a participant's response and gives them the same columns whether the task was made with Task Builder 1 or 2. Rows with instructions, continue buttons, fixation crosses, media events and other information are dropped.
gorilla_trials(x, task = NULL, all_rows = FALSE, quiet = FALSE)gorilla_trials(x, task = NULL, all_rows = FALSE, quiet = FALSE)
x |
A |
task |
Names of the tasks to include, as in the |
all_rows |
Keep all rows of the trials, not only the responses. A
column |
quiet |
If |
In Task Builder 2 a response is a row with response_type "response".
In Task Builder 1 it is a row from a response zone (zone_type starting
with response_).
Some components can record a response without a value, such as a
Click Response whose objects have no response set up in 'Gorilla'. The
clicked object is then only in object. When every response of a
component in a task is empty, a message names the task and component.
response is left empty, so use dplyr::coalesce(response, object) if the object names are
the answers.
A tibble with one row per response and columns
Who did which task, in which version and node of the experiment, with Gorilla's Repeat Key.
Name of the spreadsheet used.
Trial number.
Display and screen of the response. Task Builder 1 has no displays.
Component and object that recorded the response in Task Builder 2; zone type and zone name in Task Builder 1.
The response, as text.
Reaction time in milliseconds.
Whether the response was scored as correct.
Time of the response, in UTC.
followed by the timing columns of the export, such as reaction_onset
in Task Builder 1 or onset_time, absolute_reaction_time and
response_duration in Task Builder 2, and by the spreadsheet
(spreadsheet_) and store (store_) columns. Only columns with values
for the selected tasks are kept. All columns of the export remain in
x$tasks.
g <- read_gorilla(gorilla_example()) gorilla_trials(g) gorilla_trials(g, task = "Lexical decision")g <- read_gorilla(gorilla_example()) gorilla_trials(g) gorilla_trials(g, task = "Lexical decision")
Turns the questionnaire answers of read_gorilla() into a wide table with
one row per participant and one column per item. Items with a quantised
value, such as the position of the chosen option in a dropdown or a
Likert scale, get a second column ending in _quantised.
gorilla_wide(x, task = NULL, quantised = TRUE)gorilla_wide(x, task = NULL, quantised = TRUE)
x |
A |
task |
Names of the questionnaires to include, as in the |
quantised |
Add the |
Questionnaires from Questionnaire Builder 1 and 2, downloaded in long or
short format, give the same columns. An item that appears in more than
one questionnaire gets the questionnaire name as a prefix. Objects of
Questionnaire Builder 2 that share a name within a questionnaire, such as
several objects left with the default name Rating Scale, are different
questions and get their object ID as a suffix, as in
rating_scale_object_29. If a
participant answered the same item more than once, for example after
repeating a node or going back to a page, the later answers
go into columns ending in __2, __3 and so on. Cleaned item names never
contain a double underscore, so these columns cannot be confused with
items whose names end in a number.
A tibble with participant_private_id and one column per item.
Column names are converted to snake case.
g <- read_gorilla(gorilla_example()) gorilla_wide(g)g <- read_gorilla(gorilla_example()) gorilla_wide(g)
Reads the files that the Eye Tracking (Webgazer) component of Task
Builder 2 saves for each trial. 'Gorilla' does not put these recordings in
the main export but in files of their own, named like
123456-3-9100037-task-ab12-50000037-collection-10-2.csv (gaze) and
...-calibration-1-2.csv (calibration).
read_eyetracking(path, x = NULL, zones = NULL, quiet = FALSE)read_eyetracking(path, x = NULL, zones = NULL, quiet = FALSE)
path |
Paths to folders, CSV files or ZIP archives. Folders and ZIP
archives are searched recursively for files whose names contain
|
x |
Optional |
zones |
Names of the zones to assign samples to. All by default. |
quiet |
If |
Positions are given in normalised coordinates: 0 to 1 across the
area of the task, with the origin at the bottom left, as in the export.
Raw coordinates in pixels are kept as x_raw and y_raw, but they depend
on the participant's screen. Predictions outside the area of the task,
below 0 or above 1, are kept; webcam eye tracking produces them when
participants look away or the prediction is poor.
Each gaze sample is assigned to the zone of the screen it falls in. When
zones overlap, the smallest zone containing the sample wins. Use zones
to test only some zones, for example the pictures of a visual world task
and not the response buttons placed on them.
The recordings do not say which task they belong to or, for gaze data, the
name of the screen. Pass the main export as x to add task_name and
screen, so that the samples can be joined to gorilla_trials() by
participant_private_id, tree_node_key, display, trial and screen.
An object of class gorilla_eyetracking: a list with
One row per gaze sample, with the participant, node, task,
spreadsheet, trial and screen, the kind of sample (type, usually
"prediction"), the time of the sample in UTC
(time), the time since the start of the recording in milliseconds
(elapsed), the predicted gaze position (x, y, x_raw, y_raw)
and the zone it falls in (zone_id, zone_name).
One row per zone and recording, with the object ID
(zone_id), the name, and the edges left, right, bottom and
top in normalised coordinates.
One row per calibration point and attempt, with the
outcome of the attempt ("succeeded", "failed - retrying" or
"failed - max failures"), the position of the point, the centre and
standard deviation of the gaze predictions while the participant
looked at it, and error, the distance between point and centre,
all in normalised coordinates.
Attempts that ended before any point was measured have one row with
missing point values.
One row per file read, with its kind and number of rows.
read_mousetracking() for the Mouse Tracking component.
## Not run: g <- read_gorilla("data") eye <- read_eyetracking("data", x = g) eye$gaze eye$calibration ## End(Not run)## Not run: g <- read_gorilla("data") eye <- read_eyetracking("data", x = g) eye$gaze eye$calibration ## End(Not run)
Reads the CSV or Excel files downloaded from the Data tab of the 'Gorilla'
Experiment Builder and sorts them into tasks, questionnaires and
participants. Both kinds of download are read: one file per node of the
experiment tree (data_exp_12345-v6_task-ab12.csv) and the combined files
(data_exp_12345-v6_tasks.csv, data_exp_12345-v6_questionnaires.csv).
read_gorilla(path, quiet = FALSE)read_gorilla(path, quiet = FALSE)
path |
Paths to folders, CSV or Excel files, or ZIP archives. Folders
and ZIP archives are searched recursively for CSV and Excel files whose
names start with |
quiet |
If |
Excel files (.xlsx) are read with every cell as text, so they give the
same tables as the CSV download. Some Excel downloads store numbers as
numbers, though, and a code such as 007 saved that way has already lost
its leading zeros in the file. Download CSV files if such codes matter.
Files from Task Builder 1 and 2 and from Questionnaire Builder 1 and 2 can
be mixed, and so can files from several versions of the experiment. The
END OF FILE row at the end of each file is removed, and files from nodes
that no participant reached, which hold no data, are skipped. Files that
were opened in a spreadsheet program and saved again are read too: with
semicolons or tabs as separators, in the Windows-1252 encoding, or as
Unicode text (UTF-16 with a byte order mark, as Excel saves it). A file
that is not UTF-8 is read as Windows-1252 with a warning, because other
encodings cannot always be told apart from it.
Some problems give a warning, because the tables may not be what you expect: the same events in more than one file, as after reading both kinds of download, a file as CSV and as Excel or a second copy of a download; lines with the wrong number of columns, as in a file that was cut off or edited by hand; and a column name that appears twice in a file, as when a Task Builder 1 spreadsheet has a column with the same name as a column of the export.
Column names are converted to snake case: Participant Private ID
becomes participant_private_id, Spreadsheet: Speaker becomes
spreadsheet_speaker and Store: Alter becomes store_alter. Spreadsheet
columns from Task Builder 1, which have no prefix in the export, get the
same spreadsheet_ prefix.
A column becomes numeric only if every value in it is a number without
leading zeros, so codes such as 007 and response keys such as T and
F stay text. Identifiers and responses always stay text.
An object of class gorilla_data: a list with
All rows of all task files, one row per event, with
cleaned column names, plus builder (the task builder that made the
file) and file (the file the row comes from). See gorilla_trials()
for one row per response.
All questionnaire answers in long format, one row
per participant and item, with columns item, response,
quantised and file. See gorilla_wide() for one row per
participant.
One row per participant. See
gorilla_participants().
One row per file read, with the experiment, version, node, builder, task and number of rows.
gorilla_trials(), gorilla_wide(), gorilla_participants()
path <- gorilla_example() g <- read_gorilla(path) g g$filespath <- gorilla_example() g <- read_gorilla(path) g g$files
Reads the files that the Mouse Tracking component of Task Builder 2 saves
for each trial. 'Gorilla' does not put these recordings in the main export
but in files of their own, named like
123456-3-9100037-task-ab12-50000037-mousetracking-10-2.csv.
read_mousetracking(path, x = NULL, zones = NULL, quiet = FALSE)read_mousetracking(path, x = NULL, zones = NULL, quiet = FALSE)
path |
Paths to folders, CSV files or ZIP archives. Folders and ZIP
archives are searched recursively for files whose names contain
|
x |
Optional |
zones |
Names of the zones to assign samples to. All by default. |
quiet |
If |
Positions are given in normalised coordinates: 0 to 1 across the area
of the task, with the origin at the bottom left, as in the export. Raw
coordinates in pixels are kept as x_raw and y_raw; in these, as
recorded by the browser, y counts from the top of the window.
Each sample is assigned to the zone of the screen it falls in. When zones
overlap, the smallest zone containing the sample wins. Use zones to
test only some zones.
The recordings do not say which task they belong to. Pass the main export
as x to add task_name, so that the samples can be joined to
gorilla_trials() by participant_private_id, tree_node_key, display,
trial and screen.
An object of class gorilla_mousetracking: a list with
One row per sample, with the participant, node, task,
spreadsheet, trial and screen, the kind of sample (type, usually
"mouse"), a timer of the browser in milliseconds (timestamp, not
a date), the time since the start of the recording in
milliseconds (elapsed), the position of the pointer (x, y,
x_raw, y_raw) and the zone it is in (zone_id, zone_name).
One row per zone and recording, with the object ID
(zone_id), the name, and the edges left, right, bottom and
top in normalised coordinates.
One row per file read, with its kind and number of rows.
read_eyetracking() for the Eye Tracking component.
## Not run: g <- read_gorilla("data") mouse <- read_mousetracking("data", x = g) mouse$mouse ## End(Not run)## Not run: g <- read_gorilla("data") mouse <- read_mousetracking("data", x = g) mouse$mouse ## End(Not run)
Describes each task and questionnaire in one row, as a first check of the data after reading them.
## S3 method for class 'gorilla_data' summary(object, fast = 200, slow = 10000, ...)## S3 method for class 'gorilla_data' summary(object, fast = 200, slow = 10000, ...)
object |
A |
fast, slow
|
Reaction times in milliseconds below |
... |
Not used. |
An object of class gorilla_summary: a list with two tibbles.
One row per task: builder, number of participants, number of responses per participant (minimum, median and maximum), the proportion of responses marked as correct, the median reaction time, the proportions of fast and slow responses and the median time participants spent on the task, in minutes. The proportion correct only means something for tasks with scoring set up in 'Gorilla': components without scoring mark every response as correct, and rating scales count a response as correct only if it matches the answer column of the spreadsheet.
One row per questionnaire: number of participants, number of items and the proportion of items left unanswered.
gorilla_checks() to list participants who may need a closer
look.
g <- read_gorilla(gorilla_example(), quiet = TRUE) summary(g) summary(g)$tasksg <- read_gorilla(gorilla_example(), quiet = TRUE) summary(g) summary(g)$tasks
Writes the tidy tables to a folder of CSV files, for analysis in other
software or for sharing. The folder gets up to four files:
participants.csv from gorilla_participants(), trials.csv from
gorilla_trials(), and questionnaires.csv from gorilla_wide() with
one row per participant. questionnaires_long.csv has the questionnaire
answers with one row per answer, as in x$questionnaires. Files for data
the export does not have are not written.
write_gorilla(x, path, by_task = FALSE, overwrite = FALSE)write_gorilla(x, path, by_task = FALSE, overwrite = FALSE)
x |
A |
path |
Folder to write to. It is created if it does not exist. |
by_task |
Write the trials of each task to its own file, named after
the task, instead of one |
overwrite |
Replace files that already exist in |
The files are UTF-8 with a comma as separator. Missing values are left
empty, and times are written in ISO 8601 format in UTC. The exports contain
the identifiers Gorilla collected, so use blind_ids() first if the files
will be shared.
The paths of the written files, invisibly.
g <- read_gorilla(gorilla_example()) out <- file.path(tempdir(), "gorilla_csv") files <- write_gorilla(g, out) basename(files) readr::read_csv(files[1], show_col_types = FALSE) unlink(out, recursive = TRUE)g <- read_gorilla(gorilla_example()) out <- file.path(tempdir(), "gorilla_csv") files <- write_gorilla(g, out) basename(files) readr::read_csv(files[1], show_col_types = FALSE) unlink(out, recursive = TRUE)