Presentation scripts for presenting stimuli of various sorts in complex scenarios
How Presentation works...roughlyEach event/task that Presentation executes/does for you is called a Trial1 in Presentation. Presentation presents your stimuli using what are called Stimulus Events, that may either contain a Picture Stimulus, Sound Stimulus, Video Stimulus or a Nothing Stimulus! You define how long these stimulus events must be presented, what the event-code (for log file entry) and port-code (for sending as EEG trigger) are etc. as part of the stimulus event. These Stimuli in turn can contain other stimulus objects. A Picture Stimulus might contain a Text stimulus object, bitmap stimulus object and so on. A Sound Stimulus typically contains a Wavefile stimulus object. We define Trials in the so-called Scenario Description Language part of a Presentation script. Trials will specify, among other things, the trial duration, one or more stimulus events, the associated event codes (written in the log files) and port codes (sent as triggers to EEG). You can also specify if and whether you like the trial to be terminated by a specific response, say Enter key, or if none of the responses must be recognised etc. The Trials thus defined can then be called to be presented from the so-called Presentation Control Language part2. The PCL part offers full programmatic control of the scenario at hand and helps keep code and data (which is, in our case, stimuli and dynamic changes in stimulus parameters) separate...which by the way is a very good programming practice. All trial-related parameters, picture definitions, sound stimuli definitions etc. can be changed dynamically, thus allowing multiple versions of stimulus lists use the identical code.
Naming conventionsWhen writing a Presentation script, naming your variables in a consistent manner following some sort of convention of your own is a good practice. On the one hand, this makes it easier to distinguish SDL and PCL keywords from your own variables. On the other, this helps considerably in ‘reading through’ your own script easier later. Although this method could consume a little more writing time than using ad-hoc variable names (such as those in the examples in the official documentation), you will appreciate it when you have to work with these scripts time and again, and that with considerable gaps of not working with them. It also makes your script more approachable for others. In short, user-friendly! We have followed such a convention of our own, which when followed religiously, makes things very legible, although with unusually long variable names sometimes;-) The only disadvantage of this, as you might notice soon, is that this requires considerable consistency on the part of the script-writer … which after all is worth the effort when you consider the advantages. We have followed the conventions hereunder in all Presentation scripts featured on these pages.
|T_||Trial name definition||T_Launch_New_Trial|
|E_||Stimulus Event definition||E_Launch_New_Trial|
|P_||Picture Stimulus definition||P_Comp_Question|
|S_||Sound Stimulus definition||S_Stimulus_Sentence|
|Txt_||Text stimulus object||Txt_Comp_Question|
|Bmp_||Bitmap stimulus object||Bmp_Comp_Question|
|Wav_||Wave file stimulus object||Wav_Stimulus_Sentence|
|N_||Number of... variable name||N_of_Trials|
|F_||Filename to be used in the PCL part||F_Session_List|
|D_||Stimulus Data object||D_Stimulus_Data|
|O_||Output Port object||O_Port_to_EEG|
Notes1. Notice that this could be misleading, because what we usually call as (Experimental) Trials don’t have any name in Presentation. So what we know as an Experimental Trial actually contains several Presentation Trials. Hereafter, whenever we say Trial, we mean a Presentation Trial. To mean an Experimental Trial, we always specifically say that. 2. Trials defined in the SDL part may be presented directly (i.e., without the need for the PCL part). However, this is strongly discouraged here for the following reasons: a. In the absence of a PCL part, trials defined in the SDL part will be presented in the order of their definition. b. Any and all changes in the trial parameters will necessarily need editing the script every time the change is needed. c. Changes in the order of stimuli will also require editing the script. d. If you have different versions for different (set of) participants, then every such version would require a scenario file of its own...completely redundant, but necessary when no PCL is used. Think about your typical factorial design, think about the number of participants you need, and then think about how many copies of scenarios you need if you don't have a PCL part. Frankly, you really don't need the mess. e. There is very little, if any, programmatic control in the absence of a PCL part. No conditionals, no loops (with different stimuli every time), and no oversight. Therefore, even the simplest of scenarios featured on these pages will contain a full-fledged PCL part. And there's something called templates that are useful when everything needs to happen solely from the SDL part. We don't even talk about it here...for there's no Presentation 'script' without a PCL part in our universe;-)
Presenting Text StimuliText stimuli are perhaps one of the most common type of stimuli needed in experimental scenarios. They can be presented as part of paradigms ranging from single word presentations to those involving complex interactions with other type of stimuli. Scenarios for paradigms that are purely text-based are presented on this page. For scenarios involving text stimuli in interaction with other type of stimuli, see the other tabs above.
- Script to present sentences in a self-paced manner for left-to-right languages.
- Script to present sentences in a self-paced manner for right-to-left languages.
- Script to present full poems in a self-paced manner for left-to-right languages.
- Script to present a single tone SAT task. An example in which our convention of not using more than one stimulus event in a given Presentation trial was wittingly not followed in the interest of efficient timing of the experimental scenario.
- Script to present a multiple tone SAT task. An example in which our convention of not using more than one stimulus event in a given Presentation trial was wittingly not followed in the interest of efficient timing of the experimental scenario.
- Script to present a lexical decision task.
Implicit Association Task
- Script to present an implicit association task
Presenting pre-formatted text pages
- Script to present short stories as pre-formatted text pages in a virtual book format with a read-aloud production task.
- Script to present poems as pre-formatted text with a read-aloud production task and ratings.
Rapid Serial Visual Presentation
- Script to present sentences word by word on screen. Different triggering scheme for critical versus filler stimuli. With comprehension task.
- Script to present sentences word by word on screen with a text context sentence preceding each stimulus. With comprehension task.
- Script featuring a masked priming paradigm. An example in which our convention of not using more than one stimulus event in a given Presentation trial was wittingly not followed in the interest of efficient timing of the experimental scenario.
Presenting Audio StimuliOn this page, scenarios involving auditory stimuli are presented, which are of a passive nature in that there is very little participant interaction other than button-click responses. For scenarios involving auditory stimuli as part of a more complex design, such as those that feature an interaction of auditory stimuli with other stimuli, involve audio stimuli embedded into a (dummy) video, or those that require active participant interaction using an interface (or, in some cases, all of these combined), see the Video and Interactive UI tabs above.
Scenarios based on stimulus pairs
- Script to present pairs of musical stimuli to let participants rate whether the two stimuli are same or different and provide their confidence level in their rating.
- Script to present pairs of musical stimuli in a discrimination task to let participants rate whether the two stimuli are similar or different. The musical pairs are tethered to participants' responses in such a way that the pairs feature a subtler or clearer difference in a stepwise fashion based on the previous response of the participant to test the limit of categorical discrimination.
Event-related design scenarios
- Script to present auditory stimuli followed by a picture-matching task.
- Script to present auditory stimuli with preceding auditory context sentences, followed by a judgement task and a probe task.
- Script to present auditory stimuli with a preceding auditory context question and a text comprehension question following each trial.
- Script to present auditory stimuli in an event-related design with a 4-level acceptability judgement.
- Script to present auditory stimuli in an event-related design. Point of interest in this script: Auditory cues are integrated as part of the script: they are read dynamically online for each stimulus and sent in-situ when the sentence is still being played.
Presenting Video StimuliScenarios involving video stimuli are useful for presenting videos, of course. But often, Presentation video trials can be very handy to achieve a more fine-grained audio stimulus control based on user interation. A possible scenario is when the audio needs to stop when the user clicks a button and some other actions should take place and clicking the button a second time, the audio must play from where it stopped. Since auditory stimuli in Presentation can either be played in full (stimuli_length) or a specified duration, but not some arbitrary dynamic value from which to restart the audio at a later point. This is where video trials in Presentation lend themselves very useful. Video stimuli are played based frames, and therefore Presentation offers the possibility to stop and restart a video stimulus at any frame within the duration of the video. To use this feature, we could embed the auditory stimulus of interest in a dummy video (say, a blank screen, or some other symbol that is not dynamic on screen), such that the audio stimulus can be controlled using the features Presentation offers for video stimuli.
Scenarios with simple video stimuli
- Script to present a cover story as video between each block of auditory stimuli to engage children to get interested to perform the task attentively.
- Script similar to the one above ... here for the sake of completeness.
Scenarios with auditory stimuli embedded into a (dummy) video stimulus
- Script to present auditory stimuli that should stop and restart from where they stopped based on a user response (key press). Depending on the position in the scenario, radio button ratings and text input possibilities must be presented, after which the audio should resume from the point where it stopped. To accomplish this, the auditory stimuli in this experiment are embedded in a dummy video (the duration of which will be matched to be identical to the auditory stimulus of interest), and the start-stop-restart procedure is achieved using Presentation's video-related methods.
Presenting a mouse-enabled or touch-enabled User InterfaceSome behavioural experiments may not necessarily require timing with millisecond precision, but instead a fully dynamic interface with which the user (participant) can interact as though they are using a tablet PC or a web service. Examples include questionnaires of various types. Further, a scenario may require the participant to key-in text as part of the experiment. Except for keyboard text input and live mouse pointer, other types of UI features such as radio buttons, menu boxes etc. have to be constructed from scratch using basic picture part elements that Presentation offers. A sort of side-effect of such features is that, logging may not be automatic, and may require that it be performed as part of the code to log certain kind of user responses. Care must be taken with designing and testing such tailor-made features in order to avoid crashes during deployment, for errors could be quite intractable and take time to solve. The following is a sample list of such scenarios that are well-tested and deployed in our labs. The UI modules required for these scripts are maintained separately at https://doi.org/10.5281/zenodo.4032981.
- Script to present the BFI questionnaire and get radio button ratings
- Script to present the RSS questionnaire and get radio button ratings
- Script to present the NEO questionnaire page by page and get radio button ratings
- Script to present the MBDF questionnaire and get radio button ratings
UI scenario with auditory stimuli and radio button ratings
- Script to present auditory stimuli and get participants to rate them on several scales.
- Script to present auditory stimuli and get participant to answer a couple of rating questions and perform a memory task.
UI touch scenario with auditory stimuli and menu box choices
- Script to present an interactive user interface on a tablet PC to play musical stimuli to participants and get them to categorise these based on the primary emotion that the stimuli express.
UI scenario with auditory stimuli and valence-arousal ratings
- Script to present a user interface with mouse interaction to play musical stimuli to participants and get them to provide valence-arousal ratings. (The scenario in its working form uses radio buttons, but an option to switch to a 2D canvas is tested ready to use in the code).
Complex UI scenarios involving keyboard text input among other things
- Script to present description texts, auditory stimuli, radio button ratings, yes-no questions, keyboard text input ... all in one, and a final questionnaire.
- Script to present description texts, auditory stimuli, radio button ratings, yes-no questions, keyboard text input ... a slightly simpler version of the above.
- Script to present a user interface with mouse interaction to present short snippets from literary texts as pre-formatted text pages in a virtual book format with a rating task with radio-buttons and keyboard text input.
- Recommended audio mixer settings .
⤷ For studies that require high audio start time accuracy (low latency; ~ 1ms ), such as EEG studies: use Presentation Mixer Exclusive mode
⤷ For studies that require high audio start time accuracy (low latency; ~ 1ms), with video+audio stimuli: use Presentation Mixer Shared mode
⤷ If latency is not very important (20-50ms): use DirectX mode (... everything workds, albeit at the expense of latency)
Any and all scripts available on these pages or snippets thereof can be freely copied, reused, redistributed and modified, provided it is exclusively for non-commercial scientific research purposes. Unless otherwise explicitly mentioned in the header block, none of the scripts or snippets provided on these pages involve copyrighted material from or intellectual property of other unacknowledged sources.
Presentation is a registered trademark, owned by Neurobehavioral Systems, Inc., CA, USA.
Whilst the scripts and code snippets provided here are intended to be useful in the broader pursuit of science, they are provided 'as is', with no warranty of any sort, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the author(s) or the Institute be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the scripts provided on these pages or the use or other dealings in the scripts. Comments, criticisms and suggestions for improvements are always welcome. Please get in touch with Dr. R. Muralikrishnan in this regard. Copyleft (ↄ) R. Muralikrishnan (only for the scripts and code snippets on these pages).