PXLab Manual

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

Data Files

PXLab experiments can generate the following types of data files:

Data file names are by default derived from the SubjectCode parameter value. If no data file exists for the given SubjectCode then the SubjectCode becomes the data file name root. If a data file for the current SubjectCode already exists, then a 3-digit number is added to the SubjectCode and the number is incremented until a data file name is found which does not yet exist in the target directory.

Data File Destination

The data file destination is defined by the experimental parameter DataFileDestination. Its meaning depends on whether the experiment is running as an applet or an application.

Experiments Running as Applications

For applications the parameter DataFileDestination gives the full path name of the root directory for storing data files: 
 DataFileDestination = "C:/Data";

All data files are stored in this directory or in subdirectories contained in this directory.

By default the following experimental parameters define subdirectories of the data root for storing different types of data files. If a subdirectory name is defined to be an empty string then the respective data files are stored in DataFileDestination directly. The default value for DataFileDestination is the current working directory.

TrialDataDirectory
Trial data subdirectory of DataFileDestination. If this parameter is nonempty the it specifies a subdirectory of the DataFileDestination where to put raw trial data files (default: "dat").
DataTreeDirectory
Data tree subdirectory. If this parameter is nonempty then it specifies a subdirectory of the DataFileDestination where to put data tree files (default: "dtr").
ProcessedDataDirectory
Processed data subdirectory. If this parameter is nonempty the it specifies a subdirectory of the DataFileDestination where to put data processing results (default: "pdt"). Processed data are generated by DataDisplay objects only.
PlotDataDirectory
Plot data subdirectory. If this parameter is nonempty the it specifies a subdirectory of the DataFileDestination where to put plot data files (default: "pld"). Plot data are generated by DataDisplay objects only.

Experiments Running as Applets

In case of the experiment is running as an applet then DataFileDestination should contain the full URL where to send the data file to: 

  DataFileDestination = "/pxlab/demos/mailer.php";

The target should be a script in this case which accepts the data file and sends it to a save place. The method for sending data to this script is defined by the parameter HTTPRequestMethod. This parameter's value may be 'GET' or 'POST' for using the respective method of transfer to a server. In general it is better to use the POST method since the GET method accepts only a limited data file size. The POST method does not create a response page since it does not use the browser's connection to the server but creates its own connection to the server. One can see the server's echo on a POST request on the browser's Java console. The GET method uses the browser's connection to the server and sends the data encoded into the URL. The result is that the server's response is shown as a WWW page.

There is another parameter for HTTP-Data transfers which may be used by the receiving script. This is the parameter DataFileDestinationAddress. This parameter may be set to an E-Mail address where the receiving script should send the data to. The parameter value is contained in the PXLab message header sent to the DataFileDestination. This message actually contains three variables:

DataFileName
The name of the data file as derived from SubjectCode and also contained in the experimental parameter DataFileName.
Email
The value of the parameter DataFileDestinationAddress which may be an E-Mail address used by the receiving script.
Data
This variable has the full data file as its value.

Here is a PHP single-line-example which receives the data and then sends it via E-mail to some target destination: 

  mail($_REQUEST['Email'], "PXLab Data File ".$_REQUEST['DataFileName'], $_REQUEST['Data'], "From: PXLab" );
There elso exist some examples on how to use PXLab to send data to some arbitrary email address.

See section 'Applet Data' of chapter 'Running an Experiment' for some more information on applet data storing in the case when DataFileDestination is undefined.

The Data Tree

The design file of a PXLab experiment contains undefined experimental parameter values in the Procedure() section, which are written as a question mark: 
Procedure() {
  Session() {
    Block() {
      Trial("House", ?, ?);
      Trial("Garden", ?, ?);
      Trial("Chair", ?, ?);
      Trial("Mend", ?, ?);
      Trial("Kornte", ?, ?);
      Trial("Begren", ?, ?);
      ...
    }
  }
}
After an experimental session these parameter values have been set by the results of the respective trials: 
 Procedure()
  {
    Session()
    {
      Block()
      {
        Trial( "Chair", 1, 991);
        Trial( "House", 0, 278);
        Trial( "Begren", 1, 1275);
        Trial( "Kornte", 1, 782);
        Trial( "Garden", 0, 778);
        Trial( "Mend", 1, 613);
      }
    }
  }

Here the first question mark was the unknown ResponseCode parameter value and the second question mark was the unknown value of ResponseTime. PXLab writes the data tree file for every experimental run. This file is almost identical to the design file, but all unknown parameter values of the design file are replaced by the values of the respective parameters at the respective trial. The file name extension of the data tree file is defined by parameter DataTreeFileExtension its default is '.dtr'. The data tree file is created if the experimental parameter StoreDataTree is non-null. Its default is 1.

Note that the data tree file is only written at the end of a run. It is also used by experiments which have multiple runs for a single subject. When such an experimental run is started then PXLab checks for recent data tree files and extracts the subject dependent parameters from this file. The effect is that it is possible to write a design file such that every run of a single subject may be started with exactly the same command line. The data trees for multiple runs are accumulated if the experimental parameter JoinDataTrees is non-null. Its default is 0. If data trees are accumulated, then the last data tree file contains the complete set of data for a single subject. Section 'Multiple Runs for a Single Subject' of chapter 'Running an Experiment' contains more information on this topic.

Parameter Values for Single Trials

For every single trial PXLab writes the value of the experimental parameter DataFileTrialFormat to a data file. This data file's extension is defined by the parameter DataFileExtension and by default is '.dat'. To define the content of the data file we have to define DataFileTrialFormat. Here is an example: 
  DataFileTrialFormat = "%SubjectCode% %Interference% %Trial.Feedback.Response% %Trial.TwoStrings.ResponseTime%";

This enters the values of the experimental parameters SubjectCode, Interference, Trial.Feedback.Response, and Trial.TwoStrings.ResponseTime into the trial data string. These values are written to the data file for every trial and this is done immediately after the trial has been run. If the parameter DataFileBlockFormat is defined then its value is also written to the data file after every block which has been run.

Factor Level Data

A special version of the previously described parameter value data file is derived from the experiment's factorial structure. If the parameter DataFileTrialFormat is not defined then the data file contains the following columns of data for each trial:
  1. SubjectCode;
  2. TrialCounter;
  3. the sequence of factor levels of the independent factors;
  4. the sequence of factor levels of the covariate factors;
  5. the sequence of data values for the dependent factors.

This factor level data file is only written if the factorial sctructure is defined. If no factorial sctructure is defined and DataFileTrialFormat also is undefined then the data file simply contains the values of all Trial arguments.

Global Parameters for Output Files

File Generation Flags

RuntimeProtocol
Flag to switch on a runtime protocol (default: 0).
StoreData
Flag to indicate that formatted data of blocks and trials should be stored in a formatted data file (default: 1).
StoreDataTree
Flag to indicate that data should be stored in a data tree file (default: 1).
DataProcessingEnabled
Flag to indicate that data processing is enabled (default: 0) such that processed data files will be generated.

Runtime Protocol File Formats

RuntimeProtocol
Flag to switch on a runtime protocol (default: 0).
ProtocolFileName
Name of the runtime protocol file (default: empty).
SessionDescriptorFormat
Session descriptor file data format. This determines the format of an experiment's entry into the experiment log file. This file collects log data on experimental runs (default: "%ExperimentName% - Date: %Date% - File: %DataFileName%").

Unprocessed Data Files

StoreData
Flag to indicate that formatted data of blocks and trials should be stored in a formatted data file (default: 1).
StoreDataTree
Flag to indicate that data should be stored in a data tree file (default: 1).
DataFileDestination
Data files destination root directory name or data destination URL (default: ".").
TrialDataDirectory
Formatted trial data subdirectory of DataFileDestination. If this parameter is nonempty the it specifies a subdirectory of the DataFileDestination directory where to put formatted trial data files (default: empty).
DataTreeDirectory
Data tree subdirectory of DataFileDestination. If this parameter is nonempty then it specifies a subdirectory of the DataFileDestination directory where to put data tree files (default: empty).
DataFileName
Formatted data file name (default: empty). If this parameter is empty then its value will be created from the SubjectCode parameter value.
DataFileExtension
Formatted data file name extension (default: ".dat").
DataTreeFileExtension
Data tree file name extension (default: ".dtr").
DataFileHeader
Format of the first line in the formatted data file (default: empty).
DataFileTrialFormat
Format of a single line of trial data (default: empty).
DataFileBlockFormat
Format of a single line of block data (default: empty).
FactorialDataFormat
Generated name array of factorial data. This array is used to create the single trial output format in case the parameter DataFileTrialFormat is not defined. If DataFileTrialFormat is defined then this array is not used. The array is created automatically from the information contained in the Factors() node of the design file (default: empty).

Data File Transfer via HTTP

HTTPRequestMethod
HTTP Request method for data transfer to the data file destination directory via HTTP. Possible methods are 'GET' or 'POST' (default: "POST").
DataFileDestinationAddress
Data file destination E-mail address for data file transfers via HTTP. The receiver of a data file via HTTP should send the data file to this E-mail address. This parameter is currently ony used if the DataFileDestination is an URL (default: empty).

Processed Data

DataProcessingEnabled
Flag to indicate that data processing is enabled (default: 0) such that processed data files will be generated.
ProcessedDataDirectory
Processed data subdirectory of directory DataFileDestination. If this parameter is nonempty the it specifies a subdirectory of the directory DataFileDestination where to put data processing results (default: empty).
ProcessedDataFileExtension
Data processing results file name extension (default: ".html"). The data processing results file either is defined by parameter FileName of the data processing object or is built automatically from the parameter DataFileName using extension ProcessedDataFileExtension.
PlotDataDirectory
Plot data subdirectory. If this parameter is nonempty the it specifies a subdirectory of the DataFileDestination where to put plot data files (default: "pld"). Plot data are generated by DataDisplay objects only.
PlotDataFileExtension
Plot data file extension (default: "pld").

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

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