| 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] |
| Maintainer: | Tristan Mahr <[email protected]> |
| License: | GPL-2 |
| Version: | 0.1.2 |
| Built: | 2024-11-02 02:57:00 UTC |
| Source: | https://github.com/tjmahr/rprime |
Convert 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)
Convert a list of EprimeFrames into a FrameList object
as.FrameList(xs)as.FrameList(xs)
xs |
a list of EprimeFrames |
the original list as a FrameList object
This 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 of 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"
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 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
Filter 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.
Convert 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 EprimeFrames) is returned. when passed a
single vector 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"
These 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 whitelisted or blacklisted values for Eprime.Level |
Note that the meaning of 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 keep_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 FrameList (a list of EprimeFrames) |
preview_levels prints out the unique combinations of
Eprime.Level number, Procedure, and Running in the frame list.
preview_frames prints out example frame from each of the unique
levels. preview_eprime does both.
Nothing. Preview text is printed to the console.
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 Clock.Information XML entries. Enabled by default. |
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::str_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.
Convert Eprime Frames into data-frames
to_data_frame(x)to_data_frame(x)
x |
an EprimeFrame object, or a FrameList object (a list of EprimeFrames) |
Individual EprimeFrames are converted to a data-frame using
as.data.frame. (Strings are not converted to factors.)
Each of the individual data-frames are then rbinded together, with
missing columns being filled with NA.
all of the EprimeFrames combined into a single data frame.