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.

Methods

__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_bws_factor(factor_name, conditions)

Add a between subject factor.

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

Parameters :

factor_name : str

the name of the between subject factor

conditions : list

possible conditions of the between subject factor

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

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.

Parameters :

function : function

wait function (function)

Notes

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

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.buttonbox.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

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). It 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()

Shuffle all blocks.

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.