= Spike Sorting in Brainstorm = ''Author: Konstantinos Nasiotis'' <> {{attachment:spikesortingIntro.png||width="700"}} Spike sorting is an essential step in electrophysiology that provides information on the selectivity of individual neurons. The common practice that most spike sorters use, is to apply a threshold on a band-passed version of the raw signals, collect a few samples of the data around that threshold crossing, and then cluster those waveforms based on their shape. Multiple clustered shapes picked up from the same electrode would signify the presence of multiple neurons. This automatic clustering (unsupervised), although powerful, can often be inaccurate. Therefore, a manual inspection of the clusters is required. After the unsupervised step, users normally manually approve or modify the clusters created (supervised step). For more general information, users can consult [[http://www.scholarpedia.org/article/Spike_sorting|this non-technical article on Spike Sorting]]. Our goal was to allow users to perform both steps (unsupervised-supervised) within Brainstorm. There are currently several solutions for spike sorting and since we cannot accommodate all of them, we have embedded 3 widely used algorithms within Brainstorm – Waveclus, UltraMegaSort2000 and Kilosort. We understand that some users might not feel comfortable learning how to use a new spike sorter from scratch, therefore we created [[https://neuroimage.usc.edu/brainstorm/e-phys/ConvertToBrainstormEvents|this page]], so they can still use their spike sorter of preference (outside of Brainstorm), and later import the spiking events in Brainstorm using a compatible format. The next section shows how the users can perform the Unsupervised and Supervised steps of spike sorting, with the algorithms embedded within Brainstorm. <
> == Unsupervised Spike Sorting == {{attachment:ssUnsupervised.png||width="700"}} During the unsupervised spike-sorting step, the spike sorter assigns the spiking activity to individual neurons. When the unsupervised spike-sorting is completed, new events will be [[Tutorials/EventMarkers#On_the_hard_drive|created and linked to the raw file]] taken from the acquisition system. These events will be concatenated to the existing ones (button presses, trial onset etc.), or overwrite __the spiking-events__ that the acquisition system automatically assigned. {{{#!wiki note A backup of the events found in the unsupervised spike-sorting is saved in the file `events_UNSUPERVISED.mat`. }}} There is a collection of parameters that each spike sorter uses. In case a user needs to modify them, we have enabled this option on the window that pops-up before they are used. For performing the spike sorting, users have to drag and drop the links to the raw files into the Files to process box, press RUN, and navigate to the Electrophysiology toolbox. In the ''Unsupervised Spike Sorting'' tab, the spike sorter of their preference can be selected. {{attachment:ssWindow.png}} Once the unsupervised spike-sorting step is complete, a new set of events will be concatenated to the existing ones. Neuronal activity is assigned on each electrode based on the clustering that the spike-sorter performed. <
> {{{#!wiki note '''The following convention for the spiking events is used throughout this toolbox:''' “Spikes Channel channelLabel”, where channelLabel is the label of the electrode assigned by the acquisition system. If the acquisition system assigned the spikes' waveforms into more than one cluster/neuron during this automatic clustering, the neuronal events would be (e.g. for an electrode that picked up spikes from 3 neurons): “Spikes Channel channelLabel |1|”, “Spikes Channel channelLabel |2|”, “Spikes Channel channelLabel |3|” }}} <
> The following image shows the outcome of using an unsupervised spike-sorting process. 1. A new icon (SpikeSorterName Spike Sorting) will appear in the ytu288c-01 folder (WaveClus in this example). This icon is a link to the unsupervised spike-sorting files created from the spike-sorter. 1. New events are concatenated to those previously imported. These new events signify the neuronal activity on each channel. On this example, the spike sorter picked up 28792 spikes from a single neuron on channel with the label AD01, 18888 spikes from a single neuron on the channel with the label AD02, whereas the channel with label AD08 contained 2 neurons with 24475 and 2812 spikes respectively etc. {{attachment:ssShowSpikes.png}} For users that are interested in locating the outputs of the spike sorters, those files are placed in a folder with the suffix (“_Spikes”) within the database. The following section shows the windows with the different user selection options for each spike-sorter. At the end of each spike-sorter users can find the citation for each one. <
> === WaveClus 3 === When [[https://github.com/csn-le/wave_clus|WaveClus]] is selected as the spike sorter, the following window appears: {{attachment:WaveclusWindow.gif}} In this process, the user can select: * '''Maximum RAM to use''': Before the spike sorting, the signals are demultiplexed to save one file per channel. The larger the RAM selected is, the faster this process will perform. Make sure a high portion of your computer’s RAM is selected. * '''Parallel processing''': Activate the parallel toolbox and run processes in parallel. Greatly improves the speed of the process (requires Matlab’s parallel toolbox). * '''Apply SSP/ICA''': See the section [[https://neuroimage.usc.edu/brainstorm/e-phys/SpikeSorting#Artifact_removal_before_spike-sorting|Artifact removal before spike-sorting]]. * '''Create images''': The waveclus algorithm allows saving of a high-res image of the clusters created. However it affects the speed of the process. * '''Parameters''': Parameters of the algorithm (file ''set_parameters.m''). '''Folders''' * Demultiplexed files are saved in the Brainstorm temporary folder: <
> ''TmpDir/Unsupervised_Spike_Sorting/protocol_name/subject_name/data_name'' * To get the temporary folder: Run ''bst_get('BrainstormTmpDir')'' in the Matlab command window. * WavClus output: Saved directly in the Brainstorm database folder, in the same folder as the input raw file. To find this folder easily, right-click on the Link to raw file > File > Show in file explorer. '''References''' * Quian Quiroga R, Nadasdy Z, Ben-Shaul Y, [[https://pubmed.ncbi.nlm.nih.gov/15228749/|Unsupervised spike detection and sorting with wavelets and super-paramagnetic clustering]], '''Neural Computation''', 2004 <
> === UltraMegaSort2000 === When the [[https://github.com/danamics/UMS2K|UltraMegaSort2000]] spike sorter is selected, the following window appears: {{attachment:UMSWindow.gif}} In this process, the user can select: * '''Maximum RAM to use''': Before the spike sorting, the signals are demultiplexed to save one file per channel. The larger the RAM selected is, the faster this process will perform. Make sure a high portion of your computer’s RAM is selected. * '''Parallel Processing''': Activate the parallel toolbox and run processes in parallel. Greatly improves the speed of the process (requires Matlab’s parallel toolbox). * '''Apply SSP/ICA''': See the section [[https://neuroimage.usc.edu/brainstorm/e-phys/SpikeSorting#Artifact_removal_before_spike-sorting|Artifact removal before spike-sorting]]. * '''Filtering parameters''': The RAW signals need to be bandpass filtered before given as an input to the spike sorter. The two fields allow the user to select the lower and upper cutoff frequencies respectively. Make sure the upper cutoff frequency is set to a value less than the Nyquist frequency:''' '''Upper cutoff < Fs/2 * '''Parameters''': Parameters of the algorithm (file ''ss_default_params.m''). '''Folders''' * Demultiplexed files are saved in the Brainstorm temporary folder: <
> ''TmpDir/Unsupervised_Spike_Sorting/protocol_name/subject_name/data_name'' * To get the temporary folder: Run ''bst_get('BrainstormTmpDir')'' in the Matlab command window. * UltraMegaSort2000 output: Saved directly in the Brainstorm database folder, in the same folder as the input raw file. To find this folder easily, right-click on the Link to raw file > File > Show in file explorer. '''References''' * Hill DN, Mehta S, Kleinfeld D, [[https://www.jneurosci.org/content/31/24/8699|Quality metrics to acco mpany spike sorting ofextracellular signals]]''', ''''''Journal of Neuroscience''', 2011 * Fee MS, Mitra PP, Kleinfeld D, [[https://www.sciencedirect.com/science/article/abs/pii/S0165027096000507?via=ihub|Automatic sorting of multiple unit neuronal signals in the presence of anisotropic and non-Gaussian variability]], '''Journal of Neuroscience Methods''', 1996 <
> === Kilosort === The [[https://github.com/MouseLand/Kilosort|KiloSort]] algorithm is intended for high-density multi-electrode arrays/probes, where the same neuron can potentially be recorded from multiple electrodes. In order to follow the convention that we have kept through all the spike-sorters, once the spike-sorting procedure is complete, each neuron is assigned to a single electrode, according to which electrode the waveforms of this neuron had highest amplitude. {{{#!wiki note Running Kilosort on the GPU dramatically speeds up the spike-sorting process. Users would have to prepare their system for GPU training before calling the spike sorter. Installation instructions are provided at [[https://github.com/cortex-lab/KiloSort|Kilosort's website page]]. Suggested environment: Matlab2018a, CUDA 9.0, Microsoft Visual Studio 2013 }}} When the Kilosort spike-sorter is selected, the following window appears: {{attachment:KiloWindow.gif}} During this process, the user can select: * '''Maximum RAM to use''': Before the spike sorting, the signals are demultiplexed to save one file per channel. The larger the RAM selected is, the faster this process will perform. Make sure a high portion of your computer’s RAM is selected. * '''GPU processing''': Activate the GPU processing. * '''Apply SSP/ICA''': See the section [[https://neuroimage.usc.edu/brainstorm/e-phys/SpikeSorting#Artifact_removal_before_spike-sorting|Artifact removal before spike-sorting]]. * '''Parameters''': Parameters of the algorithm (file ''KilosortStandardConfig.m''). Before the algorithm is applied on the signals, the raw signal is converted into a .dat file to be used as an input to the KiloSort function. This input file in the Brainstorm temporary folder. To get the temporary folder: Run ''bst_get('BrainstormTmpDir')'' in the Matlab command window It should be noted here, that Kilosort works on a '''group of electrodes''' (commonly referred to as shanks) and creates separate files for each group. If a user wants to alter the grouping of the electrodes , they should edit the channels file before calling Kilosort: Right-click on the channels icon > Edit channel file > then assign the same Group ID on the desired electrodes. '''Reference''' * Pachitariu M, Steinmetz NA, Kadir S, Carandini M and Harris KD, [[https://papers.nips.cc/paper/2016/hash/1145a30ff80745b56fb0cecf65305017-Abstract.html|Fast and accurate spike sorting of high-channel count probes with Kilosort]], '''Advances In Neural Information Processing Systems''', 2016 <
> == Supervised Spike Sorting == {{attachment:ssSupervised_new.png||width="700"}} During the supervised spike-sorting step, the user inspects the clustering outputs of the spike sorters and modifies them. At the time this tutorial is being written, we have integrated the graphical user interface (GUI) of WaveClus and UltraMegaSort2000 in Brainstorm. Users can use the GUI of these spike sorters and every modification they perform in the clusters, automatically updates the [[Tutorials/EventMarkers#On_the_hard_drive|events in the database of the raw file]] it corresponds to. To open the supervised spike-sorting process, users can either double-click on the Spike Sorting icon, or drag and drop it to the process box, click Run>Electrophysiology>Supervised Spike Sorting. The GUI that will open will correspond to the sorter that performed the unsupervised-spike-sorting (WaveClus or UltraMegaSort2000). The figure below shows what the main window will look like once the supervised-spike sorter gets activated. A new tab (“Spikes”) appears, and a drop-down gets activated with the label of the electrode that is currently open on the spike sorter. The ''Save and Next'' button saves the current modification/settings on the spike sorter for the selected electrode from the drop-down, and moves to the next channel on the list that picked up spikes. If supervised-spike-sorting has already been performed on the selected electrode, a star (*) symbol will appear at the end of the label on the drop-down. This will be useful in case supervised-spike-sorting was not completed in one shot and users went back to the file to finish it, without wasting time spike-sorting the same channels all over again. {{{#!wiki caution Saving '''SHOULD NOT''' be performed through the spike-sorter's GUI. Only use the Save and Next button on the main Brainstorm window. }}} {{attachment:ssOutput.png}} <
> === WaveClus === A tutorial and information on how to use the WaveClus spike sorter can be found at:<
>https://github.com/csn-le/wave_clus/wiki In brief, the top row is just a filtered version of the raw signal (spiking activity can already be seen). The red line running along this 60 seconds segment represents the threshold applied for the spike-sorting. In the example below, there are two neurons clustered on this electrode. Neuron 1 (Cluster 1) elicited 24,475 spikes and Neuron 2 (cluster 2) 2,812 spikes. Users can either accept (default), reject (cluster it as Noise (Cluster 0)), or modify (change temperature) the current clusters. Once all the modifications are made, the user needs to press Save and Next on the main Brainstorm window. {{attachment:WaveclusSupervised.png||width="700"}} '''References''' * Quian Quiroga R, Nadasdy Z, Ben-Shaul Y, [[https://pubmed.ncbi.nlm.nih.gov/15228749/|Unsupervised spike detection and sorting with wavelets and super-paramagnetic clustering]], '''Neural Computation''', 2004 <
> === UltraMegaSort2000 === A tutorial and information on how to use the UltraMegaSort2000 spike sorter can be found at:<
>[[https://neurophysics.ucsd.edu/lab/UltraMegaSort2000%20Manual.pdf|https://neurophysics.ucsd.edu/lab/UltraMegaSort2000%20Manual.pdf]] The image below, shows 7 possible clusters that the algorithm created on electrode AD08. Users need to select the clusters they think should be merged or deleted, and sequentially press Save and select next. {{attachment:UMSSupervised2.png||width="700"}} '''References''' * Hill DN, Mehta S, Kleinfeld D, [[https://www.jneurosci.org/content/31/24/8699|Quality metrics to acco mpany spike sorting ofextracellular signals]]''', ''''''Journal of Neuroscience''', 2011 * Fee MS, Mitra PP, Kleinfeld D, [[https://www.sciencedirect.com/science/article/abs/pii/S0165027096000507?via=ihub|Automatic sorting of multiple unit neuronal signals in the presence of anisotropic and non-Gaussian variability]], '''Journal of Neuroscience Methods''', 1996 <
> === Klusters === [[http://neurosuite.sourceforge.net/|Klusters]] is a visualization tool that can be used for supervised spike sorting of the Kilosort output. There is a significant difference in the main window of Brainstorm when using Klusters. Instead of selecting each separate electrode from the drop-down window, Klusters automatically loads the electrode-group, that the spike-sorting has been performed to (right-click the channels icon and then edit channels file in order to display the channel groups - this needs to be done before spike-sorting). Klusters is a compiled program that must be installed manually from the website: <
>http://neurosuite.sourceforge.net/ {{attachment:Klusters_new.png||width="700"}} The numbers next to the events of the spikes within Brainstorm, correspond to the clusters that were selected within Klusters, as shown in the next figure. Each cluster is assigned to the channel that showed highest amplitude of its spike's waveforms. {{attachment:events_Klusters.png||width="300"}} '''References''' * Hazan L, Zugaro M, Buzsaki G, [[https://www.sciencedirect.com/science/article/abs/pii/S0165027006000410?via=ihub|Klusters, NeuroScope, NDManager: a free software suite for neurophysiological data processing and visualization]], '''Journal of Neuroscience Methods''', 2006 == Spike sorting outside of Brainstorm == In case you have data that have already been spike-sorted, you can use the spike-timestamps as separate events for each electrode, and subsequently import the events from a single events file into Brainstorm. A tutorial on how to convert the events to a Brainstorm-compatible format can be found [[https://neuroimage.usc.edu/brainstorm/e-phys/ConvertToBrainstormEvents|here]]. <
> <> == Artifact removal before spike-sorting == Invasive neurophysiology can be susceptible to several artifact sources - animal movement, juice dispenser etc. The order of magnitude of these artifacts can be much higher than the electrophysiological signals, therefore the artifacts need to be removed before the inputs are transferred to the spike-sorters, especially since those methods are typically relying on signal thresholds. Brainstorm's [[https://neuroimage.usc.edu/brainstorm/Tutorials/ArtifactsSsp|general artifact rejection]] and [[https://neuroimage.usc.edu/brainstorm/Tutorials/Epilepsy#Artifact_cleaning_with_ICA|ICA artifact removal]] pages can help users identify components that are originating from non-brain sources and easily remove them. During the demultiplexing/conversion step of the spike-sorting, the option "Apply the existing SSP/ICA projectors" must be selected in order for the artifact correction to be applied to the recordings. <> <>