Context

The Context plugin (psi.context) is one of the most powerful features of psiexperiment. It manages every variable that defines experimental behavior—from stimulus frequency and level to intertrial interval durations and randomization rules.

By using the Context system, you ensure that your experimental parameters are: 1. Observable: The GUI and other plugins can react when a value changes. 2. Persistent: Settings are automatically saved and loaded between sessions. 3. Traceable: The value of every parameter is recorded alongside your experimental data.

Types of Context Items

A context item is a single variable managed by the system. There are three primary types:

Parameters

A Parameter is a value that can be configured by the user via the GUI. * Static Parameters: These maintain a constant value throughout the experiment (though the user can change them manually). * Editable: Parameters can be updated while the experiment is running.

Roving Parameters

A Roving Parameter is like a standard parameter, but it can be controlled by a Selector to change from trial to trial. * Sequences: When a parameter is “roved,” its next value is drawn from a sequence (e.g., a list of frequencies or randomized levels). * Selectors: A selector manages the sequence for one or more roving parameters. You might have one selector for “Target” trials and another for “Distractor” trials.

Results

A Result is a value provided by a plugin after an event occurs (e.g., a calculated reaction time or a peak amplitude). * Read-Only: Results cannot be edited by the user in the GUI. * Data Storage: Like parameters, results are automatically captured by data sinks.

Expressions and Math

One of the unique features of the context system is that parameter values can be expressed as mathematical formulas.

• Variables: You can define one parameter in terms of another. For example, if you have f1_level, you can set f2_level = f1_level + 10.

• Functions: You can use built-in functions like db() or standard NumPy/SciPy functions (e.g., np.random.choice([30, 40, 50])).

• Dynamic: Formulas are re-evaluated whenever the dependent variables change.

Defining Context Items

Context items are defined in your manifest by contributing to the psi.context.items extension point.

from psi.context.api import Parameter, Result

Extension:
    id = manifest.id + '.context_items'
    point = 'psi.context.items'

    Parameter:
        name = 'intertrial_interval'
        label = 'ITI (s)'
        default = 2.0
        group_name = 'timing'

    Result:
        name = 'trial_score'
        label = 'Score'

Iterating through Settings

In your experiment controller, you interact with the context plugin to move to the next set of values in a sequence.

# Get the context plugin
context = workbench.get_plugin('psi.context')

# Advance the 'default' selector to the next trial setting
context.next_setting(selector='default')

# Retrieve all current parameter values as a dictionary
values = context.get_values()
print(f"Current frequency: {values['frequency']}")

By advancing the selector, the context plugin updates all roving parameters to their next values and notifies the rest of the system (including hardware engines and the GUI).