expyriment.design.Block

class expyriment.design.Block(name=None)

A class implementing an experimental block.

__init__(name=None)

Create a block.

Parameters:

namestr, optional

name of the block

add_trial(trial, copies=1, random_position=False)

Adds one or multiple copies of the trial to the block.

Parameters:

trialdesign.Trial

trial to add

copiesint, optional

number of copies to add (default = 1)

random_positionbool, optional

True = insert trials at random position; False = append trials at the end (default=False)

add_trials_from_csv_file(filename, encoding=None)

Read a list of trials from csv-file and append the new trials to the block. Trials are defined as combinations of trial factors.

csv-file specifications

The first row of the csv-file specifies the factor names. Each following row describes one trial. Each row must have the same amount of columns.

Parameters:

filenamestr

name (fullpath) of the csv file (str)

encodingstr, optional

the encoding to be used when reading from the file

Notes

All factors will be read in as text strings and not casted to numericals. Please do this manually if required.

add_trials_full_factorial(design_dict, copies=1)

Add trials 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)

Examples

>>> bl = design.Block()
>>> design = {
>>>    "target": ["left", "center", "right"],
>>>    "cue": [-300, 300],
>>>    "letter": ["H", "F"]}
>>> bl.add_trials_full_factorial(design, copies=10)

clear_factors()

Clear all factors.

clear_trials()

Clear all trials.

compare(block)

Compares this block with another block and returns True if all factors associated with both blocks are identical.

Parameters:

blockdesign.Block

Returns:

identical: boolean

See also

expyriment.design.Trial.compare

copy()

Return a copy of the block.

property design_as_text

Getter for design_as_text.

List of trial factors as csv table.

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

property factor_dict

The dictionary with all factors of the block.

property factor_names

Getter for factor_names.

Factor keys.

property factors_as_text

Getter for factors_as_text.

Return all factor names and values as string line.

find_trial(id)

Find the positions of a trial.

Parameters:

idint

trial id to look for

Returns:

poslist

positions as a list or None if not in trial list.

get_factor(name, return_none_if_not_defined=False)

Get a factor of the block.

Parameters:

namestr

factor name

return_none_if_not_definedboolean (default: False)

suppresses exception and returns None if factor is not defined.

Returns:

factor_valstr or numeric

get_random_trial()

Returns a randomly selected trial.

Returns:

rnddesign.Trial

random Expyriment trial

Notes

This function is useful for compiling training blocks.

get_trial_factor_values(name)

Return a list of the values of a certain factor for all trials.

Parameters:

namestr

name of the factor

has_factor(name)

Checks if a factor is defined.

Parameters:

namestr

factor name (str)

Returns:

boolboolean

property id

Getter for id.

property max_trial_repetitions

Getter for max_trial_repetitions.

Returns the maximum number of immediate trial repetitions.

property n_trials

Getter for n_trials.

Number of trials.

property name

Getter for name.

order_trials(order)

Order the trials.

Parameters:

orderlist

list with the new order of positions

read_design(filename)

Reads a list of trials from a csv file and clears the old block design.

The function considers only the trial factors and not the added stimuli. All factors will be read in as text strings and not casted to numericals. Please do this manually if required.

Parameters:

filenamestr

name (fullpath) of the csv file (str)

remove_trial(position)

Remove a trial.

Parameters:

positionint

position of the trial

save_design(filename)

Save the list of trials to a csv file.

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

Parameters filename – name (fullpath) of the csv file

set_factor(name, value)

Set a factor for the block.

Parameters:

namestr

factor name

valuestr or numeric

factor value

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

Shuffle all trials.

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

The following randomization methods are defined:

0 = total randomization of trial order (default)

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

Parameters:

methodint, optional

method of trial randomization (default=0)

max_repetitionsint, optional

see documentation of randomize.shuffle_list (default = None)

n_segmentsint, optional

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

Returns:

succeededbool

sort_trials()

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

property summary

Getter for summary.

swap_trials(position1, position2)

Swap two trials.

Parameters:

position1int

position of first trial

position2int

position of second trial

property trial_factor_names

Getter for trial_factor_names.

Get all factor names defined in trial list.

property trials

Getter for trials.