gebaSpike: User Guide Draft

Posted by Geoff, Published: 1 year, 2 months ago (Updated: 9 months, 2 weeks ago)

Now that you have installed gebaSpike, I will show you how you can go about using it. If you have not installed it, please see the installation instructions1. If you have any suggestions on features to add to gebaSpike, or bugs that you encounter, feel free to let me know. Keep in mind that this tool does not replace Tint. It simply was a quicker way for me to sort my cells, and thus it is missing some functionality that you get with Tint. I suggest using this in tandem with Tint. You can make cuts in gebaSpike, the load them in Tint to visualize the auto-correlations, spatial information, etc. I have also included a YouTube video below where I go over how to use gebaSpike as well as how it compares to Tint, feel free to check it out.

Plotting Data in gebaSpike:

  1. Launch gebaSpike: Once you launch the GUI (python -m gebaSpike), you should see the "gebaSpike - Main Window" pictured below.

    Fig 1. the Main Window of the gebaSpike GUI.

  2. Choose session(s): Located the upper left corner of the Main Window you will see a "Choose Filename" button. Press this and select (a) session(s) that you'd like to analyze. Once you have chosen the appropriate session(s), the "Filename" text-field will be updated. If you have chosen a single session, the "Cut Filename" text-field should be filled with the appropriate filename (based upon the current value within the Tetrode drop-down menu). However, if you chose multiple sessions there is no default filename convention, therefore the "Cut Filename" text-field will remain as the default value and you will have to choose your cut filename. A single-session example is pictured below.

    Fig 2. Visualization of the user choosing a single session to analyze. 

  3. Choose Tetrode: Once the session has been chosen, the "Tetrode" drop-down menu (located below the "Choose Cut Filename" button) was populated with the list of active tetrodes belonging to the session. Note: If a .cut file does not exist for the tetrodes, they will not be populated in the Tetrode drop-down menu. Also, if you chose multiple sessions, the drop-down menu will only include Tetrodes that exist in all chosen sessions. The Tetrode drop-down menu will simply change the "Cut Filename" value based upon the current value. It follows the default nomenclature for .cut files: SessionName_TetrodeNumber.cut. If your .cut filenames follow this default nomenclature, feel free to simply use this drop-down menu.
  4. Choose Cut Filename: this step is required for all multi-session use cases as there is no default nomenclature for the .cut files. If you are using the single-session mode and your .cut filenames follow the default nomenclature, then feel free to skip this step. However, if you have an alternative naming convention (or you want to use a .clu file), you will have to type the correct .cut/.clu filename value within the "Cut Filename" field, or use the "Choose Cut Filename" button and navigate to the appropriate file. If you are using multiple-sessions there will be some validation later where it will compare the sum of the spikes of a given tetrode within all sessions, and compare to the number of spikes contained within the chosen .cut file. This should give you some peace of mind that the file combination is appropriate.
  5. Plot the Waveforms / Feature Space: In order to begin sorting you must press the "Plot" button located in the lower left corner of the Main Window. This will plot the data contained in the file located in the "Cut Filename", pictured below.

    Fig 3. with appropriate files and parameters, you can plot the spikes. The image above depicts an example of what that would look like. On the left panel you will see the three dimensional (optionally two dimensional) feature space, and on the right panel, you will see the tetrodes plotted similarly to what you would see within Tint.

    • You will see in the left graph window there will be a 3D feature space where the X, Y, and Z dimensions are what is selected in the X-Axis, Y-Axis, and Z-Axis drop-down menus above the plots.
    • The right graph window will plot all of your waveforms within the .cut file.

gebaSpike Feature Space

Once you have plotted the data, you will see that the left graph (on the Main Window) contains the feature space representation of each of the spikes within the chosen .cut/.clu file. I thought of Offline Sorter when I created this graph. Back in the days when I used Offline Sorter, the sorting process was entirely manual. Thus we found isolated clusters within the 3D (or 2D) feature space, created a Region of Interest (ROI) around the cluster, and then added the unit. I had that in mind when creating this plot, however I have yet to figure out how to draw an ROI on an OpenGL object within PyQtGraph. It can likely be done, but I felt that the time necessary to implement this feature was not worth it as I needed to get to processing the data I already had. This feature already exists within Tint (in 2D feature space), so I figured the end-users could use Tint's functionality for adding the units manually, and then move over to gebaSpike for cleaning the cells.

You can change the features that are plotted by simply modifying the "X-Axis", "Y-Axis", and "Z-Axis" drop-down menu values. I was thinking about making it so that when the end-user changes any of these drop-down menus that the feature space plot refreshes (let me know if you want that feature). However, at this point you would just have to re-plot the data. 

This feature space plot is largely unused by me so it is lacking features that you'd might expect. If you feel like it would benefit your cluster cutting/cleaning by having a fully functioning feature space, then feel free to let me know. Also note: when you clean the cells, the respective points within the feature space do not get updated. This should be an easy change to the code, just feel like it would take more time updating a plot that I don't look at.

Navigating the Feature Space Plot:

  • Zoom: scroll with the Middle Mouse Wheel.
  • Pan: hold the Middle Mouse Button, and drag the cursor.
  • Rotate: hold the Left Mouse Button, and drag the cursor.

Cutting with gebaSpike

After the session has been plotted you will see that the right graph on the Main Window contains all the waveforms (besides the 0 cell) for the cells identified in Tint. This is the window where we are going to be performing all our cuts, and will be the main focus of your time using gebaSpike.

  1. Select Spikes to Cut: When using gebaSpike to cut, you must draw a line segment across the spikes that you want to invalidate (or move to another cell). You draw line segments by clicking the Left Mouse Button on one of the graphs and dragging. Any spike that intersects with our line segment will be considered invalid, so ensure that your line is drawn appropriately. An example of this is pictured below.

    Fig 4. An example of the user defining a cut. In this example it is within the 3rd channel of Cell 3. The cut is indicated by the drawn line segment. Any of the waveforms within channel 3 that intersect with this line segment will be moved to the user defined cell value.

    In order to simplify how the code determines which spikes are cut, I make an assumption about which channel the user is drawing on. When you begin drawing the line segment, the channel that you begin the line segment on is determined to be the channel in question. Therefore, in the example above, we want to cut the cells in channel 3, therefore we must begin our line within the boundaries of Channel 3. Note: You can end the line segment in whichever channel you want, it will only look at spikes within the channel that you began the line segment on. This was a way for me to speed up the code by not having to guess which channel the user is trying to cut. I should overlay the boundaries on top of this plot to avoid the confusion of where Channel X ends and Channel (X+1) begins.
    • You can tweak the start and end point of the cut line by dragging the circular handles located at each of the ends of the line.
    • There can only be one cut line at a time currently, so you could also re-draw simply by using the same method above that was used to draw the first one. Upon beginning to draw this new cut line, the old one will disappear.
    • Right now we only have this simple line, it was easy to simply calculate the line's equation, and then determine where it intersects with each of the spikes. PyQtGraph does allow for other ROI shapes, I just haven't added them yet (and likely won't unless there's a need for it).
  2. Determine Where to Move Invalid Spikes: At the top right corner of the Main Window you will see a Move to Cell value. This is the Cell ID that these spikes will be moved to once you make the cut. It will default to Cell 0, which is the dummy cell in Tint. However, you can put whichever Cell ID you want (Tint has a maximum of 30 cells so I do have some validation to ensure that you are within the range of 0 - 30). 
  3. Make the Cut: Now we can confirm the cut. If we press on the Middle Mouse Button (or alternatively the ~/` button) when your cursor is hovering over the appropriate plot (in our case over the Cell 3 plot). It will calculate the slope of the line segment, which spikes it intersects with the line segment, and move these spikes to the Move to Cell value. If the Cell ID in the Move to Cell field has not already been plotted, it will reconfigure the plots appropriately.
  4. Undo: There is an Undo button located at the bottom of the Main Window, when pressed this will undo the last cut that was made. The previous 5 cuts will be saved so you have up to 5 undo's. Theoretically I could make this value much larger, I just figured 5 would be enough for now. Let me know if you want to have this be a user defined value.
  5. Save: Once you have finished cleaning your cells, you can save by pressing the "Save Cut" button located towards the bottom left of the Main Window. It will confirm that you want to overwrite any existing .cut/.clu files. Note you can change the "Cut Filename" field before saving if you want to create an entirely new .cut/.clu file.

Changing Max Number of Plotted Spikes

You might have noticed a "Max Plot Spikes" parameter (default to 2000). This field contains the number of spikes per cell which will be plotted at a given time. This is just to speed up the plotting, if you have a cell with 60k spikes it would be annoying to plot all those spikes. I have been performing the initial sort using MountainSort and converting that data to Tint. From my experience, MountainSort tends over-combine the cells, resulting in cells with spike counts that are much larger than you would get from KlustaKwik. So this functionality is mainly to help speed up my sorting, however Tint does have a similar feature with the "limit shows to X spikes" option.

Once you have chosen an appropriate Max Plot Spikes value, you can simply make a cut and all the cells will be re-plotted with that new value. I should make a re-fresh waveforms button so you don't have to perform a cut to enact these changes, however I figure that this process is easy enough. If you feel like you want a re-fresh waveforms button let me know.

Which Spikes are Chosen to be Plotted?

If you have a value of Max Plot Spikes that is smaller than the spike count of a given cell, you might be curious how gebaSpike chooses which spikes get plotted. I wanted to ensure that nay outlier spikes are included in the plot as they could most likely be invalid. Therefore, I begin by iterating through every X-value (time) of the waveform, finding the minimum and maximum for that X-value, and including the spikes that contain those min/max values. With Tint recording the data in 50 sample chunks, there will be a minimum and maximum for each of the 50 samples, and therefore there will be 100 "outlier" spikes chosen (could be that these aren't really outliers, they just reflect the boundaries at this time point). Note: when finding outliers, we discard the spikes that have been clipped so that we can maximize the amount of outlier spikes included. The remaining spikes are simply chosen at random.

Pop-Up Cutting Window

In our example shown, we only have 4 spikes, therefore it is easy to visualize the spikes within the Main Window. However, you can imagine having 30 spikes each with their own sub-plot would be difficult to visualize. Therefore I have made a Pop-Up window which will allow you to enlarge the waveform of a chosen spike.

To open this pop-up window press Shift Left Mouse Button on the waveform of the cell that you want to cut. An example of the pop-up is pictured below.


Fig 5. an example of a pop-up window. This should allow you to get a better view of the waveform as you are cutting if the Main Window gets crowded. 

Now you see a new window with two main graphs. The right graph contains an enlarged version of what you saw on the Main Window for our chosen cell (Cell 3). On the left is only one of the channels. You can change the channel that is plotted on the left by modifying the "Channel" drop-down menu. 

Spike sorting in the Pop-Up window is the same as the Main Window, you simply left click and drag on either the right or left graph, and confirm using the Middle Mouse Button.

References

  1. gebaSpike Installation: https://geba.technology/project/gebaspike-python-spike-sorting-software-tintaxona-data

Comments

Post Comment