Skip to contents

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).

Usage

read_gorilla(path, quiet = FALSE)

Arguments

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 data_exp_, the names 'Gorilla' gives its downloads. Files named directly are read whatever their name.

quiet

If TRUE, no message about skipped files is shown.

Value

An object of class gorilla_data: a list with

tasks

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.

questionnaires

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.

participants

One row per participant. See gorilla_participants().

files

One row per file read, with the experiment, version, node, builder, task and number of rows.

Details

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.

Examples

path <- gorilla_example()
g <- read_gorilla(path)
#> Skipped 1 file without data (nodes no participant reached): data_exp_123456-v3_questionnaire-zz1e.csv
g
#> <gorilla_data> experiment 123456, version 3
#> 6 participants
#>   complete: 5, live: 1
#> Tasks:
#>   Lexical decision (Task Builder 2): 6 participants
#>   Rhyme judgement (Task Builder 1): 5 participants
#> Questionnaires:
#>   Background: 7 items, 6 participants
#>   Consent: 2 items, 6 participants
#> 1 empty file skipped
g$files
#> # A tibble: 5 × 8
#>   file                        experiment version node  kind  builder task   rows
#>   <chr>                       <chr>      <chr>   <chr> <chr> <chr>   <chr> <int>
#> 1 data_exp_123456-v3_questio… 123456     3       ques… ques… questi… Back…    66
#> 2 data_exp_123456-v3_questio… 123456     3       ques… ques… questi… Cons…    36
#> 3 data_exp_123456-v3_questio… 123456     3       ques… ques… questi… NA        0
#> 4 data_exp_123456-v3_task-ld… 123456     3       task… task  task_b… Lexi…   104
#> 5 data_exp_123456-v3_task-rh… 123456     3       task… task  task_b… Rhym…    90