======================== Plugin & Hook Reference ======================== Psiexperiment is built on a modular plugin architecture. This page provides a comprehensive reference of all core plugins, their available hooks (extension points), and the types of contributions they accept. ------------------------------------------ psi.context (Parameters and Sequences) ------------------------------------------ The context plugin manages all experimental variables, their values, and how they change over time. **Extension Point: psi.context.items** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to declare parameters, results, and other context-related items. - **Supports Factory**: Yes - **Contribution Types**: - **Parameter**: A user-configurable variable. - ``name`` (str): Unique identifier. - ``label`` (str): Human-readable label for the GUI. - ``default`` (any): Initial value. - ``dtype`` (str): NumPy-compatible type (e.g., ``'float64'``, ``'int32'``). - ``group_name`` (str): Optional group identifier for UI organization. - ``scope`` (str): Determines how the parameter is saved (``'trial'``, ``'session'``, etc.). - **Result**: A value calculated by a plugin after an event occurs. - ``name``, ``label``, ``dtype``, ``group_name``. - **ContextGroup**: Groups related parameters in a single UI pane. - ``name``, ``label``, ``visible``, ``hide_when``. - **ContextSet**: A set of parameters that should be roved together. - **ContextMeta**: Metadata about context items (e.g., whether they are linked). - **Expression**: A mathematical formula assigning a value to a parameter. - ``parameter`` (str): Target parameter name. - ``expression`` (str): Formula (e.g., ``"f1_level + 10"``). **Extension Point: psi.context.selectors** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to add trial sequence generators. - **Supports Factory**: No - **Contribution Types**: - **SequenceSelector**: Iterates through a fixed list of parameter combinations. - ``name`` (str): Unique identifier (often ``'default'``). - ``order`` (str): ``'sequential'`` or ``'random'``. - **RandomSelector**: Randomizes parameter values based on a distribution. **Extension Point: psi.context.symbols** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to add functions or constants to the expression evaluator. - **Supports Factory**: No - **Contribution Types**: - **Function**: Exposes a Python function. - ``name`` (str): Name available in expressions (e.g., ``"db"``). - ``function`` (callable): Python function reference. - **ImportedSymbol**: Imports a module or object from a module. - ``name``, ``module``, ``obj``. ------------------------------------------ psi.controller (Hardware and Flow) ------------------------------------------ The controller plugin manages hardware I/O and the high-level experiment state. **Extension Point: psi.controller.io** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to define the hardware configuration. - **Supports Factory**: No - **Contribution Types**: - **Engine**: Hardware drivers. - ``name`` (str): Unique identifier. - ``master_clock`` (bool): If True, this engine drives the system timing. - ``weight`` (int): Initialization order. - **Subclasses**: ``NIEngine``, ``LabJackEngine``, ``SoundcardEngine``, ``BiosemiEngine``. - **Channel**: Hardware-specific I/O lines. - ``name`` (str): Unique identifier. - ``channel`` (str): Hardware address (e.g., ``"ao0"``). - ``fs`` (float): Sampling frequency. - **Subclasses**: ``AnalogInput``, ``AnalogOutput``, ``DigitalInput``, ``DigitalOutput``. - **Input**: Processing blocks for incoming data. - ``name`` (str): Identifier. - ``source_name`` (str): Source channel or processing block. - **Subclasses**: ``Discard``, ``ExtractEpochs``, ``Average``, ``IIRFilter``, ``Threshold``. - **Output**: Processing blocks for outgoing signals. - ``name`` (str): Identifier. - ``target_name`` (str): Target hardware channel. - ``source`` (str): Name of the token/signal generator. - **Subclasses**: ``ContinuousOutput``, ``EpochOutput``, ``QueuedEpochOutput``. **Extension Point: psi.controller.actions** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to link experimental events to commands. - **Supports Factory**: No - **Contribution Types**: - **ExperimentAction**: Maps an event to a command. - ``event`` (str): The event identifier. - ``command`` (str): The command ID to invoke. - ``kwargs`` (dict): Optional arguments for the command. - ``weight`` (int): Execution priority (lower is earlier). - ``delay`` (float): Delay in seconds before invocation. - **ExperimentEvent**: Declares a new custom event. - **ExperimentState**: Declares a state (e.g., ``"running"``) that generates events. - **ExperimentCallback**: Maps an event to a Python callback. - **EventLogger**: Logs event occurrences. **Extension Point: psi.controller.wrapup** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used for final cleanup or displaying results after the experiment stops. - **Supports Factory**: Yes (**REQUIRED**) - **Usage**: The factory must return a callable that accepts the workbench as its first argument. ------------------------------------------ psi.data (Storage and Visualization) ------------------------------------------ Handles real-time plotting and data persistence. **Extension Point: psi.data.sinks** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to add data storage backends. - **Supports Factory**: No - **Contribution Types**: - **Sink**: Base class for storage backends. - ``name`` (str): Unique identifier. - **Subclasses**: ``ZarrStore``, ``TextStore``, ``CSVStore``, ``HDF5Store``, ``EventLog``. **Extension Point: psi.data.plots** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to contribute real-time visualizations. - **Supports Factory**: Yes - **Contribution Types**: - **BasePlotContainer**: Layout element for grouping plots. - **Subclasses**: ``FFTContainer``, ``TimeContainer``. - **ViewBox**: A coordinate system for plots. - ``y_min``, ``y_max``, ``y_mode`` (``'auto'``, ``'fixed'``, ``'mouse'``). - **BasePlot**: Individual plot types. - ``source_name`` (str): Source channel or processing block. - **Subclasses**: ``FFTChannelPlot``, ``ChannelPlot``, ``HistogramPlot``. ------------------------------------------ psi.experiment (UI and Metadata) ------------------------------------------ Manages the application workspace and global metadata. **Extension Point: psi.experiment.workspace** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to add new panes to the main application window. - **Supports Factory**: Yes - **Contribution Types**: - **DockItem**: A dockable UI panel. - ``name`` (str): Unique identifier. - ``title`` (str): Window title. **Extension Point: psi.experiment.status** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to add display elements to the status bar. - **Supports Factory**: Yes - **Contribution Types**: - **StatusItem**: A small display widget. - ``label`` (str): Display label. **Extension Point: psi.experiment.toolbar** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to add controls to the application toolbar. - **Supports Factory**: No - **Contribution Types**: - **Action**: A toolbar button. - ``text`` (str): Button text. - ``triggered`` (declarative): Logic to run when clicked. **Extension Point: psi.experiment.preferences** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Registers plugin attributes for persistence. - **Supports Factory**: Yes - **Contribution Types**: - **Preferences**: Defines which attributes should be saved. - **PluginPreferences**: Saves all preference-tagged members of a plugin. - **ItemPreferences**: Saves specific items. **Extension Point: psi.experiment.metadata** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Records global information about the experimental session. - **Supports Factory**: Yes - **Contribution Types**: - **MetadataItem**: A key-value pair. - ``name`` (str): Unique identifier. - ``value`` (any): Initial or static value. ------------------------------------------ psi.token (Signal Primitives) ------------------------------------------ Provides building blocks for creating auditory stimuli. **Extension Point: psi.token.tokens** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to add new signal primitives. - **Supports Factory**: Yes - **Contribution Types**: - **ContinuousBlock**: Infinite signal generators. - **Subclasses**: ``Noise``, ``CosSum``. - **EpochBlock**: Finite signal generators. - **Subclasses**: ``Tone``, ``Chirp``, ``Click``, ``Silence``. ------------------------------------------ psi.controller.calibration.channels ------------------------------------------ Manages hardware calibration routines. **Extension Point: psi.controller.calibration.channels** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to add calibration algorithms. - **Supports Factory**: No - **Contribution Types**: - **BaseCalibrate**: Defines how to calibrate a hardware output. - ``outputs`` (dict): Dictionary mapping output names to required parameters. - **Subclasses**: ``ToneCalibrate``, ``ChirpCalibrate``, ``GolayCalibrate``, ``ClickCalibrate``.