Experiment Files - Description

Is current?: 
Yes

The Experiment file is an xml file that calls each of the files in your study in the order you design. Think of it as the roadmap or outline of your study. There are three parts to an experiment file: the study ID, the definitions, and the map.

Study ID

This tag identifies two things: your study name and the datagroup to which it belongs. Your study name should be unique, as this is the id that will be used to call up the data from your study. It should certainly involve your name (or username) and a name for your study. Below are a few past study ids:

  • akeevil.trust1
  • jjoy.dissertationstudy6
  • calvin.contest.0001

The datagroup will either be “research” or “std.” Unless you are creating a demonstration study, the datagroup is research.

The entire opening Study tag will look something like this:

<Study id="jjoy.dissertationstudy" datagroup="research">

Be sure that the end of your experiment file ends with </Study> to close the study tag you opened at the start of the file.

Definitions

The definitions section lists each task in your study. Each task has a name within the experiment file (known as “task id”), and at least one file reference. Below are the three ways to list a task in your study:

  • To reference a file in your study folder (the same folder where the experiment file is):

<Task id="debriefing">racedebriefing.jsp</Task>

  • To reference a file in another study folder (this is recommended ONLY for files in the common folder. Almost always, your task files should be in your study folder):

<Task id="start">/common/en-us/html/Instructions.jsp</Task>

  • To reference a file in your study folder that uses another file (this is most common for implicit measures):

<Task id="iatrace1" file="iatrace1.xml">/common/en-us/html/iattask6.jsp</Task>

There are several kinds of definitions one can have in an experiment file:

  • A basic html page would look like:

<Task id="sample">sample.html</Task>

  • A jsp page would look like:

<Task id="sample">sample.jsp</Task>

  • An xml form would look like:

            <Task id="sample" type="xform">sample.xml</Task>

Remember that the Definitions tag, <Definitions> </Definitions>, should encase the list of tasks.

The order of the files in the definitions list does not matter. It may be useful to organize them in the order they come in the study, but the file does not require it.

One important note is that every definition should have a different id. For example, you might have two conditions, conditionA and condition, both of which use the same dependent measure “questionnaire.” To ensure this works properly in your file you need to create two definitions, one for the first condition and one for the second. So your definition file would look like this:

<Task id="questionnaireA">questionnaire.jsp</Task>
<Task id="questionnaireB">questionnaire.jsp</Task>

The tasks call the same questionnaire file you designed, but now they have two different ids that coincide with the conditions – presumably questionnaireA would be called during conditionA and questionnaire would be called in conditionB.

Map

The map is the section where you organize each task in the definitions into the order of your study. Each of the tasks should be listed in the following format:

<Task id="sample"/>

Be sure to use exactly the same task ID that you listed in the Definitions section. Once again, the map tag, <Map> </Map>, should encase all of the tasks in the study outline.

A few tips:

The entire experiment file is case sensitive. That is, if your experiment file calls Lastpage.htm but your file name is actually named lastpage.htm, you will get an error. You’ll also get an error if your Definitions section lists a task named lastpage but your map references a task named Lastpage. The best way to avoid any trouble with this is to avoid using any capitalization in your filenames.

Your study id is also case sensitive in that when you download your data, you will need the exact study id listed in this file to find your data.

Experiment files can be quite complex through a system called branching. Branching is very useful if you have multiple conditions or you want to randomize some or all of the tasks in your study. See the basic experiment file (no branching), the moderate experiment file (basic branching), or the advanced experiment file (branching within branching) page for more descriptions on how to create your file.