`WaveDetector`

Overview

WaveDetector is a burst detection class designed to operate on a streaming sequence of spike frames. It identifies periods of coordinated neural activity (bursts), tracks where in space the burst began (on the chip), and estimates the time and direction of the burst propagation.

This detection is frame-by-frame, updating internal metadata as the system evolves. Bursts are determined based on a thresholded spike count that must be exceeded for a minimum duration.

Conceptual Timeline

A conceptual example showing spike counts and thresholds over time:

Time (frames)  →
Spike Count    ──────────────────────────────────────────────
                 ___        ___________
                /  ↑\      /           \
               /   | \____/             \___
              ↑    |                     ↑
              |    |                     |
       burstStart   burstPeak         burstEnd
                    (maxSpikes)

Key Features

Detects bursts that exceed a spike count threshold
Tracks: - When the burst starts - Where on the chip it starts (burstStartLocation) - Where the peak occurs (maxSpikesLoc) - How long the burst lasts
Determines direction: - If peak is right of start, burstOnLeft is returned - If peak is left of start, burstOnRight is returned

Typical Usage

WaveDetector sensor(WINDOW, configPath.c_str(), framesPerSec,
                    burst_size_threshold, burst_dur_threshold, 0.5);
ChannelWindow *window = sensor.getWindow();

for (int i = 0; i < total_frames; i++) {
    maxlab::FilteredFrameData frameData;
    auto status = maxlab::DataStreamerFiltered_receiveNextFrame(&frameData);
    if (status != maxlab::Status::MAXLAB_OK) continue;

    int waveVal = sensor.processFrame(frameData, i);

    if (waveVal == Wave::burstOnLeft || waveVal == Wave::burstOnRight) {
        WaveMetadata metadata = sensor.getMetadata();
        std::cout << "Burst started at: " << metadata.burstStartFrame
                  << ", Peak location: " << metadata.maxSpikesLoc << std::endl;
    }
}

Burst Detection Parameters

burst_size_threshold: percentage of active electrodes that must spike
burst_dur_threshold: minimum duration (in seconds) above threshold
BurstFinishedThreshold: time (in seconds) system must be quiet before the burst is considered over

Return Values

From processFrame() / checkBurst():

Wave::noBurst: no burst activity detected
Wave::burstStart: new burst detected
Wave::bursting: mid-burst
Wave::burstOnLeft: completed burst with left-to-right propagation
Wave::burstOnRight: completed burst with right-to-left propagation
Wave::endShortBurst: detected activity that did not meet burst duration threshold

Members

class WaveDetector

Public Functions

WaveDetector(): Constructs a new Wave Detector object.

WaveDetector(int windowLength, const char *configPath, int framesPerSec, float burst_size_threshold, int burst_dur_threshold, int BurstFinishedThreshold)

Constructs a new Wave Detector object and initializes the window.

Parameters:

windowLength – int length of the window
configPath – c-style string containing the full path of the electrode config
framesPerSec – int sampling rate in frames per second
burst_size_threshold – float fraction of active electrodes needed to start a burst
burst_dur_threshold – int minimum burst duration (in seconds)
BurstFinishedThreshold – int minimum time (in seconds) of low activity to confirm burst ended

~WaveDetector(): Destroys the Wave Detector object.

ChannelWindow *getWindow()

Returns the window.

Returns:: pointer to ChannelWindow

WaveMetadata getMetadata()

Gets metadata of the Wave Detector.

Returns:: WaveMetadata struct

void shiftWindow(maxlab::FilteredFrameData frame)

Shifts the window, adding a new frame.

Parameters:: frame – maxlab::FilteredFrameData frame to add to the window

int processFrame(maxlab::FilteredFrameData frame, int frameNo)

Processes a frame.

Shifts the window, and returns the status of the burst

Parameters:

frame – maxlab::FilteredFrameData frame to process
frameNo – int frame number when frame was received

Returns:

int

int checkBurst(int frameNo)

Checks the direction of a burst.

Parameters:: frameNo – int frame number of the most recently received frame
Returns:: int, corresponds to enum Wave

struct WaveMetadata

Metadata tracking the state of a neural burst event.

Public Members

bool burstOnsetComplete: True once the burst has peaked and started to fall

bool bursting: True while a burst is active

int burstStartFrame: Frame when the burst started

int burstStartSpikeCount: Spike count when burst started

float burstStartLocation: X-location of onset of burst

int maxSpikes: Peak spike count observed during burst

int maxSpikesFrame: Frame when peak spike count occurred

float maxSpikesLoc: X-location where peak spike count occurred

int framesAboveThreshold: Number of frames the spike count stayed above threshold

int noSpikeFrameCount: Number of frames spike count stayed below threshold

enum Wave

Wave enum.

Values:

enumerator noBurst: Culture is not currently bursting

enumerator bursting: Culture is currently bursting

enumerator burstStart: Burst just started

enumerator endShortBurst: Burst ended but was too short to be significant

enumerator burstOnLeft: Burst ended, and it started on the Left

enumerator burstOnRight: Burst ended, and it started on the Right

Old Example

Someone should change this (me).

#include <iostream>
#include "hal.h"

#define SYS_START_BUFFER 50000

int main(int argc, char *argv[]) {
    maxlab::verifyStatus(maxlab::DataStreamerFiltered_open(maxlab::FilterType::IIR));

    int sampleRate = 10000;

    // ignore system startup activity
    for (int i = 0; i < SYS_START_BUFFER; i++) {
        maxlab::FilteredFrameData frameData;
        maxlab::Status status = maxlab::DataStreamerFiltered_receiveNextFrame(&frameData);

        if (status == maxlab::Status::MAXLAB_NO_FRAME) {
            i--;
            continue;
        }
    }

    char *configPath = "/home/mxwbio/config.cfg";

    // window length, configuration path, burst threshold, min length, hz
    WaveDetector wd = WaveDetector(200, configPath, 0.1, 1000, sampleRate);

    // examine the culture for 20 seconds
    for (int i = 0; i < 200000; i++) {
        maxlab::FilteredFrameData frameData;
        maxlab::Status status = maxlab::DataStreamerFiltered_receiveNextFrame(&frameData);

        if (status == maxlab::Status::MAXLAB_NO_FRAME) {
            i--;
            continue;
        }

        // extend the window and check for burst waves
        int val = wd.processFrame(frame, i + 200 + SYS_START_BUFFER);

        if (val == Wave::leftToRight) {
            cout << "Culture bursted left to right!" << endl;
        } else if (val == Wave::rightToLeft) {
            cout << "Culture bursted right to left!" << endl;
        }
    }

    maxlab::verifyStatus(maxlab::DataStreamerFiltered_close());
}

WaveDetector