Contributions:CCEPFilter

An demo video of the CCEP Filter with VisualizeBCI2000.

Introduction

Cortico-cortical evoked potentials (CCEPs) are generated as a response to stimulation within the cortical zone. To best view this response, the CCEP filter time locks the signal to the stimulation and allows the user to view the CCEPS from every recording electrode. There are many adaptable parameters to include flexibility for a variety of experiments.

Location

http://www.bci2000.org/svn/trunk/src/contrib/SignalProcessing/CCEPFilter

Versioning

Authors

Will Engelhardt (engelhardt@neurotechcenter.org)

Version History

05/17/2023 - First working version

Source Code Revisions

Initial development: 7199
Tested under: 7303
Known to compile under: 7364
Broken since: --

Installation

See the Installation section on the Python Visualization page to see how to install the necessary packages and how to run demo files! Once that is all set up, you can return to this page to understand the specific parameters for the CCEPs.

Processing Details

The CCEP filter has two parts - a C++ filter in the Signal Processing pipeline, and the Python filter outside of the BCI2000 chain.

BCI2000 filter
- The filter receives the raw data from the Source module, then time-locks the data based on the user-defined CCEP parameters.
- When all the data is collected, the state CCEPTriggered will pulse to let the Python filter know data is ready to be visualized.
Python filter
- Data is received through the SignalSharing feature. Specifically, the parameter ShareCCEPFilter is set to a valid port to share the data.
- When CCEPTriggered is true, the incoming data is further processed and plotted. The only processing this filter does is to calculate the area under the curve (AUC), then determine which channels have a significant response based on the threshold standard deviation set by the user. The raw values are given in the table, and the top most significant channels are visually shown.
- If Sort Channels is enabled, all the significant channels will be at the top. They are then organized based on their original order, to maintain electrode grouping. If they were sorted purely on highest to lowest AUC, it would be very difficult to tell which general areas are responding.

Python Settings

Threshold (STD)

This defines the threshold to determine a CCEP response. This value should be adjusted to maximize the number of significant channels shown, while not going over. If the value is too low, there will be more significant channels than visualized windows. This would only show you the electrodes which were originally at the top of the list, which might lead you to disregard the bottom electrodes.

Max Windows

The maximum amount of windows displayed. If you desire all the transmitted channels to be shown, set this max value to the number of channels or greater.

x₀

The minimum shown value of the x-axis for all windows, in milliseconds. You can set this to a negative value to show baseline data before the CCEP.

Hold Plots

The number of plots to keep on a window. Set to 0 to hold all plots, until manually cleared with "Clear Figures".

Average CCEPs

Enable to display the average of the plots in addition to the single trials.

Sort Channels

Disable to keep the order of the channels unchanged. If there are more transmitted channels than windows shown, the shown windows will simply be the first in the list.

Save figures on refresh

Currently broken. Enable to make sure the visualizations are never lost, as every time the plots are cleared they would first be saved. This can get cumbersome with many saved files.

BCI2000 Parameters

OnsetExpression

Expression that defines the stimulus onset. Ideally, this should be a hardware trigger to have the most precise time-locking. This expression should be true when the stimulation is triggered. See the Expression syntax page for more information.

Duration settings

These parameters all should have units of time (e.g. milliseconds), or auto.

BaselineEpochLength

The duration of desired baseline data. This baseline data is helpful for visualizing the data before the stimulation, and is also used to calculate the average signal value from which the threshold is calculated.

CCEPEpochLength

Duration of time after the baseline and latency. Essentially the amount of time that is needed to view the CCEP.

Trigger settings

These settings are best used for stimulation trains, however they can be used to specify a software trigger for the stimulation onset as well. If this used for a train, PreStimLength and PostStimLength should specify the length of the train. If it is used for software trigger, they should be the same as the Baseline and CCEP EpochLength.

SoftwareTrigger

If enabled, the filter will use the PreStim and PostStim Length parameters to define the shape of the output. This is helpful if the provided trigger is an estimate of the stimulation onset, because then the filter and save all the needed data to the output, where the python visualization can auto-detect the precise stimulation onset.

PreStimLength

If SoftwareTrigger is enabled, this will be the length of the saved baseline data.

PostStimLength

If SoftwareTrigger is enabled, this will be the length of the post-baseline data. This should be the length of the train if you are visualizing a high frequency stimulation train.

Counting settings

These parameters must be integers as they specify a quantity to count.

TriggerPeriodEnd

Enable this flag to pulse CCEPTriggered at the end of the period instead of the beginning. This can be used in combination with OnsetPeriod.

EpochsToAverage

Average this number of CCEPs before sending it to Python to visualize. This is helpful if the OnsetExpression is frequently true within a short period of time, to lower the load on Python updating.

OnsetPeriod

The period in which you expect the CCEPs to occur. This can be specified in time units or without units.

Time units: The minimum time between detection of CCEPs. For example, if this is 2s, OnsetExpression will not be true for 2s after a sample that is is triggered. After 2 seconds, it will start being evaluated again.
Without units: Skip one less than this number of CCEPs. For example, for high-frequency stimulation, the OnsetExpression might be true 50 times in 1 second. Therefore, you would want to set this number to 50. If you are also averaging the plots, it will only average the signals specified by this period.

This is helpful if you want to visualize a time range in which the OnsetExpression is met multiple times.