expyriment.design.Experiment¶

class expyriment.design.Experiment(name=None, foreground_colour=None, background_colour=None, text_font=None, text_size=None, filename_suffix=None)¶

A class implementing a basic experiment.

__init__(name=None, foreground_colour=None, background_colour=None, text_font=None, text_size=None, filename_suffix=None)¶

Create an experiment.

Parameters:	namestr, optional name of the experiment foreground_colour(int, int, int), optional background_colour(int,int,int), optional text_fontstr, optional text_sizeint, optional filename_suffixstr, optional additional suffix that will be added to the main event and data filename

add_block(block, copies=1)¶

Add a block to the experiment.

Parameters:	blockdesign.Block block to add copiesint, optional number of copies to add (default = 1)

add_blocks_full_factorial(design_dict, copies=1)¶

Add blocks of all combinations of a full factorial design.

Factors will be defined according the design_dict parameter. The design is specified by a dictionary. The keys of the dictionary indicate the factor names. Each value of the dictionary has to be a list of the factor levels.

Parameters:	design_dictdictionary keys: factor names, values: lists of factor levels copiesint, optional number of copies to add (default = 1)

add_bws_factor(factor_name, conditions)¶

Add a between subject factor.

Parameters:	factor_namestr the name of the between subject factor conditionslist possible conditions of the between subject factor

See also

get_permuted_bws_factor_condition

Notes

The defined between subject factor conditions will be permuted across the subjects when ‘using get_permuted_bws_factor_condition’. Factors that are added first are treated as hierarchically higher factors while permutation.

add_data_variable_names(variable_names)¶

Add data variable names to the design.

Parameters:	variablesstr or lst of str variable names

add_experiment_info(text)¶

Add experiment information to the design.

Parameters:	textstring or list of str text lines to be added as experiment information

property background_colour¶: Getter for background_colour.

property block_list_factor_names¶

Getter for block_list_factor_names.

Get all factor names defined in all blocks.

property blocks¶: Getter for blocks.

property bws_factor_names¶: Getter for factors keys.

property bws_factor_randomized¶

Getter for bws_factor_randomized.

Notes

Is between subject factor randomized? (True/False).

If True conditions will be assigned randomized otherwise (default) conditions will be systematically permuted across subjects.

clear_blocks()¶: Remove all blocks from experiment.

clear_bws_factors()¶: Remove all between subject factors from design.

clear_data_variable_names()¶: Remove all data variable names from design.

property clock¶: Getter for global clock.

property data¶: Getter for main data file.

property data_variable_names¶: Getter for data_variable_names.

property design_as_text¶

Getter for desing_as_text.

Trial list as csv table.

property events¶: Getter for main event files.

property experiment_info¶: Getter for experiment_info.

property filename_suffix¶: Getter for filename suffix.

find_block(id)¶

Find the position of a block, given the id.

Parameters:	idint block id to look for
Returns:	pos: int positions as a list or None if not in block list.

property foreground_colour¶: Getter for foreground_colour.

get_bws_factor(factor_name, return_none_if_not_defined=False)¶

Return all conditions of this between subject factor.

Parameters:	factor_namestr factor name return_none_if_not_definedboolean (default: False) suppresses exception and returns None if factor is not defined.
Returns:	conditionsnone or array of all conditions

get_permuted_bws_factor_condition(factor_name, subject_id=None)¶

Get the between subject factor condition for a subject.

The condition for the current subject will be returned, if expyriment is running and the function is called without a subject_id. If the function is called with a subject_id, the condition for this particular subject will be returned.

Parameters:	factor_namestr subject_idstr, optional (default=None)
Returns:	condstr condition for the current subject

Notes

see add_bws_factor

has_bws_factor(factor_name)¶

Checks if a factor is defined.

Parameters:	factor_namestr factor name (str)
Returns:	boolboolean

property is_callback_registered¶: This property indicates whether a callback function has been registered or not.

property is_initialized¶: Getter for is_initialized.

property is_started¶: Getter for is_started.

property keyboard¶: Getter for global keyboard.

load_design(filename, encoding=None)¶

Load the design from a csv file containing list of trials.

The function considers only the defined trial factors and not the added stimuli. The existing design will be deleted.

Parameters:	filenamestr name (fullpath) of the csv file (str) encodingstr, optional the encoding to be used when reading from the file

Notes

The current version of this function does not handle between_subject factors and data_variables.

log_design_to_event_file(additional_comment='')¶

Log the design (as comment) to the current main event file.

If no experiment is initialized or no event file exists the function will not do anything. This function will be automatically called after an experiment has been started.

Parameters:	additional_commentstr, optional additional comment that will be logged

See also

save_design

property log_level¶: Getter for event logging.

property mouse¶: Getter for global keyboard.

property n_blocks¶

Getter for n_blocks.

Number of blocks.

property n_bws_factor_conditions¶

Getter for n_bws_factor_conditions.

Total number of conditions in all bws_factors.

property name¶: Getter for name.

order_blocks(order)¶

Order the blocks.

Parameters:	orderlist list with the new order of positions

permute_blocks(permutation_type, factor_names=None, subject_id=None)¶

Permute the blocks.

Parameters:

permutation_typeint (permutation type): type of block order permutation (permutation type); permutation types defined in misc.constants: P_BALANCED_LATIN_SQUARE, P_CYCLED_LATIN_SQUARE, and P_RANDOM
factor_nameslist (of strings), optional: list of the factor names to be considered while permutation; if factor_names are not defined (None) all factors will be used.
subject_idint, optional: subject number for this permutation; if subject_id is defined or none (default) and experiment has been started, the current subject number will be used

register_wait_callback_function(function)¶

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 (see below).

If the callback function returns a control.CallbackQuitEvent the calling wait or event loop will be force to quit. The CallbackQuitEvent object will be then return (as first return value in the case of multiple return values).

The following functions will call the currently registered callback function (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.StreamingButtonBox.wait

io.EventButtonBox.wait

io.GamePad.wait_press

io.TriggerInput.wait

io.Mouse.wait_press

io.SerialPort.read_line

io.TextInput.get

io.TouchScreenButtonBox.wait

io.extras.CedrusResponseDevice.wait

stimulus.Video.wait_frame

stimulus.Video.wait_end

Parameters:	functionfunction wait function (function)

See also

expyriment.control.CallbackQuitEvent

Notes

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

remove_block(position)¶

Remove block from experiment.

If no position is given, the last one is removed.

Parameters:	positionint position of the block to be removed

save_design(filename)¶

Save the design as list of trials to a csv file.

The function considers only the defined trial factors and not the added stimuli.

Parameters:	filenamestr name (fullpath) of the csv file (str)

Notes

The current version of this function does not handle between_subject factors and data_variables.

property screen¶: Getter for global screen.

set_log_level(loglevel)¶

Set the log level of the current experiment

Parameters:	loglevelint The log level (0, 1, 2) of the experiment.

Notes

There are three event logging levels:

O no event logging
1 normal event logging (logging of all input & output events)
2 intensive logging; logs much more; please use this only for debugging proposes

In most cases, it should be avoided to switch of logging (loglevel=0). If log files become to big due to certain repetitive events, it is suggested to switch of the logging of individual stimuli or IO event. (see the method .set_logging() of this objects)

The logging of events can be also changed before initialize via the default value expyriment.control.defaults.event_logging.

shuffle_blocks(max_repetitions=None, n_segments=None)¶

Shuffle all blocks.

Parameters:	max_repetitionsint, optional see documentation of randomize.shuffle_list, default = None n_segmentsint, optional see documentation of randomize.shuffle_list, default = None
Returns:	successbool returns if randomization was successful and fulfilled the specified constrains (see max_repetitions)

sort_blocks()¶: Sort the blocks according to their indices from low to high.

property subject¶: Getter for global subject id.

swap_blocks(position1, position2)¶

Swap two blocks.

Parameters:	position1int position of first block position2int position of second block

property text_font¶: Getter for text_font.

property text_size¶: Getter for text_size.

property trial_factor_names¶

Getter for trial_factor_nanes.

Get all factor names defined in the trial lists of all blocks.

unregister_wait_callback_function()¶: Unregister wait function.