Contributions:CCEPFilter: Difference between revisions
Wengelhardt (talk | contribs) |
Wengelhardt (talk | contribs) |
||
| (11 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
[[Image:CCEP gif.gif | |||
[[Image:CCEP gif.gif|thumb|800px| An demo video of the CCEP Filter with VisualizeBCI2000. ]] | |||
==Introduction== | ==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. | 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. | ||
| Line 19: | Line 21: | ||
*Broken since: -- | *Broken since: -- | ||
== | ==Installation== | ||
See [[Python Visualizations#Installation|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 [[User Reference:SignalSharing|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<sub>0</sub>=== | |||
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. | |||
====OnsetExpression | ==BCI2000 Parameters== | ||
Expression that defines the stimulus onset. See the [[User Reference:Expression Syntax | Expression syntax page]] for more information | ===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 [[User Reference:Expression Syntax | Expression syntax page]] for more information. | |||
=== | ===Duration settings=== | ||
These parameters all should have units of time (e.g. milliseconds), or auto. | These parameters all should have units of time (e.g. milliseconds), or auto. | ||
====''BaselineEpochLength''==== | |||
====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. | 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. | 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. | |||
These parameters must be integers | ====''PreStimLength''==== | ||
==== | If SoftwareTrigger is enabled, this will be the length of the saved baseline data. | ||
====''PostStimLength''==== | |||
====OnsetPeriod==== | 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. | |||
==See also== | ==See also== | ||
[[User Reference:Filters]], [[Contributions:SignalProcessing]] | [[User Reference:Filters]], [[Contributions:SignalProcessing]], [[Python Visualizations]], [[Contributions:PAC]] | ||
[[Category:Contributions]] | [[Category:Contributions]] | ||
Latest revision as of 18:40, 30 July 2025
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.
x0
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.
See also
User Reference:Filters, Contributions:SignalProcessing, Python Visualizations, Contributions:PAC