CFS MATLAB toolbox: An experiment builder for continuous flash suppression (CFS) task
CFS toolbox is an open-source collection of MATLAB functions that utilizes PsychToolbox-3 (PTB-3). It is designed to allow a researcher to create and run continuous flash suppression experiments using a variety of experimental parameters (i.e., stimulus types and locations, noise characteristics, and experiment window settings). In a CFS experiment, one of the eyes at a time is presented with a dynamically changing noise pattern, while the other eye is concurrently presented with a static target stimulus, such as a Gabor patch. Due to the strong interocular suppression created by the dominant noise pattern mask, the target stimulus is rendered invisible for an extended duration. Very little knowledge of MATLAB is required for using the toolbox; experiments are generated by modifying csv files with the required parameters, and result data are output to text files for further analysis. The open-source code is available on the project page under a Creative Commons License (http://www.mikkonuutinen.arkku.net/CFS_toolbox/ and https://bitbucket.org/mikkonuutinen/cfs_toolbox).
KeywordsImage rating Image quality MATLAB Computer software
Continuous flash suppression (CFS) (Tsuchiya & Koch 2005) is an experimental method that enables the investigation of visual processing outside conscious perception. The method can be considered as an evolved form of the binocular rivalry paradigm. In this paradigm, two dissimilar stimuli are shown to the two eyes of an observer, causing that the observer’s conscious percept alternates between the competing stimuli. While traditional binocular rivalry involves two roughly equally strong stimuli, one presented to each eye, CFS involves a more unbalanced design. In CFS a series of high-contrast masks (noise patterns) are flashed to one eye, typically at a rate around 10 Hz, to temporally prevent the conscious perception of a stimulus shown to the other eye. Due to the strong interocular suppression that the dynamically changing noise pattern creates, the target stimulus (i.e., a Gabor patch) is rendered invisible for an extended duration. For instance, contrast thresholds may increase up to over tenfold as compared to thresholds during binocular rivalry (Tsuchiya & Koch, 2005; Tsuchiya, Koch, Gilroy, & Blake, 2006). Furthermore, as the transition from suppression to dominance stage can be more precisely defined under CFS than binocular rivalry, CFS reduces reporting variance that is a common concern in binocular rivalry designs. One typical approach to determine the transition during CFS is to measure the time needed for the detection of targets presented to the suppressed eye (i.e., breaking-CFS; Jiang, Costello, & He, 2007).
Because CFS provides a means to control the rivalry alteration during dichoptic viewing, it is a great tool for studying visual targets’ ability to overcome suppression; that is, to be detected. For example, research has shown that target detectability during CFS strongly depends on low-level visual features, such as the contrast (Tsuchiya et al. 2006; Yang & Blake 2012), spatial frequency, and orientation of the stimulus (Yang & Blake 2012). Some scholars have claimed that even higher-order cognitive factors, such as familiarity or emotional content, may affect the speed with which the suppressed targets break into awareness (Jiang et al. 2007; Yang & Yeh 2011). However, it should be mentioned that recent findings show contradictory results (Moors, Wagemans, van Ee, & de Wit, 2016c; Moors, Wagemans, & de Wit, 2016a; Gelbard-Sagiv, Faivre, Mudrik, & Koch, 2016; Gayet, Van der Stigchel, & Paffen, 2014).
As far as we know, no prior scholars have published easy-to-use software that enables building and executing CFS experiments with different parameters and stimuli. Most researchers have used MATLAB (Tsuchiya et al., 2006; Yang, & Blake, 2012; Hesselmann, Darcy, Ludwig, & Sterzer, 2016; Zhu, Drewes, Melcher, 2016; Gelbard-Sagiv et al., 2016; Hong, 2015) or Python (Moors, Wagemans, van Ee, & de Wit, 2016b, (Moors et al. 2016c)) environments and Psychtoolbox-3 (PTB-3) (Brainard 1997; Kleiner et al. 2007; Pelli 1997) or PsychoPy packages (Peirce, 2006, 2009) for preparing and conducting CFS experiments. A few scholars (Stein, Thoma, & Sterzer, 2015) have also used Cogent 2000 toolbox.1 Furthermore, software2 , 3 for creating CFS masks are available and these can be utilized in developing CFS-related software further. However, no links or repositories for a ready-to-use software has been previously published.
Because preparing a new CFS experiment from scratch is not a trivial task, and because programming is not necessarily the primary skill of scholars in this research area, we believe that a publicly available, easily modifiable, and versatile CFS experiment builder would be highly valuable. With the present off-the-shelf CFS toolbox, researchers are able to build CFS environments with various parameters and stimuli, and execute experiments without the need of software design and implementation.
The present article is an introduction to CFS toolbox, a platform that we developed for building and conducting continuous flash suppression experiments. The toolbox is not restricted to the specific types of stimuli or experimental settings. Instead, the user can modify the types, sizes, locations, and timings of visual stimuli and employ different noise patterns as CFS masks. The present version of the toolbox supports research designs that utilize accuracy and time-to-detection as the dependent measures of observers’ performance (cf. breaking-CFS) (Jiang et al. 2007). Furthermore, the toolbox enables the utilization of auditory stimuli. Because all settings and experimental phases are built through csv files, CFS toolbox provides tools for forming continuous flash suppression experiments without the need for programming. The toolbox source code and setup manual are available from the CFS toolbox project page (http://www.mikkonuutinen.arkku.net/CFS_toolbox/) and Bitbucket repository (https://bitbucket.org/mikkonuutinen/cfs_toolbox).
Software and hardware requirements
CFS toolbox requires the installation of MATLAB or GNU/Octave and PTB-3 (Brainard 1997; Kleiner et al. 2007; Pelli 1997). PTB-3 is a set of functions for experimental psychology research that runs on multiple platforms (Windows, Mac, Linux) and that makes the presentation of accurately controlled visual and auditory stimuli easy.
CFS toolbox has been tested under Windows 7 with MATLAB R2014a and Linux Ubuntu 15.04 with GNU/Octave 4.0. The toolbox versions for both environments are available from the project page. CFS toolbox draws and plays visual and auditory stimuli using the functions of Screen4 and PsychPortAudio5 in PTB-3. Screen is a function for the precise control of video display. PsychPortAudio contains a set of parameters for working with sounds. The functionality requires a suitable graphic and audio cards and computer. It is recommended that the user refers to the PTB-3 documentation6 for up-to-date details.
In our laboratory setup, visual stimuli are viewed through a mirror stereoscope that presents the stimuli in the right half of the display exclusively to the right eye and the stimuli in the left half of the display exclusively to the left eye (see Fig. 1). Some scholars (Hesselmann et al. 2016; Moors et al. 2016b) have used a setup in which two displays that are set opposite to each other, project stimulus to the left and right eye respectively via two mirrors. More details of our mirror stereoscope setup can be found from the toolbox project page.
Stimulus parameters file
The stimulus parameters define the location and size of the experiment window and the options for all elements of the experiment. All elements, such as border frames, noise pattern, and visual target, are drawn inside the experiment window. That is, the coordinate space of the experiment window is used for defining the locations and sizes of the elements. The location and size of the experiment window are defined using the coordinate space of the display device.
Table 1 lists the parameters of stimulus parameters file that can be changed in order to modify the experiment setup. For example, the experiment window’s location and size are set by the parameter #2a. The values of parameter #2a are the coordinates for the left-up (x1,y1) and right-down (x2,y2) corners of the experiment window. It is recommended that the user sets the coordinates to fulfill the whole screen area of display. In this way, distracting light sources from the borders of display screen can be minimized.
The coordinate options for visual targets and the coordinate values for noise patterns and border frames are set by the parameters #3c, #4i, and #5a, respectively. CFS toolbox enables the user to set eight different options for a visual target stimulus. For instance, the targets can be displayed in the four corners of the two frames (eight options), or up or down in one frame only (two options). The principle is that the eight coordinate options are recorded in stimulus parameters file from which the trial specific values are then selected for each trial according to trial parameters file.
The variables of the stimulus parameters file
Number of warmup trials
No training session before actual test \(\rightarrow \) set 0; or set 1 − n warmup trials
EW location and size
Left-up corner (x1,y1) and right-down corner (x2,y2) coordinates
EW background intensity
Gray value (0–255)
Fixation cross color
RGB values (0–255) [R G B]
Fixation cross disparity
The distance (in pixels) between the left and right fixation crosses
Noise and info image locations and sizes
Coordinate values on the experiment window
Border frames locations and sizes
Coordinate values on the experiment window
Refresh rate of visual target
Waiting time for visual target update (s)
Fade rate of visual target
The intensity amount of visual target strengthen on every update (0–1)
Visual target locations and sizes
Visual target locations on the experiment window (eight options: S1–S8)
Grayscale, pepper, color, dead leaves disk, or dead leaves square
Dead leaves sigmaa
If \(sigma \rightarrow 0\) elements are uniform; s i g m a = 3 means scale invariant image
Noise temporal frequency
How many noise images are presented per second
Number of different noise images presented
Noise intensity rangeb
The intensity range from which noise blocks are randomly selected (0–255)
Noise block sizeb
The block size of noise image
Noise start timing
The delay between noise and visual target (i.e., 2 s + random interval)
Random additive delay for noise start interval (i.e., 0–2 s – > set 2)
Random trial order
1 = yes, 0 = no; randomizing the trial order defined in the trial parameters file
Audio stimulus timing
Audio stimulus duration relative to visual stimulus (six options: A1–A6)
Timeout of trial without interaction (s)
Disable audio stimuli
1 = yes, 0 = no; If disabled, only visual stimuli are used in the experiment
1 = Up, 2 = Down, 3 = Left, 4 = Right; Two response keys can be selected
Time delay after the response keys are active after visual target onset
The border frames are used for framing the left and right active area of the experiment window; that is, the areas for the left eye and for the right eye. The border frame image (‘border.png’) is read from the director ‘/CFS/Borders_and_info’. The type of border frames can be changed by changing the image file from the director while preserving the naming of that file. Different noise types and noise presentation parameters are defined in more detail in Section “Noise”.
After the user has set or changed the coordinate values of visual target, noise, or border frames, it is recommended to run the function “test_settings.m”. The function draws a mock-up of the experiment window that can be used for checking that all experimental elements are correctly located.
A new property of CFS toolbox, compared to many previous CFS research settings, is the possibility to include timed audio stimulus for experimentation; an audio stimulus can be displayed before, at the same time, or after the visual target onset. We see that the possibility to utilize audio stimuli can create new CFS research branches. For example, audio can be utilized in triggering some novel multimodal effects. The timing options for audio stimulus are set by the parameter #6. The timing of visual and audio stimuli is defined in more detail in Section “Stimulus timing”.
Trial parameters file
Each row of trial parameters file defines the presentation of visual and auditory stimuli for one trial. The number of rows defines the number of trials. That is, if 20 rows have been filled, then the experiment will run 20 trials. The order of trials is randomized for each observer by the parameter #5 of stimulus parameters file.
The row-specific values of the trial parameters file: the types of visual (1) and audio (3) targets, the location of visual target (2) and the timing of audio target (4)
Visual stimulus type
Select visual stimulus file (1 = “visual_stimulus_1.png”, 2 = “visual_stimulus_2.png”)
Visual stimulus location
1 = S1, 2 = S2, 3 = S3, 4 = S4, 5 = S5, 6 = S6, 7 = S7, 8 = S8 (see stimulus parameter #3c)
Audio stimulus type
Select audio file (1 = “auditory_stimulus_1.wav”, 2 = “auditory_stimulus_2.wav”)
Audio stimulus timing
1 = A1, 2 = A2, 3 = A3, 4 = A4, 5 = A5, 6 = A6 (see stimulus parameter #6)
In this version of the toolbox, there is an option to use two different visual target types in experimentation. The toolbox reads the visual targets from the director ‘/CFS/visual_stimuli’. The value 1 of the parameter #2 means that the visual target is the image file named as ‘visual_stimulus_1.png’, and the value 2 means that the target is the image file ‘visual_stimulus_2.png’. Visual target images can be changed just by changing the image files from the director while preserving the naming of images.
Audio stimulus timing and type are set by the parameters #3 and #4. The timing of the audio stimulus in each trial relative to the visual target is set by integer values from 1 to 4. Actual timing values for audio stimulus relative to visual targets are coded in the parameter #6 of stimulus parameters file. For example, value 1 can be coded to mean that the audio stimulus is presented 0.5 s before the visual target, value 2 can mean that audio and visual targets are presented at the same time, and so on. The timing principle of audio and visual targets is explained in more detail in section “Stimulus timing”.
The audio stimulus type for a trial is set by the parameter #4. In this version of the toolbox, there is an option to use two different audio stimulus types in experimentation. Audio stimulus files are read from the director ‘/CFS/audio_stimuli’. The value 1 of the parameter #4 means that the audio file named as ‘auditory_stimulus_1.wav’ is selected for the trial, and value 2 means that ‘auditory_stimulus_2.wav’ is selected. As with the visual target files, audio stimuli can be changed by changing the audio files from the director while preserving naming of the files.
The length of the interval of t2 − t4 is controlled by the parameters of noise start timing (#4g) and random interval (#4h). The noise start timing is a constant delay time for all trials of the experiment. That is, what is the minimum time before visual target forming starts after the noise onset. The random interval is a random additive delay added to the noise start timing. For example, if the value of random interval is 1, then additive delay is something between 0 and 1 s, and the total delay between the noise and visual target consists of the constant noise start timing plus the random delay of 0–1 s that varies from trial to trial during the experiment.
The interval of t4 − t5 is the duration of a visual target reaching its full contrast state. CFS toolbox enables ramping up the targets so that the contrast increases slowly from low to full. This feature is used to avoid the abrupt onset of target stimuli. The duration of transition from low to full contrast is controlled by the parameters of stimulus refresh rate (#3a) and stimulus fade rate (#3b). The stimulus refresh rate defines how many times the stimulus contrast is updated per second. The stimulus fade rate defines how much the contrast increases at each update. For example, if the stimulus refresh rate, r r = 75f r a m e s/s e c o n d s, and the stimulus fade rate, f r = 0.0133, then the interval t4 − t5 is 1.0 s. That is, it takes 1 s to form a full-contrast visual target after the target triggering. If f r = 1, then the full contrast state is reached immediately after the triggering.
In the example trial presented in Fig. 6, the audio stimulus onset takes place at the time point of t3. That is, the audio file is played before the visual target onset with a duration defined as t3 − t4. For each trial, the duration of t3 − t4 is defined by the parameter #4 of trial parameters file. The principle is that CFS toolbox enables displaying audio files at different time points (as compared to the visual target) for different trials of the experiment.
A trial ends when the observer presses the arrow key in the keyboard or when the value given for the time out is reached. The value of the time out is set by the parameter #7 in stimulus parameters file. Two arrow keys (up, down, left or right) that observers use to respond to the stimuli should be set by the parameter #9. The next trial starts when the observer presses the space key.
In addition to noise type and noise type-specific parameters, the number of different noise images (n) and presentation frequency (f) should be defined. The dynamically changing noise mask (video stream) is produced by preparing n random noise images that are streamed in consecutive order. For example, when n = 60 and f = 30, CFS toolbox displays a sequence of 60 noise images with a frequency of 30 images per second. That is, the same noise video sequence is re-played every 2 s. The value n is set by the parameter #4d and f by the parameter #4c of stimulus parameters file.
After all trials defined in the trial parameters file have been run, an experiment-specific result file is saved to the result director (‘CFS/Results’). Result files are named as ‘seed-ID-date-dd.mm.yyyy-hh.mm.ss.txt’, in which ‘ID’ is the participant’s identification number, ‘dd.mm.yyyy’ is the date, and ‘hh.mm.ss’ is the exact time when the experiment was finished.
The audio file of the first trial was ‘auditory_stimulus _1.wav’ (column: audio_file). In this trial, the audio was initiated at the same time with the visual target (column: audio_start = 0.0000). The answer column shows that the observer pressed the “DOWN” button of the keyboard. The response time was 0.5798 second (column: ansdur). The response time is the duration from the visual stimulus onset to the response button press. It thus tells how long did it take for the observer to detect the visual target.
The function displays the location and size of the experiment window and all elements inside it (Fig. 4). This enables the user to ensure that all targets are displayed correctly (e.g., in the correct locations on the monitor relative to the mirror stereoscope). It is recommended to run this function before running a new experiment.
Once the experiment has been specified in the parameter files, it can be run from MATLAB command window by calling the function run_experiment. This function reads the parameter files and runs the experiment. The experiment window and visual and audio targets are presented using the function draw_stimulus. The noise mask is created using the function create_noise_basic (grayscale, pepper or color noise) or create_noise_dead_leaves (dead leaves noise).
After the experiment is finished, result data are output to a text file and saved to the folder “Results” using the participant’s ID code and the time stamp of the experiment in the file name.
To demonstrate an experiment conducted with CFS toolbox, we present a simple experiment in which the effects of visual target position (above or below the fixation cross) and audio tone pitch (high or low pitch) were investigated. Subjects responded to visual target occurrence (i.e., arrow-shaped square) based on the target’s pointing direction (i.e., left or right). Performance was defined as the time required for target detection (reaction time, RT) according to the b-CFS procedure (Jiang et al. 2007).
The subjects were 20 students from the University of Helsinki (five males; mean age = 24.8 ± 3.4 years). All subjects were right-handed and 11 of them were right-eye dominant. All subjects reported normal hearing and normal or corrected-to-normal vision, and wore normal corrective lenses during the experiment. The subjects were screened for normal stereopsis, heterophoria, and near distance visual acuity at three contrast levels (100%, 10%, and 2.5%).
Visual target and noise mask, both surrounded by a black-and-white border frame, were presented on the experiment window 13∘ apart from each other. The arrow-shaped visual targets appeared directly above or below the fixation cross at 2.2∘ eccentricity. The visual targets were ramped up to a target contrast (C M i c h e l s o n = 0.10) during the initial 400 ms, and were then kept constant until the end of the trial. Each target was accompanied with a high or low pitch tone.
Subjects were instructed to respond to target occurrence based on the arrow’s pointing direction (i.e., left vs. right). They were asked to respond immediately upon detecting the target by pressing the corresponding key (i.e., left or right arrow) on the keyboard with the right hand. The experiment consisted a total of 128 trials. Target location and pointing direction were counterbalanced within the stimuli. High and low pitch tones appeared equally often with each of these combinations.
Only correct response trials (98.8%) were included in the RT analysis. Outliers (> 3SD) were identified and removed from the dataset. In total, 3.28% of the original data was excluded. The dataset was log-transformed before statistical testing. Descriptive statistics are based on the geometric means of RT distribution.
CFS toolbox is currently in use in research laboratories at the University of Helsinki. It has proven to be useful in the experimental psychology studies of visual attention and cognition. The easy handling of experiment building and launching through the parameter files provide researchers a set of easy-to-use tools for forming complex continuous flash suppression experiments.
CFS toolbox is being actively maintained and developed. New functionalities (e.g., stimulus generator with the parameters of frequency, direction and phase) and CFS masks (e.g., pink noise images; see Gayet, Paffen, & der Stigchel, 2013; Gayet et al., 2014), an option to present stimuli with anaglyph glasses (instead of mirror stereoscope), and a graphical user interface are expected in future versions. In addition, support for Mac operating system and Python implementation will be considered.
Furthermore, researchers are welcome to add functionalities to the code themselves. We hope that the research community finds this toolbox a useful tool for their laboratories.