| Title: | Functions for Working with 'Eprime' Text Files |
|---|---|
| Description: | 'Eprime' is a set of programs for administering psychological experiments by computer. This package provides functions for loading, parsing, filtering and exporting data in the text files produced by 'Eprime' experiments. |
| Authors: | Tristan Mahr [aut, cre] (ORCID: <https://orcid.org/0000-0002-8890-5116>) |
| Maintainer: | Tristan Mahr <[email protected]> |
| License: | GPL-2 |
| Version: | 0.1.4 |
| Built: | 2026-11-04 01:25:03 UTC |
| Source: | https://github.com/tjmahr/rprime |
EprimeFrame objectConvert a list into an EprimeFrame object
as.EprimeFrame(xs)as.EprimeFrame(xs)
xs |
a list |
the original list as an EprimeFrame() object (along with dummy
Eprime metadata fields)
EprimeFrame objects into a FrameList objectConvert a list of EprimeFrame objects into a FrameList object
as.FrameList(xs)as.FrameList(xs)
xs |
a list of |
the original list as a FrameList() object
EprimeFrame objectThis constructor function converts a character vector into an
EprimeFrame object, which is just a list with some special metadata
values. Strings with the format "key: value" are parsed into key = value list items (via listify()).
EprimeFrame(keys_values)EprimeFrame(keys_values)
keys_values |
a character vector containing some |
a list with the class EprimeFrame and with special
Eprime. metadata, Running and Procedure values, all
set to NA by default.
# Default metadata values lines <- c( "key: value", "question: answer", "garbage text" ) EprimeFrame(lines) #> List of 8 #> $ Eprime.Level : num 1 #> $ Eprime.LevelName : logi NA #> $ Eprime.Basename : logi NA #> $ Eprime.FrameNumber: logi NA #> $ Procedure : logi NA #> $ Running : logi NA #> $ key : chr "value" #> $ question : chr "answer" # Normalize [Running] related lines keys_values <- c( "Running: Demo", "Demo: ExampleCode", "Demo.Cycle: 1", "Demo.Sample: 1", "Key: Value" ) EprimeFrame(keys_values) #> List of 9 #> $ Eprime.Level : num 1 #> $ Eprime.LevelName : chr "Demo_ExampleCode" #> $ Eprime.Basename : logi NA #> $ Eprime.FrameNumber: logi NA #> $ Procedure : logi NA #> $ Running : chr "Demo" #> $ Cycle : chr "1" #> $ Sample : chr "1" #> $ Key : chr "Value"# Default metadata values lines <- c( "key: value", "question: answer", "garbage text" ) EprimeFrame(lines) #> List of 8 #> $ Eprime.Level : num 1 #> $ Eprime.LevelName : logi NA #> $ Eprime.Basename : logi NA #> $ Eprime.FrameNumber: logi NA #> $ Procedure : logi NA #> $ Running : logi NA #> $ key : chr "value" #> $ question : chr "answer" # Normalize [Running] related lines keys_values <- c( "Running: Demo", "Demo: ExampleCode", "Demo.Cycle: 1", "Demo.Sample: 1", "Key: Value" ) EprimeFrame(keys_values) #> List of 9 #> $ Eprime.Level : num 1 #> $ Eprime.LevelName : chr "Demo_ExampleCode" #> $ Eprime.Basename : logi NA #> $ Eprime.FrameNumber: logi NA #> $ Procedure : logi NA #> $ Running : chr "Demo" #> $ Cycle : chr "1" #> $ Sample : chr "1" #> $ Key : chr "Value"
Locate a bundled example Eprime file
example_eprime_file(which)example_eprime_file(which)
which |
A short name or full filename identifying an example file.
Omit |
This function uses system.file() to locate files bundled with
rprime. Available short names are Blending, MINP, MP, SAILS1,
SAILS2, and not_an_eprime_file.
MP contains an interrupted experiment. not_an_eprime_file is a
non-Eprime file used to demonstrate how read_eprime() handles such input.
A filepath to the selected file. If which is missing, the named
vector of available filenames is printed and returned invisibly.
example_eprime_file() example_eprime_file("MINP") example_eprime_file("MINP_001L00XS1.txt") read_eprime(example_eprime_file("SAILS1"))example_eprime_file() example_eprime_file("MINP") example_eprime_file("MINP_001L00XS1.txt") read_eprime(example_eprime_file("SAILS1"))
Almost all of the information in an Eprime file comes in chunks of text
bracketed by the lines *** LogFrame Start *** and *** LogFrame End ***. The exception is the header information which is bracketed by
*** Header Start *** and *** Header End ***.
extract_chunks(eprime_log)extract_chunks(eprime_log)
eprime_log |
a character vector containing the lines of text from an Eprime txt file |
extract_chunks extracts the bracketed text, storing each log-frame of
text in a list. The lists also include some additional lines of text as
metadata: Eprime.FrameNumber and Eprime.Basename (the name of
the source file). The header log-frame also gets dummy lines:
Procedure: Header and Running: Header.
These character vectors of colon-separated lines are converted into proper
lists by FrameList().
a list of character vectors, where each vector contains the lines of a log-frame
lines <- read_eprime(example_eprime_file("MINP")) extract_chunks(lines)lines <- read_eprime(example_eprime_file("MINP")) extract_chunks(lines)
FrameList based on attribute valuesFilter levels in or out of a FrameList based on attribute values
filter_in(frame_list, key, values) filter_out(frame_list, key, values)filter_in(frame_list, key, values) filter_out(frame_list, key, values)
frame_list |
a list of |
key |
the name of the attribute to filter in or out |
values |
the whitelisted or blacklisted values of the attribute |
for filter_in(), only log-frames where key is one of the
values are kept. For filter_out(), log-frames where key
is one of the values are omitted.
EprimeFrame objectsConvert character vectors of implicit key-value pairs (e.g., c("key1: value1", "key2: value2")) into lists of explicit key-value pairs,
list(key1 = "value1", key2 = "value2").
FrameList(x)FrameList(x)
x |
a character vector with lines of the form |
During the conversion, if Running: x, then the
x.Sample and x.Cycle lines are simplified into Sample
and Cycle lines. The x: value line is recoded as
Eprime.LevelName: x_value. The purpose of this tidying is to force
the same set of key names (eventually, column names) onto frames with
different values for Running.
When passed a list of character vectors of "key: value" lines, a
FrameList() object (a list of EprimeFrame() objects) is returned. When
passed a single vector of "key: value" lines, a single
EprimeFrame() object is returned inside of a FrameList() object.
lines <- c( "\t*** LogFrame Start ***", "\tProcedure: FamTask", "\titem1: bear", "\titem2: chair", "\tCorrectResponse: bear", "\tImageSide: Left", "\tDuration: 885", "\tFamiliarization: 1", "\tFamInforcer: 1", "\tReinforcerImage: Bicycle1", "\tFamiliarization.Cycle: 1", "\tFamiliarization.Sample: 1", "\tRunning: Familiarization", "\tFamTarget.RESP: ", "\tCorrect: True", "\t*** LogFrame End ***" ) #> List of 1 #> $ :List of 17 #> ..$ Eprime.Level : num 2 #> ..$ Eprime.LevelName : chr "Familiarization_1" #> ..$ Eprime.Basename : chr "NA" #> ..$ Eprime.FrameNumber: chr "1" #> ..$ Procedure : chr "FamTask" #> ..$ Running : chr "Familiarization" #> ..$ item1 : chr "bear" #> ..$ item2 : chr "chair" #> ..$ CorrectResponse : chr "bear" #> ..$ ImageSide : chr "Left" #> ..$ Duration : chr "885" #> ..$ FamInforcer : chr "1" #> ..$ ReinforcerImage : chr "Bicycle1" #> ..$ Cycle : chr "1" #> ..$ Sample : chr "1" #> ..$ FamTarget.RESP : chr "" #> ..$ Correct : chr "True" #> ..- attr(*, "class")= chr [1:2] "EprimeFrame" "list" #> - attr(*, "class")= chr [1:2] "list" "FrameList"lines <- c( "\t*** LogFrame Start ***", "\tProcedure: FamTask", "\titem1: bear", "\titem2: chair", "\tCorrectResponse: bear", "\tImageSide: Left", "\tDuration: 885", "\tFamiliarization: 1", "\tFamInforcer: 1", "\tReinforcerImage: Bicycle1", "\tFamiliarization.Cycle: 1", "\tFamiliarization.Sample: 1", "\tRunning: Familiarization", "\tFamTarget.RESP: ", "\tCorrect: True", "\t*** LogFrame End ***" ) #> List of 1 #> $ :List of 17 #> ..$ Eprime.Level : num 2 #> ..$ Eprime.LevelName : chr "Familiarization_1" #> ..$ Eprime.Basename : chr "NA" #> ..$ Eprime.FrameNumber: chr "1" #> ..$ Procedure : chr "FamTask" #> ..$ Running : chr "Familiarization" #> ..$ item1 : chr "bear" #> ..$ item2 : chr "chair" #> ..$ CorrectResponse : chr "bear" #> ..$ ImageSide : chr "Left" #> ..$ Duration : chr "885" #> ..$ FamInforcer : chr "1" #> ..$ ReinforcerImage : chr "Bicycle1" #> ..$ Cycle : chr "1" #> ..$ Sample : chr "1" #> ..$ FamTarget.RESP : chr "" #> ..$ Correct : chr "True" #> ..- attr(*, "class")= chr [1:2] "EprimeFrame" "list" #> - attr(*, "class")= chr [1:2] "list" "FrameList"
FrameList based on Eprime.Level valuesThese functions are shortcuts for calls to filter_in() or
filter_out().
keep_levels(frame_list, level_numbers) drop_levels(frame_list, level_numbers)keep_levels(frame_list, level_numbers) drop_levels(frame_list, level_numbers)
frame_list |
a list of |
level_numbers |
the included or excluded values for |
Note that the meaning of the Eprime.Level value in a log-frame ultimately is
equal to one plus the number of tabs before each line in the log-frame.
for keep_levels(), only log-frames where the level matches one
of the level_numbers are kept. For drop_levels(), log-frames
where the level matches one of the level_numbers are omitted.
Convert a vector of colon-separated text lines into a list of named elements
listify(colon_sep_xs)listify(colon_sep_xs)
colon_sep_xs |
a character vector with lines of the form
|
Some minor cleaning of the input is performed:
Lines without a colon-space separator ": " are filtered out.
Once the strings are split at the separator, white-space on the left and right sides of each half-string is omitted.
a named list of the values in the colon-separated lines.
"key: value" yields list(key = "value")
Preview the levels in a parsed Eprime file
preview_eprime(frame_list) preview_levels(frame_list) preview_frames(frame_list)preview_eprime(frame_list) preview_levels(frame_list) preview_frames(frame_list)
frame_list |
a |
preview_levels() prints out the unique combinations of
Eprime.Level number, Procedure, and Running in the frame list.
preview_frames() prints out an example frame from each of the unique
levels. preview_eprime() does both.
The input FrameList() object, invisibly. Preview text is printed
to the console.
data <- read_eprime(example_eprime_file("MINP")) |> FrameList() |> preview_eprime()data <- read_eprime(example_eprime_file("MINP")) |> FrameList() |> preview_eprime()
Read in a text file generated by Eprime
read_eprime(filename, remove_clock = TRUE)read_eprime(filename, remove_clock = TRUE)
filename |
Either the full or relative path to an Eprime .txt file |
remove_clock |
Whether to exclude the |
The encoding on an Eprime txt file should be UCS-2 Little Endian,
but sometimes this is not the case. We delegate the fussy encoding details
to the stringi::stri_read_lines() function.
If the file is not an Eprime txt–that is, if it is missing the lines
*** Header Start *** and *** Header End ***–a warning is
raised and the lines of text are replaced by a dummy header.
Each line of the file is stored and returned in a character vector.
EprimeFrame objects into dataframesConvert EprimeFrame objects into dataframes
to_data_frame(x)to_data_frame(x)
x |
an |
Individual EprimeFrame() objects are converted to a dataframe
using as.data.frame(). (Strings are not converted to factors.)
The individual dataframes are then rbind()-ed together, with
missing columns being filled with NA.
all of the EprimeFrame() objects combined into a single dataframe.