The file format used to save experiments constructed in PsychoPy® builder was created especially for the purpose, but is an open format, using a basic xml form, that may be of use to other similar software. Indeed the builder itself could be used to generate experiments on different backends (such as Vision Egg, PsychToolbox or PyEPL). The xml format of the file makes it extremely platform independent, as well as moderately(?!) easy to read by humans. There was a further suggestion to generate an XSD (or similar) schema against which psyexp files could be validated. That is a low priority but welcome addition if you wanted to work on it(!) There is a basic XSD (XML Schema Definition) available in psychopy/app/builder/experiment.xsd.
The simplest way to understand the file format is probably simply to create an experiment, save it and open the file in an xml-aware editor/viewer (e.g. change the file extension from .psyexp to .xml and then open it in Firefox). An example (from the stroop demo) is shown below.
The file format maps fairly obviously onto the structure of experiments constructed with the Builder interface. There are general Settings for the experiment, then there is a list of Routines and a Flow that describes how these are combined.
As with any xml file the format contains object nodes which can have direct properties and also child nodes. For instance the outermost node of the .psyexp file is the experiment node, with properties that specify the version of PsychoPy® that was used to save the file most recently and the encoding of text within the file (ascii, unicode etc.), and with child nodes Settings, Routines and Flow.
Many of the nodes described within this xml description of the experiment contain Param entries, representing different parameters of that Component. Nearly all parameter nodes have a name property and a val property. The parameter node with the name “advancedParams” does not have them. Most also have a valType property, which can take values ‘bool’, ‘code’, ‘extendedCode’, ‘num’, ‘str’ and an updates property that specifies whether this parameter is changing during the experiment and, if so, whether it changes ‘every frame’ (of the monitor) or ‘every repeat’ (of the Routine).
The Settings node contains a number of parameters that, in PsychoPy®, would normally be set in the Experiment settings dialog, such as the monitor to be used. This node contains a number of Parameters that map onto the entries in that dialog.
This node provides a sequence of xml child nodes, each of which describes a Routine. Each Routine contains a number of children, each specifying a Component, such as a stimulus or response collecting device. In the Builder view, the Routines obviously show up as different tabs in the main window and the Components show up as tracks within that tab.
Each Component is represented in the .psyexp file as a set of parameters, corresponding to the entries in the appropriate component dialog box, that completely describe how and when the stimulus should be presented or how and when the input device should be read from. Different Components have slightly different nodes in the xml representation which give rise to different sets of parameters. For instance the TextComponent nodes has parameters such as colour and font, whereas the KeyboardComponent node has parameters such as forceEndTrial and correctIf.
The Flow node is rather more simple. Its children simply specify objects that occur in a particular order in time. A Routine described in this flow must exist in the list of Routines, since this is where it is fully described. One Routine can occur once, more than once or not at all in the Flow. The other children that can occur in a Flow are LoopInitiators and LoopTerminators which specify the start and endpoints of a loop. All loops must have exactly one initiator and one terminator.
For the experiment to generate valid PsychoPy® code the name parameters of all objects (Components, Loops and Routines) must be unique and contain no spaces. That is, an experiment can not have two different Routines called ‘trial’, nor even a Routine called ‘trial’ and a Loop called ‘trial’.
The Parameter names belonging to each Component (or the Settings node) must be unique within that Component, but can be identical to parameters of other Components or can match the Component name themselves. A TextComponent should not, for example, have multiple ‘pos’ parameters, but other Components generally will, and a Routine called ‘pos’ would also be also permissible.
<PsychoPy2experiment version="1.50.04" encoding="utf-8">
<Settings>
<Param name="Monitor" val="testMonitor" valType="str" updates="None"/>
<Param name="Window size (pixels)" val="[1024, 768]" valType="code" updates="None"/>
<Param name="Full-screen window" val="True" valType="bool" updates="None"/>
<Param name="Save log file" val="True" valType="bool" updates="None"/>
<Param name="Experiment info" val="{'participant':'s_001', 'session':001}" valType="code" updates="None"/>
<Param name="Show info dlg" val="True" valType="bool" updates="None"/>
<Param name="logging level" val="warning" valType="code" updates="None"/>
<Param name="Units" val="norm" valType="str" updates="None"/>
<Param name="Screen" val="1" valType="num" updates="None"/>
</Settings>
<Routines>
<Routine name="trial">
<TextComponent name="word">
<Param name="name" val="word" valType="code" updates="constant"/>
<Param name="text" val="thisTrial.text" valType="code" updates="set every repeat"/>
<Param name="colour" val="thisTrial.rgb" valType="code" updates="set every repeat"/>
<Param name="ori" val="0" valType="code" updates="constant"/>
<Param name="pos" val="[0, 0]" valType="code" updates="constant"/>
<Param name="times" val="[0.5,2.0]" valType="code" updates="constant"/>
<Param name="letterHeight" val="0.2" valType="code" updates="constant"/>
<Param name="colourSpace" val="rgb" valType="code" updates="constant"/>
<Param name="units" val="window units" valType="str" updates="None"/>
<Param name="font" val="Arial" valType="str" updates="constant"/>
</TextComponent>
<KeyboardComponent name="resp">
<Param name="storeCorrect" val="True" valType="bool" updates="constant"/>
<Param name="name" val="resp" valType="code" updates="None"/>
<Param name="forceEndTrial" val="True" valType="bool" updates="constant"/>
<Param name="times" val="[0.5,2.0]" valType="code" updates="constant"/>
<Param name="allowedKeys" val="['1','2','3']" valType="code" updates="constant"/>
<Param name="storeResponseTime" val="True" valType="bool" updates="constant"/>
<Param name="correctIf" val="resp.keys==str(thisTrial.corrAns)" valType="code" updates="constant"/>
<Param name="store" val="last key" valType="str" updates="constant"/>
</KeyboardComponent>
</Routine>
<Routine name="instruct">
<TextComponent name="instrText">
<Param name="name" val="instrText" valType="code" updates="constant"/>
<Param name="text" val=""Please press; 1 for red ink, 2 for green ink 3 for blue ink (Esc will quit) Any key to continue"" valType="code" updates="constant"/>
<Param name="colour" val="[1, 1, 1]" valType="code" updates="constant"/>
<Param name="ori" val="0" valType="code" updates="constant"/>
<Param name="pos" val="[0, 0]" valType="code" updates="constant"/>
<Param name="times" val="[0, 10000]" valType="code" updates="constant"/>
<Param name="letterHeight" val="0.1" valType="code" updates="constant"/>
<Param name="colourSpace" val="rgb" valType="code" updates="constant"/>
<Param name="units" val="window units" valType="str" updates="None"/>
<Param name="font" val="Arial" valType="str" updates="constant"/>
</TextComponent>
<KeyboardComponent name="ready">
<Param name="storeCorrect" val="False" valType="bool" updates="constant"/>
<Param name="name" val="ready" valType="code" updates="None"/>
<Param name="forceEndTrial" val="True" valType="bool" updates="constant"/>
<Param name="times" val="[0, 10000]" valType="code" updates="constant"/>
<Param name="allowedKeys" val="" valType="code" updates="constant"/>
<Param name="storeResponseTime" val="False" valType="bool" updates="constant"/>
<Param name="correctIf" val="resp.keys==str(thisTrial.corrAns)" valType="code" updates="constant"/>
<Param name="store" val="last key" valType="str" updates="constant"/>
</KeyboardComponent>
</Routine>
<Routine name="thanks">
<TextComponent name="thanksText">
<Param name="name" val="thanksText" valType="code" updates="constant"/>
<Param name="text" val=""Thanks!"" valType="code" updates="constant"/>
<Param name="colour" val="[1, 1, 1]" valType="code" updates="constant"/>
<Param name="ori" val="0" valType="code" updates="constant"/>
<Param name="pos" val="[0, 0]" valType="code" updates="constant"/>
<Param name="times" val="[1.0, 2.0]" valType="code" updates="constant"/>
<Param name="letterHeight" val="0.2" valType="code" updates="constant"/>
<Param name="colourSpace" val="rgb" valType="code" updates="constant"/>
<Param name="units" val="window units" valType="str" updates="None"/>
<Param name="font" val="arial" valType="str" updates="constant"/>
</TextComponent>
</Routine>
</Routines>
<Flow>
<Routine name="instruct"/>
<LoopInitiator loopType="TrialHandler" name="trials">
<Param name="endPoints" val="[0, 1]" valType="num" updates="None"/>
<Param name="name" val="trials" valType="code" updates="None"/>
<Param name="loopType" val="random" valType="str" updates="None"/>
<Param name="nReps" val="5" valType="num" updates="None"/>
<Param name="trialList" val="[{'text': 'red', 'rgb': [1, -1, -1], 'congruent': 1, 'corrAns': 1}, {'text': 'red', 'rgb': [-1, 1, -1], 'congruent': 0, 'corrAns': 1}, {'text': 'green', 'rgb': [-1, 1, -1], 'congruent': 1, 'corrAns': 2}, {'text': 'green', 'rgb': [-1, -1, 1], 'congruent': 0, 'corrAns': 2}, {'text': 'blue', 'rgb': [-1, -1, 1], 'congruent': 1, 'corrAns': 3}, {'text': 'blue', 'rgb': [1, -1, -1], 'congruent': 0, 'corrAns': 3}]" valType="str" updates="None"/>
<Param name="trialListFile" val="/Users/jwp...troop/trialTypes.csv" valType="str" updates="None"/>
</LoopInitiator>
<Routine name="trial"/>
<LoopTerminator name="trials"/>
<Routine name="thanks"/>
</Flow>
</PsychoPy2experiment>