DataThread plugin addToBuffer issues

[bgrgic-inbrain]

Hi,

I am making my own own DataThread plugin which is passing the received data through addToBuffer method. With plugin-GUI v0.6.7 everything was working great.
Since upgrading from plugin-GUI v0.67 to v1.01 (I tried with v1.0.2 as well from dev branch) I noticed big drop in visualization quality of the data in the LFP viewer, with big spikes of negative value overlaying the data. After some investigation I found out the negative values are added to the stream after each call to addToBuffer, distorting the visualization.

To be sure this is the case, I fed the buffer with a sine wave on 1 channel and made sure the data is smooth and not overflowing.

To Reproduce
DataThread plugin, LFP viewer and calling addToBuffer method to pass data with N amount of samples

Screenshots

Chunks of 768 samples being passed to addToBuffer

Chunks of 1536 samples being passed to addToBuffer

Chunks of 3072 samples being passed to addToBuffer

After I rolled back to v0.6.7 again, the problem disappeared.

Versions:

• OS: Win11
• GUI version: v1.0.1

Thanks,
Bruno

[anjaldoshi]

Hi @bgrgic-inbrain

Thanks for the detailed report.

In GUI v1.0 there was a breaking change in the way DataBuffer::addToBuffer() expects data to be arranged in memory, which affects all custom DataThread plugins. Prior to 1.0, the buffer layout could be sample‑major (e.g. raw_samples[i * NUM_CHANNELS + j], with channels interleaved per sample), but starting in 1.0 the samples for each channel must be stored contiguously before calling addToBuffer(). Concretely, if you have NUM_CHANNELS channels and N samples per callback, the buffer you pass should be in channel‑major order:

• All samples for channel 1: indices [0 … N-1]
• Then all samples for channel 2: [N … 2N-1]
• … and so on, up to channel NUM_CHANNELS.

The docs call this out here (see “Important: As of GUI version 1.0…”):
https://open-ephys.github.io/gui-docs/Developer-Guide/Open-Ephys-Plugin-API/Data-Threads.html#_CPPv412updateBufferv

If your custom DataThread is still writing data in the old interleaved (sample‑major) format before calling addToBuffer(), the GUI will interpret those values with the new channel‑major assumption, which can manifest exactly as large negative “spikes” or otherwise corrupted traces in the LFP Viewer. The fix is to either:

• Change your acquisition code to produce channel‑major data directly; or
• Add a reordering step similar to the example in the docs, which converts from interleaved raw_samples[j + i * NUM_CHANNELS] to channel‑major scaled_samples[i + j * MAX_SAMPLES_PER_CHANNEL] before calling addToBuffer().

Once the data passed to addToBuffer() is channel‑major, the artifacts you are seeing in v1.0.x should disappear and behavior will match what you observed in v0.6.7.

[bgrgic-inbrain]

Hi @anjaldoshi,

thank you for your prompt and helpful response. This change in DataThread from interleaved to contiguous completely flew past me.

It makes sense why after I reduced the number of channels to 1, I could see the sine wave again as it wasn't spread out over all of the channels.

However, in the scenario I have shown above, scaled_samples[i + j * MAX_SAMPLES_PER_CHANNEL] = raw_samples[j + i * NUM_CHANNELS] should be equal in both interleaved and contiguous cases if the number of channels is 1.
My use case naturally won't be with 1 channel so maybe the scenario is unrealistic and irrelevant.

[anjaldoshi]

You are absolutely right that for NUM_CHANNELS = 1, the memory layout for interleaved and contiguous is identical.

However, the artifacts in your screenshots (periodic spikes occurring at the end of each buffer callback) strongly suggest one of two issues is persisting in your test setup:

1. Mismatch in Channel Count: Even if you are only generating a sine wave for one channel, if the DataStream or sourceBuffers are still initialized with NUM_CHANNELS > 1 in updateSettings(), the GUI will read the buffer expecting contiguous blocks for all channels.
2. numSamples Argument: Check the last argument you are passing to addToBuffer(). If you pass a value larger than actual number of samples available, the GUI will attempt to read past the valid data range.

I tested this locally with a single-channel sine wave implementation, and I see a perfect sine wave with no artifacts: