Task design containers.

class, stack_axis=1)[source]

Trial array.

The array is not much more than a NumPy array with a stack() method for conveniently adding new data to the array. This is useful in cases where you iteratively collect new segments of data and want to concatenate them. For example, you could use an Array to collect the samples from a data acquisition device as they come in.

You usually don’t need to create an array manually – instead, use Trial.add_array().

  • data (ndarray, optional) – Data to initialize the array with. If None, the first array passed to stack() is used for initialization.

  • stack_axis (int, optional) – Axis to stack the data along.


The NumPy array holding the data.


ndarray, optional


Clears the buffer.

Anything that was in the buffer is not retrievable.


Stack new data onto the array.


data (ndarray) – New data to add. The direction to stack along is specified in the array’s constructor (stack_axis).

class, *args, **kwargs)[source]

List of trials.

Experiments often consist of a set of blocks, each containing the same set of trials in randomized order. You usually shouldn’t need to create a block directly – use Design.add_block() instead.


index (int) – Index of the block in the design. This is required to pass along to each trial in the block, so that the trial knows which block it belongs to.


Add a trial to the block.

A Trial object is created and added to the block. You can optionally provide a dictionary of attribute name/value pairs to initialize the trial.


attrs (dict, optional) – Dictionary of attribute name/value pairs.


trial – The trial object created. This can be used to add new attributes or arrays. See Trial.

Return type:


shuffle(reset_index=True, seed=None)[source]

Shuffle the block’s trials in random order.

  • reset_index (bool, optional) – Whether or not to set the trial attribute of each trial such that they remain in sequential order after shuffling. This is the default.

  • seed (int, optional) – If provided, the random seed will be set to the specified value to ensure reproducible shuffling. Note that if you have multiple identical blocks and want to shuffle them differently, use a different seed value for each block.

class, /)[source]

Top-level task design container.

The Design is a list of Block objects, which themselves are lists of Trial objects.


Add a block to the design.


block – The created block.

Return type:



Container of trial data.

There are two kinds of data typically needed during a trial: attributes and arrays. Attributes are scalar quantities or primitives like integers, floating point numbers, booleans, strings, etc. Arrays are NumPy arrays, useful for holding things like cursor trajectories.

There are two primary purposes for each of these two kinds of data. First, it’s useful to design a task with pre-determined values, such as the target location or the cursor trajectory to follow. The other purpose is to temporarily hold runtime data using the same interface, such as the final cursor position or the time-to-target.

You shouldn’t normally need to create a trial directly – instead, use Block.add_trial().


Dictionary mapping attribute names to their values.




Dictionary mapping array names to Array objects, which contain the array data.



add_array(name, **kwargs)[source]

Add an array to the trial.

  • name (str) – Name of the array.

  • kwargs (dict) – Keyword arguments passed along to Array.