In LearningToTalk/L2TWordLists: Create WordLists for L2T Word-Repetition Experiments

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)

L2TWordLists

The goal of L2TWordLists is to provide some convenient high-level functions for working with Eprime files produced by our real-word repetition and non-word repetition experiments.

Installation

Install L2TWordLists from GitHub with:

# install.packages("devtools")
devtools::install_github("LearningToTalk/L2TWordLists")

Usage

Parse an Eprime file to get trial-level information:

library(dplyr, warn.conflicts = FALSE)
library(L2TWordLists)

rwr_file <- "./tests/testthat/test-files/TimePoint3/RealWordRep_008L54MS5.txt"

# Parse Eprime file
df_rwr_trials <- get_rwr_trial_info(rwr_file)
df_rwr_trials

Create a WordList table using that trial-level information:

df_rwr_wordlist <- lookup_rwr_wordlist(df_rwr_trials)
df_rwr_wordlist

Analogous functions are available for the nonword-repetition task.

nwr_file <- "./tests/testthat/test-files/TimePoint3/NonWordRep_001L53FS5.txt"

# Parse Eprime file
df_nwr_trials <- get_nwr_trial_info(nwr_file)
df_nwr_trials

# Create Wordlist
df_nwr_wordlist <- lookup_nwr_wordlist(df_nwr_trials)
df_nwr_wordlist

Save a read-only copy of a WordList table:

# Save wordlist to a temporary file (for illustration purposes)
outpath <- tempfile("my-wordlist", fileext = ".txt")
write_protected_tsv(df_rwr_wordlist, outpath)

# mode is `444` when a file is read-only
file.info(outpath)[["mode"]]

# returns -1 when write permissions are unavailable
unname(file.access(outpath, 2))

Create a WordList from a Participant ID

# Clean up any leftovers from last time
"./tests/testthat/l2t/RealWordRep/TimePoint1/WordLists/" %>% 
  list.files(full.names = TRUE) %>% 
  unlink(force = TRUE)

# Clean up any leftovers from last time
"./tests/testthat/l2t/NonWordRep/TimePoint1/WordLists/" %>% 
  list.files(full.names = TRUE) %>% 
  unlink(force = TRUE)

The functions create_rwr_wordlist_file() and create_nwr_wordlist_file() are shortcuts that will create a WordList for a particular participant. These functions replicate the main functionality of our older R scripts. All the user needs to provide is a participant ID, a study name, and a task directory.

# Using a mock location for the package documentation...
task_dir <- "./tests/testthat/l2t/RealWordRep"
study_name <- "TimePoint1"
participant_id <- "001L"

create_rwr_wordlist_file(participant_id, study_name, task_dir)

Here's an analogous example for nonword repetition.

nwr_task_dir <- "./tests/testthat/l2t/NonWordRep"
nwr_study_name <- "TimePoint1"
nwr_participant_id <- "124L"

create_nwr_wordlist_file(nwr_participant_id, nwr_study_name, nwr_task_dir)

WordList creation options

The following examples show the options available to both functions, but use only the real-word-repetition function for conciseness.

By default, the function will not overwrite a WordList.

create_rwr_wordlist_file(participant_id, study_name, task_dir)

We can update a WordList with update = TRUE, however:

create_rwr_wordlist_file(participant_id, study_name, task_dir, update = TRUE)

If we set the participant ID to a blank "", then the function will create a WordList for every participant ID in a study folder.

create_rwr_wordlist_file("", study_name, task_dir, update = TRUE)

The function invisibly returns a list with the generated WordList and the file location. That is, we can run the function by itself and not see the generated WordList printed out --- this prevents the console from being flooded with data-frame print-outs. But we can assign the results of the function to a variable and see the WordList data and file locations. In this case, two WordsLists have been updated:

results <- create_rwr_wordlist_file("", study_name, task_dir, update = TRUE)
str(results)

# Clean up
"./tests/testthat/l2t/RealWordRep/TimePoint1/WordLists/" %>% 
  list.files(full.names = TRUE) %>% 
  unlink(force = TRUE)

Packaged stimulus information

Tables of stimulus information about the items in our word-repetition experiments are bundled with the package and accessible with l2t_wordlists.

Default forms of the list are stored by Task and TimePoint, and custom one-off lists are stored in a separate list.

l2t_wordlists

Test data coverage

list_files <- function(...) {
  list.files(..., full.names = TRUE, recursive = TRUE)
}

files <- c(
  list_files(testthat::test_path("test-files"), pattern = ".txt"),
  list_files(testthat::test_path("misc-files"), pattern = ".txt"))

df_eprime <- data_frame(
 Eprime_Path = files,
 Study = basename(dirname(Eprime_Path)),
 Eprime_Basename = basename(Eprime_Path) %>% tools::file_path_sans_ext(),
 Task = stringr::str_extract(Eprime_Basename, "^.+WordRep"))

df_exp_info <- df_eprime$Eprime_Path %>% 
  lapply(get_rwr_trial_info) %>% 
  bind_rows() %>% 
  group_by(TimePoint, Dialect, Experiment, Eprime.Basename) %>% 
  summarise(NumTrials = n()) %>% 
  ungroup %>% 
  rename(ExperimentName = Experiment, Eprime_Basename = Eprime.Basename)

df_test_info <- df_eprime %>% 
  left_join(df_exp_info) %>% 
  select(Task, Study, Dialect, ExperimentName, NumTrials) %>% 
  distinct() %>% 
  arrange(Task, Study, Dialect, ExperimentName, desc(NumTrials)) 

We created our WordList tables using an incrementally developed suite of R scripts. These original WordList tables are used to validate the behavior of this package by comparing the original tables against the ones generated by this package. These tests are in the tests folder.

The testing data was selected to use all available combinations of dialect, experiment name (i.e., the name of the Eprime executable that generated the output), and trial counts among our collected data. The table belows shows each of the combinations of dialect, experiment name, and trial counts that are tested in this package.

knitr::kable(df_test_info)

The build status badge at the top of this page indicates whether the package successfully passed all these tests (and also passed the standard checks for R packages).

LearningToTalk/L2TWordLists documentation built on May 8, 2019, 9:52 p.m.