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:

name : str, optional

name of the experiment

foreground_colour : (int, int, int), optional

background_colour : (int,int,int), optional

text_font : str, optional

text_size : int, optional

filename_suffix : str, 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:

block : design.Block

block to add

copies : int, 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_dict : dictionary

keys: factor names, values: lists of factor levels

copies : int, optional

number of copies to add (default = 1)

See also

Block.add_trials_full_factorial

add_bws_factor(factor_name, conditions)

Add a between subject factor.

Parameters:

factor_name : str

the name of the between subject factor

conditions : list

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:

variables : str or lst of str

variable names
add_experiment_info(text)

Add experiment information to the design.

Parameters:

text : string or list of str

text lines to be added as experiment information
background_colour

Getter for background_colour.

block_list_factor_names

Getter for block_list_factor_names.

Get all factor names defined in all blocks.

blocks

Getter for blocks.

bws_factor_names

Getter for factors keys.

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.

clock

Getter for global clock.

data

Getter for main data file.

data_variable_names

Getter for data_variable_names.

design_as_text

Getter for desing_as_text.

Trial list as csv table.

events

Getter for main event files.

experiment_info

Getter for experiment_info.

filename_suffix

Getter for filename suffix.

find_block(id)

Find the position of a block, given the id.

Parameters:

id : int

block id to look for
Returns:

pos: int

positions as a list or None if not in block list.
foreground_colour

Getter for foreground_colour.

get_bws_factor(factor_name)

Return all conditions of this between subject factor.

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_name : str

subject_id : str, optional

(default=None)
Returns:

cond : str

condition for the current subject

Notes

see add_bws_factor

is_callback_registered

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

is_initialized

Getter for is_initialized.

is_started

Getter for is_started.

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:

filename : str

name (fullpath) of the csv file (str)

encoding : str, 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_comment : str, optional

additional comment that will be logged

Notes

See also save_design().

log_level

Getter for event logging.

mouse

Getter for global keyboard.

n_blocks

Getter for n_blocks.

Number of blocks.

n_bws_factor_conditions

Getter for n_bws_factor_conditions.

Total number of conditions in all bws_factors.

name

Getter for name.

order_blocks(order)

Order the blocks.

Parameters:

order : list

list with the new order of positions
permute_blocks(permutation_type, factor_names=None, subject_id=None)

Permute the blocks.

Parameters:

permutation_type : int (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_names : list (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_id : int, 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:

function : function

wait function (function)

See also

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:

position : int

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:

filename : str

name (fullpath) of the csv file (str)

Notes

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

screen

Getter for global screen.

set_log_level(loglevel)

Set the log level of the current experiment

Parameters:

loglevel : int

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_repetitions : int, optional

see documentation of randomize.shuffle_list, default = None

n_segments : int, optional

see documentation of randomize.shuffle_list, default = None
Returns:

success : bool

returns if randomization was successful and fulfilled the specified constrains (see max_repetitions)

See also

randomize.shuffle_list

sort_blocks()

Sort the blocks according to their indices from low to high.

subject

Getter for global subject id.

swap_blocks(position1, position2)

Swap two blocks.

Parameters:

position1 : int

position of first block

position2 : int

position of second block
text_font

Getter for text_font.

text_size

Getter for text_size.

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.