This article applies to:
E-Prime Extensions for EyeLink 3.0
E-Prime Extensions for EyeLink 3.0 offers multiple methods for adding Interest Areas (IAs) to EyeLink-enabled paradigms. By default, when using the ELTrialBegin and ELTrialEnd PackageCalls, every visual display object and sub-object (e.g., a SlideText) between those routines results in an associated interest area. This article explains the different methods for creating interest areas.
TrialBegin (vAutomaticInterestAreaMode parameter)
The PackageCall ELTrialBegin has an optional parameter named vAutomaticInterestAreaMode. This parameter specifies if interest areas should be made automatically.
This parameter defaults to True if not specified. When True, interest areas are created for all objects / sub-objects between ELTrialBegin and ELTrialEnd. The E-Prime Component Name, interest area ID, and interest area name are all automatically written to a .txt file used by the .edf file that determines where and when the interest area occured.
A value of False does not automatically create Interest Areas. If False is specified, we recommend using the SetIA routines below to create interest areas.
NOTE: If the ELTrialBegin parameter vAutomaticDisplayObjects is set to False and vAutomaticInterestAreaMode is set to True, no automatic interest areas are made since the automatic display objects functionality is turned off. Both parameters need to be set to True. Additionally, if this value is True, but an EyeLink_SetIA routine is used during the trials, then this parameter is effectively considered False and no automatic IAs are created.
EXAMPLE: The sample experiment ELFixedPositionIA uses ELTrialBegin and ELTrialEnd. Between the PackageCalls are the Prime, Stimulus, and Feedback objects. Therefore, the interest areas in the image below are created:
NOTE: Interest areas are not created for any Feedback objects.
Interest areas are created for both of the SlideImages on the Stimulus Slide (i.e., Distractor and Target). The SlideImage's Name property is used for the name of the interest areas.
An interest area is created for the SlideText sub-object that contains the fixation on the Stimulus slide (i.e., Fixation). The SlideText's Name property is used for the name of the interest areas.
An interest area is created for the SlideText sub-object that contains the Prime Attribute on the Prime slide (i.e., Prime). The SlideText's Name property is used for the name of the interest areas.
The PackageCall ELSetIAO creates interest areas on individual specified objects / sub-objects in an E-Prime experiment. Each interest area is defined by the frame coordinates of its associated object or sub-object.
All of the parameters (strObject1-vObject15) work identically. Each parameter defines an IA that is associated with a specified object / sub-object in the .edf file. The parameters contain 3 values: E-Prime Component Name, Interest Area ID, and Interest Area Name. If all 3 are specified, they need to be written as a semi-colon delimited listing (e.g., "ComponentName; IAID; IAName").
NOTE: If more than 3 values are specified, they are effectively ignored.
The E-Prime Component Name is the E-Prime visual object that is the interest area. The IA can be any E-Prime visual display E-Object (i.e., TextDisplay, Slide, ImageDisplay, etc.) or any visual Slide sub-object (i.e., SlideText, SlideImage, etc.). For example, if a Slide exists named "Stimulus", then "Stimulus" could be specified for the first part of this parameter. This adds an IA over the whole ActiveState of the Stimulus Slide. However, if "Stimulus.SlideImage1" is specified, then an IA is created over just the SlideImage sub-object. Additionally, an ActiveState can be specified as well for this part of the parameter (i.e., Stimulus.ActiveState).
The Interest Area ID is a blank or numeric value indicating the ID number for the interest area. If this value is 0 or blank, then E-Prime auto-generates an ID number. Otherwise, E-Prime uses the ID number specified in this part of the parameter (e.g., 56). Care should be taken to not unintentionally duplicate ID numbers.
The Interest Area Name is a user provided name associated with the interest area. For example, specifying IA1 names the interest area "IA1." This part of this parameter defaults to blank if not specified.
If the parameter contains 0 semi-colon delimiters, only "E-Prime Component Name" is considered specified (i.e., the other 2 values are blank). If this parameter contains 1 semi-colon delimiter, both "E-Prime Component Name" and "Interest Area ID Number" are considered specified (i.e., Interest Area Name is blank). If this parameter contains 2 semi-colon delimiter, all 3 parts of the parameter are considered specified.
For example, "theSlide.Box1;0;myBox" creates an interest area over theSlide sub-object named Box1. The interest area is named "myBox" and the ID is auto generated by E-Prime since 0 is specified.
The use of attributes in this parameter is allowed. For example, if all 3 components of this parameter are specified as myObject, myID, and, myName in a List object then [myObject];[myID];[myName]could be specified.
EXAMPLE: This example uses a modified version of ELFixedPositionIA. ELTrialBegin is modified to have the vAutomaticInterestAreaMode parameter set to False. The ELSetIAO PackageCall is added right after ELTrialBegin. The image below shows how the parameters of ELSetIAO are configured:
After the experiment run, the following interest area is created in Data Viewer:
The only interest area created is over the Stimulus SlideImage named "IA1".
SetIAE (Elliptical) or SetIAR (Rectangle)
The EyeLink PackageFile routine EyeLink_SetIAE creates a circular interest area. The EyeLink PackageFile routine EyeLink_SetIAR creates a rectangular IA. Both of these routines have the same parameters which is why they are listed together. These routines are not advertised or in PackageCall Toolbox shortcuts. Therefore, users wanting to use them should refer to SCRIPTING: Calling PackageFile routines via InLine Script versus in a PackageCall .
The first parameter is c which is the experiment context that allows users to add variables to the experiment. The routines in the PackageFile may optionally use the experiment context to retrieve the current values of attributes stored in the context.
The second parameter is strTimeSource. The name of the object that contains the IA needs to be specified in this parameter. For example, if an elliptical IA is needed on a Slide object named "Stimulus," then "Stimulus" is specified for this parameter.
The third parameter is strIAName. This is the name of the IA to be associated with the specified object in the .edf file. For example, "BicycleIA" could be specified to name the IA "BicycleIA."
In order, the next four parameters are nLeft, nTop, nRight, and nBottom. These four parameters take the pixel coordinate position of where the elliptical or rectangular IA should go. For example, specifying 100, 100, 300, 300 will make an Interest Area with the left, top, right, and bottom pixel coordinates respectively.
The last parameter is vInterestAreaID. It is a blank or numeric value indicating the ID number for the interest area. If this value is 0 or blank, then E-Prime auto-generates an ID number. Otherwise, E-Prime uses the ID number specified in this parameter (e.g., 56). Care should be taken to not unintentionally duplicate ID numbers.
EXAMPLE: This example uses a modified version of ELFixedPositionIA. ELTrialBegin is modified to have the vAutomaticInterestAreaMode parameter set to False. The EyeLink_SetIAE routine is added in an InLine script after ELTrialBegin. The script below shows the script that creates an elliptical interest area named "myCircleIA" on the Stimulus Slide:
EyeLink_SetIAE c,"Stimulus", "myCircleIA", 100, 100, 400, 400
After the experiment run, the interest area is created in Data Viewer:
The EyeLink PackageFile routine EyeLink_SetIAP creates an Interest area in the shape of a specified polygon. This routines is not advertised or in a PackageCall Toolbox shortcuts. Therefore, users wanting to use it should refer to SCRIPTING: Calling PackageFile routines via InLine Script versus in a PackageCall .
This routine takes the same parameters as the SetIAE and SetIAR routines with the expection of the nLeft, nTop, nRight, and nBottom parameters. These parameters are replaced by the arrPoints() parameter. The final parameter listing is c, strTimeSource, strIAName, arrPoints(), and vInterestAreaID. Therefore, refer to the parameters above for information on how to use the parameters that are not arrPoints().
The parameter arrPoints() is an array of coordinates to use to create Polygon IA. The array should be specified in an InLine object before the EyeLink_SetIAP routine is called.
EXAMPLE: This example uses a modified version of ELFixedPositionIA. ELTrialBegin is modified to have the vAutomaticInterestAreaMode parameter set to False. The EyeLink_SetIAP routine is added in an InLine script after ELTrialBegin. The script below shows the script that creates an triangular polygon interest area named "myPolygonIA" on the Stimulus Slide:
DimthePoint(2) As Point
thePoint(0).x = 200
thePoint(0).y = 200
thePoint(1).x = 300
thePoint(1).y = 300
thePoint(2).x = 100
thePoint(2).y = 400
EyeLink_SetIAP c,"Stimulus", "myPolygonIA", thePoint
After the experiment run, the following interest area is created in Data Viewer: