Contributions:PAC: Difference between revisions

Latest revision as of 18:16, 2 May 2024

A demo of the Phase-Amplitude Coupling visualization

Synopsis

PAC, or phase-amplitude coupling, shows the entrainment of a certain frequency band to the power of another frequency band. In other words, the phase of one type of neural activity correlates with the amplitude of another. The dominant phase and the location of this entrainment can change for varying tasks. With this implementation, you can view the entrainment happening as the task is being completed, which can help you focus on the responsive electrodes for a certain task.

The inspiration for this visualization comes from Dr. Kai Miller's Human motor cortical activity is selectively phase-entrained on underlying rhythms paper. Specifically, Figure 5, shown below.

One can see that Section C and D are reproduced with the Phase-Amplitude Coupling (PAC) module in real-time.

Versioning

Authors

Will Engelhardt (engelhardt@neurotechcenter.org)

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 phase-amplitude coupling.

Signal Processing Pipeline

To allow for maximal flexibility, the pipeline is set up to compute Spectral Estimation in parallel with the phase-amplitude coupling computation. The pipeline for the Spectral Estimation is already described here.

Below is the diagram describing the pipeline for phase-amplitude coupling.

BCI2000 Signal Processing Pipeline

Within the BCI2000 architecture, the figure depicts the Signal Processing pipeline with the PAC Filter.

Decimation filter: Used to reduce the number of samples from the source module. This should be used if the sampling rate is too high to process a sample block size within the necessary time.
Spatial filter: Common Average Reference the data to isolate unique neural activity.
IIR Bandpass: Bandpass the desired frequency range for your phase or amplitude signal
Hilbert filter: Compute the Hilbert filter on the bandpassed data.
PAC filter: Combines the data from the amplitude and phase and groups the output data by phase bins.
- Output: Z-score of amplitude for each phase, with the range [-π, π).
SignalSharingDemo: Enables an outside connection to the BCI2000 data by using shared memory. This is how we can see the data in Python.

Parameters

The PAC Module contains many parameters from the various filters in the Signal Processing Pipeline. Refer to those pages' documentation for specific on the individual parameters. There are additionally a couple of parameters specific to the PAC filter itself.

AngleDecimation	Number of degrees of resolution. This inversely specifies the number of bins that the phases are grouped into. Must be a denominator of 360 degrees, otherwise it will be rounded to one. For example, a value of 10 will create 36 bins.
SlidingWindow	Amount of time to hold past data for. Set to 0 to hold for the whole run. Regardless of this parameter, when a New Trial occurs the data resets.
IncludeDeviation	Enable to double the size of the output and include the standard deviation of the average amplitude for each phase bin. This will be the 2nd half of the output. If this is enabled, currently the Python script will have to be changed.

Since we have a parallel filter chain with equivalent subchains, we will have two subchains with the same parameter names. These will be included under the tabs Filtering: Amplitude and Filtering: Phase. In these two subchains, a few requirements must be met.

Delay must be the same
Filtering: Amplitude must have the Hilbert OutputSignal of Hilbert envelope.
Filtering: Phase must have the OutputSignal of Hilbert phase.
Downsample must be disabled (since the two subchains will likely have varying frequencies, downsampling will mismatch the number of samples)

States

PAC_TrialNumber	Number that increments every time button New Trial is pressed. Changing this state resets all data.
PAC_TrialType	Keeps track of the trial type.

Offline Use

To run the Phase-Amplitude Coupling pipeline on data that has already been acquired, use the FilePlayback module. This plays back the BCI2000 data file as if the data is currently being recorded. You can completely replicate the results of the visualization.

@@ Line 13: / Line 13: @@
 ==Installation==
-#Python 3.7+ needs to be installed. [https://www.python.org/downloads/| You can download the lastest version here].
+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 phase-amplitude coupling.
-#A couple additional packages are used in this visualization. Run the following segments using <code>pip</code> in the command line.
-#*PyQtGraph 0.13.3+: <code>pip install pyqtgraph</code>
-#*PyQt5: <code>pip install PyQt5</code>
-#*Numpy: <code>pip install numpy</code>
-#*SciPy: <code>pip install scipy</code> (only the stats package is required)
-==Include in BCI2000==
-Update your svn to at least r7931 to include the PAC Filter. Re-run CMake (<code>BCI2000/build/Configure.sh.cmd</code>), making sure to include enable BUILD_CONTRIB flag. Once this is Configured and Generated, open your Visual Studio project and build the PAC project (<code>Contrib/SignalProcessing/PAC</code>). A default batch file is built into the batch folder (<code>PAC_SignalGenerator.bat</code>), along with the python scripts in (<code>batch/pac_visualizations</code>).
-<code>connectBCI2000Batch.py</code> is configured to let you start your own batch file (with PAC as the SignalProcessing module), and then execute this script to connect to the BCI2000 started with the batch file.
-<code>runPAC-BCI2000.py</code>, by contrast, is configured to start its own BCI2000 instance along with the visualization. This file can be customized to fit your needs. You can change anything in the <code>initBCI2000</code> function by using the [[Programming Reference:BCI2000Remote Class|BCI2000Remote Class]].
-<syntaxhighlight lang="python">
-    #configure to customize your BCI2000 instance
-    def initBCI2000(self, bci):
-        bci.WindowVisible = True
-        bci.WindowTitle = 'BCI2000: Phase-Amplitude coupling'
-        bci.SubjectID = 'test'
-        bci.Connect()
-        bci.Execute('cd ${BCI2000LAUNCHDIR}')
-        #FilePlayback is helpful if you already have the data file
-        #bci.StartupModules(('FilePlayback --PlaybackFileName=..\data\BJH041\ECOGS001R02.dat', 'PAC', 'DummyApplication'))
-        bci.StartupModules(('SignalGenerator', 'PAC', 'DummyApplication'))
-        bci.Execute('Wait for Connected')
-        bci.LoadParametersRemote('../parms/PAC/pac_pipeline.prm')
-        bci.Execute('SET PARAMETER SamplingRate 5000Hz')
-        bci.Execute('SET PARAMETER SampleBlockSize 100')
-        bci.Execute('SET PARAMETER AngleDecimation 6')
-        #bci.Execute('SET PARAMETER TransmitChList 2-5') #can choose whatever channels you want
-        bci.SetConfig()
-        bci.Start()
-</syntaxhighlight>
-By creating various files with different <code>initBCI2000</code> functions, this functionality can easily replace batch files.
+==Signal Processing Pipeline==
+To allow for maximal flexibility, the pipeline is set up to compute Spectral Estimation in parallel with the phase-amplitude coupling computation. [[User Reference:SpectralEstimator|The pipeline for the Spectral Estimation is already described here]].
-==Signal Processing Pipeline==
+Below is the diagram describing the pipeline for phase-amplitude coupling.
-Below is the diagram showing how this is made possible.
 [[File:PAC Signal processing pipeline.png|center]]
 ===BCI2000 Signal Processing Pipeline===
@@ Line 59: / Line 28: @@
 #'''[[Contributions:HilbertFilter|Hilbert filter]]:''' Compute the Hilbert filter on the bandpassed data.
 #'''PAC filter:''' Combines the data from the amplitude and phase and groups the output data by phase bins.
+#*Output: Z-score of amplitude for each phase, with the range [-π, π).
 #'''[[Programming Reference:SignalSharingDemo Signal Processing|SignalSharingDemo]]:''' Enables an outside connection to the BCI2000 data by using shared memory. This is how we can see the data in Python.
-===Python===
-threads are running within the Python scripts.
-#'''Data acquisition:''' Connects to the shared memory address and continually updates the local data when there is new data to be acquired.
-#'''BCI2000 Connection:''' Using [[Programming Reference:BCI2000Remote Class|BCI2000Remote]], we have a two-way connection between Python and BCI2000. This is used for updating and acquiring states and parameters. This can also be used to start a BCI2000 instance, instead of the common practice of using a batch file.
-#'''Visualization:''' The main thread of the Python script creates an interactive visualization with PyQtGraph. When the visualization is interacted with, BCI2000 states are updated accordingly.
 ==Parameters==