DRAFT
Writing Experiments for PsychExps: Guidelines and Suggestions
Save as a MS Word 97 Document
Phase I: Create a new experiment
Step 1) Open "New Experiment.a5p" in Authorware
Step 2) Use File/Save As to rename New Experiment with a new name for your experiment. We recommend creating a new folder for your experiment at this time, as well.
Step 3) Construct your experiment on the flowline below the "Instructions" map
Step 4) Add content to the display icons titled One/Two/Three to explain to the user what to expect and how to respond. (These icons are in the "Instructions fr" framework in the "Read Instructions" button response). You can delete unused pages. The default for this framework is to provide only Previous page", "Next page" and "Exit" buttons. (Note: it's easier to write instructions after the experiment is substantially complete).
Step 5) Save your experiment (File/Save or Ctrl-S)
Step 6) Debug. Debug. Debug. Test your experiment with inputs you don't expect. Remember, there are both dumb and malicious users out there.
Phase II: Paste the experiment into the template
Step 1) Take the experiment completed in Phase I and place everything except the "Debug and Styles" group into a new group (suppose it's called "UM Experiment")
Step 2) Select the UM Experiment group and copy it to the clipboard (File/Copy or Ctrl-C)
Step 3) Open a new instance of Authorware and open "Template2k.a5p"
Step 4) Use File/Save As to rename Template2k to the name of your experiment--place this is the same folder as the module created in Phase I. (To differentiate the two files you can append a "_t" to the file name used in Phase I. In this example the experiment alone would be in "UM Experiment.a5p" and the renamed template would be "UM Experiment_t.a5p".
Step 5) Open the "Administer Experiment Group" and click just above the "The experiment goes here" group. The paste hand should appear on the flowline.
Step 6) Paste your experiment into the template (File/Paste or Ctrl-V).
Step 7) Select the "The experiment goes here" group and delete it.
Step 8) Save your new experiment (File/Save or Ctrl-S).
Phase III: Make changes to variables in the template and set up data
Authors must make the following changes to template:
Step 1) Variables experiment, title, and author (in the "Set Experiment, Title and Author" icon) must be changed as follows
Experiment: the name of the file on the UM server where data will be stored. PsychExps folks will work with you on choosing a name.
Title: the title of the experiment, like "Lateralized Stroop". This will appear on the title page and data transmission pages
Author: the authors, as you would like them to appear on the title page
Step 2) Informed consent.
The text in the "Informed Consent" interaction must be changed to reflect the experiment being authored. The informed consent also contains "boilerplate" with respect using the PsychExps site. The informed consent text can be changed with the text tool or imported from another document.
Step 3) Subject variables.
Open the "Get Info"/"Subject variables" group. From the "Subject variables holder" decision icon, click and drag onto the flowline below the subject variables that you want to collect. Then select the "Subject variables holder" icon and the unused groups and delete them.
If you want to collect a subject variable not already in template, please talk to the PsychExps team and we will prepare a new icon and add it to template. This way, we can assure that data is collected and transmitted to the database in a uniform manner. The current choices are Gender, Handedness, and Age.
Authors may make the following changes to template:
1) If your experiment does not involve timed displays or reaction time measurements, you may want to delete the two yellow timecheck (timechk and 2d timechk) icons. These icons perform the consistency test and assist in estimating the error in web-delivered experiments.
2) "Feedback" within the PostURL Data Group. If you'd like to provide feedback to the participants in your experiment, you may modify this icon group. We believe that users should be given feedback only after they've chosen to submit data to the archive and the transmission has occurred.
Please do not make any changes to the following:
1) Debug and Styles.
These contain predefined text styles that are common to all experiments at PsychExps. You may add new styles if you like, but please do not modify this group.
2) Initialize Answer.
PsychExps uses a list variable to hold subject variables, trial data, and other information. For example, the variable experiment is always put in Answer[1] and is the first datum transmitted to the server when data is archived. The processing scripts on the server look for a file with the name of the first datum and append the data there. "Initialize Answer" sets this up, among other things.
3) The Logo.
We'd just like for all PsychExps experiments to identify themselves as so internally. You can erase the logo within the experiment if you need to--as we had to do with our Poggendorff experiment.
4) Get Name and ID Group.
To preserve the confidentiality of users of PsychExps, publicly accessible data will be identified only by an experiment-assigned ID (a random three-character, three-digit ID). A separate file will be maintained which links the user-entered name and the ID, and instructors will be given access to this file in order to award credit to students who are participating as part of a class project. Note that there's no guarantee that a user will enter his or her real name.
5) Get Project Group.
PsychExps keeps a list of "registered" projects in a file on the server. This icon group reads the file from the server and presents it to the user to choose an "affiliation", which is included in the archived data. This enables classes to separate their data from the entire set. (The number of affiliates is rising so rapidly that this interface is slated for attention this summer--any volunteers or suggestions?).
6) PostURL Data Group.
This icon group takes data from the list variable Answer[] and formats it so that it can be processed by the script on the server. It also presents information to the user and encourages the user to not send data if he or she believes that the data is not valid. This icon group contains the PostURL command that sends data to the UM server. (Authors can change the "Feedback" icon group within the PostURL Data Group).
Suggestions and comments
We've learned a lot from studying Authorware pieces that others have created. If your new experiment structure is similar to that of an existing experiment, create your new experiment by modifying the existing source code (which can be downloaded from the PsychExps site). The first step after loading the existing experiment will be File/Save As …, and save the experiment under a new name. Then, make the changes to modify the experiment. When it's working well, you can either copy/paste it into template as described above, or simply make the necessary changes to experiment, author, title, Feedback, etc.
To create a new structure, we suggest you begin with NewExperiment.a5p, which already contains the "Styles and Debug" icon. This way you will have the common styles available to you during the entire authoring process. As when modifying an existing experiment, the first step is File/Save As … under a new name.
Macromedia suggests that lay out the structure of your experiment with empty icons, and "run" the program (Control/Restart or Ctrl-R). Whenever AW encounters an empty icon it pauses and opens up the authoring tools. This way your content can always be created in context.
As you develop the experiment and modify it, you can place empty display, erase, or calculation icons in the flowline by dragging them from the toolbar. Ctrl-R will run the piece and pause in the authoring environment when the empty icon is encountered.
If you have an icon which has content that you'd like to modify or add to, and you want to do this in context, and it's far down in the piece, you can save time by dragging the "Start" flag on to the flowline and using Control/Restart from Flag (Cntrl-Alt-R).
When you need the content of a single previous icon displayed in order to align elements of the current icon, you can first double-click the icon that displays the necessary material. Close that display. Hold down the Shift key while double-clicking the icon that you want to modify or add to.
If you need the contents of several icons visible while you set content for the current icon, you can set the context by shift-double click and close several times. Double-click 1st icon--1st icon contents are displayed. Shift-double-click 2d icon--1st and 2d icon contents are displayed. … Shift-double-click icon to be modified--all previous icon contents are displayed.
At any time the experiment is executing in Authorware, you can pause the piece and bring up the authoring tools by double-clicking on an object displayed on the screen. Since the screen may be displaying contents of several icons, you can change authoring from icon to icon by double-clicking on different parts of the screen.
If double-clicking is not possible because you're in the middle of text entry, (or because a click is the interaction desired, or for other reasons) you can pause the piece with Ctrl-P. Now, double-clicking an object brings up the authoring tools. Alternatively, View/Current Icon (Control-B) will take you from the display screen to the flowline, where you can double-click or shift-double-click on the icon you wish to examine or modify. You can resume execution with Control-Play (Ctrl-P). Note that Ctrl-P acts like a Pause/Play toggle.
While an experiment is paused, you can click on the "variables" icon (next-to-rightmost at the top of AW) and examine system and custom variables. Custom variables are those you (or the template) have defined, and are always accessible by choosing the last option in the category list.
Debugging
Attending the Macromedia User's Conference in 1997 changed my programming life. For one thing, I learned about Shockwave technology, which led to the FIPSE grant proposal, which led to involvement in cognitive psychology experiments. For another, I heard a professional Authorware developer tell this story:
I often have clients call for support when they're developing a new piece. If we can talk them through it, we do; but sometimes we reach a point where they want to send us the piece and have our staff debug the problem. Of course, the next question is "How much will this cost?" My answer is, "How many icons do you have that are untitled?"
Debugging is difficult at best, and is very difficult unless you know where you are. After using Ctrl-P to pause the piece, double-clicking on an object provides the information you need, if you've named your icons.
Good authoring practice is to give an icon a descriptive unique name as soon as you drag it to the flowline. If you copy and paste an icon, then change the name to a unique name immediately after pasting. I even recommend giving descriptive names to Erase icons so that you can read their function while examining the flowline (although you'll find that I don't always follow my own recommendations).
Debugging will be easier if you'll run the piece (Ctrl-R) often during authoring, checking each step along the way to make sure the experiment is performing as you intend it to. Then, when something fails you know that either the recently added icons contain an error, or that the recently added icons are interacting with previous icons in a way to create an error.
I believe that the most frequent causes of errors are incorrect settings for one or more icon's properties, or misunderstanding how to set up the desired effects. These are cases where tech support can help you find an error.
Errors caused by mis-typing are much harder to find, and simply require very careful attention to the flowline. If variables are involved, you can use the variables viewer to make sure that there are not two similarly named custom variables when you only intended for there to be one.
In the end, when all else fails, you can simply recreate the section that's failing from the very beginning. Don't cut and paste, because you may paste in the cause of the error. If you do this and the error reoccurs, you've either found a "bug" or you have some misunderstanding of functions or properties.
Packaging and Web-Packaging
In order to prepare experiments for delivery over the web, the first step is to "package" the piece (File/Package). Packaging compacts your piece and prepares it to be distributed as an executable file. Your choices are:
"without runtime" - Used to distribute when the recipient already has the authorware player. This is also the option for web delivery, since the plugin, or Web Player, is simply the authorware player running through the browser.
"For Windows 3.1" - for older operating systems. Also a subtle source of error if internal paths contain long file names. In this case the program works on Win 95, but that function fails for the intended target.
"For Windows 95/98/NT" - for newer operating systems.
The outcome of the packaging step is a file called filename.a4r.
Web packaging involves breaking up the packaged file into a number of segments (*.aas files) and creating a map file (*.aam) that tells the browser how many segments there are and how long each segment is. To package for web delivery, open up the Authorware Web Packager and browse until you've located the a4r file. You'll be prompted for the name of the *.aam file. After accepting the default or providing a new name, you'll be asked to provide a segment prefix and segment size—both of these have some performance implications.
The segment prefix is only 4 characters long, and the default is the first 4 characters of the file name. Be careful not to overwrite existing segments. To avoid overwriting, you can change the default segment prefix. For example, if you had two files, temp9902.a5p and temp9905.a5p, the default segment prefix for both would be "temp". If you wanted to be able to run both from the same directory (folder), you could make the temp9902 segment prefix "tem2" and the temp9905 prefix "tem5".
The segment size affects the user's experience when running the experiment through the browser, and may affect the accuracy of experiments that depend on precise timing. Choice of a small segment size means that the first segment will load quickly and the user can begin the experiment with little delay. While he or she is involved in answering the early questions, subsequent segments are streamed in the background. A large segment means that there's a long initial delay, but there are fewer segments to download.
However, any background activity is a probable cause of error for experiments that depend on reaction time measurements or tachistoscopic displays. Our recommendation for reaction time or tachistoscopic display experiments is to set the segment size so large that the entire experiment is packaged in a single segment. The user will have a longer initial delay, but the experiment accuracy will be determined by the capabilities of the user's computer and not by background network activity.
Our policy so far has been that experiments at PsychExps will run in "non-trusting" mode. This prohibits the experiment from causing any mischief in the user's computer or snooping around and reading files. The tradeoff is that this prevents use of digital movies and third-party add-ons (Xtras), because these would have to be downloaded to the user's hard disk before the experiment began.