The ioHub Experiment Device

Platforms: Windows, OS X, Linux

class psychopy.iohub.devices.experiment.Experiment(*args, **kwargs)[source]

Bases: psychopy.iohub.devices.Device

The Experiment class represents a virtual device ( the Python run-time within the PsychoPy Process ), and is unique in that it is the client of the ioHub Event Monitoring Framework, but can also generate events itself that are registered with the ioHub process.

The Experiment Device supports the creation of general purpose MessageEvent’s, which can effectively hold any string up to 128 characters in length. Experiment Message events can be sent to the ioHub Server at any time, and are useful for creating stimulus onset or offset notifications, or other experiment events of interest that should be associated with events from other devices for post hoc analysis of the experiments event steam using the ioDataStore.

The Experiment Device also support LogEvents, which result in the log text sent in the event being saved in both the PsychoPy logging module file(s) that have been defined, as well as in the ioHub DataStore. The ioHub Process itself actually uses the LogEvent type to log status and debugging related information to the DataStore and your log files if the log level accepts DEBUG messages.

clearEvents()

Clears any DeviceEvents that have occurred since the last call to the device’s getEvents(), or clearEvents() methods.

Note that calling clearEvents() atthe device level only clears the given device’s event buffer. The ioHub Process’s Global Event Buffer is unchanged.

Args:
None
Returns:
None
enableEventReporting(enabled=True)

Specifies if the device should be reporting events to the ioHub Process (enabled=True) or whether the device should stop reporting events to the ioHub Process (enabled=False).

Args:
enabled (bool): True (default) == Start to report device events to the ioHub Process. False == Stop Reporting Events to the ioHub Process. Most Device types automatically start sending events to the ioHUb Process, however some devices like the EyeTracker and AnlogInput device’s do not. The setting to control this behavour is ‘auto_report_events’
Returns:
bool: The current reporting state.
getConfiguration()

Retrieve the configuration settings information used to create the device instance. This will be a combination of the default settings for the device (found in iohub.devices.<device_name>.default_,defice_name>.yaml, plus any device settings specified by the experiment author within an iohub_config.yaml file if the ioHubExperimentRuntime is being used to define the experiment logic, or if using the iohub.launchHubProcess() function in the experriment script, as device settings in dictionary form.

Changing any values in the returned dictionary has no effect on the device state.

Args:
None
Returns:
(dict): The dictionary of the device configuration settings used to create the device.
getEvents(*args, **kwargs)

Retrieve any DeviceEvents that have occurred since the last call to the device’s getEvents() or clearEvents() methods.

Note that calling getEvents() at a device level does not change the Global Event Buffer’s contents.

Args:

event_type_id (int): If specified, provides the ioHub DeviceEvent ID for which events should be returned for. Events that have occurred but do not match the event ID specified are ignored. Event type ID’s can be accessed via the EventConstants class; all available event types are class atttributes of EventConstants.

clearEvents (int): Can be used to indicate if the events being returned should also be removed from the device event buffer. True (the defualt) indicates to remove events being returned. False results in events being left in the device event buffer.

asType (str): Optional kwarg giving the object type to return events as. Valid values are ‘namedtuple’ (the default), ‘dict’, ‘list’, or ‘object’.

Returns:
(list): New events that the ioHub has received since the last getEvents() or clearEvents() call to the device. Events are ordered by the ioHub time of each event, older event at index 0. The event object type is determined by the asType parameter passed to the method. By default a namedtuple object is returned for each event.
isReportingEvents()

Returns whether a Device is currently reporting events to the ioHub Process.

Args: None

Returns:
(bool): Current reporting state.

Experiment Device Default Settings

# This file includes all valid Experiment Device
# settings that can be specified in an iohub_config.yaml
# or in a Python dictionary form and passed to the quickStartHubServer
# method. Any device parameters not specified when the device class is
# created by the ioHub Process will be assigned the default value
# indicated here.
#
Experiment:
    # name: The unique name to assign to the evice instance created.
    #   The device is accessed from within the PsychoPy script 
    #   using the name's value; therefore it must be a valid Python
    #   variable name as well.
    #
    name: experiment

    # monitor_event_types: Specify which of the device's supported event
    #   types you would like the ioHub to monitor for.
    #
    monitor_event_types: [MessageEvent, LogEvent]

    # enable: Specifies if the device should be enabled by ioHub and monitored
    #   for events.
    #   True = Enable the device on the ioHub Server Process
    #   False = Disable the device on the ioHub Server Process. No events for
    #   this device will be reported by the ioHub Server.
    #    
    enable: True

    # saveEvents: *If* the ioHubDataStore is enabled for the experiment, then
    #   indicate if events for this device should be saved to the
    #   data_collection/keyboard event group in the hdf5 event file.
    #   True = Save events for this device to the ioDataStore.
    #   False = Do not save events for this device in the ioDataStore.
    #    
    save_events: True

    # streamEvents: Indicate if events from this device should be made available
    #   during experiment runtime to the PsychoPy Process.
    #   True = Send events for this device to  the PsychoPy Process in real-time.
    #   False = Do *not* send events for this device to the PsychoPy Process in real-time.
    #    
    stream_events: True

    # auto_report_events: Indicate if events from this device should start being
    #   processed by the ioHub as soon as the device is loaded at the start of an experiment,
    #   or if events should only start to be monitored on the device when a call to the
    #   device's enableEventReporting method is made with a parameter value of True.
    #   True = Automatically start reporting events for this device when the experiment starts.
    #   False = Do not start reporting events for this device until enableEventReporting(True)
    #   is set for the device during experiment runtime.
    #
    auto_report_events: True

    # event_buffer_length: Specify the maximum number of events (for each
    #   event type the device produces) that can be stored by the ioHub Server
    #   before each new event results in the oldest event of the same type being
    #   discarded from the ioHub device event buffer.
    #
    event_buffer_length: 128

    # The device manufacturer's name.
    #   It is not used by the ioHub, so is FYI only.
    #
    manufacturer_name: N/A
    
    # The device number to assign to the device. 
    #   Device_number is not used by this device type.
    #
    device_number: 0

    # The serial number for the specific isnstance of device used
    #   can be specified here. It is not used by the ioHub, so is FYI only.
    #
    serial_number: N/A

    # manufacture_date: The date of manufactiurer of the device 
    # can be specified here. It is not used by the ioHub,
    # so is FYI only.
    #   
    manufacture_date: DD-MM-YYYY

    # The device model name can be specified here.
    #   It is not used by the ioHub, so is FYI only.
    #
    model_name: N/A

    # The device model number can be specified here.
    #   It is not used by the ioHub, so is FYI only.
    #
    model_number: N/A
    
    # The device driver and / or SDK software version number.
    #   This field is not used by ioHub, so is FYI only. 
    software_version: N/A

    # The device's hardware version can be specified here.
    #   It is not used by the ioHub, so is FYI only.
    #
    hardware_version: N/A
    
    # If the device has firmware, its revision number
    #   can be indicated here. It is not used by the ioHub, so is FYI only.
    #
    firmware_version: N/A

Experiment Event Types

class psychopy.iohub.devices.experiment.MessageEvent(*args, **kwargs)[source]

Bases: psychopy.iohub.devices.DeviceEvent

A MessageEvent can be created and sent to the ioHub to record important marker times during the experiment; for example, when key display changes occur, or when events related to devices not supported by the ioHub have happened, or simply information about the experiment you want to store in the ioDataStore along with all the other event data.

Since the PsychoPy Process can access the same time base that is used by the ioHub Process, when you create a Message Event you can time stamp it at the time of MessageEvent creation, or with the result of a previous call to one of the ioHub time related methods. This makes experiment messages extremely accurate temporally when related to other events times saved to the ioDataSore.

Event Type ID: EventConstants.MESSAGE Event Type String: ‘MESSAGE’

text

The text attribute is used to hold the actual ‘content’ of the message. The text attribute string can not be more than 128 characters in length. String type

prefix

The prefix attribute is a 0 - 3 long string used as a ‘group’ or ‘category’ code that can be assigned to messages. The prefix attribute may be useful for grouping messages into categories or types when retieving them for analysis by assigning the same prix string to related Message Event types. String type.

msg_offset

The msg_offset attribute can be used in cases where the Experiment Message Evenet needs to be sent before or after the time the actual event occurred. msg offset should be in sec.msec format and in general can be calculated as:

msg_offset=actual_event_iohub_time - iohub_message_time

where actual_event_iohub_time is the time the event occured that is being represented by the Message event; and iohub_message_time is either the time provided to the Experiment Message creation methods to be used as the Message time stamp, or is the time that the Message Event actually requested the current time if no message time was provided. Both times must be read from Computer.getTime() or one of it’s method aliases. Float type.

class psychopy.iohub.devices.experiment.LogEvent(*args, **kwargs)[source]

Bases: psychopy.iohub.devices.DeviceEvent

A LogEvent creates an entry in the ioHub dataStore logging table. If psychopy is available, it also sends the LogEvent to the Experiment Process and it is entered into the psychopy.logging module.

The LogEvent is unique in that instances can be created by the ioHub Server or the Experiment Process psychopy script. In either case, the log entry is entered in the psychopy.logging module and the DataStore log table (if the datastore is enabled).

It is critical that log events created by the psychopy script use the core.getTime() method to provide a LogEvent with the time of the logged event, or do not specify a time, in which case the logging module uses the chared time base by default.

Event Type ID: EventConstants.LOG Event Type String: ‘LOG’

text

The text attribute is used to hold the actual ‘content’ of the message. The text attribute string can not be more than 128 characters in length. String type

log_level

The log level to set the log event at. If psychopy is available, valid log levels match the predefined logging levels. Otherwise the following log levels are available (which match the predefined psychopy 2.76 logging settings):

  • CRITICAL = 50
  • FATAL = CRITICAL
  • ERROR = 40
  • WARNING = 30
  • WARN = WARNING
  • DATA = 25
  • EXP = 22
  • INFO = 20
  • DEBUG = 10
  • NOTSET = 0

The int defined value can be used, or a string version of the log level name, for example specifying “WARNING” is equal to specifying a log level of LogEvent.WARNING or 30. Default: NOTSET String or Int type.

Notes and Considerations

None at this time.