expyriment.design.Block

class expyriment.design.Block(name=None)

A class implementing an experimental block.

Methods

__init__(name=None)

Create a block.

Parameters:

name : str, optional

name of the block

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

Add trial to the block.

Parameters:

trial : design.Trial

trial to add

copies : int, optional

number of copies to add (default = 1)

random_position : bool, 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:

filename : str

name (fullpath) of the csv file (str)

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

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.

Returns:identical: boolean :

See also

Trials.compare

copy()

Return a copy of the block.

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.

factor_dict

The dictionary with all factors of the block.

factor_names

Getter for factor_names.

Factor keys.

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:

id : int

trial id to look for

Returns:

pos : list

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

get_factor(name)

Get a factor of the block.

Parameters:

name : str

factor name (str)

get_random_trial()

Returns a randomly selected trial.

Returns:

rnd : design.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:

name : str

name of the factor

id

Getter for id.

max_trial_repetitions

Getter for max_trial_repetitions.

Returns the maximum number of immediate trial repetitions.

n_trials

Getter for n_trials.

Number of trials.

name

Getter for name.

order_trials(order)

Order the trials.

Parameters:

order : list

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:

filename : str

name (fullpath) of the csv file (str)

remove_trial(position)

Remove a trial.

Parameters:

position : int

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:

name : str

factor name

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

method : int, optional

method of trial randomization (default=0)

max_repetitions : int, optional

see documentation of randomize.shuffle_list (default = None)

n_segments : int, optional

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

Returns:

succeeded : bool

sort_trials()

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

summary

Getter for summary.

swap_trials(position1, position2)

Swap two trials.

Parameters:

position1 : int

position of first trial

position2 : int

position of second trial

trial_factor_names

Getter for trial_factor_names.

Get all factor names defined in trial list.

trials

Getter for trials.