PTB¶

class +o_ptb.PTB(ptb_config)¶

PTB is the main class, controlling the underlying PsychToolbox and devices.

Initializing an experiment with this library normally involves the following steps:

Issue ‘restoredefaultpath’ to make sure that you work with a clean path
Add the top-level folder of this library to the Matlab path. You do not need to add all the subfolders!
Create an instance of +o_ptb.PTB_Config and set all the preferences you need.
Create an instance of this class supplying your +o_ptb.PTB_Config instance
Setup the subsystems by calling the appropriate setup methods.

IMPORTANT: Per default, your resolution is ALWAYS 1920x1080!!! If your window or screen is smaller, the content gets scaled accordingly.

Variables

win_handle (PTB window handle) – The window handle of the PTB window
win_rect (PTB Rect) – The window rect (i.e. the position and size) of the PTB window
flip_interval (float) – The amount of time between two screen refreshes
width_pixel (int) – The width of the PTB window in pixels
height_pixel (int) – The height of the PTB window in pixels
using_datapixx_video (bool) – True if a Datapixx system was found
base_path (string) – The folder of the o_ptb.
assets_path (string) – The folder of the o_ptb assets (pictures etc).

The constructor method:

static get_instance(ptb_config)¶

Return an instance of the PTB class.

If ptb_config is supplied, this methods attemps to create a new instance of +o_ptb.PTB. If such an instance has already been created, this method is going to fail.

If no parameter is supplied, this method returns the currently active +o_ptb.PTB. If none has been created earlier, it will fail.

Parameters: ptb_config (+o_ptb.PTB_Config, optional) – The configuration. Only supply if you want to create a new instance!
Returns: +o_ptb.PTB – The current or new PTB.

Methods to set up the different subsystems:

setup_screen()¶

Set up the screen for the experiment.

You need to call this method before doing any drawing on the screen or working with visual stimuli.

setup_audio()¶

Set up the audio system for the experiment.

You need to call this method before working with auditory stimuli.

setup_trigger()¶

Set up the triggering system for the experiment.

You need to call this method before working with triggers.

setup_response()¶

Set up the response system for the experiment.

You need to call this method before working with responses.

setup_tactile()¶

Set up the tactile system for the experiment.

You need to call this method before working with tactile stimuli.

setup_eyetracker()¶

Set up the eyetracker system for the experiment.

You need to call this method before working with the eyetracker.

Methods to schedule stimuli:

draw(stimulus)¶

Draw a visual stimulus.

Draw a visual stimulus to the offscreen buffer. It does not appear immediately but at the next screen flip.

Parameters: stimulus (Instance of subclass of +o_ptb.+stimuli.+visual.Base) – The stimulus to draw.

prepare_audio(stimulus, delay, hold, mix)¶

Prepare and upload an auditory stimulus.

This is the first step of using an auditory stimulus. This method will prepare the audio stimulus and upload it to the audio subsystem. This may take some processing time so it should be done when timing is not crucial. The second step would be to call schedule_audio.

Note

If you prepare two stimuli at overlapping time-intervals, the latter overwrites the earlier one.

Parameters

stimulus (Instance of subclass of +o_ptb.+stimuli.+auditory.Base) – The stimulus to prepare.
delay (float, optional) – The delay in seconds. Default = 0
hold (bool, optional) – If this is set to true, the previous stimuli will be retained. If it is set to false, the previous stimuli will be deleted. This is useful if you want to schedule multiple sounds with different delays. Please be aware that if sounds overlap, the new one wins.
mix (bool, optional) – If this is set to true, a new stimulus overlapping a previously prepared one will not overwrite the former. Instead, both streams will be mixed.

schedule_audio()¶

Schedule the prepared auditory stimuli.

This is the second step of using an auditory stimuli. This method will do the final preparations of the audio subsystem to emit the stimulus. In order to actually fire the stimulus, you need to call either play_without_flip to stimulate immediately or play_on_flip to stimulate at the next flip command.

Note

Calling this method without calling prepare_audio first results in the previously prepared stimulus being played again.

set_audio_background(background_object)¶

Set the audio background.

The sound data in background_object will be played continuously. If an auditory stimulus is prepared, it will be added to the background noise.

The background should be a signal that does not create distortions when the position of the current audio frame jumps.

The background audio will start right away.

Parameters: background_object (Instance of subclass of +o_ptb.+stimuli.+auditory.Base) – The sound object to play in the background

stop_audio_background()¶: Stop the background audio.

prune_audio(seconds)¶

Make sure that the audio stream is at most seconds long.

This method works on the audio data that has been prepared but not yet scheduled.

Parameters: seconds (float) – Maximum length of the audio stream.

prepare_trigger(value, delay, hold)¶

Prepare to fire a trigger.

This is the first step of firing a trigger. This method will upload the trigger value to the trigger subsystem. This may take some processing time so it should be done when timing is not crucial. The second step would be to call schedule_trigger

Parameters

value (int) – The trigger value to prepare.
delay (float, optional) – The delay in seconds.
hold (bool, optional) – If this is set to true, the previous triggers will be retained. If it is set to false, the previous triggers will be deleted. This is useful if you want to schedule multiple triggers with different delays. Please be aware that if triggers overlap, the new one wins.

schedule_trigger()¶

Schedule the prepared trigger.

This is the second step of firing a trigger. This method will do the final preparations of the trigger subsystem to emit the trigger. In order to actually fire the stimulus, you need to call either play_without_flip to stimulate immediately or play_on_flip to stimulate at the next flip command.

Note

Calling this method without calling prepare_trigger first results in the previously prepared trigger being fired again.

prepare_tactile(stim, delay, hold)¶

Prepare a tactile stimulus.

This is the first step of doing tactile stimulation. This method prepares the stimulus, uploads it to the stimulator and prepares the triggers. This may take some processing time so it should be done when timing is not crucial. The second step would be to call schedule_tactile

Parameters

stim (+o_ptb.+stimuli.+tactile.Base) – The stimulus to prepare.
delay (float, optional) – The delay in seconds.
hold (bool, optional) – If this is set to true, the previous stimuli will be retained. If it is set to false, the previous stimuli will be deleted. This is useful if you want to schedule multiple stimuli with different delays. Please be aware that if stimuli overlap, the new one wins.

schedule_tactile()¶

Schedule the prepared tactile stimuli.

This is the second step of doing tactile stimulation. This method will do the final preparations of the tactile subsystem to emit the stimuli. In order to actually fire the stimulus, you need to call either play_without_flip to stimulate immediately or play_on_flip to stimulate at the next flip command.

Note

Calling this method without calling prepare_trigger first results in the previously prepared trigger being fired again.

Methods to emit stimuli:

play_without_flip()¶: Play scheduled sounds and fire triggers immediately.

play_on_flip()¶

Play scheduled sounds and fire triggers at the next flip.

Please note that in order for this to work, you need to use the flip shortcut function provided by this class.

flip(varargin)¶

Issues a screen flip.

This is basically a shortcut to the PTB Screen(‘Flip’, …) command that also takes sure that stimuli scheduled with play_on_flip are fired. So, always use this one.

Parameters and return values are identical to the Screen(‘Flip’) command with the exception that you must not provide the windowPtr.

Methods to handle responses:

wait_for_keys(keys, until)¶

Wait for specified keys or buttons to be pressed.

This method uses the underlying response subsystem to wait keys or buttons being pressed by the participant. It uses the button mapping specified in +o_ptb.PTB_Config

Parameters

keys (cell array of key_ids) – A cell array of key_ids to wait for.
until (float, optional) – Timeout of the method in PTB seconds.

Returns

keys_pressed (cell array of strings) – A cell array of the keys that were pressed. Empty if no key was pressed.
timestamp (cell array of floats) – The timestamps of the key presses.

start_record_keys()¶

Starts recording button presses.

As soon as you call this method, button presses are recorded internally. After calling stop_record_keys, you can query what keys (if any) have been pressed in that interval using get_recorded_keys,

stop_record_keys()¶

Stops recording button presses.

As soon as you call this method, you can query what keys (if any) have been pressed in the interval between the call to start_record_keys and this call using get_recorded_keys.

get_recorded_keys(keys)¶

Return recorded keys.

Return keys pressed between start_record_keys and stop_record_keys

Returns

keys_pressed (cell array of strings) – A cell array of the keys that were pressed. Empty if no key was pressed.
timestamp (cell array of floats) – The timestamps of the key presses.

Methods to control the Eyetracker

eyetracker_verify_eye_positions()¶: Verify the position of the eyes for the eyetracker.

eyetracker_calibrate(out_folder)¶

Do eyetracker calibration

Parameters: out_folder (str) – Folder where to store the logs and images of the calibration.

start_eyetracker()¶: Start the eyetracker.

stop_eyetracker()¶: Stop the eyetracker

save_eyetracker_data(f_name)¶

Save the data acquired during an eyetracker measurement run.

Parameters: fname (str, optional) – Filename to save the digital eyetracker data to

Other methods:

deinit()¶

Uninitializes the system.

Closes the window and all connections to the subsystems.

is_screen_ready()¶

Query if we have a valid and open window.

Returns: bool – true if the screen is ready.

screen(command, varargin)¶

Shortcut for the PTB Screen functions.

It allows you to call all the PTB Screen function that need a windowPtr as their first parameter. Instead of providing it yourself, it gets inserted automatically. The rest of the parameters and return values is exactly the same.

screenshot(fname)¶

Takes a screenshot of the current display and save it to a file.

Parameters: fname (string) – The filename to save the screenshot to.

wait_for_stimulators()¶: Wait until the tactile stimulators are ready.

static is_lab_pc()¶

Check if the current PC is a lab stimulus PC.

Whether it is a lab PC is determined by the O_PTB_IS_LAB_PC environment variable.

Returns: bool – true if the this is a lab stimulus PC.