PXLab Manual

[Home]    [Content]    [Previous Chapter]    [Next Chapter]


Running an Experiment

A special feature of PXLab is that experiments may be run as local applications or as applets within HTML pages. It is even possible to create experimental design files which can do both without any change. Laboratory applications will usually be run as local applications. Internet experiments will use applets to run experimental design files. Applets, however, have certain restrictions which limit their usefulness for running experiments. They are very useful for running demonstration experiments where some of the restrictions do not apply. In these cases it is rather convenient to have an applet which at least in principle can do the same as a full featured laboratory experiment but does not need any special preparation and can be run by any modern browser.

Running an Application

There are two ways to run an experiment as an application. One is the command line application ExRun and the other one is the design editor ExDesignEditor which is described in chapter 'The Experimental Design Editor'.

The class ExRun is mainly a command line application. It is controlled by command line options and arguments. The following table describes all available command line options.

-s code set SubjectCode to 'code'
-g code set SubjectGroup code to 'code'
-r framed window on primary screen device
-x full screen on primary screen device
-z full screen on secondary screen device
-w n set window width to n pixels
-h n set window height to n pixels
-R n set display device refresh rate n
-S n set display device type or mode n. Use '?' to get a list of possible modes.
-E enc use encoding 'enc'. Possible values are defined by
-f file use design file 'file'
-d file write formatted data to file 'file'
-t file write processed data to file 'file'
-i file add file 'file' to list of initialization files
-p file use protocol output data file 'file'
-J convert design file to a Java source file
-H convert design file to a HTML text file
-D code set debugging option 'code'. Use '?' to get a list of available debug option
-L lang set default language for multi-language design files
-T print design file tree after parsing
-M start a memory monitor to watch heap space consumption
-Z run data processing nodes only. No experiment is run.
-V show version number only
-? show this help text

Thus the command line

  java de.pxlab.pxl.run.ExRun -f demo.pxd
immediately starts the experiment running the design file 'demo.pxd' which must be contained in the current working directory.

It also is possible to enter global parameter assignments in the command line. Such an assignment must not contain spaces and must be delimited by a colon:

  java de.pxlab.pxl.run.ExRun -f demo.pxd SubjectCode=4;
This assigns the code '4' to the parameter 'SubjectCode'. Assignments are assignments of values to experimental parameters. Assignments must be closed by a ';'-character. Quote characters in assignments must be escaped by the '\'-character. Depending on the operating system it may also be necessary to quote assignments in the command line. Thus under Windows we actually have to type
  java de.pxlab.pxl.run.ExRun -f demo.pxd "SubjectCode=4;"

The display device option '-S' selects the display device type and mode which is used for the stimulus display. The type may be full screen or window. The device may be the primary, the secondary or both screens. Here are the respective display device type codes as defined in DisplayDeviceCodes:

CodeVerbalType
0 'framedA display window embedded into a decorated frame (the default).
1 'unframedA display window embedded into an undecorated frame.
2 'fullscreen'An ordinary full screen display window.
3 'secondary'A full screen display window on the secondary screen device.
4 'exclusive'A full screen exclusive mode window. This mode should guarantee the best possible performance on most graphics devices.
5 'secexclusive'A full screen exclusive mode window on the secondary screen device. This mode should guarantee the best possible performance on most graphics devices which can control two independent dsiplays.
6 'dualframedTwo framed windows on a single device.
7 'dualunframed'Two unframed windows on a single device.
8 'dualfull'Two full screen windows on the primary and secondary screen device respectively.
9 'dualexclusive'Two full screen exclusive mode windows on the primary and secondary screen device respectively.

The verbal display type codes may be shortened until it uniquely defines one of the options.

In addition to setting the display device type the option '-S' may also be used to set the mode of full screen exclusive windows. Thus if the option '-S 4' is set then an additional option may set the resolution and refresh rate of full screen exclusive mode. Thus '-S 800x600x100' will set a resolution of 800x600 pixels at a refresh rate of 100 Hz. Setting the resolution and refresh rate, however, requires that the graphics hardware supports the respective mode. The resolution may also be set by using the options '-w' and '-h' and the refresh rate may be set by using option '-R'. The 'Graphics Environment' submenu of the 'Info' menu of application ExDesignEditor may be used to see a list of most of the available pixel resolutions and refresh rates for the current graphics hardware.

The debug option '-D' accepts numeric option codes as defined by DebugCodes or the following string options codes:

files Show file open/close protocol.
parser Print parser protocol.
assignment Assignment execution trace.
expression Expression evaluation trace.
colorgamut Print colors which cannot be shown on the current color device.
node Print design node creation protocol.
display Trace special display object properties.
list Trace display list management.
push Show push/pop operations for design node arguments.
argval Show display list argument values after execution.
states Show session control, error, and feedback states.
multisession check active session list for multiple sessions.
adaptive Adaptive procedure parameter protocol.
timing Show display list timing protocol.
hrtiming Show display list timing protocol using nanosecond resolution.
voicekey Trace voive key levels.
media Trace media events.
textposition Show text frames and position reference points.
edit Show design tree editing operations.
data Check data analysis computations.
factory Trace design tree factory methods.
symbol Watch the symbol table generation.
focus Trace focus changes.
errors Print stack trace on errors.
none don't add a debug option.

Entering as many letters as is necessary to identify an option is sufficient.

When Running out Memory

In some cases it may be possible that the default options for the Java Virtual Machine do not provide enough heap space for a PXLab application. If this happens then an experiment may be terminated with an OutOfMemoryError from the Java Virtual Machine.

This problem may be solved by using a command line option for the java command. The option is '-Xmx' followed by the amount of heap memory to be used:

  java -Xmx256m de.pxlab.pxl.run.ExRun
will start the application ExRun with a maximum heap size of 256 MB. This should be enough for most PXLab applications.

The demonstration program VisionDemonstrationsshould always be started with option '-Xmx64m' to ensure proper working of all demos.

Working with Applets

There are two ways to integrate a PXLab applet into a HTML page: using class ExRunApplet or using class ExRunStarterApplet. In both cases there is an important restriction to observe: Multiple runs of experiments in the same context are not possible. PXLab tries to prevent a second instance of an experimental run to start when one is already running. However, this may not succede in all possible cases of applet usage. Note that this does not affect the applet classes ExRunApplet and ExRunStarterApplet themselves but only the experimental runs. Thus it is possible to have multiple starter applets embedded into a single HTML page, but at any point in time only one of them can be running an experiment.

Using a Start Button to Start an Applet

The applet class ExRunStarterApplet shows only a single start button within the HTML page and the experiment starts when this button is pressed. This opens a new window within which the experiment is run. Here again is the example for using the ExRunStarterApplet applet class as shown in chapter 'The Design of an Experiment':

The HTML-code for embedding this starter button into a HTML page is:

<applet 
        codebase="." 
        archive="exrunbutton.jar, pxlabrt.jar" 
        code="de.pxlab.pxl.run.ExRunStarterApplet.class"
	width=500 height=60 mayscript>
  <param name="CommandLine" value="-S0">
  <param name="DesignFile" value="design_file_demo_01.pxd">
  <param name="StartButtonLabel" value="Start Demo Experiment"> 
</applet>
This starts the applet ExRunStarterApplet whose code is contained in the jar file pxlab.jar which itself is contained in the same directory as the HTML file containing this applet tag. The tag also defines three parameters of the applet:
DesignFile
is the name of the experimental design file. The name of this file is relative to HTML file's directory.
StartButtonLabel
is the label of the start button. Pressing this button starts the experiment.
CommandLine
is a string which may contain additional command line arguments. See the previous section for additional command line options.

Note that the experimental design file must be defined by using the parameter DesignFile otherwise the applet will not be able to start an experiment. It is not possible here to use a command line option to define the design file name.

Using an Embedded Applet Window

The applet class ExRunApplet creates a window within the HTML page and can run the experiment within that window. The window contains a button bar which makes it possible to start or stop the experiment. Here we use the class ExRunApplet to embed the display window into the HTML-page:

The HTML-code for embedding this applet is

<applet
   archive="pxlabrt.jar" 
   code="de.pxlab.pxl.run.ExRunApplet.class" 
   width=640 height=480 mayscript>
   <param name="CommandLine" value="-S0">
   <param name="DesignFile" value="design_file_demo_01.pxd">
</applet>
Note that the class ExRunApplet accepts only two parameters:
CommandLine
The content of this parameter is evaluated in exactly the same way as the command line of an application.
DesignFile
The name of the design file to run.

Applet Data

Java applets are not allowed to write data to the client's file system. And usually this actually is not what is wanted when running an experiment on the net. In most cases the data should be sent back to the server. Currently PXLab uses the GET- or the POST-method of the HTTP protocol to send data to the server. The data file destination is defined within the experimental design file. Here are the rules for experiments which run as an applet:
  1. If the experimental parameter DataFileDestination is undefined then the applet opens another browser window and shows the data in that window. This requires that the applet tag has the mayscript property enabled and the JavaScript method showData() is defined:
    <SCRIPT>
      function showData(s) {
         ergWin = window.open()
         ergWin.document.write(s)
      }
    </SCRIPT>
    

    This piece of code must be contained in the HTML file containing the applet in order to satisfy the request for opening a new window for showing the data. Note, however, that this only works if the client's browser has JavaScript enabled and the browser has a correct implementation of JavaScript.

  2. If the experimental parameter DataFileDestination is defined and contains a valid URL then the data file is sent to that URL using the GET method as defined in the HTTP protocol. Thus the URL should contain a valid script program for accepting the data. Here is a simple example for a PHP script to accept the data of an experiment and show them in a browser window:
       echo $DataFileName;
       echo $Data;
    
    The PHP-variable DataFileName contains the name of the data file and the variable Data contains the complete set of data.
  3. A disadvantage of the GET-method is its limited capacity. Using the GET method transfers the data within the URI. If the parameter HTTPRequestMethod is set to 'POST' then the POST-method is used to transfer the data to the server. The receiving script may use the same variables as described for the GET-method to receive the data and store them in a file. Here is a PHP example which receives the data and then sends it via E-mail to some destination:

      mail($email, "PXLab Data File ".$DataFileName, $Data, "From: PXLab" ); 
    

    here the PHP-variable '$email' must contain a valid E-mail address.

Parameter Initialization at Startup

When PXLab starts an experiment it follows a special sequence of parameter initialization steps. This includes initialization from built in defaults but also includes initialization from parameter files which may be global system files or may be files specific for a single experiment, a single user or a special display device.
  1. Initialize to Built In Defaults
  2. The first step of initialization at startup is to set all experimental parameters to their built in defaults. Every experimental parameter has a default value which is defined in the source code. At startup every parameter is reinitialized to this value.

    After all parameters have their built in default values several assignment files are executed. These files may be used to adapt the default parameter values to the computing environment where PXLab is running.

  3. Global 'system.pxd' in Directory Named by 'pxlab.home'
  4. The first initialization file read is the file system.pxd which must be located in the global PXLab home directory. The location of the global PXLab home directory is defined in the PXLab properties file named pxlab.properties by the property pxlab.home. The pxlab.properties file is searched in the following locations: the current working directory, the user home directory, the Java class path, the Java library path, the Java library extensions directory, the Java installation jar files directory, and the Java installation executables directory.

  5. Local 'system.pxd' in Directory Named by 'pxlab.home'
  6. The next initialization file read is also called system.pxd but must be located in a local PXLab directory. This directory also is defined in the file pxlab.properties by the property pxlab.local. The separation between pxlab.home and pxlab.local may be especially useful for network installations of PXLab where the global PXLab home is located on a server and the local PXLab home is located on a client machine.

  7. Initialization of Local Screen Properties
  8. After the files system.pxd have been read PXLab tries to read local initialization files which define the display screen properties. The default name for such a file is screen.pxd, however, this name may be changed in the system.pxd file by setting the parameter ScreenParameterFile. This parameter may contain an array of file names for defining the screen parameters of multiple screen display systems. The location of these files must be the local PXLab home directory as defined by the property pxlab.local.

  9. Command Line Initialization Files
  10. Additional startup parameter value assignments may be contained in files which are given on the command line of a PXLab application by using the option -i. These files are executed after the system initialization files and before the experimental design file.

  11. Context Node Assignments
  12. The next step is that all assignments which are contained in the Context node of the design file are executed. This includes assignments in an AssignmentGroup node and assignments which are contained in DisplayList and Display definitions. This also creates all new experimental parameters defined in any AssignmentGroup.

  13. Command Line Assignments
  14. Finally all those assignments which are given in the command line are executed.

  15. Implicit Factor Parameters
  16. The last step then is to create all experimental parameters which are implicitly defined by the Factors node as independent factors and which do not yet exist.

Initialization Files Overview

FileLocationPurpose
pxlab.properties the current working directory,
the user home directory,
the Java class path,
the Java library path,
the Java library extensions directory,
the Java installation jar files directory,
the Java installation executables directory
Define the global and the local PXLab home directory. Example:
pxlab.home=X:/pxlab
pxlab.local=C:/pxlab
system.pxddefined by the property pxlab.homedefine global (server related) system parameters.
system.pxddefined by the property pxlab.localdefine local (client related) system parameters. Example:
ScreenParameterFile = ["gamma1.pxd", "gamma2.pxd"];
This defines screen initialization files for a dual screen display system. These files must be located in the directory defined by pxlab.local.
screen.pxddefined by the property pxlab.localdefine display system parameters.
option -icontained in the argumentrun time specific initializations.

[This file was last updated on July 15, 2010, 12:07:01.]

[Home]    [Content]    [Previous Chapter]    [Next Chapter]