expyriment.control¶

The control package of expyriment.

Modules¶

expyriment.control.defaults

Classes¶

expyriment.control.CallbackQuitEvent

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, optional: function 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.initialize(experiment=None)¶

Initialize an experiment.

This initializes 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 a event file are created and added to the experiment. The initialization screen is shown for a short delay to ensure that Python is fully initialized and time accurate. Afterwards, “Preparing experiment…” is presented on the screen.

After experiment initialize 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 initialize
Returns:	expdesign.Experiment initialized experiment

expyriment.control.pause()¶

Pause a running experiment.

This will show a pause screen and waits for ENTER to be pressed to continue.

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()¶: Run the Expyriment test suite.

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.initialize_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(experiment=None, auto_create_subject_id=None, subject_id=None, skip_ready_screen=False)¶

Start an experiment.

This starts an experiment defined by ‘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 experiment start the following additional properties are available:

experiment.subject – the current subject id
experiment.data – the main data file

Parameters:

experimentdesign.Experiment, optional (DEPRECATED): don’t use this parameter, it only exists to keep backward compatibility
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