expyriment.control

The control package of expyriment.

Modules

Classes

Functions

expyriment.control.end(goodbye_text=None, goodbye_delay=None, confirmation=False, fast_quit=None, system_exit=False, pre_quit_function=None)

End expyriment.

Parameters:
goodbye_textstr, optional

text to present on the screen when quitting

goodbye_delayint, optional

period to show the goodbye_text

confirmationbool, optional

ask for confirmation (default = False)

fast_quitbool, optional

quit faster by hiding the screen before actually quitting (default = None)

system_exitbool, optional

call Python’s sys.exit() method when ending expyriment (default = False)

pre_quit_functionfunction or list of functions, optional

function(s) to be called before quitting Pygame

Returns:
outbool

True if Expyriment (incl. Pygame) has been quit.

expyriment.control.get_audiosystem_is_playing(channel=None)

Check if the audiosystem is busy playing sounds.

Parameters:
channelpygame.mixer.Channel, optional

specific channel to check

Returns:
outbool

Returns True if any sound is playing.

expyriment.control.get_defaults(search_str='', as_string=False)

Return a dictionary with all default values in the current Expyriment environment. The keys represent the variables names.

Parameters:
search_strstr, optional

search for a specific expression

as_stringbool, optional

print as string instead of dict

expyriment.control.initialise(experiment=None)

Initialise an experiment.

This initialises an experiment defined by ‘experiment’ as well as the underlying expyriment system. If ‘experiment’ is None, a new Experiment object will be created and returned. Furthermore, a screen, a clock, a keyboard and an event file are created and added to the experiment. The initialisation screen is shown for a short delay to ensure that Python is fully initialised and time accurate. Afterwards, “Preparing experiment…” is presented on the screen.

After the experiment has been initialised, the following additional properties are available:

  • experiment.screen – the current screen

  • experiment.clock – the main clock

  • experiment.keyboard – the main keyboard

  • experiment.mouse – the main mouse

  • experiment.event – the main event file

Parameters:
experimentdesign.Experiment, optional

the experiment to initialise

Returns:
expdesign.Experiment

initialised experiment

expyriment.control.initialize(experiment=None)

Initialise an experiment.

This initialises an experiment defined by ‘experiment’ as well as the underlying expyriment system. If ‘experiment’ is None, a new Experiment object will be created and returned. Furthermore, a screen, a clock, a keyboard and an event file are created and added to the experiment. The initialisation screen is shown for a short delay to ensure that Python is fully initialised and time accurate. Afterwards, “Preparing experiment…” is presented on the screen.

After the experiment has been initialised, the following additional properties are available:

  • experiment.screen – the current screen

  • experiment.clock – the main clock

  • experiment.keyboard – the main keyboard

  • experiment.mouse – the main mouse

  • experiment.event – the main event file

Parameters:
experimentdesign.Experiment, optional

the experiment to initialise

Returns:
expdesign.Experiment

initialised experiment

expyriment.control.pause(text='Paused', key=13)

Pause a running experiment.

This will show a pause screen and waits for a key (default=ENTER) to be pressed to continue.

Parameters:
textstr, optional

the text to be shown at the pause screen (default=”Paused”)

keyint, optional

the key to be pressed for continuing (default=misc.constants.K_RETURN)

expyriment.control.register_wait_callback_function(function, exp=None)

Register a wait callback function.

The registered wait callback function will be repetitively executed in all Expyriment wait and event loops that wait for an external input. That is, they are executed by the following functions (at least once!):

  • control.wait_end_audiosystem

  • misc.Clock.wait

  • misc.Clock.wait_seconds

  • misc.Clock.wait_minutes

  • io.Keyboard.wait

  • io.Keyboard.wait_char

  • io.Mouse.wait_press

  • io.SerialPort.read_line

  • io.StreamingButtonBox.wait

  • io.EventButtonBox.wait

  • io.GamePad.wait_press

  • io.TriggerInput.wait

  • io.TextInput.get

  • io.TouchScreenButtonBox.wait

  • io.extras.CedrusResponseDevice.wait

  • stimuli.Video.wait_frame

  • stimuli.Video.wait_end

Parameters:
functionfunction

the wait function

expdesign.Experiment, optional

specific experiment for which to register wait function

See also

unregister_wait_callback_function

Notes

CAUTION! If wait callback function takes longer than 1 ms to process, Expyriment timing will be affected!

expyriment.control.run_test_suite(item=None)

Run the Expyriment test suite.

Parameters:
itemint, optional

the item to run; runs all tests if None (default=None)

expyriment.control.set_develop_mode(on=True, intensive_logging=False, skip_wait_methods=False)

Set defaults for a more convenient develop mode.

Parameters:
onbool, optional

set develop_mode on (True) or off (False)

intensive_loggingbool, optional

True sets expyriment.io.defaults.event_logging=2 (default = False)

skip_wait_methodsbool, optional

If True, all wait functions in the experiment (i.e. all wait functions in expyriment.io and the clock) will be omitted (default = False)

Notes

The function set the following global variables

>>> expyriment.control.defaults.initialise_delay = 0
>>> expyriment.control.defaults.window_mode = True
>>> expyriment.control.defaults.fast_quit = True
>>> expyriment.control.defaults.auto_create_subject_id = True
>>> expyriment.io.defaults.outputfile_time_stamp = False
expyriment.control.start(auto_create_subject_id=None, subject_id=None, skip_ready_screen=False)

Start an experiment.

This starts the currently initialised experiment and asks for the subject number. When the subject number is entered and confirmed by ENTER, a data file is created. Eventually, “Ready” will be shown on the screen and the method waits for ENTER to be pressed.

After the experiment has been started, the following additional properties are available:

  • experiment.subject – the current subject id

  • experiment.data – the main data file

Parameters:
auto_create_subject_idbool, optional

if True new subject id will be created automatically

subject_idinteger, optional

start with a specific subject_id; no subject id input mask will be presented; subject_id must be an integer; setting this parameter overrules auto_create_subject_id

skip_ready_screenbool, optional

if True ready screen will be skipped (default=False)

Returns:
expdesign.Experiment

The started experiment will be returned.

expyriment.control.start_audiosystem()

Start the audio system.

Notes

The audiosystem is automatically started when initializing an Experiment!

expyriment.control.stop_audiosystem()

Stop the audio system.

expyriment.control.unregister_wait_callback_function(exp=None)

Unregister all wait callback functions.

Parameters:
expdesign.Experiment, optional

specific experiment for which to unregister the wait callback function

See also

register_wait_callback_function
expyriment.control.wait_end_audiosystem(channel=None, callback_function=None, process_control_events=True)

Wait until audiosystem has ended playing sounds.

Blocks until the audiosystem is not busy anymore and only returns then.

Parameters:
channelpygame.mixer.Channel, optional

specific channel to wait for end of playing

callback_functionfunction, optional

function to repeatedly execute during waiting loop

process_control_eventsbool, optional

process io.Keyboard.process_control_keys() and io.Mouse.process_quit_event() (default = True)

Notes

This will also by default process control events (quit and pause). Thus, keyboard events will be cleared from the cue and cannot be received by a Keyboard().check() anymore!