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)

See also

expyriment.design.Block.add_trials_full_factorial
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_randomised

Getter for bws_factor_randomised.

Notes

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

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

property bws_factor_randomized

Getter for bws_factor_randomised.

Notes

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

If True conditions will be assigned randomised 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 design_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: list of 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_initialised

Getter for is_initialised.

property is_initialized

Getter for is_initialised.

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 initialised 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 off 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 initialise via the default value expyriment.control.defaults.event_logging.

shuffle_blocks(method=0, max_repetitions=None, n_segments=None)

Shuffle all blocks.

The function returns False if no randomisation could be found that fulfills the max immediate block repetition criterion. The different type of blocks are only defined by the factors. Shuffle does not take into account the added trials.

The following randomisation methods are defined:

0 = total randomisation of block order (default)

1 = randomisation within small miniblocks. Each miniblock contains one block of each type (only defined by factors!); in other words, copies of one block type are always in different miniblocks

Parameters:
methodint, optional

method of block randomisation (default=0)

max_repetitionsint, optional

see documentation of randomise.shuffle_list (default = None)

n_segmentsint, optional

this parameter will be only considered for randomisation method 0; see documentation of randomise.shuffle_list (default = None)

Returns:
succeededbool

returns if randomisation 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.