Table of Contents


readspd - Get reading speeds (ERP DOS programs)


readspd scenariofile resultsfile
OR readspd scenariofile -d


readspd is used to present sentences either phrase-at-a-time or word-at-a-time in a self-paced manner to subjects. The program reads a scenariofile that describes sentences and questions to be presented, presents them to the subject, and finally records timing information in the Resultsfile.

readspd uses a "moving window" paradigm. Before each sentence is presented, dashes are displayed on the screen in every place that the sentence has a letter or punctuation character. As each word or phrase in the sentence is displayed, the dashes for that word are replaced with the actual word, and the letters for the previously displayed word are replaced with dashes. The subject presses the space bar to display each successive word or phrase in the sentence. For example, the sentence "This is a test." would be presented like this (each line shows what the screen looks like after you press the spacebar):

---- -- - -----
This -- - -----
---- is - -----
---- -- a -----
---- -- - test.
---- -- - -----


The resultsfile may be replaced with -d, in which case the scenario file is read, a synopsis of the scenario file contents is printed to stdout, and the program exits without presenting any of the stimuli. This is useful for debugging scenario files.


Scenario File Format

The scenario file describes the stimuli to be presented to the subject. A stimulus is nothing more than a sentence to be presented with the moving window paradigm, or a question that is displayed all at once rather than word at a time. Every line in the scenario file begins with one of 6 uppercase letters (to be described in a moment), a number unique to each stimulus(sentence) and a colon (’:’). These are followed by various parameters.

In the scenario file, the experimenter assigns a unique number to each stimulus (sentence or question displayed on the screen), and a digitial code to each word (or phrase) to be presented with the moving window paradigm. Each stimulus is also assigned a "task" name, which is the name for the experimental condition with which the stimulus is associated. We’ll take a look at the scenario file syntax by starting with an example. Our experiment consists of 4 sentences to be presented word at a time in the moving window paradigm, and we want to follow the the third and fourth sentences with questions. Also, we want the all the sentences except for the third one to be displayed on two lines. Note that only one sentence appears on the screen at a time, and that the questions appear all by themselves. The sentences are:

One fish, two fish,
Red fish, blue fish.

This one has a little star,
This one has a little car.

My what a lot of fish there are!

Some are red, some are blue,
Some are old, some are new.

The questions are:

The blue fish drives a car. (T/F)
How many fish are there? (0-9)

The scenario file for this experiment looks like this:

S1:    One    fish,    two    fish,
C1:    10    71    20    71
S1:    Red    fish,    blue    fish
C1:    31    70    41    70
T1:    intro
S2:    This    one    has    a    little    star,
C2:    1    11    1    1    1    1
S2:    This    one    has    a    little    car.
C2:    1    11    1    1    1    1
T2:    possess
S3:    My    what    a    lot    of    fish    there    are!
C3:    1    1    1    1    1    1    1    1
T3:    possess
Q4:    The blue fish drives a car. (T/F)
E4:    character tfTF
S5:    Some    are    red,    some    are    blue,
C5:    1    1    3     1    1    40
S5:    Some    are    old,    and    some    are    new.
C5:    1    1    1    1    1    1    1
T5:    describe
Q6:    How many fish are there? (0-9)
E6:    number 0-9
Q7:    Thank You for participating in our experiment!
Q7:    Press any key to quit.

Yes, this example has gotten pretty contrived already, but it should serve our purpose. Each line of each sentence is preceded by an ’S’, the number of the sentence, and a colon. Following each line of each sentence is a list of numbers. These are the digital codes associated with the words in the sentences. In the first sentence, the digital codes are assigned like this:

One(10) fish,(71) two(20) fish,(71)
Red(31) fish,(70), blue(41) fish(70).

Notice that tabs were used to make the digital codes line up with the words with which they are associated. You can do this because readspd ignores extra spaces and tabs in the scenario file.

One of the things you may have noticed was that there are two lines in the example scenario file that begin with "S1:". This is how you tell readspd that you want the first sentence to have more than one line on the screen. If you wanted the first sentence to have three lines, you would just add another "S1:" line to the scenario file.

As you may have guessed from Q7: in the example, questions can have more than one line too, by using the same sort of syntax used for muli-line sentence stimuli. The questions are centered on the screen in this way: if there is more than one line for a question, the longest line is centered, and all other lines are left-justified to the beginning of the longest line.

The line:

T1: intro
is used to associate sentence one with a task called "intro". This is just a convenient way of adding information to the results file that may be useful for analysis. readspd does NOT require you to associate a task identifier with every stimulus (sentence or question), but it is recommended that you do so.

readspd presents the first sentence like this:

--- ----- --- -----
--- ----- ---- -----
One ----- --- -----
--- ----- ---- -----
--- fish, --- -----
--- ----- ---- -----
--- ----- two -----
--- ----- ---- -----
--- ----- --- fish,
--- ----- ---- -----
--- ----- --- -----
Red ----- ---- -----
--- ----- --- -----
--- fish, ---- -----
--- ----- --- -----
--- ----- blue -----
--- ----- --- -----
--- ----- ---- fish.
--- ----- --- -----
--- ----- ---- -----

The line:

Q4: The blue fish drives a car. (T/F)
tells readspd to display this question centered on the screen after presenting sentence 3. The line:
E4: character tfTF
Tells readspd to allow a single character answer from among the letters ’t’, ’f’, ’T’, and ’F’ to this question. Any other response will simply cause the computer to beep. The ’E:’ command, as indicated in this example, describes allowable responses (expected responses) to questions, and is optional. If not given, the subject simply presses the space bar to continue. The syntax for the ’E:’ command is:
E#: response_type [optional parameters]
where response_type must be one of:
single character response. A list of allowable characters can be given as an optional parameter.
any string of characters
numbers only. A range of allowable numbers can be given as an optional parameter as in question 3 for the above example (only numbers in the range 0-9 were allowed in this case).

There is still one command that didn’t make it into the example. Use the ’A:’ command to provide an expected answer for a question. When questions are summarized in the results file, the actual answer and the expected answer (if it has been specified) are printed along with the text of the question. The content of the results file is described at the end of this section.

readspd can present sentences phrase-at-a-time as well as word-at-a-time. In fact, word-at-a-time is just a special case where each phrase consists of one word. To present a sentence in phrases, begin the sentence with a forward slash (’/’), and separate each phrase with a forward slash. For example, to present the sentence,

"My what a lot of fish there are!"
in three phrases, the scenario file would look like this:

S1:    /My    /what a lot    /of fish    /there are!
C1:    1    1        1        1

Note that there is only one digital code associated with each phrase.

Scenario File Format Summary

Here is a summary of the scenario file commands.

Sentence    S#:    word word word...
Task identifier    T#:    identifier
Digital Codes    C#:    code code code...
Question    Q#:    question text
Allowable Responses    E#:    response_type [parameters]
           response_type can be one of:

           character [character list]

           number [range]


Expected Answer    A#:    answer

Results File

The resultsfile contains information about all of the stimuli and timing information all in a columnized format that could easily be used with programs like awk for subsequent analyses. The output for the first sentence in our example would look something like this:

1    10    SENT    intro    383    383    One
1    71    SENT    intro    347    730    fish,
1    20    SENT    intro    348    1078    two
1    71    SENT    intro    313    1391    fish,
1    31    SENT    intro    270    1661    Red
1    70    SENT    intro    278    1939    fish,
1    41    SENT    intro    297    2236    blue
1    70    SENT    intro    334    2570    fish.

The first column contains the stimulus number. The second column contains the digital code associated with a particular word (or phrase). The third column contains the type: either SENT (for sentence) or QUEST (for question). The fourth column contains the task identifier. The fifth column contains the response time for each word in milliseconds (e.g. "two" was displayed for 348 milliseconds before the subject pressed the space bar). The sixth column contains the total elapsed time for the sentence to which each word belongs. The seventh column contains the word that was presented.

The output for questions is a little different than the output for sentences. For questions: the CODE column contains an asterisk (*), since there is no digital code for a question, and the TEXT column is preceded by the subject’s actual response, and the given expected answer or a hyphen (’-’) if none was supplied in the scenario file. For example, for Q3 in our example, the results file would contain a line like:

4    *    QUES    possess    1795    1795    [RESP:t] [EXPRES:-]    The blue fish drives a car. (T/F)

For questions, the RTIME and ETIME will always be the same. This is the number of milliseconds from the time the subject was presented with the question to the time the subject responded to the question.


Q:\PUBLIC\READSPD.EX1 -- the scenario file used in this example.


There are many possible error messages to describe errors that occurred while parsing the scenario file. These are all preceded by the line number where the error occurred, the text of the line with the error, and a (hopefully) understandable message describing the problem.

While presenting the stimuli, the following fatal errors are possible:

"Drawing time too slow"    
readspd took more than 5 milliseconds to draw a particular phrase on the computer monitor.
"Internal Clock Error"
Something went wrong with the PC timer chip that is used to time the stimuli.
"No memory for recording response"
This is fairly self-explanatory. Make sure somebody hasn’t executed a command shell on the computer without exiting. You can do this by typing "exit". Also, the DOS command "mem /c | more" gives useful information.
"Ran out of memory during sentence display"
This is a lot like the previous memory error.
"Cause undetermined!"
This one is highly unlikely, but if it should occur, see the author for some needed debugging!


Ron Ohst

Table of Contents