The ioHubExperimentRuntime Class

class psychopy.iohub.client.ioHubExperimentRuntime(configFilePath, configFile)[source]

Bases: object

The ioHubExperimentRuntime class brings together several aspects of the ioHub Event Monitoring Framework, making it simplier to define and manage experiments that use multiple ioHub Device types, particularly when using more complicated devices such as the Eye Tracker or Analog Input Device.

Other benefits of using the ioHubExperimentRuntime class include:

  • Automatic creation of an ioHubConnection instance with configuration of devices based on the associated Device Configuration Files.
  • Access to the ioHubConnection instance, all created ioHub Devices, and the ioHub Computer Device interface via two class attributes of the ioHubExperimentRuntime.
  • Optional support for the presentation of an Experiment Information Dialog at the start of each experiment session, based on the experiment settings specified in one of the associated configuration files.
  • Optional support for the presentation of a Session Variable Input Dialog at the start of each experiment session, based on the session settings specified in one of the associated configuration files. This includes the ability to collect input for custom experimenter defined session level fields that is stored in the ioHub DataStore for later retrieval and association with the event data collected during the experiment session.
  • Runtime access to the experiment, session, and device level configuration settings being used by the experiment in the form of python dictionary objects.
  • Automatic closure of the ioHub Process and the PsychoPy Process at the end of the experiment session, even when an unhandled exception occurs within your experiment scripting.

The ioHubExperimentRuntime class is used to define the main Python script that will be run during each session of the experiment being run. In addition to the Python file containing the ioHubExperimentRuntime class extension, two configuration files are created:

  1. experiment_config.yaml : This file contains configuration details about the experiment itself, the experiment sessions that will be run to collect data from each participant of the experiment, and allows for process affinities to be set for the Experiment Process, ioHub Process, as well as all other processing on the computer. For details on defining an experiment_config.yaml file for use with the ioHubExperimentRuntime class, please see the Configuration Files section of the documentation.
  2. iohub_config.yaml : This file contains configuration details about each device that is being used by the experiment, as well as the ioHub DataStore. For details on defining an iohub_config.yaml file for use with the ioHubExperimentRuntime class, please see the Configuration Files section of the documentation.

By separating experiment and session meta data definitions, as well as device configuration details, from the experiment paradigm logic contained within the ioHubExperimentRuntime class extension created, the ioHub Event Framework makes it possible to modify or switch between different implementations of an ioHub Device Interface without having to modify the experiment program logic. This is currently most beneficial when using an Eye Tracker or Analog Input Device, as these Device Interfaces support more than one hardware implementation.

Many of the example scripts provided with the ioHub distribution use the ioHubExperimentRuntime class and config.yaml configuration files. The second example used in the Quick Start section of the documentation also uses this approach. Please refer to these resources for examples of using the ioHubExperimentRuntime class when creating an ioHub enabled project.

Finally, there is an example called startingTemplate in the top level ioHub examples folder that contains a Python file with the base ioHubExperimentRuntime class extension in it, along with the two necessary configuration files. This example project folder can be copied to a directory of your choosing and renamed. Simply add the experiment logic you need to the run() method in the run.py file of the project, modify the experiment_config.yaml file to reflect the details of your intended application or experiment paradigm, and modify the iohub_config.yaml ensuring the devices required by your program are defined as needed. Then run the project by launching the run.py script with a Python interpreter.

hub = None

The hub attribute is the ioHubConnection class instance created for the ioHubExperimentRuntime. When the custom script provided in ioHubExperimentRuntime.run() is called, .hub is already set to an active ioHubConnection instance.

devices = None

The devices attribute is a short cut to the ioHubConnection instance’s .devices attribute. i.e. self.devices = self.hub.devices. A refernce to the Computer class is also added to the devices attribute, so when using the ioHubConnection devices attribute, the ioHub Computer class can be accessed using self.devices.computer; It does not need to be imported by your script.

run(*sys_argv)[source]

The run method must be overwritten by your subclass of ioHubExperimentRuntime, and would include the equivelent logic to what would be added to the main starting script in a procedural PsychoPy script.

When the run method starts, the ioHub Server is online and any devices specified for the experiment are ready for use. When the contents of the run method allow the method to return or end, the experiment session is complete.

Any sys_argv are equal to the sys.argv received by the script when it was started.

Args:
sys_argv (list): The list of arguments passed to the script when it was started with Python.
Returns:
User defined.
getConfiguration()[source]

Returns the full parsing of experiment_config.yaml as a python dictionary.

Args:
None
Returns:
dict: The python object representation of the contents of the experiment_config.yaml file loaded for the experiment.
getExperimentMetaData()[source]

Returns the experiment parameters saved to the ioHub DataStore experiment_metadata table. The values are actually only saved the first time the experiment is run. The variable names and values contained within the returned dict are also what would be presented at the experiment start in the read-only Experiment Information Dialog.

Args:
None
Returns:
dict: The python object representation of the experiment meta data, namely the experiment_code, title, version, and description fields.
getSessionMetaData()[source]

Returns the experiment session parameters saved to the ioHub DataStore for the current experiment session. These are the parameters defined in the session_defaults section of the experiment_config.yaml and are also optionally displayed in the Session Input Dialog at the start of each experiment session.

Args:
None
Returns:
dict: The python object representation of the session meta data saved to the ioHub DataStore for the current experiment run.
getUserDefinedParameters()[source]

Return only the user defined session parameters defined in the experiment_config.yaml. These parameters are displayed in the Session Input Dialog (if enabled) and the value entered for each parameter is provide in the state of the returned dict. These parameters and values are also saved in the session meta data table of the ioHub DataStore.

Args:
None
Returns:
dict: The python object representation of the user defined session parameters saved to the ioHub DataStore for the current experiment run.
isSessionCodeInUse(current_sess_code)[source]

Session codes must be unique within an experiment. This method will return True if the provided session code is already used in one of the existing experiment sessions saved to the ioHub DataStore. False is returned if the session code is not used, and would therefore make a valid session code for the current run.

Args:
current_sess_code (str): The string being requested to be used as the current experiment session code. maximum length is 24 characters.
Returns:
bool: True if the code given is already in use. False if it is not in use.
prePostExperimentVariableCallback(experiment_meta_data)[source]

This method is called prior to the experiment meta data being sent to the ioHub DataStore to be saved as the details regarding the current experiment being run. Any changes made to the experiment_meta_data dict passed into the method will be reflected in the data values saved to the ioHub DataStore.

Note that the same dict object that is passed into the method as an arguement must be returned by the method as the result.

Args:
experiment_meta_data (dict): The state of the experiment meta data prior to being sent to the ioHub DataStore for storage.
Returns:
dict: The experiment_meta_data arg passed to the method.
prePostSessionVariableCallback(session_meta_data)[source]

This method is called prior to the session meta data being sent to the ioHub DataStore to be saved as the details regarding the current session being run. Any changes made to the session_meta_data dict passed into the method will be reflected in the data values saved to the ioHub DataStore for the session.

Note that the same dict object that is passed into the method as an arguement must be returned by the method as the result.

Args:
session_meta_data (dict): The state of the session meta data prior to being sent to the ioHub DataStore for storage.
Returns:
dict: The session_meta_data arg passed to the method.
static printExceptionDetails()[source]

Prints out stack trace information for the last exception raised by the PsychoPy Process.

Currently a lot of redundant data is printed regarding the exception and stack trace.

TO DO: clean this up so there is not so much redundant info printed.

Args:
None
Returns:
None
static mergeConfigurationFiles(base_config_file_path, update_from_config_file_path, merged_save_to_path)[source]

Merges two iohub configuration files into one and saves it to a file using the path/file name in merged_save_to_path.

Example Usage

The Quickstart section of this manual contains an example of how to use the ioHubExperimentRuntime class and create the two .yaml configuration files.

The ioHub examples folder also has many demos of how to use this class, as most of the demos were written using the ioHubExperimentRuntime class.