[Top] [Contents] [Index] [ ? ]

ESP Manual


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. Overview

ESP (Experience Sampling Program) is free software for Palm Pilots to gather data from people in their daily lives. ESP displays questions, receives responses, and measures reaction times. It is useful for surveys, questionnaires, and scientific research.

In a nutshell:

  1. You (the experimenter) hand out Palm Pilots to a bunch of people (the participants).
  2. The Palms ask questions to your participants, recording their responses and reaction times. The set of questions can be asked as many times as you want. Each time is called a trial.
  3. You upload the data to your favorite PC for analysis.

ESP is provided with no support. However, there is an ESP mailing list where you can discuss the software with other researchers. See section For More Information.

The development of this software was supported by National Science Foundation grant BCS 0322352 to Lisa Feldman Barrett.

About ESP

ESP for the Palm Pilot has two modes of operation:

Let’s look at some examples.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Manual Mode: What it Looks Like

Manual mode is for event-contingent sampling, which is a fancy way of saying the participant launches the trials. Initially the Palm displays the screen:

pix/esp-manual

At any time, the participant may tap the screen to begin a trial. She is guided through a sequence of questions, each with a set of response buttons at the bottom of the screen. For example:

pix/esp-question

When each question is answered, the next appears, until the last question has been answered. The participant is once again presented with:

pix/esp-manual

and the process may be repeated.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Automatic Mode: What it Looks Like

Automatic mode is for fixed or random sampling, which means that ESP launches the trials itself. The participant is prompted to answer questions at times determined by the experimenter. Initially the Palm sleeps and displays a neutral screen:

pix/esp-wait

When the time arrives for a trial, the Palm beeps (for a predetermined time set by the experimenter) and displays:

pix/esp-hello

The participant has a limited time to respond (determined by the experimenter). If there is no response, ESP ends the trial and returns to sleep.

If the participant taps anywhere on the screen, however, she is then guided through a sequence of questions, each with a set of response buttons at the bottom of the screen. For example:

pix/esp-question

The participant once again has limited time to answer each question (again, determined by the experimenter). If she fails to respond to a question within the allowed time, the trial ends and ESP goes back to sleep. Otherwise, she responds to each question in sequence until the last question has been answered and the trial ends.

pix/esp-wait

After a number of trials (set by the experimenter), the experiment ends, and the participant is shown:

pix/esp-goodbye
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Terminology

Packages

ESP 4.0 includes a suite of software packages:

The program ESPView, supplied with older versions of ESP, is no longer needed nor recommended. Use ESP Desktop instead.

Experiments

The largest unit in ESP is called an experiment. It consists of:

People

The person who sets up ESP is called the experimenter. The experimenter runs ESP Desktop and/or ESPPrefs and designs questions. When we say “you” in this document, we generally mean the experimenter.

The people who use ESP are called the participants.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2. Installation

To run ESP in its full glory, you will need:

Be prepared to dedicate your Palms and your desktop computer to ESP. This means:

ESP and ESPPrefs should run properly on most Palms and compatibles. You should be thoroughly familiar with Palm usage, including:

Now let’s see how to install ESP.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1 Installing on Windows

Prerequisites

ESP has been tested on Windows XP. It will probably work fine on most other versions of Windows. Please tell us about any combinations that do or don’t work.

Before installing ESP on a Windows machine, you must install:

Make sure these programs are installed before proceeding.

Installing ESP

To install this software, you will need administrator privileges on your Windows machine. Then follow these directions:

  1. Make sure you have installed the prerequisites listed above.
  2. If you haven’t already done so, download ESP from the ESP web site. For Windows, ESP is provided as an installer program, EspDesktopConduitInstaller.
  3. Double-click on EspDesktopConduitInstaller and follow the instructions. Some important notes:

    You have finished installing ESP. Now you must configure the Mozilla or Firefox browser to run ESP Desktop. This involves editing a Mozilla/Firefox system file to add one line.

  4. Locate the system directory containing Mozilla or Firefox’s system files. On Windows systems it is often ‘C:/Program Files/Mozilla’ or ‘C:/Program Files/Mozilla Firefox’.
  5. Locate the ‘chrome’ subfolder and enter it.
  6. Locate the file ‘installed-chrome.txt’ and edit it with a plain text editor such as WordPad. (Don’t use a word processor like Word or Wordperfect: you might destroy the file. Notepad also isn’t great: it deals poorly with linebreaks.) If the file does not exist (which is the case in Firefox 1.5 and higher), create your own in the ‘chrome’ subfolder.
  7. Copy the line below and paste it into the file ‘installed-chrome.txt’ at the very end, on a line by itself:
     
    content,install,url,file:///c:/Program%20Files/esp4/
    

    and press ENTER afterward.

    NOTE: Mozilla and Firefox each have their own ‘installed-chrome.txt’ file. To use both browsers with ESP Desktop, you must paste the above line into both ‘installed-chrome.txt’ files.

  8. You’re ready to run ESP Desktop. Run Mozilla and hit the URL:
     
    chrome://espdesktop/content/desktop.xul
    

    The first time you run ESP Desktop, you might see a warning about unsafe operation. See section Special note about permissions.

  9. Test ESP Desktop by running its built-in self-test. Under the Help menu, select Test ESP Desktop and follow the instructions. See section Testing the Installation.

If the installation failed, or if ESP Desktop will not run, See section Troubleshooting. For a list of known bugs, See section Bugs.

Uninstalling ESP

  1. In the Windows Control Panel, run Add Or Remove Programs, and uninstall every program whose name contains “ESP Desktop.”
  2. Delete the folder ‘C:/Program Files/esp4’.
  3. (Optional.) Delete the ESP Preferences held within your web browser. Shut down all copies of Mozilla and/or Firefox. Then locate your browser preferences file ‘prefs.js’, which is usually found somewhere in:

    Edit ‘prefs.js’ using a plain text editor like Emacs or WordPad, not a word processor like Word or WordPerfect which will destroy the file. (Notepad isn’t great either: it doesn’t deal well with linebreaks.) Delete all lines that set a preference beginning with “esp.”, such as:

     
    user_pref(esp.download.deletedata, true);
    user_pref(esp.latestexperiment, ...);
    user_pref(esp.questioneditor, ...);
    user_pref(esp.upload.esp, true);
    user_pref(esp.upload.espprefs, true);
    user_pref(esp.upload.initialize, false);
    user_pref(esp.upload.preferences, true);
    user_pref(esp.upload.preserveIDs, false);
    user_pref(esp.upload.questions, true);
    

    Then delete the lines that look like:

     
    user_pref(capability.principal.codebase.p0.granted, UniversalXPConnect);
    user_pref(capability.principal.codebase.p0.id, file://);
    
  4. If you want to use this PC for other Palm hotsynching, reinstall your Palm Desktop software.
  5. On your Palm(s), delete the applications “ESP” and “ESPPrefs.”

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2 Installing on Linux

ESP was developed and tested on SUSE Linux Professional 9.1. It will probably work fine on most other Linux distributions. Please tell us about any combinations that do or don’t work.

Prerequisites

Before installing ESP on a Linux machine, you must install some other packages. Most Linux distributions include them, though they might not be installed by default, so check your computer and your installation media.

Make sure these programs are installed before proceeding.

Also, if you have other hotsync software running, such as KDE’s kpilot, uninstall it. Otherwise kpilot will monopolize the USB port where your ESP Palm is connected, preventing ESP Desktop from finding your Palm. (Many KDE installations have kpilot enabled by default.)

Installing ESP

  1. Make sure you have installed the prerequisites listed above.
  2. If you haven’t already done so, download ESP from the ESP web site. For Linux, ESP is provided in a compressed tar file, ‘esp4-linux.tar.gz’.
  3. Extract the contents of ‘esp4-linux.tar.gz’ into ‘/usr/local’, e.g.,
     
    cd /usr/local
    tar xvzf <path>/esp4-linux.tar.gz
    

    When tar is finished, you’ll see it has created a subdirectory, ‘/usr/local/esp4’. This is where all the ESP system files are kept.)

    You have finished installing ESP. Now you must configure the Mozilla or Firefox browser to run ESP Desktop. This involves editing a Mozilla/Firefox system file to add one line.

  4. Locate the system directory containing Mozilla or Firefox’s system files. On Linux systems it might be ‘/usr/local/mozilla’, ‘/opt/mozilla/lib’, ‘/usr/share/mozilla’, etc.
  5. Locate the ‘chrome’ subdirectory and enter it.
  6. Locate the file ‘installed-chrome.txt’ and edit it with a text editor such as emacs or vi. (Don’t use a word processor: you’ll destroy the file.) If the file does not exist (which is the case in Firefox 1.5 and higher), create your own in the ‘chrome’ subdirectory.
  7. Copy the line below and paste it into the file ‘installed-chrome.txt’ at the very end, on a line by itself:
     
    content,install,url,file:///usr/local/esp4/
    

    and press ENTER afterward.

    NOTE: Mozilla and Firefox each have their own ‘installed-chrome.txt’ file. To use both browsers with ESP Desktop, you must paste the above line into both ‘installed-chrome.txt’ files.

  8. You’re ready to run ESP Desktop. Run Mozilla or Firefox (as appropriate) and hit the URL:
     
    chrome://espdesktop/content/desktop.xul
    

    The first time you run ESP Desktop, you might see a warning about unsafe operation. See section Special note about permissions.

  9. Test ESP Desktop by running its built-in self-test. Under the Help menu, select Test ESP Desktop and follow the instructions. See section Testing the Installation.

If the installation failed, or if ESP Desktop will not run, See section Troubleshooting. For a list of known bugs, See section Bugs.

Uninstalling ESP

  1. Delete the directory ‘/usr/local/esp4’ and its contents.
  2. (Optional.) Delete the ESP Preferences held within your web browser. Shut down all copies of Mozilla and/or Firefox. Then locate your browser preferences file ‘prefs.js’, which is usually found somewhere in:

    Edit ‘prefs.js’ using a plain text editor like Emacs or WordPad, not a word processor like Word or WordPerfect which will destroy the file. (Notepad isn’t great either: it doesn’t deal well with linebreaks.) Delete all lines that set a preference beginning with “esp.”, such as:

     
    user_pref(esp.download.deletedata, true);
    user_pref(esp.latestexperiment, ...);
    user_pref(esp.questioneditor, ...);
    user_pref(esp.upload.esp, true);
    user_pref(esp.upload.espprefs, true);
    user_pref(esp.upload.initialize, false);
    user_pref(esp.upload.preferences, true);
    user_pref(esp.upload.preserveIDs, false);
    user_pref(esp.upload.questions, true);
    

    Then delete the lines that look like:

     
    user_pref(capability.principal.codebase.p0.granted, UniversalXPConnect);
    user_pref(capability.principal.codebase.p0.id, file://);
    
  3. If you uninstalled your previous hotsync software such as kpilot, reinstall it.
  4. On your Palm(s), delete the applications “ESP” and “ESPPrefs.”

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3 Testing the Installation

After installing ESP on your desktop computer, you can check if it’s properly installed. Run ESP Desktop and in the Help menu, select Test ESP Desktop. Follow the instructions and you’ll get a report of success or failure at the end. If there’s a failure, See section Troubleshooting.

If you cannot run ESP Desktop at all, then you probably forgot (or messed up) the step about editing the ‘installed-chrome.txt’ file.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4 Using ESP without ESP Desktop

If you are a masochist, you can run experiments without ESP Desktop. Older versions of ESP worked this way. In this case:

In short: take the time to use ESP Desktop. It is much more convenient.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.5 Upgrading ESP

ESP 4.0 is more powerful than our old ESP 2 and its offshoot iESP (see section iESP) and includes important new features like ESP Desktop (see section ESP Desktop). However, ESP 4.0 is not completely compatible with the older versions. Your questions (the most complex part of your ESP experiment) are compatible, but other parts are not. The following table explains what is compatible and what to do about it.

Old ESP FeatureCompatible with ESP 4.0?To Upgrade to ESP 4.0
Questions (stored in the Palm Memo Pad)YesSimply reuse the questions, unchanged. ESP 4.0 supports the same extended types of questions as iESP. (ESP 2 does not.) By the way, ESP Desktop will copy your questions to a fleet of Palms on request.
Settings (created by ESPPrefs)NoLaunch ESPPrefs on an existing Palm running ESP 2 or iESP, and write down your configuration for safekeeping. Then recreate it using ESP Desktop. This might seem like a pain, but there aren’t really many settings, and ESP Desktop will conveniently deploy your new settings to a whole fleet of Palms.
Experiment results contained in .PDB filesNoFor posterity, use ESPView from ESP 2 (or iESPView from iESP) to convert your PDB files into human-readable format. These files are not used by ESP 4.0. When you run experiments with ESP 4.0, use ESP Desktop and you’ll never need to look at .PDB files.
ESPViewNoUse ESP Desktop

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.6 Inventory

Here’s a list of what gets installed with ESP.

Just about everything is placed into a single directory (folder):

PlatformDirectory/Folder
Windows:C:/Program Files/esp4
Linux:/usr/local/esp4

Within this directory you’ll find:

On Windows, several DLL files are also placed into ‘C:\Program Files\Palm’:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. Creating Questions

The experimenter creates the questions that ESP asks during each trial. The same set of questions is used in every trial. However:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1 Overview of Questions

ESP’s questions are stored in the Palm’s Memo Pad, one question per memo pad entry. You may create the questions in three ways:

You may create as many questions as you like, limited only by available memory.

Each question must be stored in a separate Memo Pad entry. Do not make the mistake of typing all your questions into a single memo on multiple lines. This won’t work. You need to create a separate memo for each question.

Each question occupies one memo in the Memo Pad.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2 Ordinary Questions

Ordinary questions are the same type supported by the original ESP for the Palm. An ordinary question consists of five parts:

  1. An integer ID number, either positive or negative, that uniquely identifies the question. Do not use zero.
  2. The symbol "|" (vertical bar) which indicates the end of the ID number.
  3. The question itself. It may contain any text except:
  4. The symbol "|" (vertical bar) which indicates the end of the question text.
  5. One or more labels for the response buttons at the bottom of the screen, left to right. Labels are separated by (you guessed it) vertical bars.

For example, the question "How are you feeling today?" with a unique ID of 37 and response buttons labeled "good", "bad", and "lousy" would be:

 
37|How are you feeling today?|good|bad|lousy

Notice that there is no additional space (i.e., space characters, tabs) surrounding the vertical bars, and there are no vertical bars at the beginning or end. Think of the vertical bars as separators: they go between items. Later versions of ESP are a bit more lenient about extra space, but for maximum compatibility, avoid it.

ESP will display this question as follows:

pix/esp-question-example

You may define as many button labels as will fit on one row of the screen. If you define too many, the screen will simply not look right (so be sure to examine each question’s screen before running your experiment).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.1 Response Types

By default, the responses for a question are presented as buttons in a horizontal row. You can change this with the %TYPE keyword.

 
37|How are you feeling today? %TYPE popup|good|bad|lousy

Supported %TYPE values are:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.2 About Question IDs

You must assign each question a unique, integer-valued ID between 1 and 32768, or between -1 and -32768. (Zero is not permitted.) These IDs serve two important purposes.

  1. They are stored with the participant’s responses. Therefore, in your data, you can identify which question is associated with each response. In this example question:
     
    37|How are you feeling today?|good|bad|lousy
    

    a "37" would be stored with the participant’s response.

  2. They may determine the order that the questions are asked in a trial. If you do not randomize the questions, they are asked in increasing numeric order by ID.

Your question IDs must be unique. If not, you will not be able to identify the question associated with each response.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.3 Negative Question IDs

You may choose negative IDs for your questions (-1, -2, etc.). If you choose to randomize the order of the questions, negative IDs have a special purpose. Questions with negative IDs never get randomized: they are always asked in ascending order. Therefore, they always come before the randomized questions.

For example, suppose you specify the following questions:

 
1|Who?|a|b|c
2|What?|a|b|c
37|Why?|a|b|c
16|Where?|a|b|c
5|When?|a|b|c
-4|Are you ready to begin?|yes|no

If you do not randomize the questions, they will be asked in strictly increasing order: -4, 1, 2, 5, 16, 37. However, if you randomize the questions, the one with the negative ID ("Are you ready to begin?") will always be asked first. This allows your experiment to ask fixed, preliminary questions before beginning randomized questions.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.4 What About Other Memo Pad Entries?

ESP notices only those Memo Pad entries that contain a "|" (vertical bar) in the text. Anything else in the Memo Pad is ignored by ESP. (So you could make notes to yourself if desired.)


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3 Branching Questions with %NEXT

During a trial, by default, ESP presents its questions strictly in order by question ID. Sometimes you’ll want to ask a question based on the answer to a previous question, e.g., "If the participant responds Yes, go to question 15, otherwise go question 71." ESP supports control of this kind using branching questions. (Branching was added by iESP.)

To create a branching question, add the keyword %NEXT to any response, followed by a question ID. For example, the question:

 
10|How are you feeling?|Good %NEXT 20|Bad %NEXT 30|Hungry %NEXT 40

branches to question 20, 30, or 40, if the participant responds Good, Bad, or Hungry, respectively. Here’s a more fleshed-out example:

 
10|How are you feeling?|Good %NEXT 20|Bad %NEXT 30|Hungry %NEXT 40
20|I'm glad to hear that|OK %NEXT 50
30|Sorry to hear that|OK %NEXT 50
40|Would you like a doughnut?|Yes|No
50|Goodbye|OK

For example, if the participant sees question 10 and responds Bad, the next question displayed is 30, "Sorry to hear that." The participant responds OK, which branches to question 50, displaying "Goodbye".

Alternatively, if the participant sees question 10 and responds Hungry, the next question displayed is 40, "Would you like a doughnut?" Question 40 does not have any %NEXT keywords, so no matter how the participant responds, the next question will be the one with the next-higher ID, 50, "Goodbye."

You can also add %NEXT to the body of a question:

 
10|How are you feeling? %NEXT 200|Good|Bad|Hungry

which causes control to pass to question 200 after question 10, unconditionally.

%NEXT cannot refer to a question set ID, only a question ID.

 
This is illegal:
%QSET 1|100|Is this illegal?|yes|no %NEXT 101
%QSET 1|101|You cannot jump into a question set!|OK

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4 Probabilistic Questions with %PROB and %SNEXT

By default, ESP asks all questions (unless you branch around them; see section Branching Questions with %NEXT). You can change this by assigning a probability to a question. (Probabilities were added by iESP.)

You assign a probability to a question with the %PROB keyword, like this:

 
10|How are you feeling? %PROB 50|Good|Bad|Hungry

The above question has a 50% likelihood of being asked. If it is not asked, it is skipped. When a question is skipped, control will pass to the "next" question in the experiment. This is ordinarily the question with the next higher ID.

 
10|How are you feeling? %PROB 50|Good|Bad|Hungry
20|What's your favorite fruit?|Apple|Banana|Cherry

In the above example, whether question 10 is asked or not, control passes to question 20. From our discussion of branching (see section Branching Questions with %NEXT), you know you can control the next question with the %NEXT keyword. But this applies only if the question is asked. What if it is skipped? You control this possibility with the %SNEXT keyword, which means "Skipped Next". For example, this question has a 75% probability of being asked:

 
10|How are you feeling? %PROB 75 %NEXT 30 %SNEXT 40|Good|Bad|Hungry

If asked, ESP will continue to question 30. However, if the question is skipped, the next question will be 40.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5 Question Sets with %QSET

ESP 4.0 has a new feature called question sets so you can do sampling of questions in a trial. Sampling may be ordered or random.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.1 Defining a Question Set

A question set is simply a set of ESP questions, defined in the Memo Pad as usual, but each question is preceded by:

  1. The string %QSET
  2. Whitespace
  3. A vertical bar

For example, if you have the following three questions:

 
10|This is the first question|OK
11|This is the second question|OK|Thanks
12|This is the third question|OK|Thanks|Goodbye

you turn them into a question set (say, with ID 5) like this:

 
%QSET 5|10|This is the first question|OK
%QSET 5|11|This is the second question|OK|Thanks
%QSET 5|12|This is the third question|OK|Thanks|Goodbye

These lines merely define a question set, but they do not use the questions in the experiment. They will not appear to any participants until you sample from the question set.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.2 Sampling from Question Sets with %CHOOSE and %RANDOM

There are two ways to sample questions from a question set: ordered and random. Ordered sampling will use the questions in numeric order by question ID. Random sampling will choose random questions from the set.

Notice that the question set itself does not specify ordered or random sampling. It’s just a set. The choice of ordered vs. random is made when you refer to the set, using a special question called a sampler. A sampler is a question that means "sample one question from a given set." Here is one example of a sampler that chooses a question from set 25:

 
100|%CHOOSE 25

Note that like other questions, this one begins with a question ID (100), but its question part is a sampler: the special keyword %CHOOSE, followed by the ID of the question set you’re sampling.

All sampling is without replacement for a given trial. In other words, if question 16 is sampled during a trial, it will not be sampled again during that trial. If you have ten questions in a question set, and you sample it ten times, you’ll get each question exactly once. If you sample from that set an eleventh time, that’s an error in your experiment.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.2.1 A limitation of %QSET

If you have a question set containing only N questions, your experiment may not sample from that question set more than N times. That’s to be expected, since we sample without replacement, but there is also an associated bug: your experiment may not contain more than N questions that sample from that set. If you do, ESP may display the error “No questions in Question Set” and crash, even if the logic of your experiment would prevent sampling more than N times from your experiment.

For example, the following experiment will obviously cause trouble because it’s sampling too many times:

 
%QSET 1|100|Sampled question|OK
1|%CHOOSE 1
2|%CHOOSE 1

There is only one question to sample, but you’re sampling twice. That’s clearly bad; but the next example is less obvious:

 
%QSET 1|10|Sampled question|OK %NEXT 999
50|%CHOOSE 1
51|%CHOOSE 1
999|Goodbye|OK

This experiment “should” work, but it doesn’t. Although we sample twice from a question set with only one question, the second %CHOOSE should never run. That’s because the first %CHOOSE will branch to question 999 and end the trial. However, because of the above-mentioned limitation, the experiment will fail.

We hope to eliminate this limitation in the future. In the meantime, if your experiment must include more %CHOOSE or %RANDOM statements than the size of your question set, there is a workaround. Define several identical question sets (with different IDs) and sample from them as needed.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.2.2 Ordered Sampling from Question Sets with %CHOOSE

Ordered sampling is done with the %CHOOSE sampler keyword. Suppose you have a question set:

 
%QSET 5|10|This is the first question|OK
%QSET 5|11|This is the second question|OK|Thanks
%QSET 5|12|This is the third question|OK|Thanks|Goodbye

The statement:

 
%CHOOSE 5

means sample once from question set 5. Each time you apply %CHOOSE to a question set, the next question (in numeric order by ID) is retrieved and used.

This sampler itself is a question in your experiment, with its own ID number, say, 200:

 
200|%CHOOSE 5

Here is a complete experiment with the question set and several %CHOOSE statements:

 
%QSET 5|10|This is the first question|OK
%QSET 5|11|This is the second question|OK|Thanks
%QSET 5|12|This is the third question|OK|Thanks|Goodbye
200|%CHOOSE 5
201|%CHOOSE 5

This experiment will produce the following sequence of questions:

 
This is the first question
This is the second question

Here’s another example:

 
%QSET 5|10|This is the first question|OK
%QSET 5|11|This is the second question|OK|Thanks
%QSET 5|12|This is the third question|OK|Thanks|Goodbye
200|%CHOOSE 5
201|How are you feeling?|Good|Bad|Hungry
202|%CHOOSE 5

which asks:

 
This is the first question
How are you feeling?
This is the second question

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.2.3 Random Sampling from Question Sets with %RANDOM

Random sampling is done with the %RANDOM sampler keyword. Each time you apply %RANDOM to a question set, a random question is selected and used from the question set. In the following experiment, two questions are selected at random from question set 5:

 
%QSET 5|10|This is the first question|OK
%QSET 5|11|This is the second question|OK|Thanks
%QSET 5|12|This is the third question|OK|Thanks|Goodbye
200|%RANDOM 5
201|%RANDOM 5

So the output might be any of the following outcomes:

 
This is the first question
This is the second question

This is the second question
This is the first question

This is the first question
This is the third question

This is the third question
This is the first question

This is the second question
This is the third question

This is the third question
This is the second question

Likewise, this example:

 
%QSET 5|10|This is the first question|OK
%QSET 5|11|This is the second question|OK|Thanks
%QSET 5|12|This is the third question|OK|Thanks|Goodbye
200|%RANDOM 5
201|How are you feeling?|Good|Bad|Hungry
202|%RANDOM{} 5

samples one random question, then displays "How are you feeling?", then samples another random question. Here’s one possible result:

 
This is the third question
How are you feeling?
This is the first question

Remember, sampling is without replacement: no question will be repeated in a trial.

By default, random sampling always assigns every question in the set equal weight. That is, any question in the set is equally probable to be selected. You can change this with the %FREQ keyword.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.2.4 Random Sampling with Weights from Question Sets, with %FREQ

The %FREQ keyword assigns positive integer weights to questions in a question set, representing the likelihood of being sampled. (Negative and zero weights are illegal.) For example, the following experiment that displays one question. That question is 25% likely to be the first, 60% likely to be the second, and 15% likely to be the third.

 
%QSET 5|10|This is the first question %FREQ 25|OK
%QSET 5|11|This is the second question %FREQ 60|OK|Thanks
%QSET 5|12|This is the third question %FREQ 15|OK|Thanks|Goodbye
100|%RANDOM 5

Weights need not sum to 100. The following example is equivalent to the preceding one.

 
%QSET 5|10|This is the first question %FREQ 5|OK
%QSET 5|11|This is the second question %FREQ 12|OK|Thanks
%QSET 5|12|This is the third question %FREQ 3|OK|Thanks|Goodbye
100|%RANDOM 5

To determine the probability of a question’s being sampled, divide its %FREQ value by the sum of all %FREQ values in the question set. In the above case, the sum is 5 + 12 + 3 = 20, so the first question has likelihood 5/20 = 25%.

Some facts about %FREQ:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.2.5 Sampling with Question Probabilities from Question Sets

You can use %PROB, %NEXT, and %SNEXT with question sets for both ordered and random sampling. But what happens in a case like this?

 
1|%CHOOSE 100 %NEXT 2
2|Hello|OK
3|Goodbye|OK
%QSET 100|4|My question %NEXT 3|OK

Here we have a sampler (%CHOOSE) with a %NEXT value, selecting a question ("My question") that also has a %NEXT value. Which %NEXT will win? The rule is this: the %NEXT value in the sampled question overrides %NEXT value in the sampler. So the above example will produce:

 
My question
Goodbye

In more detail:

The same rule applies for %SNEXT: if both the question and the sampler have it, the question’s %SNEXT takes precedence.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.2.6 Combining %FREQ and %PROB

%FREQ is not the same as %PROB, which is the probability that a question is asked at all (versus being skipped). You can use %FREQ and %PROB together just fine. If you use both in a single question:

Consider this example:

 
%QSET 1|10|My question %PROB 44 %FREQ 25|OK
%QSET 1|11|Second question %FREQ 75|OK
888|%CHOOSE 1 %PROB 15

This means:

Thus, the probability of question 10 being displayed is (15*25*44)% and question 11’s is (15 * 75)%.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.3 Important Facts about Question Sets


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.6 Custom Messages with %MSG

The special marker %MSG lets you change several text messages that ESP displays.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.6.1 STARTTRIAL

When ESP begins a trial, it displays the message “Tap the screen to begin.” You can change this message with the entry %MSG STARTTRIAL in the Memo Pad:

 
%MSG STARTTRIAL|OK, ready, let's go!

You should have at most one STARTTRIAL entry per experiment.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.6.2 ENDTRIAL

When ESP ends a trial, it displays the message “Questionnaire completed. Thank you.” You can change this message with the entry %MSG ENDTRIAL in the Memo Pad:

 
%MSG ENDTRIAL|All done now.

You should have at most one ENDTRIAL entry per experiment.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.6.3 SLEEPING and WAITMSG

When ESP sleeps between trials, it displays the message “ESP is sleeping...” in the titlebar at the top of the screen. You can change this message with the entry %MSG SLEEPING in the Memo Pad:

 
%MSG SLEEPING|Snore snore...

By default, the rest of the display is blank. You can add a more detailed message below the titlebar using %MSG WAITMSG in the Memo Pad:

 
%MSG WAITMSG|The next trial will begin shortly. Please be patient.

You should have at most one SLEEPING entry per experiment, and at most one WAITMSG entry per experiment.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. ESP Desktop

ESP Desktop is a major new feature of ESP 4.0! You can able to configure full experiments and manage all your participant data from your favorite personal computer. It runs under Windows and Linux.

ESP Desktop requires the Mozilla or Firefox web browser. Other browsers are not supported. (This is not just a whim: ESP Desktop is implemented in a programming language called XUL that works only in Mozilla-based browsers.)


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1 Getting Started with ESP Desktop

Assuming you have installed ESP Desktop already on your local machine (see section Installation) here’s how to run it:

  1. Run Mozilla
  2. Hit the URL chrome://espdesktop/content/desktop.xul

Now you’re ready to work with an experiment.

 
Note: If you were previously working on an experiment, but you quit ESP
Desktop without closing the experiment, then ESP Desktop will offer you
the choice to reload that experiment.

To begin, you can either create a new experiment or work with an existing experiment.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1.1 Creating a new experiment

When you first run ESP Desktop, you’ll be presented with this:

pix/ed-begin

To create a new experiment, use the File menu and select New Experiment.

pix/ed-begin-file

This action will display a dialog to pick a directory (folder) to contain your new experiment.

pix/ed-filerequestor

This is a standard Mozilla file dialog. Choose an existing directory, or create a new one, and click Select. (Note: the Mozilla file dialog is a little finicky about picking directories. You cannot select a directory by double-clicking it – if you do, you’ll go into the directory. Instead, single-click the directory name and then Select.)

An empty experiment will be created in the directory you chose. ESP Desktop will display a default experiment name (usually “My New Experiment”), the file path to the experiment, and a new, extended menu bar:

pix/ed-newexperiment

and now you’re ready to work on your experiment.

The first time you run ESP Desktop, you might see a warning about unsafe operation. See section Special note about permissions.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1.2 Opening an existing experiment

To open an existing experiment, choose Open Experiment from the File menu. This action will display a dialog to select the directory (folder) that contains your desired experiment.

pix/ed-filerequestor

The experiment will be loaded from the directory you chose. ESP Desktop will display the experiment name, the file path to the experiment, and a new, extended menu bar:

pix/ed-newexperiment

and now you’re ready to work on your experiment.

The first time you run ESP Desktop, you might see a warning about unsafe operation. See section Special note about permissions.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1.3 Copying an experiment

To copy an experiment, any of these methods will work:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1.4 Special note about permissions

The first time you run ESP Desktop, you may see a warning dialog about unsafe operation:

pix/ed-permission

This is because ESP Desktop needs to read and write files, and run other programs, on your computer. Web browsers don’t normally do that. To use ESP Desktop, grant these permissions by checking the checkbox “Remember this decision” and clicking Allow. This eliminates the dialogs. If you don’t do this, you’ll see this ESP Desktop error:

pix/ed-universalxp-failed

and ESP Desktop will not operate.

Choosing “Allow” places the following line into your ‘prefs.js’ file in your Mozilla folder.

user_pref("capability.principal.codebase.p0.granted", "UniversalPreferencesWrite UniversalXPConnect UniversalPreferencesRead");

which you can delete later if desired. (Shut down Mozilla before editing ‘prefs.js’ or your changes won’t take effect.)

A future revision of ESP Desktop will eliminate this issue.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2 Changing Settings


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.1 How ESP Desktop Operates

ESP Desktop is for editing the settings and questions for your experiment. Once you’ve modified them to your liking, you transfer them to one or more connected Palm Pilots.

You edit settings right in ESP Desktop’s main window. Questions, however, are edited in a text editor (such as Notepad or Emacs) that ESP Desktop will launch for you.

When it’s time to transmit your experiment between ESP Desktop and the Palm, here’s what happens:

  1. From ESP Desktop’s menu, you choose a command such as “send to Palm” or “load from Palm”; there are a variety of such commands.
  2. A dialog will appear, telling you to run a hotsync. The dialog looks different – and asks you to different things – depending on your operating system. If you’re running Windows, the dialog looks like this: pix/ed-hotsync-windows

    and is followed by:

    pix/ed-hotsync-windows2

    On the other hand, if you’re using Linux, you get only a single dialog like this:

    pix/ed-hotsync

    In either case, do what the dialog says to do.

  3. The desired information will be transmitted between your PC and your Palm.

So in general, ESP will prompt you to start a hotsync. Once it’s done, ESP Desktop will be ready for your next action.

If things go wrong, you will see an error dialog. For example, if you fail to connect a Palm, you’ll see

pix/ed-hotsync-err

On Windows, if you click “OK” before a hotsync is complete, you might see:

pix/ed-hotsync-windows-toosoon
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.2 General Settings for ESP Desktop

pix/ed-prefs-general

The Subject ID uniquely identifies the person carrying this Palm Pilot. If your experiment uses multiple Palm Pilots, make sure each of them is set with a different Subject ID. Valid values are 1 to 32767 inclusive. Do not use zero. Larger values may cause ESP to crash.

This value is used in two ways:

The Automation setting selects between manual mode (see section Manual Mode: What it Looks Like) and automatic mode (see section Automatic Mode: What it Looks Like) for your experiment. In manual mode, the participant initiates trials herself. In automatic mode, the Palm initiates them.

The Take Over Machine setting determines whether the participant can run other Palm programs while ESP is running. The recommended setting is to check this box. Otherwise, the participant will be able to halt ESP at any time and/or waste the batteries by running undesired software.

When we say "Take Over," we really mean it. None of the buttons will operate. This is good for keeping participants from fiddling with the Palm, but inconvenient when the experimenter needs to use the Palm, say, for transferring data to the PC using ESP Desktop. So, if you use Take Over Machine, you’ll need to get the Palm out of this mode before you can hotsync your results data to your PC with ESP Desktop (see section Collect Data).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.3 Automation Settings for ESP Desktop

pix/ed-prefs-automation

These settings are available only if Automation is selected in General Settings. If you are running an experiment in manual mode (see section Manual Mode: What it Looks Like), these settings will not be visible when editing and will not take effect in the experiment.

The Begin Day and End Day settings specify the allowable times of day that trials may be run. Outside of this time range, no trials will occur. Times are on a 24-hour clock, from 0:00 (midnight) to 23:59 (11:59 pm). If the Begin and End times are equal, trials can run at all times. Setting the End time earlier than the Begin time is an error.

Total Trials and Trials Per Day control the frequency of trials. For example, if you request 100 trials in total and 20 trials per day, your experiment will last for five days (total trials divided by trials per day, or 100/20). If you request 101 trials and 20 per day, your experiment will last for six days, with the last day having only one trial (the hundred-and-first).

The Randomize Trials setting determines whether trials occur at predetermined or random times. If you’ve requested N trials per day, the period between the Begin and End times is split into N intervals of equal length. (For example, if the period is between 12:00 and 22:00 and you request 20 trials per day, this creates 20 intervals of 30 minutes each.) If Randomize Trials is unchecked, trials will occur at the beginnings of these N intervals. If checked, trials will occur at a random time within each interval. In our "20 trials per day" example, the first trial would occur at a random time between noon and 12:30, the next between 12:30-13:00, etc. So "random" means "random within each interval."

Max Seconds To Respond sets a time limit, in seconds, for the participant to respond to a trial. The Palm will beep continuously during this time. If there is no response within this time period, the trial ends. The related setting Seconds Between Beeps determines how frequently the Palm will beep while waiting for the participant to respond. (NOTE: Values of less than 2 seconds are unreliable.) So, if you request 30 seconds of beeping with 3 seconds per beep, the Palm will beep 10-11 times.

Run At Invocation is an experimenter’s aid. When you first run ESP by tapping its icon, should a trial begin immediately (checked box) or should a trial simply be scheduled to run later (unchecked box)? Depending on your needs, you might want the participant to answer questions immediately (say, as practice in front of the experimenter) or not.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.4 Question Settings for ESP Desktop

pix/ed-prefs-question

Max Seconds To Respond sets a time limit for a participant to respond to a question. If no response occurs within this limit, the trial ends. If you want no time limit on answering a question, use a large value like 99999999. (Or if appropriate, run the experiment in Manual mode instead of Automatic mode.)

Important: This timer begins running when a question appears, and it keeps running until the question is fully answered. If the participant slides a slider, writes Graffiti, taps checkboxes, etc., this does not prevent a timeout! In other words, the time limit can be reached while the participant is in the middle of writing Graffiti, moving a slider, etc. Be aware of this and plan appropriately.

Non-Answer Value sets the value to be stored if the participant does not answer a question.

Default Widget determines whether responses are presented as buttons, a dropdown menu, etc., by default. (If you don’t want the default, you can specify the widget directly for each question with the %TYPE keyword.)

Randomize Questions determines whether the questions are presented in strictly ascending numerical order (based on their question ID: see section About Question IDs) or in random order. Remember that questions with negative IDs are never randomized (see section Negative Question IDs).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.5 Sound Settings for ESP Desktop

pix/ed-prefs-sound

Here you may select the beep sound (via pop-up menu) to alert the participant to begin a trial. This sound will be repeated according to your Automation Prefs "Max Seconds to Respond" and "Seconds Between Beeps."

NOTE: Many of these beeps sound the same. They are all of the system-supplied beeps. WARNING: if you use the “Alarm” beep, your experiment can run into trouble if you’re not careful. The Alarm sound has a longer duration than the others. If you set “Seconds Between Beeps” to be too short (shorter than the duration of Alarm), then as the Alarm sound rings, it will overlap itself, with the next beep beginning before the previous one has ended. This can interfere with the timing of your experiment. Therefore, if you use Alarm, make sure that “Seconds Between Beeps” is longer than the duration of the Alarm sound, and test it carefully.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3 Menu Reference


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.1 File Menu

The File menu is for creating, opening, saving, and closing whole experiments. Before you create or open an experiment, the File menu has these choices:

pix/ed-begin-file

New Experiment will create a brand-new experiment in a directory (folder) of your choice. If you choose a directory that already contains an experiment, ESP Desktop will ask if you want to open it.

Open Experiment will open an existing experiment from a directory of your choice. If you choose a directory that has no experiment, ESP Desktop will ask if you want to create one.

When an experiment is loaded, the File menu contains the following choices:

pix/ed-menu-file

Save will save your experiment in place. Save As will prompt you for a new location to save your experiment. (This is the easiest way to copy an experiment: open it, then choose Save As.) Close will close your experiment. Revert will reload the last saved settings for your experiment.

All file operations – and many others – will warn you if you’re about to lose unsaved settings. For example, if you try to load settings from the Palm into an unsaved experiment, you’ll see:

pix/ed-areyousure

If you don’t want to lose your settings in ESP Desktop, click Cancel, save your experiment, and repeat the operation.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.2 Living in a browser window

ESP Desktop is a complete application, but it runs in a web browser (Mozilla) which has the usual Back, Forward, and Reload buttons and other common browser features. Try to treat ESP Desktop as an application and not as a web browser, and you’ll have the most success.

ESP Desktop has its own menu as we’ve seen, and in particular, it has a Save command for saving your work. Make sure you use it. You can cause yourself problems up by clicking the browser’s Reload button or quitting Mozilla without saving your experiment. In these cases, any changes you have not saved will be lost. So, as a general rule, always Save before reloading the page or quitting Mozilla.

ESP Desktop cannot stop you from reloading the page or exiting the browser. Therefore, as a convenience, ESP Desktop remembers which experiment you are working on until you explicitly use the Close menu command in the File menu.

For example, if you quit Mozilla while editing an experiment, then the next time you run ESP Desktop, it will automatically prompt you to load that experiment:

pix/ed-reloadlast

If you click OK, the experiment is reloaded. If you click Cancel, ESP Desktop will display its initial screen where you can choose a new experiment to work on. (In either case, if you had unsaved changes when you quit Mozilla, those changes are gone.)

Likewise, if you click Mozilla’s Reload button without closing an experiment, then you’ll be prompted to reload that experiment. (Though any unsaved changes will again be gone.)

 
Note: If you want to get rid of unsaved changes and revert back
to the last saved version of your experiment, you can click the
browser’s Reload button (or quit Mozilla) to do this. However, we
recommend using ESP Desktop’s own Revert command in the
File menu instead.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.3 Experiment Menu

The Experiment menu is for operating on your entire experiment at once.

pix/ed-menu-experiment

Set name changes the name of the experiment, as it appears below the heading “ESP Desktop”. It pops up a dialog to enter the new name.

pix/ed-setexperimentname

Read from Palm downloads a whole experiment – both the settings and the questions – from the connected Palm into ESP Desktop. (But not the participant data: that’s done with Download data from Palm.)

Install on Palm uploads the current experiment onto the connected Palm. You may upload the settings, questions, the ESP program, and/or the ESPPrefs program in any combination. Additionally, if ESP has already been run on the connected Palm, you may choose to keep the existing participant ID or assign a new one. ESP Desktop prompts you to make these choices:

pix/ed-install

asks you for confirmation:

pix/ed-install2

then performs the installation.

Install on many Palms leads you through a sequence of dialogs to upload the current experiment onto a fleet of Palms. It begins with the same choices as Install on Palm:

pix/ed-install

asks you for confirmation:

pix/ed-install2

asks you how many Palms will be processed:

pix/ed-install3

optionally assigns new participant IDs (if you chose to do so):

pix/ed-install4

and then does all the installations in sequence from first to last:

pix/ed-install5

and so forth. When finished (or if you exit prematurely), ESP Desktop displays statistics on how many Palms were successfully processed. For instance, if you’d specified five Palms but done only the first few, you might see:

pix/ed-installdone
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.4 Settings Menu

The Settings menu is for operating only on your experiment’s settings.

pix/ed-menu-settings

Read from Palm downloads the only the experiment settings (but no other information) from the connected Palm into ESP Desktop.

Set to global ESP defaults will initialize your experiment to use the ESP defaults. Use this if you feel hopelessly lost and want to start your experiment over.

Send settings to Palm is the opposite of Read from Palm: it uploads only the current settings from ESP Desktop to the connected Palm.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.5 Questions Menu

The Questions menu is for operating only on your experiment’s questions.

pix/ed-menu-questions

Edit questions runs an external editing program to edit the questions for your experiment. The default editor is GNU Emacs on Linux systems (‘/usr/bin/emacs’), and Notepad on Windows. (Any editor can be used as long as it opens its own window and accepts a filename as an argument.) Enter your questions one per line. ESP Desktop will upload them to your Palm(s) ready for ESP to use.

You can change the editor with the Set question editor menu command:

pix/ed-questioneditor

You must provide the full path to the editor program, such as ‘C:\winnt\notepad.exe’ for Notepad on some Windows systems, not just ‘notepad’. Also, your answer is global: the selected editor will be used for all experiments you edit.

Read from Palm downloads only the questions (but no other information) from the connected Palm into ESP Desktop.

Send questions to Palm is the opposite of Read from Palm: it uploads only the current questions from ESP Desktop to the connected Palm.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.6 ESP Menu

The ESP menu is for copying the ESP and ESPPrefs programs to the connected Palm.

pix/ed-menu-esp
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.7 Participants Menu

The Participants menu is for dealing with participant data.

pix/ed-menu-participants

Download data from Palm transfers all participant data from the connected Palm to your experiment directory, inside a subdirectory called ‘subject-data’. See section Data.

After you download the data, you may optionally delete the data from the Palm. Download data from Palm will offer you this choice:

pix/ed-download1
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.8 Help Menu

The Help menu is for documentation.

pix/ed-menu-help

Help on the web takes you to the ESP web site.

Manual displays this ESP manual on your local computer.

View License displays the GNU Public License, which explains that you may copy and share ESP software for free.

Credits tells you who created ESP Desktop.

About displays the version number of ESP Desktop.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4 ESP Desktop Internals

ESP Desktop presents a friendly user interface, but sometimes you might want to get under the hood. We’ll explain the files and programs that ESP Desktop uses internally. Most files are plain text and you can edit them, and most programs can be invoked directly.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4.1 Experiment Internals

When you create an experiment directory (folder), you’ll find these files in it:

espprefs.xml’: This is an XML file containing the experiment settings. You can modify it with a text editor.

experiment.txt’: This is a plain text file containing the experiment name on a single line. You can modify it with a text editor.

questions.txt’: This is a plain text file containing the experiment questions, one per line. You can modify it with a text editor.

subject-data’: This subdirectory contains all your participant data for the experiment.

Any other files are for internal use only.

If you modify a file by hand while ESP Desktop is running, this is at your own risk. ESP Desktop is not guaranteed to see your changes and might overwrite them.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4.1.1 Default Internals

When you create a new experiment, several default files are copied into the experiment directory (folder): ‘espprefs.xml’, ‘questions.txt’, and ‘experiment.txt’ (see section Experiment Internals). These default files come from the ESP system directory ‘C:/Program Files/esp4’ (Windows) or ‘/usr/local/esp4’ (Linux). Normally you don’t need to think about these files, but if you’d prefer to change the defaults when new experiments are made, you can edit these files with a text editor.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4.2 Hotsync Internals

On Linux, hotsync operations are handled by a program called espprefs-conduit-unix, found in ‘/usr/local/esp4’. Run the command with no arguments to find out what it does. You can run it manually to do various ESP-specific hotsync operations: copying question files, settings files, etc.

On Windows, hotsync operations are handled by the ordinary Hotsync Manager. However, this presents a unique challenge to ESP Desktop, since hotsyncs run independently from ESP Desktop. In other words, ESP Desktop isn’t aware when hotsyncs start or finish. As a result, ESP Desktop asks you to click an extra “OK” button after a hotsync completes, so it can examine the results. This makes the Windows version of ESP Desktop more verbose than on other platforms: it displays more dialogs and asks for more confirmation from you.

The Windows hotsync structure consists of three programs:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. ESPPrefs

ESP for the Palm Pilot may be configured with the included program ESPPrefs (short for "ESP Preferences"). The experimenter can control numerous aspects of ESP’s behavior with simple settings.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.1 Getting Around ESPPrefs

When you first run ESPPrefs, you will see the following screen:

pix/esp-prefs-general

This is one of several screens for modifying ESP’s behavior. You can reach the other screens from the Preferences menu (press the Menu key):

pix/esp-menu-prefs
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.2 Saving and Loading Settings in ESPPrefs

When you change values within ESPPrefs, they do not take effect until you save them. Saving is done from the File menu:

pix/esp-menu-file

The other menu item, Restore Defaults, brings ESPPrefs back to its initial values as shipped. Select this item if your settings get hopelessly confused. However, you still must select Save to make these default values take effect.

Credits simply displays information about ESPPrefs.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3 Changing Settings


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3.1 General Settings for ESPPrefs

pix/esp-prefs-general

The Subject ID uniquely identifies the person carrying this Palm Pilot. If your experiment uses multiple Palm Pilots, make sure each of them is set with a different Subject ID. Valid values are 1 to 32767 inclusive. Do not use zero. Larger values may cause ESP to crash.

This value is used in two ways:

The Automation setting selects between manual mode (see section Manual Mode: What it Looks Like) and automatic mode (see section Automatic Mode: What it Looks Like) for your experiment. In manual mode, the participant initiates trials herself. In automatic mode, the Palm initiates them.

The Take Over Machine setting determines whether the participant can run other Palm programs while ESP is running. The recommended setting is to check this box. Otherwise, the participant will be able to halt ESP at any time and/or waste the batteries by running undesired software.

When we say "Take Over," we really mean it. None of the buttons will operate. This is good for keeping participants from fiddling with the Palm, but inconvenient when the experimenter needs to use the Palm, say, for transferring data to the PC using ESP Desktop. So, if you use Take Over Machine, you’ll need to get the Palm out of this mode before you can hotsync your results data to your PC with ESP Desktop (see section Collect Data).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3.2 Automation Settings for ESPPrefs

pix/esp-prefs-automation

These settings are available only if Automation is selected in General Settings. If you are running an experiment in manual mode (see section Manual Mode: What it Looks Like), these settings will not be visible when editing and will not take effect in the experiment.

The Begin Day and End Day settings specify the allowable times of day that trials may be run. Outside of this time range, no trials will occur. Times are on a 24-hour clock, from 0:00 (midnight) to 23:59 (11:59 pm). If the Begin and End times are equal, trials can run at all times. Setting the End time earlier than the Begin time is an error.

Total Trials and Trials Per Day control the frequency of trials. For example, if you request 100 trials in total and 20 trials per day, your experiment will last for five days (total trials divided by trials per day, or 100/20). If you request 101 trials and 20 per day, your experiment will last for six days, with the last day having only one trial (the hundred-and-first).

The Randomize Trials setting determines whether trials occur at predetermined or random times. If you’ve requested N trials per day, the period between the Begin and End times is split into N intervals of equal length. (For example, if the period is between 12:00 and 22:00 and you request 20 trials per day, this creates 20 intervals of 30 minutes each.) If Randomize Trials is unchecked, trials will occur at the beginnings of these N intervals. If checked, trials will occur at a random time within each interval. In our "20 trials per day" example, the first trial would occur at a random time between noon and 12:30, the next between 12:30-13:00, etc. So "random" means "random within each interval."

Max Seconds To Respond sets a time limit, in seconds, for the participant to respond to a trial. The Palm will beep continuously during this time. If there is no response within this time period, the trial ends. The related setting Seconds Between Beeps determines how frequently the Palm will beep while waiting for the participant to respond. (NOTE: Values of less than 2 seconds are unreliable.) So, if you request 30 seconds of beeping with 3 seconds per beep, the Palm will beep 10-11 times.

Run At Invocation is an experimenter’s aid. When you first run ESP by tapping its icon, should a trial begin immediately (checked box) or should a trial simply be scheduled to run later (unchecked box)? Depending on your needs, you might want the participant to answer questions immediately (say, as practice in front of the experimenter) or not.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3.3 Question Settings for ESPPrefs

pix/esp-prefs-questions

Max Seconds To Respond sets a time limit for a participant to respond to a question. If no response occurs within this limit, the trial ends. If you want no time limit on answering a question, use a large value like 99999999. (Or if appropriate, run the experiment in Manual mode instead of Automatic mode.)

Important: This timer begins running when a question appears, and it keeps running until the question is fully answered. If the participant slides a slider, writes Graffiti, taps checkboxes, etc., this does not prevent a timeout! In other words, the time limit can be reached while the participant is in the middle of writing Graffiti, moving a slider, etc. Be aware of this and plan appropriately.

Non-Answer Value sets the value to be stored if the participant does not answer a question.

Default Widget determines whether responses are presented as buttons, a dropdown menu, etc., by default. (If you don’t want the default, you can specify the widget directly for each question with the %TYPE keyword.)

Randomize Questions determines whether the questions are presented in strictly ascending numerical order (based on their question ID: see section About Question IDs) or in random order. Remember that questions with negative IDs are never randomized (see section Negative Question IDs).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3.4 Sound Settings for ESPPrefs

pix/esp-prefs-beep

Here you may select the beep sound (via pop-up menu) to alert the participant to begin a trial. This sound will be repeated according to your Automation Prefs "Max Seconds to Respond" and "Seconds Between Beeps."

NOTE: Many of these beeps sound the same. They are all of the system-supplied beeps. WARNING: if you use the “Alarm” beep, your experiment can run into trouble if you’re not careful. The Alarm sound has a longer duration than the others. If you set “Seconds Between Beeps” to be too short (shorter than the duration of Alarm), then as the Alarm sound rings, it will overlap itself, with the next beep beginning before the previous one has ended. This can interfere with the timing of your experiment. Therefore, if you use Alarm, make sure that “Seconds Between Beeps” is longer than the duration of the Alarm sound, and test it carefully.

pix/esp-prefs-beep-menu
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6. Experiments

Here are the steps, in order, for creating and running a complete experiment with ESP.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1 Get Ready

Install the Palm Desktop and other associated software (included with your Palm) on a PC. We will call this machine your Desktop PC.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2 Create Experiment

To create your experiment, use ESP Desktop:

  1. Create a new experiment (see section Creating a new experiment)
  2. Create questions (see section Creating Questions)
  3. Edit the experiment settings (see section Changing Settings)

Alternatively, you can create the experiment on the Palm using ESPPrefs (for settings) and the Memo Pad (for questions), but this is quite cumbersome.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3 Make Palms


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3.1 Set Up a Test Palm

  1. Designate one Palm as your test machine.
  2. Perform a hard reset on the Palm to restore it to the factory default configuration. (While holding the power button, press the reset button on the back; or see your Palm manual.)
  3. Run ESP Desktop (see section ESP Desktop) to install the ESP software and configure your experiment. (Alternatively install ESP.prc and ESPPrefs.prc using the Palm Desktop, and run ESPPrefs (see section ESPPrefs) to configure your experiment.)
  4. Run ESP and carry this Palm for a week (or whatever length of time is appropriate for your experiment), making sure that the experiment is working as you require.
  5. Run ESP Desktop (see section ESP Desktop) to download the data onto your personal computer.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3.2 Make Your “Production” Palms

Use ESP Desktop (see section ESP Desktop) to copy ESP and your experiment onto multiple Palms.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.4 Distribute Palms

Tap the ESP icon to start the experiment, and give the Palm to the participant.

Recommended: Instruct the participant not to monkey with the Palm or his/her remuneration may be at risk.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.5 Collect Data

Collect data from your participants regularly.

  1. Take the Palm out of sight.
  2. If ESP is using the Take Over Machine setting, then ESP will still be running and the Palm cannot hotsync. Therefore, you will need to get ESP out of this mode before you can upload data. Here’s how to do it:

    (Thanks to the iESP Project for this writeup.)

  3. Use ESP Desktop to download the subject’s data.
  4. If you’re using rechargeable batteries, swap the participant’s Palm for another fully-charged one. (Use ESP Desktop to set the participant ID to the same number as the original, using the Install on Palm menu command.) If you’re using non-rechargeable batteries, change them and perform a soft reset (to avoid an operating system bug associated with battery changes).
  5. Tap the ESP icon to resume the program.
  6. Return the Palm to the participant.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.6 Analyze Data

In each experiment, the participant data is found in a directory (folder) called ‘subject-data’. See section Data.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7. Data

ESP Desktop downloads the data from the Palms to your PC, to a specific place within your experiment folder.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.1 Where the Data is Located

ESP Desktop automatically creates and maintains a set of directories (folders) for your participant data, located inside your experiment directory.

All of these files and directories are created and maintained automatically by ESP Desktop when you download data.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.2 What the Data Looks Like

Data is written to files, one line per question asked. The file format is always the same, but here is an example to make things concrete. Given this experiment:

 
%QSET 50|11|First sampled question|A|B|C
%QSET 50|12|Second sampled question|D|E|F|G
%QSET 50|13|Third sampled question|H|I
5|%RANDOM 50
6|%RANDOM 50
7|%RANDOM 50
100|How are you feeling?|good|bad|ugly

here is an example data file representing the responses of participant 18:

 
20050113140732        18        12            187         2  1        50 "E"
20050113140732        18        13             93         2  1        50 "I"
20050113140732        18        11             58         1  1        50 "A"
20050113140732        18       100             72         2  1         0 "good"
20050113140740        18        11             73         2  1        50 "B"
20050113140740        18        13             65         1  1        50 "H"
20050113140740        18        12             59         2  1        50 "E"
20050113140740        18       100             81         3  1         0 "bad"
....

Each line represents one participant’s response to one question. The values on each line represent the following:

ColumnsMeaningSample Value
1-4Year that trial began2005
5-6Month that trial began01
7-8Calendar day that trial began13
9-10Hour that trial began14
11-12Minute that trial began07
13-14Second that trial began32
15-24Subject ID18
25-34Question ID12
35-49Response time to this question, measured in ticks (hundredths of a second)187
50-54Ignore: reserved for future use
55-59Button number representing the response. Buttons are numbered from left to right beginning with 1. See below for checkboxes.2
60-62Widget type: 1 (button), 2 (pop-up list), 4 (list box), 5 (checkbox), 6 (slider), 7 (text field)1
63-72Question set ID, or zero if the question isn’t in a question set.50
73One space character
74-endThe text of the selected button or widget, enclosed in double quotes“good”

NOTE: This data format is new. It is not compatible with ESP 2.0 nor iESP.

For checkboxes, the “button number” value is a bit vector: a binary (base 2) value indicating which checkboxes were checked. A "1" bit means the checkbox was checked, and a "0" means unchecked. For example, if the question has 6 checkboxes, and the participant checked the first, second, and fifth, the response will be recorded as 010011 = 19. (Note that the values are read from right to left: the rightmost bit is the first checkbox, etc.) This is a standard technique called a "bit vector"; if you’re uncomfortable with base 2, ask any computer science student for help. To decode the data, many scientific calculators can convert numbers from base 10 to base 2 for you.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.3 File and Data Handling

The file names and data are set up to allow the experimenter great flexibility. In general, you can freely combine the data for multiple trials and participants without accidentally losing information.

So, to obtain all the data for a single participant in the order it was created, simply concatenate all files in that participant’s directory in alphabetical order. For example, on Linux systems, the command:

 
$ cd subject-data
$ cat 18/* > 18.txt

produces a file ‘18.txt’ containing all of participant 18’s data, sorted by timestamp. You can also easily do this for all participants:

 
#!/bin/bash
cd subject-data
for p in *
do
  cat $p/* > $p.txt
done

This shell script produces a ‘.txt’ file for each participant, named ‘1.txt’, ‘2.txt’, etc.

You can freely concatenate, mix, and match the data without losing information. Every line of data identifies its participant and trial. For example, on a Linux system, you can produce a single file containing all data, sorted by time, with:

 
$ cd subject-data
$ find . -type f -print0 | xargs -0 cat | sort > alldata.txt

This all might seem trivial, but actually it’s important. Imagine if every participant’s data were kept in a file called ‘data.txt’ instead of a uniquely named file. If you wanted to copy them all to the same directory, they’d collide. Similarly, if the data didn’t contain the participant IDs on every line, you couldn’t combine the data from multiple participants for analysis.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8. Practical Matters


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.1 Memory considerations

Palm Pilots have limited memory for storing a participant’s responses. Nevertheless, ESP’s memory use is small. Each response (to a single question) occupies less than 100 bytes of RAM. Therefore, a two-megabyte Palm (the minimum configuration we’ve seen in years) will comfortably hold 18,000 to 20,000 responses, provided you have not installed any other third-party software on the Palm.

For example, if you prompt the user with 20 questions 10 times each day, that’s 200 responses per day. You can run this experiment for 90-100 days without filling up the RAM of even a low-end Palm. With a modern Palm (8 MB or RAM or more) you have space galore.

Nevertheless, you should have your participants visit you regularly to upload their data to a PC for safekeeping and to change batteries. Otherwise, you risk losing data due to accidents.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.2 Battery considerations

Make sure to plan for battery changes if your experiment will run longer than the Palm’s expected battery life. (See your Palm’s documentation on battery life.)

Modern Palms have rechargeable batteries. We recommend keeping extra, fully-charged Palms around and swapping them when participants check in. Just be sure to keep the same participant ID on the old and new Palm!

Older Palms use disposable batteries. Keep a good supply around and change the batteries when participants check in.

 
Important Note:
Some versions of the Palm operating system have a bug concerning battery
changes.  After replacing batteries, always perform a soft reset.
If you don’t, the Palm’s alarm timer may become incorrect.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9. Troubleshooting


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.1 Troubleshooting ESP

Q: How do you get the Palm out of “Take Over Machine” mode? I tried a soft reset but it didn’t work.

A: See section Collect Data.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.2 Troubleshooting ESPPrefs

(No info yet)


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.3 Troubleshooting ESP Desktop

General Issues

Q: On Windows, the installer program EspDesktopConduitInstaller refuses to run. It display the error message, “Catapult could not detect a compatible Palm Desktop software configuration and will cancel installation.”

A: First, make sure you have Palm Desktop installed, and reboot after you install it. On some PCs the problem continue anyway. We don’t know the cause. If you have any clues please let us know.

Q: I can’t load ESP Desktop at all. Everything installed without error, but my browser cannot find the URL chrome://espdesktop/content/desktop.xul.

A: If this occurs, there are several things to check:

  1. Make sure you edited the ‘installed-chrome.txt’ file as explained in the installation instructions. Make sure you edited for the right browser: Mozilla and Firefox have separate ‘installed-chrome.txt’ files.
  2. Make sure you edited ‘installed-chrome.txt’ using a plain text editor such as Emacs or WordPad, and saved it as plain text with no “formatting.” Otherwise you can corrupt the file.
  3. Make sure that you installed ESP in the right place on your PC. On Windows, when you ran EspDesktopConduitInstaller, did you change the folder where ESP is installed? Or on Linux, did you extract ‘esp4-linux.tar.gz’ somewhere other than ‘/usr/local’? Don’t do that. Uninstall and reinstall ESP. A common mistake on Linux is to create ‘/usr/local/esp4’ by hand and then extract ESP into it. That is incorrect: you should extract ESP directly into ‘/usr/local’ and let the “esp4” subfolder be created automatically. If you do it wrong, you’ll wind up installing ESP one level too deep, in ‘/usr/local/esp4/esp4’, and Mozilla won’t be able to find ESP Desktop.

    So on Windows, look in ‘C:/Program Files/esp4’, and on Linux, look in ‘/usr/local/esp4’. Inside, you should see a whole bunch of files. (And specifically not just another subfolder called “esp4”.) Uninstall and reinstall ESP if necessary to correct this.

Q: My browser loads the ESP Desktop page, but something else is not working.

A: Test ESP Desktop by running its built-in self-test. Under the Help menu, select Test ESP Desktop and follow the instructions. See section Testing the Installation.

Q: On Windows, the ESP Desktop Test succeeds except the hotsynching test. You might see an error, “Synchronization generated one or more messages. Please see the HotSync log for details.” Or you might see an error message from the Hotsync Conflict Notifier, saying “A conflict in the installed conduits has been detected.”

A: We’ve seen this sometimes in earlier versions of the Palm Desktop. A heavy-handed solution is to uninstall Palm Desktop and then upgrade to the most recent version. If you use your PC for hotsynching purposes other than ESP, then uninstalling Palm Desktop might disrupt your other work; but if your PC hotsynching is only for ESP, this is the recommended solution.

If that does not work for you, a less radical solution is to delete some Palm conduits from your system. (A conduit is a piece of hidden software that transfers data between the PC and the Palm.) This is done with a program such as Conduit Buddy (http://www.livepim.com/). (Or if you happen to be a registered Palm software developer, you can use the utility program condcfg.exe from Palm’s Conduit Development Kit (CDK)). Using one of these programs, delete the conduits that have the Creator ID “memo”, “Pmem”, and “PMem”. Then install ESP Desktop again. The problem should be fixed.

Hotsync Issues

Q: On Linux, when I try to hotsync, the kpilot program runs and interferes with ESP Desktop. What can I do?

A: Uninstall kpilot. This is a brute-force solution but it works. If someone has a less drastic way to prevent kpilot from running in KDE, let us know.

Q: On Linux, ESP Desktop will not hotsync with my Palm to transfer data.

A: Make sure ‘/dev/pilot’ points to the actual device for your Palm, typically a serial or USB device. To determine the device, view the system log file ‘/var/log/messages’ or its equivalent with tail -f:

 
# tail -f /var/log/messages

connect your Palm, initiate a hotsync, and watch the messages printed by tail. They will reveal the device name, e.g., ‘/dev/usb/ttyUSB1’. Now make sure ‘/dev/pilot’ points to this device:

 
# ls -l /dev/pilot

If it points to the wrong device, correct this, e.g.,

 
# rm /dev/pilot
# ln -s /dev/usb/ttyUSB1 /dev/pilot

and try hotsynching with ESP Desktop again.

For further debugging, you can also try running the underlying hotsync program directly, espprefs-conduit-unix, found in the directory where you installed ESP (e.g., ‘/usr/local/esp4’). Run espprefs-conduit-unix for usage information.

Permissions Issues

Q: When I run ESP Desktop, I see warnings about unsafe operations or special permissions required.

A: See section Special note about permissions.

Menu Issues

Q: In the Help menu, the Help on the Web, Manual, and View License menu commands don’t work.

A: Your browser’s popup blocker is probably blocking these windows from opening. Edit your blocker preferences to permit the site “espdesktop” to open popup windows. This problem is due to Mozilla bug 247965.

Q: The File menu acts funny sometimes. I click it and nothing happens.

A: This problem is due to Mozilla bug 267215. A workaround is to click a different menu item (such as Help), then return to the File menu.

Q: In the Experiment menu, when I select Install on Palm or Install on Many Palms, nothing happens. Isn’t a dialog supposed to appear?

A: You’re probably viewing ESP Desktop directly as a file in your browser (e.g., a file://... URL) or as an http://... URL. You have to view it as chrome://espdesktop/content/desktop.xul. This is necessary for certain pop-up dialogs to work. Did you install ESP as instructed? See section Installation.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10. Bugs

ESP is provided without support of any kind. That being said, you are welcome to report defects and problems to barretli@bc.edu.

IMPORTANT: When reporting a bug, attach your ‘questions.txt’ and ‘espprefs.xml’ files from your experiment. They are found right in the folder you created to contain your experiment. (This assumes you are using ESP Desktop.)

There is also an ESP mailing list that you can join to discuss ESP with fellow users. See section For More Information.

Known Defects

ESP

ESP Desktop

ESPPrefs

Limitations

ESP

ESP Desktop

ESPPrefs

Problems Caused by the Palm Operating System

How to Report a Suspected Bug

Bug reports may be mailed to barretli@bc.edu. Include your:

  1. Palm model (e.g., Palm IIIx)
  2. Palm operating system version (tap home, then the menu button, then "Info..." under the App menu, then Version, and look for "Palm OS Software v. XXXX"). pix/esp-version
  3. ESP and ESPPrefs versions (on the same version screen as above).
  4. ESP Desktop version (from its “Help / About” menu)
  5. If the bug involves ESP Desktop, include the files ‘questions.txt’ and ‘espprefs.xml’ files from your experiment. They are found right in the folder you created to contain your experiment.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11. iESP

iESP is an enhanced ESP produced by the University of Washington and Intel. It is based on our ESP 2.0, but with many extensions. ESP 4.0 includes all features of iESP version 3.2, plus more.

ESP and iESP settings and data are not compatible. A configuration for ESP (e.g., using ESP Desktop or ESPPrefs) will not work for iESP, and vice-versa.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12. Modifying ESP

ESP is free, open source software, licensed under the GNU Public License (GPL). Programmers are welcome (and encouraged) to modify ESP. Here’s how to do it.

ESP is developed largely on Linux in the following languages:

using the following tools:

The Windows version of ESP Desktop additionally requires:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13. For More Information

Obtaining ESP

To download ESP, visit the ESP web site.

Support

To get help with ESP, join the Experience Sampling mailing list where you can discuss the software with fellow users:

http://groups.yahoo.com/group/experience-sampling/

The mailing list is hosted at the Yahoo Groups web site, so you will need a (free) Yahoo username and password in order to join. Visiting the link above will guide you through the subscription process.

Alternatively you can use email to subscribe, unsubscribe, and post messages:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Index

Jump to:   %  
A   B   C   D   E   F   G   H   I   K   L   M   N   O   P   Q   R   S   T   U   V   W  
Index Entry Section

%
%CHOOSE3.5.2 Sampling from Question Sets with %CHOOSE and %RANDOM
%CHOOSE3.5.2.2 Ordered Sampling from Question Sets with %CHOOSE
%FREQ3.5.2.4 Random Sampling with Weights from Question Sets, with %FREQ
%FREQ3.5.2.6 Combining %FREQ and %PROB
%MSG3.6 Custom Messages with %MSG
%NEXT3.3 Branching Questions with %NEXT
%NEXT3.5.2.5 Sampling with Question Probabilities from Question Sets
%PROB3.4 Probabilistic Questions with %PROB and %SNEXT
%PROB3.5.2.5 Sampling with Question Probabilities from Question Sets
%PROB3.5.2.6 Combining %FREQ and %PROB
%QSET3.5 Question Sets with %QSET
%QSET3.5.1 Defining a Question Set
%QSET3.5.3 Important Facts about Question Sets
%QSET, bug3.5.2.1 A limitation of %QSET
%RANDOM3.5.2 Sampling from Question Sets with %CHOOSE and %RANDOM
%RANDOM3.5.2.3 Random Sampling from Question Sets with %RANDOM
%SNEXT3.4 Probabilistic Questions with %PROB and %SNEXT
%SNEXT3.5.2.5 Sampling with Question Probabilities from Question Sets
%TYPE3.2.1 Response Types
%TYPE4.2.4 Question Settings for ESP Desktop
%TYPE5.3.3 Question Settings for ESPPrefs

A
About4.3.8 Help Menu
Automatic modeAbout ESP
Automatic mode1.2 Automatic Mode: What it Looks Like
Automatic mode4.2.2 General Settings for ESP Desktop
Automatic mode5.3.1 General Settings for ESPPrefs
Automation4.2.2 General Settings for ESP Desktop
Automation5.3.1 General Settings for ESPPrefs
automation settings4.2.3 Automation Settings for ESP Desktop
automation settings5.3.2 Automation Settings for ESPPrefs

B
battery considerations, Palm8.2 Battery considerations
beep settings5.3.4 Sound Settings for ESPPrefs
Begin Day4.2.3 Automation Settings for ESP Desktop
Begin Day5.3.2 Automation Settings for ESPPrefs
branching3.3 Branching Questions with %NEXT
bugs10. Bugs
buttons3.2.1 Response Types

C
checkboxes3.2.1 Response Types
Close4.3.1 File Menu
conditional questions3.3 Branching Questions with %NEXT
copying an experiment4.1.3 Copying an experiment
creating an experiment4.1.1 Creating a new experiment
creating an experiment6.2 Create Experiment
Credits4.3.8 Help Menu

D
dataExperiments
data7. Data
data collection4.3.7 Participants Menu
data collection6.5 Collect Data
data, format7.2 What the Data Looks Like
data, handling and combining7.3 File and Data Handling
data, location7.1 Where the Data is Located
database name4.2.2 General Settings for ESP Desktop
database name5.3.1 General Settings for ESPPrefs
Default Widget4.2.4 Question Settings for ESP Desktop
Default Widget5.3.3 Question Settings for ESPPrefs
downloading ESPObtaining ESP
DummyConduit.dll4.4.2 Hotsync Internals

E
Edit questions4.3.5 Questions Menu
End Day4.2.3 Automation Settings for ESP Desktop
End Day5.3.2 Automation Settings for ESPPrefs
ENDTRIAL3.6.2 ENDTRIAL
ESP Desktop4. ESP Desktop
ESP Desktop4.2.1 How ESP Desktop Operates
ESP Desktop, browser window4.3.2 Living in a browser window
ESP Desktop, defaults4.4.1.1 Default Internals
ESP Desktop, internals4.4 ESP Desktop Internals
ESP Desktop, menus4.3 Menu Reference
ESP Desktop, troubleshooting9.3 Troubleshooting ESP Desktop
ESP menu (ESP Desktop)4.3.6 ESP Menu
EspDesktopConduit.dll4.4.2 Hotsync Internals
ESPPrefs2.4 Using ESP without ESP Desktop
ESPPrefs5. ESPPrefs
espprefs-conduit-unix4.4.2 Hotsync Internals
espprefs-conduit-win.exe4.4.2 Hotsync Internals
espprefs.xml file4.4.1 Experiment Internals
event-contingent sampling1.1 Manual Mode: What it Looks Like
Experiment menu4.3.3 Experiment Menu
experiment.txt file4.4.1 Experiment Internals
experimenter1. Overview
experimenterPeople
experimentsExperiments
experiments, copying4.1.3 Copying an experiment
experiments, creating4.1.1 Creating a new experiment
experiments, creating6.2 Create Experiment
experiments, data combining7.3 File and Data Handling
experiments, data format7.2 What the Data Looks Like
experiments, data handling7.3 File and Data Handling
experiments, ESP Desktop files4.4.1 Experiment Internals
experiments, installing4.3.3 Experiment Menu
experiments, installing6.3 Make Palms
experiments, opening4.1.2 Opening an existing experiment
experiments, overview6. Experiments
experiments, saving4.3.1 File Menu
experiments, testing6.3.1 Set Up a Test Palm
experiments, uploading participant data4.3.7 Participants Menu
experiments, uploading participant data6.5 Collect Data

F
file dialog box (Mozilla/Firefox)4.1.1 Creating a new experiment
File menu4.3.1 File Menu

G
general settings5.3.1 General Settings for ESPPrefs

H
Help menu4.3.8 Help Menu
Help on the web4.3.8 Help Menu
hotsynching4.2.1 How ESP Desktop Operates

I
iESP11. iESP
iESP, upgrading2.5 Upgrading ESP
Install on many Palms4.3.3 Experiment Menu
Install on Palm4.3.3 Experiment Menu
installation problems9. Troubleshooting
installed-chrome.txt fileInstalling ESP
installed-chrome.txt file2.2 Installing on Linux
installing ESP2. Installation
installing ESP, Linux2.2 Installing on Linux
installing ESP, Windows2.1 Installing on Windows
internals of ESP Desktop4.4 ESP Desktop Internals
introduction to ESP1. Overview

K
kpilotPrerequisites

L
Linux, installing ESP2.2 Installing on Linux
Linux, uninstalling ESPUninstalling ESP

M
Manual4.3.8 Help Menu
Manual modeAbout ESP
Manual mode1.1 Manual Mode: What it Looks Like
Manual mode4.2.2 General Settings for ESP Desktop
Manual mode5.3.1 General Settings for ESPPrefs
Max Seconds To Respond4.2.3 Automation Settings for ESP Desktop
Max Seconds To Respond4.2.4 Question Settings for ESP Desktop
Max Seconds To Respond5.3.2 Automation Settings for ESPPrefs
Max Seconds To Respond5.3.3 Question Settings for ESPPrefs
measuring reaction times7.2 What the Data Looks Like
Memo Pad3.1 Overview of Questions
Memo Pad3.2.4 What About Other Memo Pad Entries?
memory considerations, Palm8.1 Memory considerations
menus, ESP Desktop4.3 Menu Reference
messages, customizing3.6 Custom Messages with %MSG
modifying ESP12. Modifying ESP

N
National Science Foundation (NSF)1. Overview
New Experiment4.3.1 File Menu
Non-Answer Value4.2.4 Question Settings for ESP Desktop
Non-Answer Value5.3.3 Question Settings for ESPPrefs

O
Open Experiment4.3.1 File Menu
ordered sampling3.5.2 Sampling from Question Sets with %CHOOSE and %RANDOM
ordered sampling3.5.2.2 Ordered Sampling from Question Sets with %CHOOSE
overview of ESP1. Overview

P
participants1. Overview
participantsPeople
Participants menu4.3.7 Participants Menu
popup lists3.2.1 Response Types
practical considerations8. Practical Matters
prefs.js file4.1.4 Special note about permissions
problems9. Troubleshooting

Q
question IDs3.2.2 About Question IDs
question IDs, negative3.2.3 Negative Question IDs
question sets3.5 Question Sets with %QSET
question sets3.5.1 Defining a Question Set
question sets3.5.3 Important Facts about Question Sets
question settings5.3.3 Question Settings for ESPPrefs
questionsExperiments
Questions menu4.3.5 Questions Menu
questions, branching3.3 Branching Questions with %NEXT
questions, conditional3.3 Branching Questions with %NEXT
questions, first asked3.2.3 Negative Question IDs
questions, ordered sampling3.5.2 Sampling from Question Sets with %CHOOSE and %RANDOM
questions, ordered sampling3.5.2.2 Ordered Sampling from Question Sets with %CHOOSE
questions, ordinary3.2 Ordinary Questions
questions, overview3. Creating Questions
questions, overview3.1 Overview of Questions
questions, precedence3.5.2.5 Sampling with Question Probabilities from Question Sets
questions, probabilities3.4 Probabilistic Questions with %PROB and %SNEXT
questions, random sampling3.5.2 Sampling from Question Sets with %CHOOSE and %RANDOM
questions, random sampling3.5.2.3 Random Sampling from Question Sets with %RANDOM
questions, random sampling3.5.2.4 Random Sampling with Weights from Question Sets, with %FREQ
questions, response types3.2.1 Response Types
questions, weighted3.4 Probabilistic Questions with %PROB and %SNEXT
questions.txt file4.4.1 Experiment Internals

R
random sampling3.5.2 Sampling from Question Sets with %CHOOSE and %RANDOM
random sampling3.5.2.3 Random Sampling from Question Sets with %RANDOM
random sampling with weights3.5.2.4 Random Sampling with Weights from Question Sets, with %FREQ
Randomize Questions4.2.4 Question Settings for ESP Desktop
Randomize Questions5.3.3 Question Settings for ESPPrefs
Randomize Trials4.2.3 Automation Settings for ESP Desktop
Randomize Trials5.3.2 Automation Settings for ESPPrefs
reaction times7.2 What the Data Looks Like
Read from Palm4.3.3 Experiment Menu
Read from Palm4.3.4 Settings Menu
Read from Palm4.3.5 Questions Menu
resetting the Palm6.5 Collect Data
response times7.2 What the Data Looks Like
Run At Invocation4.2.3 Automation Settings for ESP Desktop
Run At Invocation5.3.2 Automation Settings for ESPPrefs

S
sampling3.5.2 Sampling from Question Sets with %CHOOSE and %RANDOM
Save4.3.1 File Menu
saving an experiment4.3.1 File Menu
Seconds Between Beeps4.2.3 Automation Settings for ESP Desktop
Seconds Between Beeps5.3.2 Automation Settings for ESPPrefs
Send questions to Palm4.3.5 Questions Menu
Send settings to Palm4.3.4 Settings Menu
Set name4.3.3 Experiment Menu
Set question editor4.3.5 Questions Menu
Set to global ESP defaults4.3.4 Settings Menu
settingsExperiments
Settings menu4.3.4 Settings Menu
settings, automation4.2.3 Automation Settings for ESP Desktop
settings, automation5.3.2 Automation Settings for ESPPrefs
settings, beep5.3.4 Sound Settings for ESPPrefs
settings, general5.3.1 General Settings for ESPPrefs
settings, question5.3.3 Question Settings for ESPPrefs
settings, sound5.3.4 Sound Settings for ESPPrefs
SLEEPING3.6.3 SLEEPING and WAITMSG
sliders3.2.1 Response Types
sound settings5.3.4 Sound Settings for ESPPrefs
source code for ESP12. Modifying ESP
STARTTRIAL3.6.1 STARTTRIAL
Subject ID4.2.2 General Settings for ESP Desktop
Subject ID5.3.1 General Settings for ESPPrefs
subject-data directory4.4.1 Experiment Internals
subject-data directory7.1 Where the Data is Located
subjects1. Overview
subjectsPeople
support10. Bugs
support for ESPSupport

T
Take Over Machine4.2.2 General Settings for ESP Desktop
Take Over Machine5.3.1 General Settings for ESPPrefs
Take Over Machine, disabling6.5 Collect Data
terminology1.3 Terminology
Testing ESP Desktop2.3 Testing the Installation
testing ESP experiments6.3.1 Set Up a Test Palm
text input, free-form3.2.1 Response Types
Total Trials4.2.3 Automation Settings for ESP Desktop
Total Trials5.3.2 Automation Settings for ESPPrefs
Trials Per Day4.2.3 Automation Settings for ESP Desktop
Trials Per Day5.3.2 Automation Settings for ESPPrefs
troubleshooting9. Troubleshooting

U
uninstalling ESP, LinuxUninstalling ESP
uninstalling ESP, WindowsUninstalling ESP
UniversalXPConnect4.1.4 Special note about permissions
unsafe operation warning4.1.4 Special note about permissions
upgrading ESP2.5 Upgrading ESP
uploading data from Palm4.3.7 Participants Menu
uploading data from Palm6.5 Collect Data

V
vertical bar “|” symbol3.2 Ordinary Questions
View License4.3.8 Help Menu
vocabulary1.3 Terminology

W
WAITMSG3.6.3 SLEEPING and WAITMSG
widgets (ESP)3.2.1 Response Types
Windows, installing ESP2.1 Installing on Windows
Windows, uninstalling ESPUninstalling ESP

Jump to:   %  
A   B   C   D   E   F   G   H   I   K   L   M   N   O   P   Q   R   S   T   U   V   W  

[Top] [Contents] [Index] [ ? ]

Table of Contents


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated by Daniel Barrett on October 5, 2016 using texi2html 1.82.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ < ] Back Previous section in reading order 1.2.2
[ > ] Forward Next section in reading order 1.2.4
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ Up ] Up Up section 1.2
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated by Daniel Barrett on October 5, 2016 using texi2html 1.82.