The ioHub DataStore

The ioHub DataStore contains the fucntionality responsible for saving Device Events to the HDF5 file format used by the ioHub Process. The DataStore also includes a simple API to access the events and experiment information saved to it, but using the ExperimentDataAccessUtility class.

Advantages of using the ioHub DataStore are:

Data File Viewers

Both of these program’s are very useful for openning the HDF5 files saved by the ioHub DataStore and viewing the data saved quickly and efficiently. Both programs are cross-platform, open source, and free to use.

  • ViTables : Written in Python using the PyQt GUI package.
  • HDFView : Written in Java, maybe a bit more up to date given it is written and maintained by the HDFGroup.

Data File Access

ioHub DataStore data files are standard HDF5 formatted files with an experiment and session metadata, as well as device and experiment event structure specified.

Therefore any HDF5 API can be used to read the files saved. For Python, these include:

If you need to use Matlab, the files can also be read natively by using information found here.

You can also use the ExperimentDataAccessUtility class prodied as part of the ioHub DataStore to access the files based on experiment and session code(s), and retrieve event information based on ioHub Event Types.

ioHub DataStore File Structure

HDF5 Files saved by the ioHub DataStore all use a common structure for the data saved.

/(RootGroup) ‘ioHub DataStore - Experiment Data File.’

/class_table_mapping (Table) ‘Mapping of ioHub DeviceEvent Classes to ioHub DataStore Tables.’ /data_collection (Group) ‘Data Collected using the ioHub Event Framework.’

/data_collection/experiment_meta_data (Table) ‘Information About Experiments Saved to This ioHub DataStore File.’ /data_collection/session_meta_data (Table) ‘Information About Sessions Saved to This ioHub DataStore File.’ /data_collection/condition_variables (Group) ‘Tables created to Hold Experiment DV and IV’s Values Saved During an Experiment Session.’ /data_collection/events (Group) ‘All Events that were Saved During Experiment Sessions.’

/data_collection/events/analog_input (Group) ‘AnalogInput Device Events.’ /data_collection/events/experiment (Group) ‘Experiment Device Events.’

/data_collection/events/experiment/LogEvent (Table) ‘LogEvent Data.’ /data_collection/events/experiment/MessageEvent (Table) ‘MessageEvent Data.’

/data_collection/events/eyetracker (Group) ‘EyeTracker Device Events.’ /data_collection/events/gamepad (Group) ‘GamePad Device Events.’ /data_collection/events/keyboard (Group) ‘Keyboard Device Events.’

/data_collection/events/keyboard/KeyboardCharEvent (Table) ‘KeyboardCharEvent Data.’ /data_collection/events/keyboard/KeyboardKeyEvent (Table(114,)) ‘KeyboardKeyEvent Data.’
/data_collection/events/mouse (Group) ‘Mouse Device Events.’
/data_collection/events/mouse/MouseInputEvent (Table(0,)) ‘MouseInputEvent Data.’

The ExperimentDataAccessUtility Class

Intro to be Added.

class psychopy.iohub.datastore.util.ExperimentDataAccessUtility(hdfFilePath, hdfFileName, experimentCode=None, sessionCodes=[], mode='r')[source]

Bases: object

The ExperimentDataAccessUtility provides a simple, high level, way to access data saved in an ioHub DataStore HDF5 file. Data access is done by providing information at an experiment and session level, as well as specifying the ioHub Event types you want to retieve data for.

An instance of the ExperimentDataAccessUtility class is created by providing the location and name of the file to read, as well as any session code filtering you want applied to the retieved datasets.

Args:

hdfFilePath (str): The path of the directory the DataStore HDF5 file is in.

hdfFileName (str): The name of the DataStore HDF5 file.

experimentCode (str): If multi-experiment support is enabled for the DataStore file, this arguement can be used to specify what experiment data to load based on the experiment_code given. NOTE: Multi-experiment data file support is not well tested and should not be used at this point.

sessionCodes (str or list): The experiment session code to filter data by. If a list of codes is given, then all codes in the list will be used.

Returns:
object: the created instance of the ExperimentDataAccessUtility, ready to get your data!
printTableStructure(tableName)[source]

Print to stdout the current structure and content statistics of the specified DataStore table. To print out the complete structure of the DataStore file, including the name of all available tables, see the printHubFileStructure method.

Args:
tableName (str): The DataStore table name to print metadata information out for.
printHubFileStructure()[source]

Print to stdout the current global structure of the loaded DataStore File.

getExperimentMetaData()[source]

Returns the the metadata for the experiment the datStore file is for.

Docstr TBC.

getSessionMetaData(sessions=None)[source]

Returns the the metadata associated with the experiment session codes in use.

Docstr TBC.

getTableForPath(path)

Given a valid table path within the DataStore file, return the accociated table.

getEventTable(event_type)[source]

Returns the DataStore table that contains events of the specified type.

Docstr TBC.

getEventMappingInformation()

Returns details on how ioHub Event Types are mapped to tables within the given DataStore file.

getEventsByType()

Returns a dict of all event tables within the DataStore file that have atleast one event instance saved. Keys are Event Type constants, as specified by Psychopy.iohub.EventConstants. Each value is a row iterator for events of that type.

getConditionVariableNames()[source]

Docstr TBC.

getConditionVariables(filter=None)[source]

Docstr TBC.

getValuesForVariables(cv, value, cvNames)[source]

Docstr TBC.

getEventAttributeValues(event_type_id, event_attribute_names, filter_id=None, conditionVariablesFilter=None, startConditions=None, endConditions=None)[source]

Docstr TBC.

Args:
event_type_id event_attribute_names conditionVariablesFilter startConditions endConditions
Returns:
Values for the specified event type and event attribute columns which match the provided experiment condition variable filter, starting condition filer, and ending condition filter criteria.
getEventIterator(event_type)[source]

Docstr TBC.

Args:
event_type
Returns:
(interator): An interator providing access to each matching event as a numpy recarray.
close()[source]

Close the ExperimentDataAccessUtility and associated DataStore File.

Examples

Intro to be added.