General Experimental Parameters

be used.

The core of PXL are its functions for handling experimental variables. These variables support its design philosophy of keeping things adaptable by the user. This chapter gives a description of all the built in experimental variables. Any application will extend this set and will have to give a special description of its extended set. Only a subset of all the parameters give here is used by library internals. Many of the parameters may be used by applications for their own purpose. However, programmers should prefer to create new parameters instead of using existing ones for nonstandard purposes.

Messages

There are several variables that define text messages that may be used to prepare the subject for different parts of an experiment. These messages are used in a rather similar way by most PXL programs such that they may be presented here all together. Table msgvars gives these variables' names and their special function. Each message has a message text and a display time parameter. The message text parameter ends on msg and the timing parameter ends on tm. The message text is the string that is written on the screen. The text will usually be centered on the screen. This string may contain newline escape characters for writing multiple lines. The timing parameter may be a positive or a negative integer number, or may be zero. In the latter case no message is displayed. If the timing parameter is a positive integer then it is taken to be the display time in milliseconds. If the timing parameter is negative, then the message is written on the screen and then the program will wait until a response event is detected before the program goes on. This mechanism may be used to either allow the subject or the experimenter to control the procedure.


Insert Table msgvars here.

The list specified in Table msgvars does not mean that all PXL programs do actually use all of these parameters. Some programs may use only some of the parameters. If this is the case then the program's description will contain the actual usage of the respective parameter. Also note that the message defined by blockstartmsg will not be printed before the first block and blockendmsg will not be printed after the last block.

The appearance of messages is controlled by the parameters msgfont, msgsize, and msglum which give the font, character size and luminance of the message text. Note that the default font for messages and signal text is scrn at a rather small size which is the built in screen raster font. Larger raster fonts use the font rasterfont (Chap. graphics).

Binary Parameters: Flags

Most PXL programs use a set of global binary parameters. These are defined by the string parameter flags. Each single binary parameter is a letter which either is lower or is upper case. A flag parameter is said to be set if and only if its corresponding letter is capitalized. The flag letters are contained in the string parameter flags. Thus the example
   flags = "AbcdefgiLmnpqRstUvwz"
on page \pagerefflagExample has the flags A, L, R, and U set and all other flags clear. The meanings of the single flag letters are not identical across applications. Each program has its own flags and identical flag letters do not mean that these parameters have the same meaning for different programs. Flag parameters always are global and the flag string must not be contained in the block or trial argument list. Programs which need local binary parameters define these as ordinary integer parameters.

An Alphabetical List

adapmaskpars (string)
This parameter can be a single string or a range of strings which actually must be names of trial parameters. The parameters listed in adapmaskpars are used to decide which trials in a block are considered to belong to the same adaptive sequence. The most simple case is to use a single indicator parameter like ident to identify trials belonging to the same adaptive sequence.

adproctype (int)
The type of the adaptive procedure to be used. Currently there are four adaptive types implemented and one non-adaptive type exists as a default. The adaptive procedures are defined by the tables in Chapter adaptive. These values of adproctype are currently implemented:

NONADAPTIVE (0)
Do not use an adaptive procedure.

NONCHANGING (1)
Do not change the adaptive parameter, simply take over the parameter value of the previous trial.

ADPROC1U1D (2)
Use the 1-up-1-down procedure given in Fig. 1up1do.

ADPROC1U2D (3)
Use the 1-up-2-down procedure given in Fig. 1up2do.

ADPROC1U3D (4)
Use the 1-up-3-down procedure given in Fig. 1up3do.

ADPROCD1U1D (5)
A delayed 1-up-1-down procedure.

advar (string)
This is the name of the adaptive variable in adaptive designs. In earlier versions of PXL the adaptive variable has been specified by its display parameter index advarindex which is still available but should no longer be used. The adaptive variable is the one that is changed by the adaptive procedure. This variable has to be a trial variable and thus must be listed in the formal trial arguments list. advarindex identifies the adaptive variable by its position in the trial arguments list. The first variable has index 0, the second variable has index 1, and so on.

advarindex (int)
See advar on how to define the adaptive variable.

answer (string)
Holds verbal response strings.

bfactor (int)
Block multiplication factor. Each block of trials is actually executed bfactor times. Thus bfactor provides a way to multiply each block. However, before replication, the current block parameter array is copied into the replication. Thus the repeated blocks do not start with a new block parameter array, as given in the definitions file. Since each block copy inherits the previous copy's parameter array, it becomes possible to transfer information from one block copy to the next.

blockcount (int)
Counter for blocks. This counter is automatically incremented for each new block.

blockendmsg (string)
Message shown at the end of a block if there is one more block to come.

blockendtm (int)
Block end message visibility time.

blockrepcount (int)
Counter for replications of a block which are generated by a value of bfactor larger than 1.

blockstartmsg (string)
Block start message. It is not shown before the first block. Use bosmsg to present a message before the first block.

blockstarttm (int)
Block start message visibility time.

blockstate (int)
Block running state. The blockstate may be used to transfer information about the complete trial list from one block to the next, since the blockstate value from the current block is always handed over to the next block. This is done automatically for block replications by bfactor. It is effective for all blocks if blockstate is global.

bluegamma , bluegain , blueoffset (float)
In case there is no gamma table file available the gamma functions for the three channels are computed according to Equation \eqrefBernsMotta in Chapter colors. The equation parameters may be specified by these parameters.

bluegammatable , greengammatable , redgammatable (float)
If any of these parameters is defined then it should be range valued and contain the gamma values of the respective color channel. The position index in the range entry gives the DAC output palette value and the entry itself should give actual luminance. The number of entries must correspond to the current color device's number of possible palette values. These are 64 for standard VGA and 256 for many SVGA boards. See Chapter colors for more information about gamma tables.

blueprimaryx , blueprimaryy , blueprimaryL (float)
These together give the CIE coordinates of the blue primary used for high resolution color displays. The luminance component blueprimaryL gives the maximum luminance that may be produced by the current device's blue color channel.

bofwarning (string)
The warning message that is printed during the instruction phase of a program if the subject tries to page backwards beyond the first line of the instruction text file.

bosmsg (string)
Begin of session message.

bostm (int)
Begin of session message visibility time.

colorsensor (int)
Color measurement device code.

comptype (int)
Determines how adaptive results are computed. These values are currently available:

COMPADPROC (0)
Use current value of adproctype to determine the method for computing the result. This result is computed as the mean of the last useturns turning points of an adaptive procedure.

NONCHANGING (1)
Do not compute anything. Print out the unmodified list of trials. This also applies if both comptype and adproctype are 0 or comptype is 0 and adproctype is 1.

COMPSUM (10)
Compute the sum of the adaptive parameter values from all trials in a single adaptive sequence.

COMPMEAN (11)
Compute the mean of the adaptive parameter values from all trials in a single adaptive sequence.

contfile (int)
Write continuation file flag. If this flag is ON, then PXL will create a continuation file for the current subject. Thus if the list of blocks is not yet finished, the continuation file will contain all those blocks that still have to be worked on. If a PXL program is started it will first check whether there is a continuation file for the present subject. If such a file exists, it will be used as a parameter file. Only if such a file does not exist, will the default parameter file be executed. Note that this mechanism works correctly only if no explicit parameter file is given in the command line. See Chapter defs for more information on multiple sessions.

copyright (string)
Copyright message.

corrmsg (string)
Feedback message for correct responses.

date (string)
Current date.

dbufmode (int)
Video mode number of the highest resolution graphics mode which provides at least 2 screen buffers and at least 16 colors.

dfactor (int)
Display multiplication factor. On execution of a block, each trial in the block's trial list will be shown dfactor times. Thus if the same trial has to be presented multiple times, dfactor is the easiest way to create the multiples.

dspcount (int)
In adaptive procedures dspcount is counting the trials within an adaptive sequence. This counter is used in some procedures to modify adaptive parameters. The parameter trialcount should be used for counting trials across blocks.

dspmsg (string)
Trial display message.

dspstate (int)
Trial state. Used in adaptive procedures to code the history of responses for the current trial.

dsptime (int)
Presentation time for some trial specific displays.

dsptm (int)
Trial display message visibility time.

endtime (string)
End time of run. This will be available only after all data have been collected. It is known when the results file is written.

eofwarning (string)
The warning message that is printed during the instruction phase of a program if the subject tries to page forward beyond the last line of the instruction text file.

eosmsg (string)
End of session message.

eostm (int)
End of session message visibility time.

eval (int)
Response evaluation result. Generally correct responses correspond to 0 and false responses to 1. Illegal responses give values between 90 and 999.

evaluation (int)
Type of response evaluation used. The available response evaluation methods depend on the experimental task .

exname (string)
Long name of the experiment.

falsemsg (string)
Feedback message for false responses.

feedbackmsg (string)
General response feedback message.

feedbacktime (string)
Response feedback message duration.

fieldheight , fieldwidth (int)
Height and width of the display field subsection of the screen which is used by some programs.

fieldcolx , fieldcoly , fieldlum (float)
Display field color and luminance.

firstblock (int)
Gives the number of the first block to work on.

fixmarklum (float)
Luminance of fixation mark.

fixmarksize (int)
Size of fixation mark.

flags (string)
A string of flag letters that may be used to set or reset binary flags. Each flag corresponds to one of the letters from A to Z. A capital letter indicates that the flag is set, while a lower case letter indicates that the flag is clear. The meaning of a flag letter depends on the individual application. See the previous section for more details on the flags string.

funkeynumbers (int)
Function key code translation table. This is a range type parameter which contains pairs of values: the first entry of each pair is the keyboard key scan code and the second entry is the corresponding PXL event code. This makes it possible to assign arbitrary event codes to any keyboard key. By default funkeycode ist
   funkeycode = [75, 1, 77, 2, 79, 3]
which defines the codes 1, 2, and 3 to the cursor left, cursor right and END key.

gammaindex (int)
Drawing index values for corresponding gamma tables (see Chapter colors for an explanation).

gammatable (string)
Gamma table file names (see Chapter colors for an explanation).

greengamma , greengain , greenoffset (float)
See bluegamma for a description.

greengammatable (float)
See bluegammatable for a description.

greenprimaryx , greenprimaryy , greenprimaryL (float)
These together give the CIE coordinates of the green primary used for high resolution color displays. The luminance component greenprimaryL gives the maximum luminance that may be produced by the current device's green color channel.

hicolmode (int)
Video mode number of the highest resolution graphics mode which provides 256 simultanous colors.

hiresmode (int)
Video mode number of the highest resolution graphics mode which provides at least 16 colors.

ident (int)
This parameter is not used by PXL programs. It may be used to identify trials for statistical data analysis.

illegalmsg (string)
Feedback message for illegal responses.

instruction (int)
If ON then the file introfile is shown to the subject before the session starts. This file should contain instructions for the subject. See Capter files how this mechanism works.

intdsptime (int)
Waiting time between trials.

introfile (string)
This is the name of the file that may contain instructions for the subject and is shown if instruction is ON.

keyhelp (string)
The help message that is printed during the instruction phase of a program in order to tell the subject how to page through a file of instructions with the keyboard.

language (int)
Message language to be used.

0
German;

1
English.

lastblock (int)
The number of the last block to work on.

machinecode (int)
Not yet used.

maxblocks (int)
Gives the maximum number of blocks per session.

maxturns (int)
If a stopping rule is used that uses the number of turning states as a criterion, then maxturns gives the limit for turncount. If turncount is equal to maxturns the sequence is stopped.

mousehelp (string)
The help message that is printed during the instruction phase of a program in order to tell the subject how to page through a file of instructions with the mouse buttons.

msgfont (string)
Font name for procedural text messages.

msglum (float)
Text message luminance.

msgsize (int)
Text message character size.

nokey (int)
Response device key code for "NO" responses. By default this corresponds to the cursor right key for keyboard and to the left button for mouse or switch responses. See Chapter timing for a detailed description.

nokeybreak (int)
If this variable is OFF then CTRL-C may be used to stop any PXL program. If nokeybreak is ON then CTRL-C is disabled. nokeybreak is OFF by default.

parfilename (string)
Parameter file name.

preprocessing (int)
If ON then the preprocessor is applied to the parameter file before parsing. If OFF then no preprocessor is used. The default is ON. Setting preprocessing to OFF is only effective if it is done in the startup file startup.pxl. Preprocessing may also be disabled by giving the command line option -m.

preprocmd (string)
This is the command string that is used to call the preprocessor for macro expansion in parameter files. The default is preprocmd = prepxl. Note that the command line has to define PXLRUN in order to tell the parameter files that this is the execution of a PXL program as opposed to a compilation. This feature makes it possible to use one and the same header file during execution and compilation. Changing the value of preprocmd is only effective in the startup file startup.pxl.

printflag (int)
Contains various flags for printing information into the data file:

1
parameter file protocol into the log file;

2
print special local variables into data file;

4
print system variables into data file;

8
print block and trial definitions into data file.

progversion (string)
Defaults to the compilation date of the program.

pxlversion (string)
Contains the version number and the compilation date of the library.

randomize (int)
Trial sequence randomization flag. If this flag is set to ON, then all trials within a block are mixed randomly before presentation. Note that blocks are never randomized. Trials are randomized by default.

randseed (int)
Controls the random generator seed value. If randseed is zero, then the random number generator is not initialized. If randseed has a positive value then the random number generator is initialized to it. If randseed is negative, then the random number generator is initialized with the current value of the millisecond timer clock. This has the effect of giving different random sequences for every run.

rasterfont (string)
The name of the font which is used as a raster font for sizes larger than the standard screen raster font. This parameter defaults to dcss10 which is a sans serif font from the TeXComputer Modern family of fonts. The corresponding font files are contained in the standard PXL distribution. Any TeX PK type font file may be used.

redgamma , redgain , redoffset (float)
See bluegamma for a description.

redgammatable (float)
See bluegammatable for a description.

redprimaryx , redprimaryy , redprimaryL (float)
These together give the CIE coordinates of the red primary used for high resolution color displays. The luminance component redprimaryL gives the maximum luminance that may be produced by the current device's red color channel.

resformat (string)
Format string for printing parameter values into the results file. This string may contain any text and variable names embedded between percent signs. These names are then replaced by their current values. Note that the results file is only printed at the end of the experimental session. Only the data file is printed while the experiment is running.

resheader (string)
This string is printed as a header line into the results file if it is defined. This header may be used by some statistical analysis programs to identify the names of the data variables in a results file.

response (int)
Used for subject responses that are coded as integer numbers. String responses are stored in answer. Evaluated responses are returned in eval. Some programs use this parameter to define "correct" responses in the parameter file.

result (float)
Final result of an adaptive sequence. This variable is used by the functions that compute the results of an adaptive procedure. The final value is stored in result. An estimate of the standard deviation of result is computed in stddev.

rtime (int)
Response time.

savedata (int)
Save data flag. If this flag is ON, then the data are saved on disk. If savedata is OFF then no data are saved.

sreencolx , screencoly , screenlum (float)
Screen background color and luminance.

screenheight , screenwidth (int)
Height and width of the display screen in pxlm (1 pxlm = 1/10 mm). screenheight and screenwidth describe the physical screen size. Usually these are set in the startup file startup.pxl. The program scrnsize may be used to adjust these parameters interactively. Note that all metric information in parameter definitions is relative to the values of screenheight and screenwidth.

screenprotocol (int)
This variable is used by some internal functions to decide whether a screen protocol should actually be printed or not. If screenprotocol is OFF the protocol is suppressed. This is useful only for double screen implementations of PXL.

sessionstate (int)
Running state of a session. May be used to stop a session before other stopping criteria apply.

sounddevice (int)
Device for sound output. These are available:

0
Use Soundblaster device if possible. If not then use the internal PC speaker.

1
Definitely use the internal PC speaker as a sound device.

starttime (string)
Start time of run.

stdcolors (float)
This parameter may be used to redefine PXL's standard color array which is derived from the IBM PC EGA default color array. stdcolors must be range valued and must contain a triple of color coordinates for each color to be defined.

stddev (float)
Standard deviation of the final result result for adaptive variables.

stepdiv (float)
The step dividend that determines the step size according to the adaptive procedure's parameter function.

stepdivdelta (float)
The value that gives the amount of change for stepdiv in case there is a change after a turning point which corresponds to a response direction change.

stepdivgamma (float)
The value that gives the amount of change for stepdiv in case there is a change during a longer run of constant responses.

stepmin (float)
The minimum step size to be used for changing the value of the adaptive variable.

stepsize (float)
The initial step size for changing the adaptive variable.

stopkey (int)
Keyboard key code for "stop" responses. By default this corresponds to the END-key for keyboard and to the center button for mouse or switch responses. See Chapter timing for a detailed description.

stoppingrule (int)
The type of stopping rule to be used. These are currently available:

DONTSTOP (0)
No preliminary stopping. Stop if the complete list of trials has been finished.

STOPONTURNS (1)
Stop if maxturns turning points have been found.

STOPONMINTURNS (2)
Stop if maxturns turning points have been found after stepsize has become less than stepmin.

STOPONSTOP (3)
Stop if the stopkey is pressed.

STOPONLAST (4)
Stop if the current stimulus is the only one remaining in the list of trials. This is used for inserting non-adaptive distractor items in a block. If these use adproctype NONCHANGING and stoppingrule STOPONLAST the distractor is stopped if all other adaptive sequences are finished.

subjectcode (string)
Subject identification code as given in the command line. If no command line code is given then subjectcode is equal to vp.

switchhelp (string)
The help message that is printed during the instruction phase of a program in order to tell the subject how to page through a file of instructions with a switch board.

switchmask (int)
This parameter allows a run time definition of almost all aspects of a switch board connected to any I/O port. Look into the source file for the switch board interface to find out about the meaning of the entries in switchmask. See Chapter timing for a detailed description.

switchnumbers (int)
This parameter may be used to assign nonstandard switch numbers to the single bits of external switches. It must be range valued and give the switch number for each of the 8 bits of the input pattern. See Chapter timing for a detailed description.

switchport (int)
Number of printer port used as a switch port. Usually these numbers correspond to the LPT-numbers of the operating system. Possible numbers are 1, 2, and 3. See Chapter timing for a detailed description.

switchtype (int)
This variable tells PXL what type of response switch to install. See Chapter timing for a detailed description. This parameter may be set in the command line by using option -t. Switch numbers determine the type, number, and configuration of the switches. The following types are available (Chap. timing):

0
Keyboard.

1-5
Up to 4 digital switches connected to the game port adapter.

11-16
Up to 5 digital switches connected to the parallel printer port.

18-19
Configurable switches connected to any parallel I/O register. port.

20
Mouse buttons. The number of buttons is detected automatically.

21-23
Mouse buttons restricted to the given number.

40
Keyboard and mouse combined.
textfont (string)
Name of stimulus text font in graphic applications. See Chapter graphics and Table fontab for the available font names.

textlum (float)
Luminance for text written in graphics mode.

textsize (int)
Character size for graphic fonts.

timeout (int)
Response time limit.

timeoutmsg (string)
Feedback message for time out cases.

training (int)
This variable should be set to TRUE during training blocks and FALSE while actual data collection takes place. If it is TRUE then the results of this block are not written into the results file. The data file protocol in the data file is not affected by the state of training.

trialcount (int)
Used as a counter for trials within one session. Trials are counted across blocks.

trialsave (int)
Flag to enforce saving data after each trial. If this flag is ON, then the data are saved after each trial, if it is OFF, then the data are saved after the end of the block.

turncount (int)
Counts the number of turns in an adaptive procedure.

unlinkothers (int)
If this variable is ON, which is the default, then all remaining trials in an adaptive sequence are unlinked from the trial list after the stoppingrule has applied.

upstepfactor (float)
The upward steps of the ADPROC1U1D adaptive procedure are multiplied by this factor.

useturns (int)
The number of turning points to be used in computing the result of an adaptive sequence.

videomode (int)
Video mode to be used. Table vmodes contains a list of all possible values for videomode. This parameter may be set in the command line by using option -v.

yeskey (int)
Response device key code for "YES" responses. By default this corresponds to the cursor left key for keyboard responses and to the left button for mouse or switch responses. See Chapter timing for a detailed description.

Value Precedence

Here is a short overview on the precedence determining the values of experimental variables. This is necessary since some variables may get there values from several different sources. Note that this is not true for all but only for some variables. This mechanism requires that any parameter may only then be set on the command line, if no definition is contained in the parameter file. Note, however, that the macro processing capability of PXL makes it possible to define macros in the command line and thus set any parameter value from the command line and also to define defaults in the parameter file which are used only if no command line options are given.


Back to table of contents


Author: Hans Irtel

irtel@psychologie.uni-mannheim.de