Events and ONI

[bparks13]

Background

With this plugin, we have several devices on the ONIX Breakout Board that do not have a consistent data stream and would benefit from being saved as events instead. However, we are running into some issues with how to implement that in the current architecture of the GUI and the plugin.

For reference, the two main devices we are trying to save as events are the DigitalIO and the MemoryMonitor devices. DigitalIO only sends data when the state changes, meaning it cannot be quantified as a stream with a timestamp, whereas the MemoryMonitor would benefit from being saved every ~1 second as a float value instead of being saved as an unsigned integer like it would be in a regular data stream.

Main Issue

The issue we are running into is that we want to create EventChannels for the two devices, but in order to do that we need to attach them to a stream. In the plugin, we currently have it setup so that each device that is connected is responsible for creating its own StreamInfo objects, which are then fully instantiated as streams in the main DataThread class (in this case, OnixSource.cpp). There are a number of issues with this current setup:

1. It is entirely possible that all devices are disabled except for either DigitalIO or MemoryMonitor, which means there are zero active streams for them to attach the EventChannel to.
2. It is possible to change the devices that are enabled from one recording to the next, so if we always tried to attach the EventChannel to the first stream, the name of the stream the events are saved to could change from recording to recording, which is not ideal.
3. If we always try to attach the EventChannel to a particular stream, there is no guarantee that this stream would be present if the device creating the stream is not connected or disabled.

Potential Workarounds

There are a few potential ways around this, but some of them would require reworking how the GUI handles events.

1. Specifically for ONIX Breakout Boards, we could create a stream for the Heartbeat data, which is always enabled, and then attach these event channels to this stream.
   • This is not a great solution, because the Heartbeat data should not be exposed for the user to see, and would be basically an empty data stream outside of the events attached to it.
2. Change how events are handled by the GUI such that they do not require a stream.
   • This is a big shift from how things are currently done, since my understanding is that an event requires a stream in order to grab the current timestamp. This ensures that the events can be aligned properly to the data streams.
   • For ONI, since we are using (or will be using) the frame->time we have the universal timestamp for all devices from the hardware directly, meaning that we do not need a stream for each event because the events would come with the correct timestamp for alignment already.
3. Enable the creation of "hidden" streams.
   • For instance, this would allow us to implement fix (1) above, where we create the Heartbeat stream and attach events to it, but the stream itself is not saved. This would give the benefits defined above without exposing the stream to the user directly.

BinaryEvents

Currently we are not decided on the format needed for the DigitalIO events, but for MemoryMonitor we were planning to create a BinaryEvent with a float type. In the BinaryEvent header, there is a note indicating that this might not be a valid way to do it since the checkForEvents() method does not work for binary events. Is this true? And does this affect saving the data using the RecordNode?

It appears that the data might be serialized correctly in the GenericProcess::addEvent() method, since there are class-specific overloads, but it is unclear if that translates to the RecordNode correctly.

Add Binary Event in DataThread Class

This one might be more of a skill issue, but should be mentioned here for completeness:

The plugin is currently only inheriting from DataThread, meaning that we don't have access to the GenericProcess::addEvent() method described above. We do have access to the BinaryEvent::createBinaryEvent() method, so we could easily create the event packet needed, but I don't see a way to get this event to where it needs to go. Would it be valid to inherit from GenericProcess as well to gain access to these methods, or does that complicate matters too much to be practical?

[jsiegle]

I think the main question is how these data streams will be used -- the reason we switched to requiring all events to be associated with continuous data is that it was too cumbersome to define the functionality of every plugin such that it would respond gracefully to event-only streams.

I would recommend copying the DigitalIO events across all incoming streams, so they will be saved alongside each stream and can be accessible for display-triggering, latency measurements, etc. This will create some redundant data, but will be way easier to deal with from a user perspective. To add events using a DataThread class, you just include the event code for each sample in the addToBuffer call.

For the MemoryMonitor events, do these need to be sent through the signal chain? This is the type of thing that seems like it would be helpful to display as a metric inside the ONIX Source plugin, but which doesn't need to be sent downstream.

[bparks13]

The MemoryMonitor data is currently being displayed as a metric in the editor, but it would be helpful to also save the data as events every ~1 Hz so that the memory can be tracked over time, even if the user is not sitting at the computer the whole time.

We could copy the events across all streams, that is a possibility.

Unfortunately, for the MemoryMonitor and DigitalIO there is no buffer. Because of how the OnixDevice base class was initially created, each device is responsible for its own buffer. Normally this has no issues, but when we have events-only devices we now have a problem because these devices are not writing to a buffer. Hence the need for the addEvent() method call.

[jsiegle]

For the MemoryMonitor, I would upsample (to 100 Hz or so) and send the values as a separate continuous stream with its own DataBuffer. That way they can be more readily visualized in the LFP Viewer and saved by the Record Node.

For the DigitalIO, each continuous stream should check for available events and insert them at the appropriate sample. Then events will be pre-aligned to every data stream, and can be used by downstream plugins without needing to translate them across streams (e.g. with Event Translator plugin).

[jonnew]

This should be closed by issue #42 when that is addressed.