Programming Reference:SignalSharing Python Demo

Demo example of the flexibility of visualizations with Python

Location

src/core/SignalProcessing/SignalSharingDemo/PythonClientApp

Synopsis

The SignalSharing Python Demo demonstrates how to make a complex real-time visualization in Python using data parallelly collected in BCI2000.

Function

The SignalSharing Python Demo creates a basic visualization in Python using the data collected in BCI2000. Since this is done outside of the BCI2000 processing loop, rendering visualizations can take as long as needed. Using Python also allows for the use of the numerous packages that are available to create complex figures.

This Demo has two parts, a source and a client. The source is the BCI2000 SignalProcessing Filter, and the client is the Python app that visualizes the data:

1. SignalSharing Signal Processing Filter: This is the same filter as what is used for the SignalSharingDemo with the C++ application. Please refer to that page for details on the BCI2000 Filter aspect.
2. Python visualization app: A simple Python script that connects with the port that is being used to synchronize the data transfer, and updates the visualization as data is being streamed.

Source vs Client

The BCI2000 data is sent according to the format specified in BCI2000 Messages Wiki page, as Descriptor=4: Visualization and Brain Signal Data Format, then Descriptor Supplement=1: Signal Data, then data type 2.

With this demo, BCI2000 and the Python script must be run on the same computer. The script expects the data stream to be sending the name of the shared memory, which will only happen if they are both on the same computer. It is possible to grab BCI2000 data from another computer, and is implemented in the C++ SignalSharing Demo. If on separate computers, the actual data points are being shared instead of the memory name. Implementing this would require a simple extension of this demo.

How to run

1. Build BCI2000 as you would, make sure to check BUILD_DEMOS
2. Make sure the SignalSharingDemo works first
3. Navigate to src\core\SignalProcessing\SignalSharingDemo\PythonClientApp, where there is a batch file and a Python file. Copy the batch file to your BCI2000 batch folder
4. Run the Python file. For example from the command line, navigate to the folder and run python SignalSharingPythonDemo.py
5. Run the batch file, and press "Start Run" (it already sets the configuration, it won't work it you press it multiple times)
   • If you change the Parameter SignalSharingDemoClientAddress, make sure to also change it in the Python script

Python Script

Here is the same code that is on the SVN (r7815)

#import libraries
import socket
from multiprocessing import shared_memory
import matplotlib.pyplot as plt
import numpy as np

#user input
HOST, PORT = "localhost", 1879
print("Waiting for BCI2000 on %s at port %i" %(HOST, PORT))

#initialize variables
CHANNELS = -1
ELEMENTS = -1
SPACE = 32 #ascii code for space
EMPTY = b''
lastEl = SPACE
setProps = False
gotMemoryName = False
chNames = []
myBuffer = [] #add stream to this buffer, items separated by space
figure, ax = plt.subplots(figsize=(10, 8))
ax.set_xlim(-2,2)
ax.set_ylim(-2,2)
figure.set_facecolor((0,0,0,1))
ax.set_axis_off()
ax.set_frame_on(0)
figure.canvas.draw()
chEndIndex = 1

#attempt connection to specified port
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.bind((HOST, PORT))
    s.listen(1)
    conn, addr = s.accept()
    with conn:
        print('Connected by', addr)
        try:
            while True: #go until we manually stop program
                while setProps is False: #get properties
                    #get stream
                    stream = conn.recv(128) 
                    #split into names
                    names = stream.split(b' ')
                    #remove any empty characters
                    while(EMPTY in names):
                        names.remove(EMPTY)

                    #combine name if it is split up
                    if lastEl != SPACE and stream[0] != SPACE:
                        #last channel name was split apart
                        namePart = names.pop(0)
                        myBuffer[-1] += namePart
                    #save in case it was a space
                    lastEl = stream[-1] 

                    myBuffer = np.append(myBuffer, names)
                    if len(myBuffer) > chEndIndex+1 and CHANNELS == -1:
                        # we have at least part of ch information
                        chID = myBuffer[1] # either start of channel names or number of channels
                        if chID==b'{': #start of channel names
                            while chEndIndex < len(myBuffer):
                                if myBuffer[chEndIndex] != b'}': #end of channel names
                                    chEndIndex += 1
                                else:
                                    chNames = myBuffer[2:chEndIndex]
                                    CHANNELS = len(chNames) #we have all the channels
                                    break
                        else:
                            CHANNELS = int(str(chID, encoding='utf-8'))
                            chNames = range(1,CHANNELS+1)
                            #chEndIndex -= 1
                    
                    if CHANNELS == -1:
                        continue 
                    #-----DONE WITH CHANNELS-----#

                    #element size is next
                    elIndex = chEndIndex+1                      
                    if elIndex+1 < len(myBuffer): #wait for extra element in case element number is split up
                        #got element number
                        el = myBuffer[elIndex]
                        elementString = str(el, encoding='utf-8')
                        ELEMENTS = int(elementString)

                    if CHANNELS == -1 or ELEMENTS == -1:
                        continue
                    #-----DONE WITH CHANNELS AND ELEMENTS-----#


                    #initialize variables once we have channels and elements
                    phi = np.zeros((CHANNELS, ELEMENTS))
                    bla = np.zeros((ELEMENTS,1))
                    lineArr = list(range(CHANNELS))
                    for i in range(0,CHANNELS):
                        lineArr[i], = ax.plot(bla, bla)

                    print("Properties: Channels: %i, Elements: %i" %(CHANNELS, ELEMENTS))
                    setProps= True

                #block until we get data
                stream = conn.recv(128)
                if not gotMemoryName:
                    for b in stream:
                        if b==47: #47=b'\', right before memory name
                            #get memory name
                            streamName = stream.split(b'/')[1] #mem name right after
                            byteName = streamName.split(b'\x00')[0]
                            mName = str(byteName, encoding='utf-8')
                            mem = shared_memory.SharedMemory(mName)
                            gotMemoryName = True
                            print("Connected to shared memory")
                            print("Visualizing data...")
                            
                else:
                    #update visualization with new data
                    data = np.ndarray((CHANNELS,ELEMENTS),dtype=np.double, buffer=mem.buf)
                    for ch in range(0,CHANNELS):
                        for el in range(0, ELEMENTS):
                            phi[ch, el] = el*2*np.pi/(ELEMENTS-1)

                        xdata = np.multiply(1+0.003*data[ch,:],np.cos(phi[ch,:]))
                        ydata = np.multiply(1+0.003*data[ch,:],np.sin(phi[ch,:]))
                        #update plots
                        lineArr[ch].set_xdata(xdata)
                        lineArr[ch].set_ydata(ydata)

                    #update figure
                    figure.canvas.draw()
                    plt.pause(0.01) #render update                   
        except:
            print('exception')
            conn.close() #close connection to client
        finally:
            print('disconnected')
            conn.close() #close connection to client

Conclusion

This demo shows how to grab data from BCI2000 and plot it in Python! The main advantage of this demo shows how to access the data in Python. Once this is done, Python's extensive library can be used to create complex, real-time visualizations and calculations!

See also

Programming Reference:SignalSharingDemo Signal Processing, Technical Reference:BCI2000 Messages, User Tutorial:BCI2000Remote