State Routines

Each routine in a state has one or more parameters. To add a new routine to a state select the state in the program editing window and choose Append Routine from the drop-down list; to insert a routine among others already in a state, select the state and Ctrl-click on the cell for the routine before which you want to insert the new one. To modify the parameters for any routine already in a state, double-click the cell that contains the routine. In each case, Expo drops a sheet that displays all the parameters.

The routine sheet contains check boxes through which you can specify whether Expo should record parameter values when the program is running, whether conditions set up by a routine should persist beyond the end of the state that contains it, and whether or not the routine should assert STOP or DONE events. Not all routines can assert STOP or DONE events, so these check boxes may be disabled. For routines that create displayable objects, an additional check box allows Expo to create displayable tokens that represent the objects in windows other than the main screen.

Display Routines
Surface Surface Overlay Surface Element Surface Matrix Dot Field Glass PatternDKL Texture DKL Base LMS Texture LMS Base RGB Texture Image Texture Movie Texture RGB Screen

Other I/O Routines
Analog Input Analog Bounds Analog Output Digital Input Digital Output Read Key Read Mouse Read Wheel Sound

Methods
2AFC If… Else… Op Variable Pulse Quest Random Resolve Unresolve Waveform Spike Count Spike FT Staircase Statistics

Plugin Routines

Calling Collections of Routines
Run State

Obsolete Routines
DKL Contrast DKL Entry DKL Plaid Dots Dots Plane Dots Rect Gabor Grating Interferometer LMS Contrast Mask Pan & Scroll Picture Plaid RGB Entry

Display Routines

Expo uses OpenGL to generate displays. Expo requires a renderer that uses hardware acceleration and supports full-screen displays. It also requires that the renderer support multitexturing. It will not use a monitor supported by an inadequate renderer. Appendix A provides more information about how Expo uses OpenGL.

Expo deals with displayable objects as transparent 2-D surfaces in the fronto-parallel plane. These surfaces can have arbitrary shapes. Surfaces are made visible by applying a texture—a one- or two-dimensional pattern—to the surface. A texture's position on the surface can be changed in controlled ways, and the texture (and therefore the surface on which it lies) can be variably transparent. The upshot is that Expo can produce arbitrary patterns that move in defined ways within the boundaries of planar objects.

To make any displayable object you need to call at least two routines, one to define a surface or collection of surfaces, and one to define a texture to be laid on it (you can actually apply a compound texture that is the product of two component textures). You can form complex patterned objects by overlaying several differently-textured surfaces of variable opacity. To display any surface you must call one of the routines DKL Texture, LMS Texture, RGB Texture, Image Texture, or Movie Texture, followed by a call to define a Surface or Surface Overlay or Surface Element; if you define a Surface Element that will be part of an aggregate image, you must also call a routine, such as Surface Matrix or Dot Field, to specify how elements are aggregated for display. In each state you must specify a texture before specifying the surface or overlay or element to which it will be applied.

Display Tokens

Routines that display objects can also create visible tokens that Expo will place on the XY display of the Analog Signal window (Signals->View Samples) if that is visible. Each token carries the following attributes of the object it represents: form (oval or rectangular), orientation, x- position, y-position, width, height. The token is displayed as a filled gray object with a line through it that identifies its orientation. To make a routine create a token, check the Display Token box in the sheet through which you create/edit routines. The check box is dimmed when a routine cannot generate a token.

Surface

This routine creates a transparent surface of defined shape, and attaches to it a texture that can move in a specified direction across the surface at a specified rate. Choose the Form of object from the popup menu. Expo provides several built-in shapes; it can also use arbitrary two-dimensional shapes loaded from images in the Resources folder. The names of usable files containing shape masks appear in the menu after the built-in ones. Specify the Orientation of the surface in Cartesian coordinates (0° is horizontal). An object that is upright has an orientation of 90°. Use Width, Height, X-position and Y-position to specify respectively the height, width and X and Y positions (relative to the center of the screen). Use Texture ID to identify the texture (whose properties will be separately specified) to be applied to the surface. This may be any number from 0 through 29. If you want the texture to move across the surface, specify a Drift Rate and Direction. This is specified in Cartesian coordinates in relation to the upright surface, so that when the surface is upright (orientation 90°) a direction of 0° will cause the texture to move across the surface from left to right. Phase determines which part of the texture is aligned with the center of the form (0° is sin phase)—but see the special case described in DKL Texture. For the purpose of interpreting the phase, a texture is assumed to be periodic. If the texture is drifting, Phase determines the phase in which the surface appears at the start of a state; when a grating drifts the Phase value is added to the instantaneous value computed by Drift Rate.

Surface Overlay

This routine augments a Surface (above) by layering a second (overlay) texture on top of the first (base) texture. The base and overlay textures are multiplied to produce a compound texture that is laid on the surface. Base Texture ID identifies the base texture that will be multiplied by the overlay. The base texture ID implicitly identifies the surface to which the overlay will be applied. Specify the overlaid texture in Overlay Texture ID. This may be any number from 0 through 29. Specify the Orientation of the overlay relative to the orientation of the Surface to which it will be applied. If you want the texture to move across the surface, specify a Drift rate and Direction (in relation to the direction of the base Surface). Phase determines which part of the texture is aligned with the center of the form (0° is sin phase)—but see the special case described in DKL Texture. For the purpose of interpreting the phase, a texture is assumed to be periodic. If the texture is drifting, Phase determines the phase in which the surface appears at the start of a state; when a grating drifts the Phase value is added to the instantaneous value computed by Drift Rate.

Surface Element

This routine works almost exactly like Surface, and takes most of the same parameters, but instead of rendering the element on the screen, it creates a description of it that is used by another routine (such as Surface Matrix, or Dot Field, below) that will display aggregates of surface elements. For this reason the element has no defined X- or Y-position on the screen. Element ID, a number in the range 0-9, is used to identify the element to routines that use it.

Surface Matrix

This routine displays a 2 dimensional matrix of elements (defined by Surface Element). Elements may be all the same or may differ on one attribute that varies randomly within specified limits, at a specified rate.

Choose from Field Form the shape the field will have. Expo provides several built-in shapes; it can also use arbitrary two-dimensional shapes loaded from images in the Resources folder.

Specify the Orientation of the field in Cartesian coordinates (0° is horizontal). Use Field Size, X-position and Y-position to specify the width and height (which are always the same) and X and Y positions of the field (relative to the center of the screen). Use Cell Size to specify the size of the cells within which surface elements will be placed. The number of elements in the matrix is the number of cells that fit within Field Size. If Cell Size is 0, the cell size is taken to be the size of the surface element. Element ID identifies the element (whose properties are separately specified via Surface Element) that will populate the matrix.

The routine can introduce a random variation in any one of the following attributes of the surface elements:

• One of the three chromatic attributes of the texture applied to the element (if a DKL Texture, LMS Texture or RGB texture—you cannot control attributes of Image textures or Movie textures)
• Element size
• Element orientation
• Spatial phase of the texture on the element
• X or Y spatial frequency of the texture on the element

Choose the attribute to be controlled from the Variable Attribute drop-down list. Expo takes the value of this attribute from the appropriate parameter of the surface element or the texture applied to it, and generates a distribution of values around that mean. Choose from Normalized Range the fraction of its natural range over which the attribute may vary about the mean. Expo understands the following natural ranges for parameter values:

• DKL Texture: Contrast ± 1; Elevation ± 90°; Azimuth ± 180°
• LMS Texture: L ± 1; M ± 1; S ± 1
• RGB Texture: R 0-1; G 0-1; B 0-1
• Size: ± 1 decade
• Orientation: ± 180°
• Spatial Phase: ± 180°
• Spatial Frequency: ± 1 decade

Choose from the Distribution drop-down list how the randomly generated values for the variable attribute will be distributed (Binary, Ternary, Uniform or Gaussian) about the mean. Values are distributed over ± Normalized Range (for the Gaussian distribution, this corresponds to ± 3 standard deviations; values outside that range are clipped). Set Seed to the value to be used to seed the random number generator. Expo reads Seed at the start of each pass through the state containing the routine (for each pass to generate a different sequence of elements, Seed should be different). Within the running state the routine generates a new set of attribute values at the interval specified by Frame Duration. If this is 0 a single set of values is generated at the beginning of each pass through the state.

Dot Field

This routine creates a two-dimensional array of randomly positioned elements (defined by Surface Element) within a field of defined shape. Choose from Field Form the shape the field will have. Expo provides several built-in shapes; it can also use arbitrary two-dimensional shapes loaded from images in the Resources folder. Specify the Direction in which elements will move (in Cartesian coordinates—0° is rightward; a field moving upwards has a direction of 90°). Use Field Width, Field Height, X-position and Y-position to specify respectively the width, height and X and Y positions of the field (relative to the center of the screen). Set Seed to the seed value to be used by the random number generator that specifies element positions. Expo reads Seed at the start of each pass through the state containing the routine (for each pass to generate a different sequence of elements, Seed should be different). Enter the density of elements at Dots/Epoch/Deg². Specify in Epoch the interval (typically a small number of frames) after which an element will be regenerated in a new position. Within each of the N frame ticks in an epoch, Expo normally generates 1/N of the elements specified by Dots/Epoch/Deg². To make Expo generate all the elements synchronously in the first frame of the epoch, set Epoch to a negative value (a setting of 0 produces no display).

After each epoch an element moves to a new position determined by whether the element will be coherent or incoherent. Which kind of element it becomes is determined randomly with the probability defined by Coherence. If the element is to be coherent it continues on its previous trajectory; if it is to be incoherent it reappears in a new random position in the field. Speed specifies the speed with which coherent elements will move. Element ID identifies the element (whose properties are separately specified via Surface Element) that will populate the field.

Glass Pattern

This routine creates a two-dimensional array of randomly positioned elements (defined by Surface Element) within a field of defined shape. Choose from Field Form the shape the field will have. Expo provides several built-in shapes; it can also use arbitrary two-dimensional shapes loaded from images in the Resources folder. Random elements are paired to create Glass patterns according to rules specified by Pattern. For Linear patterns, all elements are separated along a single axis: specify the Direction in which elements will be displaced (in Cartesian coordinates - 0° is rightward). For Circular and Radial patterns, elements are separated along centered circles or radial lines. For Random Dipole patterns, each pair elements is separated in freshly-chosen random direction. Use Spatial Offset to determine the distance between paired elements. Use Field Width, Field Height, X-position and Y-position to specify the width, height and X and Y positions of the field (relative to the center of the screen). Set Seed to the seed value to be used by the random number generator that specifies element positions. Expo reads Seed at the start of each pass through the state containing the routine (for each pass to generate a different sequence of elements, Seed should be different). Enter the density of elements as Dots/Deg²/Frame. Specify in Dwell the period for which a particular pattern will be displayed before being replaced by a fresh one (a Dwell value of 0 is equivalent to one tick, so a new pattern is generated every frame).

The probability that a given Element will be paired is determined randomly with the probability defined by Coherence. Element ID identifies the element (whose properties are separately specified via Surface Element) that will populate the "first" element of each pair; Element ID2 identifies the element that will populate the "second" paired element. Half of the unpaired elements are populated with each Element ID.

Glass Pattern

This routine creates a two-dimensional array of randomly positioned elements (defined by Surface Element) within a field of defined shape. Choose from Field Form the shape the field will have. Expo provides several built-in shapes; it can also use arbitrary two-dimensional shapes loaded from images in the Resources folder. Random elements are paired to create Motion Glass patterns according to rules specified by Pattern. For Linear patterns, all elements are separated along a single axis: specify the Direction in which elements will be displaced (in Cartesian coordinates - 0° is rightward). For Concentric and Radial patterns, elements are separated along centered circles or radial lines. For Random Dipole patterns, each pair elements is separated in freshly-chosen random direction. Use Spatial Offset to determine the distance between paired elements. Use Field Width, Field Height, X-position and Y-position to specify the width, height and X and Y positions of the field (relative to the center of the screen). Set Seed to the seed value to be used by the random number generator that specifies element positions. Expo reads Seed at the start of each pass through the state containing the routine (for each pass to generate a different sequence of elements, Seed should be different). Enter the density of elements as Dots/Deg²/Frame. Specify in Dwell the period for which a particular pattern will be displayed before being replaced by a fresh one (a Dwell value of 0 is equivalent to one tick, so a new pattern is generated every frame).

The probability that a given Element will be paired is determined randomly with the probability defined by Coherence. Element ID identifies the element (whose properties are separately specified via Surface Element) that will populate the "first" element of each pair; Element ID2 identifies the element that will populate the "second" paired element. Half of the unpaired elements are populated with each Element ID.

DKL Texture

This routine creates a 1- or 2-dimensional texture that will be associated with a surface (Surface or Surface Element or Surface Overlay), and which will specify the chromatic modulation of the surface or element in DKL color space. The texture is associated with the surface or element by its ID, a number in the range 0 through 29. The texture can be thought of as a one- or two-dimensional array of values that defines one cycle of an arbitrary waveform. Expo provides several built-in one- and two-dimensional textures that can be applied to surfaces. It can also use arbitrary textures loaded from greyscale images in the Resources folder; Appendix A describes the requirements images must satisfy before Expo can use them. Choose from the Type popup menu the form of the texture to be applied to the surface. Built-in 1-D and 2D textures appear first in the list; textures from files in the Resources folder appear last. Textures obtained from image files are assumed to define intensity variations. One-dimensional textures are periodic in the X-dimension; two-dimensional textures are periodic in the X- and Y-dimensions. Use Spatial Frequency X and Spatial Frequency Y to specify the spatial frequency (1/period) of the texture in the X- and Y-dimensions respectively. For a one-dimensional texture the spatial frequency in the Y dimension is ignored. You can set the spatial frequency in either dimension to –1 to specify that exactly one period of the texture pattern covers the width or height of the surface to which it will be applied. When you use a spatial frequency of –1, the texture expands or contracts on the surface as the surface grows or shrinks. In addition, the surface's Start Phase is interpreted relative to the edge of the surface rather than its center, ensuring that in the default phase of 0° the edges of the texture are aligned with the edges of the surface.

DKL Base

This routine specifies the mean chromaticity of an associated DKL Texture. The mean chromaticity is specified as an excursion (in DKL color space) from the screen background. When DKL Texture is called, the mean chromaticity of the texture defaults to the screen background, and is altered only by a preceding call to DKL Base.

LMS Texture

This routine creates a 1- or 2-dimensional texture that will be associated with a surface, and which will specify the chromatic modulation of the surface or element in LMS color space. Other details as for DKL Texture.

LMS Base

This routine specifies the mean chromaticity of an associated LMS Texture. The mean chromaticity is specified as an excursion (in LMS color space) from the screen background. When LMS Texture is called, the mean chromaticity of the texture defaults to the screen background, and is altered only by a preceding call to LMS Base.

RGB Texture

This routine creates a 1- or 2-dimensional texture that will be associated with a surface, and which specifies the color of the surface or element in RGB color space. Each of the R, G and B values controls one gun on the monitor, and can range between 0 and 1. Other details as for DKL Texture.

Image Texture

This creates a 2-D texture from an RGB image, without any color transformation. Choose from the Type popup menu the name of the image to be displayed. Expo provides one built-in demonstration image (the Expo icon). Other images in the menu are those of any RGB image files in the Resources folder; Appendix A describes the requirements images must satisfy before Expo can use them. Spatial Frequency X and Spatial Frequency Y have the same meanings and take the same values as in DKL Texture. Opacity (from 0 to 1) determines surface transparency. ID identifies the texture so that it can be associated with a Surface or Surface Element or Surface Overlay.

Movie Texture

This creates a 2-D texture from a movie, without any color transformation. Choose from the Name popup menu the name of the movie to be displayed. The names in the menu are those of any movie files in the Resources folder; Appendix A describes the types of movies that Expo can play. Mode determines whether the movie stops when it reaches its end, or loops continuously. When Synchronization is set to Lock, Expo displays movie frames at the rate the monitor is refreshed; when set to Free Run Expo plays the movie at the rate encoded in the movie. Set Sound on or off to play or suppress the movie soundtrack. Opacity (from 0 to 1) determines how transparent the surface will be. Natural Size is a variable into which the routine puts the size of the square box that would contain the movie at its natural resolution. When constructing the surface on which the movie will be displayed you can use the value from Natural Size to display the movie at its natural size. ID identifies the texture so that it can be associated with a Surface or Surface Element or Surface Overlay.

RGB Screen

This routine is designed for calibrating a monitor. It allows you to specify exactly the R, G and B pixel values used in the OpenGL background. These values, after translation by the device lookup table, give rise to the uniform background displayed on the screen. The screen state can be set to persist between states.

Other I/O Routines

Analog Input

This routine reads the value from the analog input channel Channel and assigns it to the variable Destination. Channel can have any value between 0 and 7. The routine needs an active analog input device. If no device is active when you run the program, Expo will warn you. If the device has no active channel at the index you specified, EXPO will return 0 as input. The value read can be expressed in normalized volts (full amplitude signal = 1), in volts, or (for cases where the signal represents a gaze direction) in degrees, which in turn have equivalent expressions in screen distances (cm and pixels). The scale factors for translation among analog units are device- and environment-dependent. You can set these via Environment->Calibration.

The value read from Channel is scaled by the current gain setting for that channel. If gain is adjustable you can specify it in the appropriate device settings (Environment->Sound or Environment->Cards).

Analog Bounds

This routine is designed principally for monitoring analog signals that represent eye-position, though it has other uses too. It tracks the input signals on one channel or a pair of channels and sets a TRUE or FALSE output as appropriate when the signals are inside or outside defined ranges. When ranges on two channels are specified, the routine tracks the locus of the signal in a two-dimensional region.

Choose from Form the shape of the region of interest (oval or rectangular). Set Base Channel to the first of the channel(s) to be examined (for the purposes of defining the threshold region the base channel represents the X-dimension; the next channel represents the Y-dimension). Set in X Position and Y Position the coordinates of the center of the region of interest; Set in Width and Height the width and height of the region. Choose from Mode how the routine should detect signal movements into or out of the region: Inside causes Destination to be set to TRUE when the signal is inside the defined region; Outside causes Destination to be set to TRUE when the signal is outside the defined region. With either of these settings, the routine sets the destination each time there is a transition into or out of the region; if you choose Inside (lock) or Outside (lock), Expo tracks the signal until the test is first TRUE, then locks the result and stops tracking. The exact time of the most recently recorded transition is saved in Time (to the nearest 100µsec). If no transition has ever been recorded (the signal was always inside or outside bounds), Time is set to NAN.

To detect threshold crossings on one (X) channel only, set Height to 0.

Analog Output

Sets the value specified in Value on the DAC output line specified by Channel. The routine needs an analog output device, configured and enabled (through Environment->Cards). If the device is not enabled when you run the program, Expo will warn you.

Digital Input

This routine reads (as TRUE or FALSE) the value from the digital input line Line and assigns it to the variable Destination. Line can have any value between 2 and 15, though not all input devices support 16 lines. The routine needs a digital I/O device, which must be enabled. If no device is present and enabled when you run the program, Expo will warn you. If the device has no active line at the index you specify (most National Instruments devices provide only 8 lines), EXPO will read it as FALSE.

Digital Output

This routine sets (to TRUE or FALSE) the State of the digital input line Line. Line can have any value between 1 and 15. The routine needs a digital I/O device, which must be enabled. If no device is present and enabled when you run the program, Expo will warn you. If the device has no active line at the index you specify (most National Instruments devices provide only 8 lines), EXPO will do nothing.

Digital Word

This routine writes an 8 bit word to the digital output device. Line can have any value between 1 and 15. The routine needs a digital I/O device, which must be enabled. If no device is present and enabled when you run the program, Expo will warn you. If the device has no active line at the index you specify (most National Instruments devices provide only 8 lines), EXPO will do nothing.

Read Key

This routine checks the keyboard for hits on specified keys, and generates appropriate events when a target key is pressed. Assert on keys specifies the set of keys from which any keypress will assert STOP and/or DONE, depending on the state of Assert STOP and Assert DONE.

The routine can also perform a specified operation on two operands, Source 1 and Source 2, placing the result in Destination, whenever you hit a key specified in the sets Increment keys or Decrement keys. Three pairs of operations are possible: when a key in the set of Increment keys is hit, Destination is set to Source 1 + Source 2, or Source 1 * Source 2, or simply Source 1, as specified by the first three items of Operation. When a key in the set of Decrement keys is hit, Destination is set to Source 1 – Source 2, or Source 1 ÷ Source 2, or simply Source 2, as specified by Operation. Two sets of operations available in the Operation menu. They differ in how they initialize Destination when a state starts (no key has yet been hit). The three operations in the first set initialize the Destination to Source 1; operations in the second set initialize the Destination to NaN.

The routine attends to each hit on a key that belongs to one of its sets, so can be used to drive the value of the destination variable progressively.

The time (to the nearest 100µsec) after the start of the state at which the last acceptable key is hit is place in the variable specified for Time. When the state starts (no key has yet been hit), the value of Time is initialized to NaN.

Read Mouse

Reads the current X- and Y-positions of the mouse if permitted by Modifier, which stipulates any modifier key that must be pressed when the mouse position changed. X- and Y- coordinates are placed in Destination X and Destination Y respectively.

Read Wheel

Reads the current position of the mouse wheel(s). Expo can read the positions of up to three wheels (X, Y or Z—on a single-wheel mouse the wheel is Y) in one of two modes. To read the absolute position of the wheel, choose X, Y or Z; to read the change in position since the start of the state choose X (Relative), Y (Relative) or Z (Relative). Modifier stipulates any modifier key that must be pressed for the wheel position to be read. The value read is placed in Destination.

Sound

This routine emits a sound. Specify the sound by name from the menu. The menu of available sounds displays, in order: the names of sounds built-in to Expo (currently none); the names of sounds available in the Expo Resources folder; the names of System sounds. You can specify an onset delay (from the start of the state containing the routine) with the Delay parameter. If the onset delay is set to -1, the sound is suppressed.

Methods

2AFC

This routine provides a filter that takes two input values, Source1 and Source2, and in two different intervals assigns one or the other to an output variable Signal Out. Each interval has a duration specified by Duration; the intervals are separated by the interval ISI (inter-stimulus interval). Within each interval, Expo also generates an envelope waveform that can be used to shape the rise and fall of the output signal. The envelope has a rise and fall time specified by Rise Time, and a shape specified by Onset Waveform (Gaussian, ramp, or raised cosine); if a Gaussian, the rise spans three standard deviations up to the peak value. If the rise time is exactly 50%, the destination value grows for the first half of the interval, and declines for the second half; it has peak value of 1. If the rise time is less than 50%, the waveform value sits at its peak value between rise and fall. The waveform is made available through the output variable Envelope. The product of Signal Out and Envelope is set in Destination.

If Swap Sources is 0, source 1 is delivered in the first interval and source 2 in the second; if Swap Sources is 1, source 2 is delivered in the first interval and source 1 in the second. By driving Swap Sources with the results of a call to Random (0,1) you can randomize over trials the order in which source 1 and source 2 appear.

If the time occupied by the two intervals plus the ISI exceeds the time for which the state containing the routine is active, Expo simply stops execution of the routine when the state ends. You can exploit this if you want to shape the rise, maintenance and fall of a single signal: assign the signal to Source1 and set Duration to the time for which the state will be active.

If… Else…

This tests up to two conditions to filter one of three input values to the output variable Destination. If the If condition is TRUE (non-zero), Destination is set to Input 1, otherwise if the Else If condition is TRUE, Destination is set to Input 2, otherwise Destination is set to Input 3.

Op Variable

This routine is a filter that performs the arithmetic or logical operation defined by Operation on two inputs (Source 1 and Source 2—usually variables) and assigns the result to the variable Destination (which may be an input variable). For the logical operations (&&, ||, !=, <, >, <=, >=, ==) the destination is set to 0 if the result is FALSE and 1 if the result is TRUE; for the arithmetic comparison operation <>, the destination is set to 0 if the result is FALSE, -1 if Source 1 is less than Source 2, and 1 if Source 1 is greater than Source 2. For %, the result is the fractional part of Source1 divided by Source2; for ^ the result is Source1 raised to the power Source2. Expo updates the output variable on each timebase tick. If the output variable is also an input variable, the updated value is always based on the value that variable had when the state started.

Pulse

This routine places in Destination a train of pulses of value Amplitude, beginning at Start Time and lasting for Train Duration. Each pulse is of form Pulse Type, and is separated from the next by Interpulse Interval. The phase is end-aligned, so that the last pulse and the pulse train end simultaneously. Except during a pulse, Destination is set to 0. If Pulse Duration is 0, the train consists of a single pulse of duration Train Duration.

Quest

This routine uses a Quest procedure driven by the input variable Response to set the estimate of threshold in the output variable Destination. Destination is set initially to the value Start (Q0 Mean), and within the limits set by Min and Max its value is controlled by the value of Response: a response of -1 increases the estimate of threshold in Destination; a response of 1 decreases the estimate of threshold. If Response is 0, the trial is ignored.

Response typically comes from a Read Key function, and that Read Key must occur after the Quest. This is because Quest operates at state start time, whereas Read Key operates at state continuation time and has only its reset value at state start time.

If Quest is used to drive a two-interval, forced-choice experiment, the stimulus interval is usually randomized by something such as Random (0,1), which puts its value, say, in $2; this value goes to the Reorder parameter of the 2afc. A Read Key deposits a -1 or +1 in, say $3. The quantity ($2 * 2 -1) * $3 is then computed and placed in Quest's Response.

The parameters Beta and Gamma determine the Weibull function used in estimating threshold. In computing Destination each trial normally has a weight that varies inversely with its position in the series. You can change this by assigning a number other than 1 to Trial weight, which weights the trial by the number: trial^((weight-1)/weight). Assert after specifies the number of times the Destination value needs to remain between two adjacent values before the routine generates a DONE signal. (DONE is actually asserted only if Assert DONE is checked).

In computing its estimate of threshold Quest uses the history of all passes through the state that contains it.

Appendix D provides an example of how to use Quest.

Random

This routine generates a pseudo-random number drawn from one of several distributions: uniform (optionally constrained to integral values), Exponential or Gaussian.

The different settings of Distribution generate numbers as follows:

• Uniform (0,1…N). An integer in the range 0 through Norm, added to Base.
• Uniform (0…N). A real number in the range 0 through Norm, added to Base.
• Exponential (0…N). A number distributed about a mean of Norm, added to Base.
• Gaussian (-N…0…N). A number distributed about a mean of 0, with standard deviation Norm, added to Base.

Within the running state the routine generates new numbers at the rate determined by Generation Rate. If the rate is 0 a single number is generated at the beginning of each pass through the state. Each running program maintains its own random number generator, which is seeded when the program starts. The seed used to generate the first number on each pass through the state is saved in Seed.

Resolve

This resolves a vector, of direction Direction and magnitude Magnitude, into X and Y components, adds them to X base and Y base, respectively, and sets them in the variables specified for X out and Y out.

Unresolve

This is the inverse of Resolve. It converts a vector specified by its X and Y components into a direction and magnitude, and sets them in the variables assigned to Direction and Magnitude.

Waveform

This routine provides a filter that multiplies the input value Amplitude by the waveform specified in Waveform, of frequency Rate, and assigns the output to the variable specified in Destination. The peak value of the output is Amplitude. The waveform starts in the phase specified by Start phase.

Spike Count

This routine counts spikes collected during a pass through the state, and assigns the count to the variable Destination. Spike specifies which spike template is used in finding spikes. Start time specifies the time after onset of the state that counting begins; Duration specifies the interval for which spikes will be counted (–1 means count until the state ends). This routine requires spike recording to be enabled. Expo will warn you if recording is disabled.

Spike FT

This routine does a Fourier Transform at frequency Frequency on the train of spikes collected during a pass through the state, and assigns the amplitude to the variable Destination. Spike specifies which spike template is used in finding spikes. Start time specifies the time after onset of the state that sampling begins; Duration specifies the interval for which spikes will be sampled (–1 means count until the state ends). This routine requires spike recording to be enabled. Expo will warn you if recording is disabled.

Staircase

This routine tracks a response Response against a criterion Criterion to drive an output variable Destination. Values set in Destination are determined by a staircase procedure [Levitt, H. (1971). Transformed up-down methods in psychoacoustics. Journal of the Acoustical Society of America, 49, 467-477]. The general rule is that if Response exceeds Criterion the value in Destination is reduced, and if Response is below Criterion the value in Destination is increased. If the response matches the criterion exactly, the routine does nothing. On the very first pass through the state containing the routine, Destination is set to Initial Value. On subsequent passes the value in Destination is increased by a step if Response was below criterion; the value is reduced by a step only when Response has exceeded Criterion on the number of consecutive passes specified by Success Rule. The different success rules cause the value in Destination to converge on different success rates (One: 0.5; Two: 0.707; Three: 0.794; Four: 0.841). The step change in the value of Destination is initially set at Initial Step; step size is halved after the first, third, seventh, …, reversal in the direction of the staircase, until it would drop below Minimum Step, after which it remains fixed. Values placed in Destination can range between 0 and Maximum Value, and are clamped if they would fall outside this range. If you check Assert DONE, Expo will assert DONE when the value in Destination would be out of range, or when the step size would fall below Minimum Step.

Appendix D provides an example of how to use Staircase.

Statistics

This computes the mean and standard deviation of the values of Source accumulated over successive passes through the state, and places them in Mean and s.d. respectively. On each pass the routine uses the value of Source updated immediately before the pass ends (or at the point at which events are recorded, if sooner). The computation is made for the number of most recent passes specified in Recent Passes (up to 100). If you set Recent Passes to -1, Expo will compute the statistics for all passes run.

Values provided by Statistics can be used in the calculation of decision criteria (e.g., in Staircase).

Plugin Routines

Expo supports runtime loading of routines contained in plugins. See Appendix C for more information on how to write a routine plugin.

Calling Collections of Routines

You can form a collection of routines that will be called as an integrated unit from within any state in a program. To do this you put all the routines in a simple state, then from any other state in the program use the special routine Run State to call the state containing the collection. The collection can be called as often as you wish, from a single state or multiple states. Routines in the called and calling states share the same local variables, so you can pass arguments freely among them.

Run State

This runs all the routines contained in the named State. You cannot call a matrix nor can you call the calling state (either directly or indirectly), but you can call any other state any number of times. The called state may (but need not) be one that is used independently in the program schedule.

With the exception noted below, the routines in the called state behave as though they lie in sequence in the calling state immediately following the point of the call.

When Expo calls a routine in a collection it ignores settings of the following routine flags: Record, Persist, Assert Stop, Assert Done. All are implicitly unset. If you want to capture data values from routines in the called state you should pass them through variables to routines in the calling state.

Deprecated Routines

The routines described below are deprecated: each has been superseded by a different routine of the same name. A deprecated routine will run properly in any Expo program that contains it, but is not available to add to any program.

Random (Old)

This routine generates a pseudo-random number drawn from one of several distributions: uniform (optionally constrained to integral values), Exponential or Gaussian.

The different settings of Distribution generate numbers as follows:

• Uniform (0,1…N). An integer in the range 0 through Norm, added to Base.
• Uniform (0…N). A real number in the range 0 through Norm, added to Base.
• Exponential (0…N). A number distributed about a mean of Norm, added to Base.
• Gaussian (-N…0…N). A number distributed about a mean of 0, with standard deviation Norm, added to Base.

The routine generates a new number on each pass through the state that contains it. Each running program maintains its own random number generator, which is seeded when the program starts.

Obsolete Routines

The routines described below are obsolete, either because they use Classic OS technologies (QuickDraw, and direct access to video lookup tables) or control obsolete hardware (NuBus cards). Expo can examine (though will not run) old programs that contain obsolete routines, and can analyze data files generated from them.

DKL Contrast

This routine specifies, in DKL space, the contrast and color of gratings drawn by the Grating routine. DKL Contrast manipulates the lookup table for the active video device. Contrast (vector length) is specified with Contrast (maximum value 1). For achromatic gratings this is Michelson contrast; for gratings modulated along the other cardinal directions it represents the maximum contrast attainable without overmodulating the guns; along certain intermediate directions in color space unit contrast corresponds to an overmodulation. Elevation and Azimuth specify the elevation and azimuth, respectively. Elevation can take values in the range -90° to +90°, where 0° confines modulation to the isoluminant plane; azimuth can take values from -360° to +360°, where 0° is the L direction along an L–M line. When Expo draws gratings, the waveform of the grating is determined by the organization of entries in the lookup table. Hence the parameter Type, which identifies the waveform the will be drawn by the Grating routine. All other properties of the grating (size, orientation, spatial-frequency, etc.) are specified via the Grating routine.

From index and To index specify the inclusive range of lookup table entries manipulated by the routine. The maximum possible range is 1-255, but by using a smaller range you can, through multiple calls to DKL Contrast, create multiple independently managed regions of the lookup table, each of which can be attached to a different grating.

Base Contrast, Base Elevation and Base Azimuth specify, in the notation introduced above, the point from which the contrast vector originates, in relation to the monitor's white point.

Some DKL contrasts—those with non-zero Base parameters or along certain intermediate directions in color space—specify overmodulation. Most of these are truncated. That is, they are displayed with the vector defined by Contrast, Elevation and Azimuth changed to one of the same direction but lesser magnitude. Contrast is reduced to the largest value which specifies a color gamut that can be generated by the three guns. Note that none of the other parameters, including Base Contrast, is ever reduced or changed.

If you use this routine, call it in a state before you call the Grating routine.

DKL Entry

This routine directly assigns a contrast and color (in DKL co-ordinates) to a single entry in the lookup table. The individual entry is specified by LUT index (range 0 to 255), and any pixel whose value is that index will take the color specified by this routine. This routine is useful in assigning colors to the different components of pictures being displayed by Expo (pictures are displayed by the Picture routine). LUT entry 0 defines the background.

Contrast (vector length) is specified with Contrast (maximum value 1). For achromatic vectors this is Michelson contrast; for vectors along the other cardinal directions it represents the maximum contrast attainable without overmodulating the guns; along certain intermediate directions in color space unit contrast corresponds to an overmodulation. Elevation and Azimuth specify the elevation and azimuth, respectively. Elevation can take values in the range -90° to +90°, where 0° confines the vector to the isoluminant plane; azimuth can take values from -360° to +360°, where 0° is the L direction along an L–M line.

The vector defined by Contrast, Elevation and Azimuth is based on a point in color space specified by Base Contrast, Base Elevation and Base Azimuth. The base vector is referred to the white point in the color space (Base contrast 0, Base elevation 0, Base azimuth 0).

Some DKL entries—those with non-zero Base parameters or along certain intermediate directions in color space—specify overmodulation. Most of these are truncated. That is, they are displayed with the vector defined by Contrast, Elevation and Azimuth changed to one of the same direction but lesser magnitude. Contrast is reduced to the largest value which specifies a color within the gamut of all three guns. Note that none of the other parameters, including Base Contrast, is ever reduced or changed.

DKL Plaid

This routine facilitates drawing a plaid grating (pair of transparent gratings in the same location). Each of the two gratings is specified by a DKL Plaid and a Plaid (below).

This routine specifies, in DKL space, the contrast and color of gratings drawn by the Plaid routine. DKL Contrast manipulates the lookup table for the active video device. Contrast (vector length) is specified with Contrast (maximum value 1). For achromatic gratings this is Michelson contrast; for gratings modulated along the other cardinal directions it represents the maximum contrast attainable without overmodulating the guns; along certain intermediate directions in color space unit contrast corresponds to an overmodulation. Elevation and Azimuth specify the elevation and azimuth, respectively. Elevation can take values in the range -90° to +90°, where 0° confines modulation to the isoluminant plane; azimuth can take values from -360° to +360°, where 0° is the L direction along an L–M line. When Expo draws plaid gratings, the waveform of the grating is determined by the organization of entries in the lookup table. Hence the parameter Type, which identifies the waveform the will be drawn by the Grating routine. The two extant DKL plaids are intended to have the same Type, and if not the first is ignored. All other properties of the plaid grating (size, orientation, spatial-frequency, etc.) are specified via the Plaid routine.

Base Contrast, Base Elevation and Base Azimuth specify, in the notation introduced above, the point from which the contrast vector originates, in relation to the monitor's white point.

Component Number specifies which of the two gratings in the Plaid will receive this color specification. Plaids use the entire 256-entry lookup-table, filling it with the cross product of a sixteen-entry component one and a sixteen-entry component two. In each case, the first of the sixteen entries indicates the absence of any grating, so the grating is quantized into fifteen steps per cycle.

If you use this routine, call it in a state before you call the Plaid routine.

Dots

Dots writes on the screen of the active monitor a dynamic, random-dot kinematogram (in the manner of Douglas Williams or Bill Newsome) to the rectangle specified by Dots Rect (see below) specified by Rect Number. Dots have a specified motion dx, dy, and dt. After every time step (dt) all of the dots are dynamically updated. Correlation specifies the chance (a number from zero through one) that a given dot will be moved by (dx, dy). If it is not moved, the dot replaced by a new one at a randomly generated location in the rectangle defined by Dots Rect. The number of dots is a product of the Density and the area covered by the rectangle. All dots are 2x2 pixels square. Dot color and transparency are controlled through Dots Plane (see below) to which Rect refers.

Given the correlation, the longest-living dot lives no more clock-ticks than are needed. Correlations up to .5 mean no dot is alive on more than two clock-ticks: after the second tick it is replaced by a dot at a new, random location. Similarly, correlations up to .667 mean a maximum life of three ticks, etc.

If Expo cannot draw all the dots in a single clock tick it will crash. The maximum number of dots that can be displayed depends on the processor, so Expo checks at run-time that number of dots specified is not too many. For a 68040 the number of dots allowed is 1000; this value is halved for each previous generation in the 680x0 family. Unknown CPUs allow 1000 dots. These limits are estimates that assume little other run-time computation is done by the state, since most Expo routines are fast.

To use the same dots in multiple states check Persist. This will prevent unnecessary erasure and redrawing of the pixel elements that Expo uses to animate the dots. The corresponding Dots Plane and Dots Rect routines must also persist. If there are kinematograms or other objects in overlapping screen positions all (or none) of them must persist, otherwise parts of persisting objects will be cleared by the erasure of other, volatile, objects and will never be redrawn.

Dots Plane

Defines a bitplane, typically for use with one or more Dots Rect and Dots routines. Bg LUT and Fg LUT are two lookup-table indices, typically defined by DKL Entry, which specify a background and foreground color. This allows routines, such as Dots, which write images to the bitplane to use exactly two colors: a pixel can be set or cleared, but nothing more. Transparent backgrounds can be gotten by setting Bg LUT to –1. 32 lookup-table entries are used so that up to five different bitplanes can coexist at any pixel, with transparency, real time set and clear, and so forth.

Bitplane Name tells which of five different 32-entry blocks in the lookup-table will be populated by the bitplane. The blocks' names include the numeric indices, and of course the Bg LUT and Fg LUT must not use any of those indices.

Dots Rect

This draws a rectangle on the screen with a location and size specified by X-position, Y-position, Width, and Height. It doesn't draw it with a specified color; rather, it draws with a specified Bitplane. This means that another routine can draw to that area, setting and clearing parts of it, and that those operations will have an effect specified by the Dot Plane routine. Dots Rect initializes the area to the bitplane's background color.

Routines that write to the rectangle refer to it by its Rect Number.

Gabor

This routine draws a stationary Gabor patch—a grating windowed by a Gaussian—on the screen of the active monitor (choose the active monitor through the Monitors item in the Environment menu). The routine specifies all characteristics of the grating except its contrast, color and waveform (sin, square, etc.). These properties are controlled by the routine DKL Contrast or the routine LMS Contrast. In assembling routines in a state you should make the call to DKL Contrast or LMS Contrast before you make the call to Gabor.

Spatial Frequency specifies the spatial frequency; Orientation specifies the orientation in a Cartesian co-ordinate system , StD (Width) and StD (Length) specify the standard deviations of the Gaussian envelope, in the directions of the grating's width and length, respectively, and X-position and Y-position specify the position of the center of the grating in relation to the center of the screen. Spatial Phase specifies the starting phase of the grating in relation to the center of the grating patch (0 is sin phase). StDs to Draw specifies the number of standard deviations in the diameter of the entire Gabor patch, beyond which is clipped. The Gabor patch is drawn using the inclusive range of pixel values between From pixval and To pixval. This range should match the range of lookup table indices specified in the contrast-controlling routine DKL Contrast or LMS Contrast. Using fewer than the possible 255 pixel values for a grating makes it possible to display multiple Gabors concurrently, each with its own control of contrast, color, etc.

If you use the routine several times in a state to draw multiple overlaid Gabors, arrange the calls so that the rearmost Gabor is drawn first.

Expo uses QuickDraw to draw a grating, and that is one of the slowest operations the program undertakes. To use the same Gabor in multiple states you should check Persist. This will prevent unnecessary erasure and redrawing of the Gabor as Expo enters each state. For the Gabor to be visible each state will have to make a new call to DKL Contrast or LMS Contrast, or ensure that a setting persists. If there are Gabors or other objects in overlapping screen positions all (or none) of them must persist; otherwise parts of persisting objects will be cleared by the erasure of other, nonpersistent objects, and will never be redrawn.

Grating

This routine draws a grating on the screen of the active monitor (choose the active monitor through the Monitors item in the Environment menu). The routine specifies all characteristics of the grating except its contrast, color and waveform (sin, square, etc.). These properties are controlled by the routine DKL Contrast or the routine LMS Contrast. In assembling routines in a state you should make the call to DKL Contrast or LMS Contrast before you make the call to Grating.

Spatial Frequency specifies the spatial frequency; Orientation specifies the orientation in a Cartesian co-ordinate system , Width and Length specify width and length, respectively, and X-position and Y-position specify the position of the center of the grating in relation to the center of the screen. Spatial Phase specifies the starting phase of the grating in relation to the center of the grating patch (0 is sin phase). Drift rate specifies the drift rate. The grating is drawn using the inclusive range of pixel values between From pixval and To pixval. This range should match the range of lookup table indices specified in the contrast-controlling routine DKL Contrast or LMS Contrast. Using fewer than the possible 255 pixel values for a grating makes it possible to display multiple gratings concurrently, each with its own control of contrast, drift rate, color, etc.

If you use the routine several times in a state to draw multiple overlaid gratings, arrange the calls so that the rearmost grating is drawn first.

Expo uses QuickDraw to draw a grating, and that is one of the slowest operations the program undertakes. To use the same grating in multiple states you should check Persist. This will prevent unnecessary erasure and redrawing of the grating as Expo enters each state. For the grating to be visible each state will have to make a new call to DKL Contrast or LMS Contrast, or ensure that a setting persists. If there are Gratings or other objects in overlapping screen positions all (or none) of them must persist; otherwise parts of persisting objects will be cleared by the erasure of other, nonpersistent objects, and will never be redrawn.

Interferometer

This routine controls the properties of the grating made by the interferometer. Spatial Frequency controls spatial frequency, Orientation controls orientation, Phase controls phase (0 is sin phase, in relation to some undefined point), Drift rate controls rate of movement, and Contrast specifies Michelson contrast. The routine requires the NB-DIO-32 and the NB-TIO-10 to be enabled; it also requires serial port B to be enabled and connected to the controller for the motors that drive spatial frequency and orientation. If any required device is disabled, Expo will warn you when you try to run a program.

LMS Contrast

This routine specifies, in LMS space, the contrast and color of gratings drawn by the Grating routine. LMS Contrast manipulates the lookup table for the active video device. The parameters Long, Medium and Short specify the contrast for the L, M and S cones respectively, as a fraction of the maximum contrast attainable in each of these directions without overmodulating the guns; along certain intermediate directions in color space unit contrast will result in overmodulation.

When Expo draws gratings, the waveform of the grating is determined by the organization of entries in the lookup table. Hence the parameter Type, which identifies the waveform that will be drawn by the Grating routine. All other properties of the grating (size, orientation, spatial-frequency, etc.) are specified via the Grating routine.

From index and To index specify the inclusive range of lookup table entries manipulated by the routine. The maximum possible range is 1-255, but by using a smaller range you can, through multiple calls to LMS Contrast, create multiple independently managed regions of the lookup table, each of which can be attached to a different grating.

If you use this routine, call it in a state before you call the Grating routine.

Mask

This routine defines the clipping region on the screen of the active monitor, and can be used to shape the boundaries of objects drawn on the screen (e.g., making a elliptical patch of grating). It should be called in a state before the routine (e.g., Grating, Picture) that will do the drawing. Defining a clipping region with Mask will generally slow the drawing of other objects, so don't use the routine unless you need it.

Form specifies the shape of the mask, oval or rectangular. Outer Width and Outer Length specify the outer dimensions of the mask (or the only dimensions if you want a solid region), Inner Width and Inner Length specify the inner dimensions; they are currently ignored for ellipses; if Inner Width is 0, then the outer dimensions are taken to define a solid region. Xposition and Yposition specify the position in relation to the center of the screen. Orientation specifies the orientation in a Cartesian coordinate system.

If within a single state you want to mask a region of screen for one drawing operation (e.g., a grating), then draw again without a mask, you should call Mask before drawing the second time, and set Outer Width to 0. This restores the default clipping region.

Pan & Scroll

This routine specifies the amount by which the image drawn by the active video device should be offset from its standard position on the screen. The routine deals directly with the hardware registers that specify drawing position, so, on those video devices that support it, the whole image is shifted. Of the graphics cards that Expo knows about, the only ones that support hardware pan and scroll are the Radius Thunder series (Power Mac) and the NuVista and the ProColor 32 (68k Mac). If any other card is the active video device, Expo ignores calls to this routine.

X offset specifies the horizontal displacement of the screen image from its standard position on the screen; Y offset specifies the vertical displacement.

Picture

This routine displays a picture at a defined size and position. The set of possible pictures is contained in Expo's picture file [ExpoMT and earlier]. The parameter Picture specifies which picture in the file is to be displayed. Height and Width control the size of the displayed picture, and X-position and Y-position control its position. The color(s) in which the picture is displayed is determined by the pixel values it uses, and the values assigned to these by the routines that write to lookup tables (DKL Contrast, LMS Contrast, and—probably more relevant—DKL Entry or RGB Entry). The routine that you use to control lookup table values should be called before the Picture routine.

Expo uses QuickDraw to draw a picture, and that is one of the slowest operations the program undertakes. To use the same picture in multiple states you should check Persist. This will prevent unnecessary erasure and redrawing of the picture as Expo enters each state. For the picture to be visible each state will have to make a new call to DKL Entry or RGB Entry, or ensure that a setting persists. If there are Pictures or other objects in overlapping screen positions all (or none) of them must persist; otherwise parts of persisting objects will be cleared by the erasure of other, nonpersistent objects, and will never be redrawn.

Plaid

This routine draws a plaid grating (pair of transparent gratings in the same location) on the screen of the active monitor (choose the active monitor through the Monitors… item in the Environment menu). The routine specifies all characteristics of the gratings except their contrast, color and waveform (sin, square, etc.). These properties are controlled by a pair of calls to the routine DKL Plaid. In assembling routines in a state you should make the calls to DKL Plaid before you make the call to Plaid. The plaid uses 256 lookup-table entries.

Spatial Frequency specifies the spatial frequency; Orientation specifies the orientation in a Cartesian co-ordinate system , Width and Length specify the size of the grating, and X-position and y-position specify its position. Spatial Phase specifies the starting phase of the grating in relation to the center of the grating patch (0 is sin phase). Drift rate specifies the drift rate. Component Number specifies which of the two DKL Plaids it uses for its lookup-table.

Expo uses QuickDraw to draw the plaid gratings, and that is one of the slowest operations the program undertakes. To use the same plaid grating in multiple states you should check Persist. This will prevent unnecessary erasure and redrawing of the grating as Expo enters each state. For the grating to be visible each state must make a new call to DKL Plaid, or ensure that a setting persists.

RGB Entry

This routine directly assigns an RGB value to a single entry in the lookup table. The individual entry is specified by LUT index (range 0 to 255), and any pixel whose value is that index will take the color specified by this routine. LUT entry 0 defines the background. This routine is useful in calibration, for it allows independent control of the signals sent to the three guns of a monitor.

Red specifies the red gun signal (value between 0 & 255, except for the ProColor 32 board, which can take values between 0 and 511, and the Thunder/24GT board which takes values between 0 and 1023). Similarly, Green and Blue specify the signals for the green and blue guns.