Contrast Sensitivity: Lesson 1

The aim of this experiment is to measure contrast detection threshold for a Gabor stimulus of given spatial frequency and size using a staircase method and a horizontal/vertical discrimination procedure.

Launch Psykinematix, and select the Designer panel by clicking on its icon in the toolbar.

The Experiment Designer panel presents a hierarchical view of the experiments. Before going further, make sure to deselect any event by clicking on an empty row or ⌘-clicking on the selected event to deselect it.

Now, create a new group event by clicking on the folder icon with the '+' symbol in the bottom toolbar.

Tip: A group event embeds one or several events. This allows to create the hierarchy of the design structure.

The new event appears at the top in the table with a default title (New Events). Change its title to Contrast Sensitivity to reflect the experiment purpose (double-click on the title to edit it).

Note the two last columns of the designer table: the right-most one indicates the lock status of the event (either unlocked or locked to protect it from changes) and the 2nd right-most column shows the event status (for example, a question mark or a warning sign would indicate that the event function and properties are still undefined, while a check mark would indicate the event is fully specified).

Each event is characterized by a category that defines its function inside your experimental design. To change the default category (Undefined), use the pop-up menu to select the Experiment entry. Note how the small icon in front of the event changed from a small folder to a small red psi icon specific to the Experiment event.

Tips:
Each category of events has its own small icon to depict its function.
The Undefined category with the folder icon can be used to group several experiments under one roof (eg: all experiments related to the same study).

Select the Experiment event you just created (Contrast Sensitivity), and add a new group event by clicking on the '+' folder icon again.

A new Undefined event embedded in the Experiment event is automatically revealed with its title ready to be renamed.

Tip: Click on the small arrow in front of a group event to expand or collapse the first level of its hierarchical structure (option-click to reveal the whole hierarchy). The first level can be also revealed or hidden by selecting the event and pressing the space bar.

Select the Staircase sub-category Method to automatically rename the new event New Staircase. You can then simply rename it Staircase if you wish.

Similarly to the previous step, select the Method event, add a new group event, set its category and sub-category to Procedure and Discrimination, then rename it Vertical/Horizontal Discrimination.

Now, select the Procedure event, and add a new leaf event by clicking on the file icon with the '+' symbol in the bottom toolbar. Change the sub-category and title of this leaf event to Visual Stimulus/Grating and Gabor Stimulus.

Tip: As atomic events, leaf events do not embed other events hence the absence of the small arrow in front of their descriptive mini-icon.

Your description of the experiment should now look very similar to this.

As you can see, the design follows the Method/Procedure/Stimulus paradigm depicted here which is the basis of many behavioral experiments, not just the psychophysical ones. This experimental paradigm is both conceptually simple, intuitive, and powerful enough, and constitutes a well-proved template for most experimental needs.

Tip: This hierarchical description describes the logic of the experiment both in terms of its conceptual semantics and operational execution. Most of the experiments created by Psykinematix should follow the above Method/Procedure/Stimulus hierarchical template as experimental paradigm.

We have completed the basic hierarchical structure of the experiment, so let's move on to the customization of each event.

Click on the Staircase event to select it, and click on the Inspector button (or press the ⌘-i keystroke) to inspect the properties of the Method.

If you did not select yet a sub-category for the Method event in step 3 above, then the properties page for this event appears with the Examples tab selected by default. In this case, click on the Staircase tab to select the Staircase Method and view/edit its properties.

The default settings are suitable for a standard staircase method but should be customized to better fit your experimental requirements. The mandatory changes are those associated with the dependent variable, that is the stimulus parameter that drives the threshold estimation, which is the Gabor contrast in this experiment design as illustrated below.

The name of the stimulus parameter and its initial value (in the range specified by a uniform distribution, mean ± deviation) need to be set appropriately. Change these values to match those of the figure: the parameter can be named "contrast" and its initial value set to be in the range 90 ± 10 (in %). You can also specify optionally minimum and maximum clamping values for the contrast (i.e. to restrict its values to the 0-100% range).

Click on the OK button on the properties page to validate these changes and return to the Designer panel.

Once you have returned to the Designer panel, select the Vertical/Horizontal Discrimination Procedure event, and click on the Inspector button to inspect its properties.

The properties page for the Procedure event consists of three sections:

1) A right side common to all procedures that specifies the properties to be applied to each trial,

2) A top-left section that specifies the type of procedure (Which? tab selected by default) and its properties,

3) A bottom-left section that provides more customization for some of the procedures (reaction times, pedestal, etc).

Let's customize each of these sections:

1) First, in Trial Properties change the type of inputs used by the subject to provide his/her responses: select the Keyboard device instead of the default (Mouse). The top/down arrows will be used by the subject to indicate a vertical stimulus, while the left/right arrows will indicate a horizontal stimulus (see below).

Uncheck the Fixation Mark option, so no fixation is displayed during the stimulus presentation (pre- and post-stimulus fixations may be still present). This minimizes the possibility of interference between a low contrast stimulus and the fixation.

2) If you did not select yet a sub-category for the Procedure event in step 4 above, then the procedure-specific section appears with the Which? tab selected by default. In this case, click on the Disc tab to select the Discrimination Procedure and view/edit its settings.

Make sure to specify a discrimination among 2 choices about the stimulus by setting n to 2; n also corresponds to the number of inputs as there is one input for each alternative decision (vertical or horizontal) in the Discrimination Procedure.

Enter the subject response associated with each alternative decision: select the first choice index with the stepper (1 in the above figure) and enter the keyboard keys (right_arrow, left_arrow in the figure) corresponding to the horizontal decision, followed by RETURN.

Tip: Several inputs, separated by a comma, can be specified for the same decision.

Similarly, set the up_arrow, down_arrow response keys for the second choice index corresponding to the vertical decision, followed by RETURN.

Now let's indicate explicitly the relationship between the decision and the random variable that will control the stimulus orientation. The subject is expected to provide a correct response when pressing the right or the left arrows for a horizontal stimulus (orientation of 0 deg).

To specify this:

1) select the choice input 1,
2) click on the '+' button to add an expression entry in the table,
3) in the "Correlated with Expression" column enter the name of the stimulus variable to be jugded (we will name it orientation) between brackets, and its expected value in the "= Value" column (0 deg for the horizontal choice response).

Similarly, the subject is expected to provide a correct response when pressing the up or the down arrows for a vertical stimulus (orientation of 90 deg):

1) select the choice input 2,
2) click on the '+' button to add an expression entry in the table,
3) in the "Correlated with Expression" column enter the name of the orientation variable between brackets, and its expected value in the "= Value" column (90 deg).

Click on the OK button to validate the changes and return to the Designer panel.

From the Designer panel, select the Gabor Stimulus event, and click on the Inspector button to access its properties.

If you did not select yet a sub-category for the Visual Stimulus event in step 5 above, then the properties page for this event appears with the Examples tab selected by default. In this case, click on the Grating tab to select the Grating-like Stimulus and view/edit its settings.

The properties page for the Visual Stimulus event consists of four sections:

1) A top section common to all types of visual stimulus that specifies their position, duration, and appearance,

2) A middle section that specifies the carrier properties,

3) A bottom-left section that specifies the envelope properties,

4) A real-time preview in the bottom right-hand corner that can be zoomed in and out.

Let's customize each of these sections:

1) Connect the Stimulus Contrast to the parameter used by the Staircase Method by selecting the contrast variable that appears in the contextual menu when control-clicking on the text field, as illustrated above. Make sure to select the entire content of the text field before selecting the variable in the menu so the selection completely replaces the previous content.

Tip: the contrast variable was automatically added to this contextual menu because it was declared as a dependent variable for the Staircase Method event in step 6 above.

Once selected, the variable name appears in brackets, indicating that the variable is providing a value to the stimulus parameter.

Note that the stimulus preview became blank. This is because its contrast is linked to the variable contrast whose value will be specified by the staircase method when running the experiment. When using a variable-based expression to define a stimulus parameter, the preview is generated assuming a default value of 0 for each variable.

To display a preview for a variable value other than the default one, add the desired value preceded by a colon before the closing bracket (eg: [contrast:50]). This value is used only for preview purposes and has no effect on the experimental design or during its execution.

2) To create the Gabor stimulus: select the Grating type from the Carrier pop-up menu in the middle section; select Sinusoidal modulation; and set the values for the tested spatial frequency and phase. Remember that in this lesson, contrast sensitivity is only measured for a single spatial frequency (the one you enter at this step). However in the next lesson we will extend the current design to measure contrast sensitivity for a range of spatial frequency.

Most importantly, connect the Carrier Orientation to the parameter used by the Discrimination Procedure by entering the orientation variable in brackets.

Note: the orientation variable does not appear in the contextual menu when control-clicking on the orientation text field because it has not been declared yet (see step 9 below).

Again to display a preview with a value of the carrier orientation other than the default (0), add the desired value preceded by a colon before the closing bracket (eg: [orientation:90]).

3) In the bottom-left section, select a Gaussian envelope and set the value for its sigma. Select the circular shape with an aspect-ratio of 1.

4) Note how the preview is automatically updated with your changes (use the slider to zoom the preview in and out).

We have finished with the experimental design so click on the OK button to validate the changes and return to the Designer panel.

We have almost completed the experiment design. Two things remain to be done:

1) to specify the possible values taken by the orientation variable (so far we have just specify its expected values relative to the subject's discrimination task in step 7 above).

2) to take advantage of the bit-stealing technique to improve the measurement of the contrast thresholds beyond the default 8-bit resolution [Note that this option is not available in the Student Edition of Psykinematix].

Both can be done by customizing the Experiment properties. From the Designer panel, select the Contrast Sensitivity Experiment event, and click on the Inspector button to inspect its properties.

1) On the properties page, click on the Control Settings tab to view/edit the control settings, ie. those settings that affect the experimental protocol.

2) Click on the '+' button to add an entry in the Independent Variables table.

3) Edit this entry and name its parameter orientation and specify its possible values separated by a comma: 0 and 90. Each time this variable will be used to define the stimulus orientation, its value will be randomly chosen among these 2 values. Note that there is no bracket around the variable because it is simply declared.

4) Click on the Display tab to view/edit the display settings, ie. those settings that affect the stimuli rendering on the experimental display.

5) Select the Mono 11.6 bits Bit-Stealing option in the Chromatic Mode pop-up menu. This indicates the use of the bit-stealing technique to improve the contrast resolution from 256 (8-bits) to 3310 (11.6-bits) gray levels (see the Defaults Preferences section of the documentation to learn more about it. Note that this option is not available in the Student Edition of Psykinematix).

6) Click on the OK button to validate these changes and return to the Designer panel.

To run an experiment, simply do the following:

1) Select the Contrast Sensitivity Experiment event which is at the root of your experiment design.

2) Check the validity of your design by clicking on the Check button in the button toolbar (if this button is greyed out the checking is done automatically): if correct, all the indicators in the check column turn into green check marks. If these indicators do not appear as green marks, then review your design and make sure that you have carefully followed the previous steps.

3) Toggle the experimental session between windowed or full-screen mode: the windowed mode is appropriate for testing purposes only as neither Gamma correction nor timing checks are performed during the experiment, and the session results are not saved into Psykinematix database (they will only appear as temporary data under the Plotter panel). The full-screen mode should always be used to collect data you intend to include in your study.

4) Click on the Run button to run the experiment.

Tips:
– Experiments can also be run through the Experiments menu which contains an up-to-date list of all the experiments present in the Designer panel.
– If the Check button is disabled, Auto-Checking is activated so an event status is automatically updated every time the event is modified (see related option in the Reports section of Preferences panel).

This warning message is displayed when no calibration configuration is specified for the experiment running (see the end of the Calibration Tutorial to learn how to specify a calibration configuration); however, you can still run the experiment using a default calibration by clicking on the Continue button.

Before the session starts in full-screen mode, a panel summarizing the Session Information is displayed. You can either run the session in testing mode (Test button), which does not require the specification of the subject and group, or in real mode (Start Session button) if you specify them. In testing mode, the session data will only appear as temporary data under the Plotter panel and will not be actually saved in the results database (shown under the Subjects panel).

If you have already entered subjects and groups in the Subjects panel (see the Subjects Tutorial), you can select them using the two pop-up menus provided. Their age, gender, and handedness are then shown.

Click on the Test or Start Session button.

Press ESC (escape keyboard key) to stop the session at any time.

If the experiment aborts by itself because some critical error occurred during the session, the logging panel will automatically show up with the relevant error messages. In that case, carefully review the different steps above using the indications provided by these error messages.

Important note: To save the session results in Psykinematix database for future retrieval, always make sure to:

- run the experiment in full-screen mode by toggling the display icon in the Designer bottom toolbar,
- select the subject and group in the Session Information panel,
- click on the Run Session button in the Session Information panel.

Once the session has completed normally, you are asked to press ESC to return to the Designer panel. If an error occurred during the session, a logging panel will automatically show up with relevant error and warning messages. This panel also includes a summary of the experimental conditions in terms of subject, display setup, and various other diagnostic information. If no error occurred, you can still reveal this panel by clicking the Experiment log button at the bottom on the Designer panel.

Upon termination of an experimental session, the results data can be visualized immediately from the Plotter panel:

1) Click on the Plotter icon in the toolbar to access the panel. The results for the last session appear at the top of the table.

As noted above, the results are saved in the Psykinematix database only if the session was run in real mode. In this example, the Subject (Group) column shows Testing Mode (None) (highlighted in blue) which indicates that the session has not been run in real mode and that these results will not be saved in the database after quitting Psykinematix.

2) Option-click on the small arrow in front of the session entry to expand the whole hierarchy of the results data.

3) Select one of the entries in the final level of the hierarchy to plot its attached dataset (each entry contains a different dataset).

4) You can customize the appearance of the graph by clicking the "Graph Settings" button to access the Graph Properties palette (6) or the "Data Settings" button to access the Data Analysis palette (5).

5) Some data analysis options specific to the selected dataset are available from the tabs available in the Data Analysis palette on the right side of the results table: for staircase data for example, it is possible to select whether an arithmetic or geometric mean is used, or whether troughts or/and peaks of the reversal data points are considered to estimate the displayed threshold. The threshold estimate (mean ± std) is automatically updated on the graph.

6) Numerous aspects of the graph appearance can be customized using the Graph Properties palette: here for example, a more specific title, a log scale, a minimum of 0 and a maximum value of 100 were selected for the y-axis and the legend showing the contrast threshold estimate was repositioned.

7) Control-click inside the graph to print, copy, or save it to a file.

8) Click on the Data Table button to reveal the spreadsheet containing the selected data (3) used to plot the graph. Control-click inside the spreadsheet to print or export the data. The data table shown above is the one associated with the "Vertical/Horizontal Discrimination" section of the results table.

When selecting the root object of the session entry (named in this example 0003 - Contrast Sensitivity), the data table will present a summary of the measurements, in this example the threshold estimate (mean ± std) under the Contrast tab also shown on the graph above.

See the Subjects Tutorial and the Plotter Tutorial to learn how to select, import, and plot data collected during previous Psykinematix sessions.

In this lesson, you learned the Psykinematix basics: how to create the hierarchical structure of an experiment, how to customize the events, how to use variables to connect procedural and stimulus events, and how to run a session and inspect the results.

In the next lesson, you will learn how to interleave several staircases to investigate the effect of spatial frequency on contrast thresholds (Lesson 2). You may also consider the following lessons of the Orientation Discrimination tutorial to learn how to:

- implement a sandwich paradigm with forward and feedback masking noise (Lesson 3),
- add a spatial and temporal context (Lesson 4),
- add motion & dynamics through the use of a 1st-order drifting Gabor (Lesson 5).