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 randomisation 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 randomisation methods are defined:

0 = total randomisation of trial order (default)

1 = randomisation 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 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_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.