E-STUDIO: Experiment Object [22698]

Overview
The Experiment object is created automatically for the user when a new experiment specification file is opened. It appears only as the first object in the Structure view, with the experiment name listed in parentheses, and cannot be deleted or moved. Every experiment within E-Prime must have an Experiment object.

 

The Experiment object as it appears in the Structure view window.

 

Interface
The interface for the Experiment object consists of a set of tabbed Property pages enabling the user to set global properties for the experiment, such as the screen resolution to be used when running the experiment, sound properties (i.e., the format for the creation of audio buffers), and available input devices. Furthermore, the Experiment object’s Property pages allow the user to enable the StartupInfo dialogs (collecting subject number, session number, etc. at runtime), and determine the specific information to be collected.

 

Property Pages
The Experiment object Property pages may be displayed by double clicking the Experiment object in the Experiment Explorer Structure view, or by selecting the Experiment option in the Edit menu.

 

General Tab
The General tab on the Experiment object’s Property pages is used to enter information concerning the author of the experiment, and an abstract of the study. Version information of the experiment can be tracked in the General tab, and it can be specified to increment the build on every save. This information may be extremely useful when reviewing a study, or passing an experiment on to a student or colleague.

 

Notes Tab

The Notes tab is a location where notes about the experiment can be recorded. At first, the tab is blank, but notes can be added in as an experiment is developed.

Startup Info Tab
The Startup Info tab is used to define the subject information collected when an experiment is launched. By default, dialog boxes are displayed to collect subject and session number values at the beginning of each run, and a dialog displaying a summary of the information is presented for confirmation.

 

The startup information may be modified by adding or deleting variables in the Startup Info Parameters field. Alternatively, default values may be used, and dialog prompts may be disabled. While parameters may be added, deleted and/or modified, the Subject and Session parameters are system variables, and must always be present. Therefore, editing of the Subject and Session parameters information is restricted, and the user is not able to either delete or disable these parameters. All parameters enabled via the Startup Info tab are logged as session level variables in the data file (i.e., their values do not vary during the session).

 

Local and Global Startup parameters can be edited on this tab as well. Local values only apply to the current experiment. Global values can be applied with all *.es3 or *.ebs3 files. For more information on Local / Global Startup files view STARTUPINFO EDITOR: Local and Global Values [22734].

 

Field	Description
Name	Name used to log information related to the parameter in the data file.
Prompt Text	Text displayed in the dialog when prompting the user to enter a value for the parameter.
Data Type	Type of data logged by the parameter.
Default (optional)	Value displayed in the dialog when collecting data, or default value used for the parameter if not collected at runtime.

In the Name field of the Startup Info Parameters, the checkboxes indicate which parameters will be enabled for the experiment. If the checkbox next to a parameter is checked, the script for the parameter will be generated, and the value for that parameter will be logged in the data file. If the checkbox is unchecked, E-Studio does not generate script for that parameter, and no value is logged. The state of the checkbox determines only whether or not the parameter is enabled, and does not affect the settings for the parameter. Thus, the checkbox permits the user to enable or disable a parameter without having to recreate the parameter, or re-enter the parameter settings.

 

The question marks next to a parameter name indicate whether a dialog will be presented to collect information at run time, or whether the information will be logged according to the default value.

 

Name State	Description
	Dialogs will be presented to collect a value at runtime.
	Default value will be used, and a dialg will not be presented to collect information for the variable.

For example, if a study is being run at various sites, the location of the site might be included in the startup information, and could be set to a default value rather than being entered at run time. In the image above, the checkboxes indicate that Subject, Session, and Group information will be logged for each subject. The question marks indicate that dialogs will be presented to collect only Subject and Session information, and the Group parameter will be logged according to its default value.

 

Adding Startup Parameters

Listed Parameters
A list of frequently used parameters is displayed in the Startup Info Parameters field. To add a listed parameter to the data file (i.e., enable the collection of data for the parameter), click the box to the left of the parameter name so that a checkmark appears in the box. Script will not be generated for unchecked parameters, nor will the unchecked parameters be logged in the data file.

 

If a dialog box is needed to collect a value for the parameter at the beginning of the experiment, click the question mark next to the parameter name in order to remove the circle with the line through it. When the circle with the line through it is present over the question mark, no dialog will be presented to collect information, and the default value will be logged for the parameter. Subsequent clicks on the question mark will toggle between the two states.

 

To modify the settings (e.g., prompt, default value, etc.) for a parameter, click the parameter name to select it, and click the Edit button, or double-click the parameter name. The Edit Startup Info Parameter dialog will be displayed, allowing the user to edit the settings for the selected parameter. Refer to the Editing Startup Parameters section for a complete description of parameter settings.

 

User-Specified Parameters
Parameters not already listed on the Startup Info page may be added by clicking the Add button below the Startup Info Parameters field.
 

 
The Add… button displays the Edit Startup Info Parameter dialog (see Editing Startup Parameters), allowing the user to enter a parameter name, set the parameter’s data type and value range, and specify whether to log a default value, or to display a dialog at run time to collect the parameter value. If the parameter value is to be collected using a dialog box at run time, the prompt to be displayed is specified in the Edit Startup Info Parameter dialog as well.

 

Removing Startup Parameters
To delete a variable from the startup information, select the parameter in the name column and click the Remove button.

 

 
When a parameter is removed, it is no longer listed in the parameter list. The parameter may be re-entered using the Add… button (see User-Specified Parameters), but parameter settings must be entered manually (i.e., settings will be initialized to defaults). In order to disable the parameter and retain the settings (i.e., not completely remove it from the experiment), click the checkbox to the left of the parameter name to uncheck the box. When a parameter is disabled, it remains in the parameter list and its settings are retained, but when the program is generated, no script is generated in relation to that parameter.

 

Editing Startup Parameters
Settings for existing parameters may be modified using the Edit… button. Select the parameter to be modified in the Name column of the Startup Info Parameters field. When a parameter is selected, the Edit… button is enabled. Click the Edit… button to display the Edit Startup Info Parameter dialog, permitting the user to edit the settings for the selected parameter.

 

Field	Possible Values	Description
Log Name	String values	Sets the name to be used in the data file when logging values for the selected parameter.
Prompt	String values	Specifies the text to be displayed in the dialog prompting the user to enter a value for the parameter.
Data Type	Numeric, String, Choice	Sets the data type allowed for the parameter.
Default	Integers	Value displayed by the dialog collecting the value at run time, or the value assigned to the parameter when the value is not collected at run time.
Min	Integers	Minimum value allowed for the parameter (Numeric data only).
Max	Integers	Maximum value allowed for the parameter (Numeric data only).
Max Length	Integers	Maximum number of characters allowed (String data only).
Prompt the user for this startup info parameter	Checked, Unchecked	Designates whether to use the default value or to collect the information via a dialog box presented when the experiment is run. When the box is checked, a dialog will be presented to collect a value for the variable at the beginning of the experiment run. When the box is unchecked, the default value (i.e., the value in the Default field) will be logged for the selected variable. This field may also be set on the main Startup Info page by clicking the question mark next to the parameter name to toggle its state.
Enable this startup info parameter	Checked, Unchecked	Enables or disables the selected parameter. This is equivalent to checking or unchecking the checkbox to the left of the variable name on the main Startup Info page.

 

Choice Data Type
Startup Info parameters may be defined as accepting one of three data types (i.e., String, Integer, Choice). The Choice data type allows the experimenter to specify a list of choices from which the subject must select. Tool buttons are provided for adding or deleting options, and for rearranging the order in which the options are presented.

 

ToolButton	Description
	Inserts a line to add an option.
	Deletes the selected option.
	Moves the selected up in the order of the options.
	Moves the selected option down in the order of the options.

 

At runtime, the subject is presented with a dialog displaying the choice options. The mouse or the arrow buttons may be used to highlight a selection before accepting it by clicking OK or pressing {Enter}.

 

Data File Tab
The Data File tab on the Experiment object’s Property pages allows the user to set parameters related to the writing of data files, and the names to be used for log levels within the data file. E- Prime’s method of writing data involves a two-step process. Data is first written to a text file, then converted to .edat3 format after the experiment terminates. Refer to TIMING: Time Audit: Confirming Accurate Timing [22864] for more information concerning data file conversion.

 

 

Field	Description
Display a warning before overwriting an existing datafile.	Indicates that a file with the same name exists, and prompts the user for
Receive feedback while data file is being converted.	Notifies the user that the data is currently being converted.  The dialog will only appear if time permits (e.g., while converting a very large data file).
Display a warning if conversion of the data file is not successful.	Notifies the user that the data file was not successfully converted from the text data file to an .edat3 file.
Remove the E-Recovery text data file after the experiment finishes.	Determines whether the text data file is deleted after successful completion to an .edat3 file.
Create a tab-delimited copy of the data file.	Determines if a tab-delimited copy of the data file is created after a test session. See LOGGING: Automatic Generation of Tab-Delimited Data File [23601]for more information about the auto generation of a tab-delimited file.
Log Level Names	Allows the user to specify names for the logging levels in the data file
Data File Name	Allows the user to specify the name for the Data File produced for a test session. See LOGGING: Data File Name [22758].

Editing Log Level Names
To modify the name by which a level will be logged in the data file, click on the level name in the Log Level Names field and press {F2} (or simply click the level name a second time) to enter edit mode.

 

 
When in edit mode, type the new name for the level and press {Enter}, or click elsewhere in the dialog, to accept the new name. Click OK to accept the new setting and dismiss the dialog. Restrictions for renaming log levels are listed in the table below:

Rules for naming log levels:

• Cannot rename Session level
• Name cannot be empty
• Must begin with an alpha character
• Permitted characters include a-z, A-Z, 0-9, _(underscore), .(period)
• Cannot exceed 80 characters
• Cannot conflict with device name (e.g., Keyboard) or device type (e.g., KeyboardDevice)
• Cannot be the same as any other log level name
• Cannot be the same as any type in the Toolbox (e.g., TextDisplay, Wait, etc.)
• Cannot be the name of an E-Object

Devices Tab
The Devices tab permits the enabling and initialization of hardware devices to be used in the experiment. By default, the Keyboard, Mouse, Display, Sound, Script, and Button devices are enabled when a new experiment specification file is created. Devices that are not enabled by the Experiment object will not be available to other objects. For example, to accept input using the PST Chronos Response device, Chronos must first be enabled via the Experiment object. Once enabled, the device is available to other objects. See E-STUDIO: Devices [22721] for further information on devices.

 

 
Adding Devices
Devices may be added (i.e., enabled) in the Experiment object by clicking the Add… button on the Devices tab. Clicking the Add… button displays the Add Device dialog, from which available devices may be selected.

To add a specific device to the devices list, select the device in the Add Device dialog and click the OK button. When the Add Device dialog is dismissed, the selected device will appear in the devices list, and will be enabled (i.e., the checkbox next to the device will be checked).

 

Removing Devices
Devices may be removed from the devices list by clicking on the name of the device to select it, and clicking the Remove button.

 

 
When a device is removed, it no longer appears in the devices list. The device may be re- enabled using the Add… button (see Adding Devices), but specific device settings must be entered manually (i.e., settings will be initialized to defaults). In order to disable the device and retain the settings (i.e., not completely remove it from the experiment), click the checkbox to the left of the device name to uncheck the box. When a device is disabled, it remains in the devices list and its settings are retained, but when the program is generated, the Open command is not called in relation to that device.

Editing Device Settings
The properties or settings for a specific device may be viewed by double-clicking the device in the Name column, or by selecting the device to highlight it, and clicking the Edit button. A dialog box specific to the device allows the setting of properties for that device. For example, it may be necessary to edit the SRBox settings in order to designate the correct Port address.

 

 

For more information on specific devices and settings, view E-STUDIO: Available Devices in E-Prime [22722].

 

Timing Tab

E-Prime 2.0 introduced the ability to choose from available clocks in E-Studio. The clock is specified on the Timing tab on the Experiment Object Properties.



When the E-Prime Realtime Clock is selected, then no additional settings are required unless the Experiment Advisor flags an operating system specific error. If this is the case, it is noted that PST Product and Support should be contacted.

When the SNTP Realtime Clock is selected, then additional property settings are required. A file named SNTPClockExtension.ini file must be created to specify the required property (the IP address of the NTP server) along with any combination of the optional properties (see below). The SNTPClockExtension .ini file must be in one or both of the following locations:

• The same location as the SNTPClockExtension.ebn file. The default location for this file is C:\Program Files (x86)\PST\E-Prime 3.0\Program. Note that administrator privledges are usually needed in order to create or edit files in this folder.
• The My Experiments folder. This location is recommended for easier editing by users who do not have administrator privledges.

The SNTPClockExtension can contain the following properties in the [General]section:

Property Name	Description
IP	IPv4 address of NTP server (default: invalid/error)
Port	Port to connect to (default: 123)
PollInterval	Time in milliseconds to poll NTP Clock Server
Timeout	Time in milliseconds to wait for response from NTP Clock Server
Affinity	Enable/disable logging (default: 1)
Log	Prohibit servers IPs outside RFC1918 local ranges (default: 1)

 

Experiment Advisor Tab

The Experiment Advisor tab is accessed through the Experiment Object. The Experiment Advisor provides E-Prime experiments the ability to detect design and timing errors in E-Studio and E-Run. In addition, statistics on the OnsetToOnsetTime, OnsetDelay, and LoadTime of objects can be reported.

 

View E-STUDIO: Experiment Advisor Window [22679] for more information on the Experiment Advisor tab.

 

Packages Tab
The Packages tab is used to install or remove an E-Prime Package File, allowing the user to import pre-written script and subroutines into the experiment. Refer to E-STUDIO: PackageCall Object [22713] for information concerning the use of package files. For a package file to be available, it must first be installed via the Packages tab in the Experiment object properties. By default, no packages are added, so the Packages tab is blank. 

 

 

To install a package file, click the Add button, and navigate to the appropriate folder. Each package file must exist in a unique subdirectory within the \Program Files(x86)\PST\E-Prime 3.0\Program\Packages folder. The unique subdirectories are not part of the E-Prime installation, they are user-created, and necessary only when using package files. All files associated with the package file (i.e., EPK, BMP) must be placed within the unique subdirectory.

 

For example, the PST or MyPackageFile.EPK and associated images (*.BMP) are located in the \MyPackage folder. If an EPK file does not have an associated .ico or image file, the default icon will be used. For more information about changing the associated image files for an Package File icon, see SCRIPTING: Routines (PackageFile Editor) [22896].

 

 

Select the desired package file from the list of available packages, and click OK. Once installed, the package file will appear on the Packages tab, and the checkbox next to the package name will be checked, indicating that the package is enabled. Unchecking the checkbox will disable the package file, but not remove it from the experiment.

 

 

Next Article: E-STUDIO: Procedure Object [22699]
Previous Article: E-STUDIO: E-Objects [22697]