Need help with Kilosort?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

MouseLand
142 Stars 99 Forks GNU General Public License v2.0 562 Commits 82 Opened issues

Description

Fast spike sorting with drift correction for up to a thousand channels

Services available

!
?

Need anything else?

Contributors list

Kilosort3: spike sorting on GPUs with template matching, drift correction and fancy clustering

Now is the best time to post feedback (good or bad) so please use Github issues freely!

For older versions, please see Github releases:
updated from Kilosort2.5 on Jan 30, 2021.
updated from Kilosort2 on Oct 28, 2020.

Welcome to Kilosort3, a MATLAB package for spike sorting electrophysiological data up to 1024 channels. In many cases, and especially for Neuropixels probes, the automated output of Kilosort3 requires minimal manual curation. The main change from v2.5 is a completely new and much more sophisticated clustering algorithm, which we will document soon. To learn about Kilosort2.5, the primary reference is the Neuropixels 2.0 paper. The Github wiki still refers to Kilosort2, and it will be updated.

Kilosort2.5 improves on Kilosort2 primarily in the type of drift correction we use. Where Kilosort2 modified templates as a function of time/drift (a drift tracking approach), Kilosort2.5 corrects the raw data directly via a sub-pixel registration process (a drift correction approach). Kilosort2.5 has not been as broadly tested as Kilosort2, but is expected to work out of the box on Neuropixels 1.0 and 2.0 probes, as well as other probes with vertical pitch <=40um. For other recording methods, like tetrodes or single-channel recordings, you should test empirically if v2.5 or v2.0 works better for you (use the "releases" on the github page to download older versions).

Kilosort2 can still be accessed by downloading the release "Kilosort 2.0". It improves on the original Kilosort primarily by employing drift correction, which changes the templates continuously as a function of drift. Drift correction does not depend on a particular probe geometry, but denser spacing of sites generally helps to better track neurons, especially if the probe movement is large. Kilosort2 has been primarily developed on awake, head-fixed recordings from Neuropixels 1.0 data, but has also been tested in a few other configurations. To get a sense of how probe drift affects spike sorting, check out our "eMouse" simulation here and its wiki page.

To aid in setting up a Kilosort2/2.5 run on your own probe configuration, we have developed a graphical user interface where filepaths can be set and data loaded and visually inspected, to make sure Kilosort2/2.5 sees it correctly. The picture above is another GUI visualization: it shows the templates detected by Kilosort2 over a 60ms interval from a Neuropixels recording. The final output of Kilosort2/2.5 can be visualized and curated in the Phy GUI, which must be installed separately. Since Phy is in Python, you will also need the npy-matlab package.

Installation

Required toolboxes: parallel computing toolbox, signal processing toolbox, Statistics and Machine Learning Toolbox, MATLAB >=R2016b

You must run and complete successfully

mexGPUall.m
in the
CUDA
folder. This requires mexcuda support, which comes with the parallel computing toolbox. To set up mexcuda compilation, install the exact version of the CUDA toolkit compatible with your MATLAB version (see here). On Windows, you must also install a CPU compiler, for example the freely available Visual Studio Community 2013. Note that the most recent editions of Visual Studio are usually not compatible with CUDA. If you had previously used a different CPU compiler in MATLAB, you must switch to the CUDA-compatible compiler using
mex -setup C++
. For more about mexcuda installation, see these instructions.

General instructions for running Kilosort2

Option 1: Using the GUI

Navigate to the

Kilosort
directory and run
kilosort
: ```

cd \my\kilosort\directory\ kilosort ``` See the GUI documentation for more details.

Option 2: Using scripts (classic method)

  1. Make a copy of
    main_kilosort.m
    and
    \configFiles\StandardConfig_MOVEME.m
    and put them in a different directory. These files will contain your own settings, and you don't want them to be overwritten when you update Kilosort.
  2. Generate a channel map file for your probe using
    \configFiles\createChannelMap.m
    as a starting point.
  3. Edit the config file with desired parameters. You should at least set the file paths
    ops.fbinary
    ,
    ops.root
    and
    ops.fproc
    (this file will not exist yet -
    kilosort
    will create it), the sampling frequency
    ops.fs
    , the number of channels in the file
    ops.NchanTOT
    and the location of your channel map file
    ops.chanMap
    .
  4. Edit
    main_kilosort.m
    so that the paths at the top (lines 3–4) point to your local copies of those GitHub repositories, and so that the configuration file is correctly specified (lines 6–7).

Parameters

If you are unhappy with the quality of the automated sorting, try changing one of the main parameters:

ops.Th = [10 4]
(default). Thresholds on spike detection used during the optimization
Th(1)
or during the final pass
Th(2)
. These thresholds are applied to the template projections, not to the voltage. Typically,
Th(1)
is high enough that the algorithm only picks up sortable units, while
Th(2)
is low enough that it can pick all of the spikes of these units. It doesn't matter if the final pass also collects noise: an additional per neuron threshold is set afterwards, and a splitting step ensures clusters with multiple units get split.

ops.AUCsplit = 0.9
(default). Threshold on the area under the curve (AUC) criterion for performing a split in the final step. If the AUC of the split is higher than this, that split is considered good. However, a good split only goes through if, additionally, the cross-correlogram of the split units does not contain a big dip at time 0.

ops.lam = 10
(default). The individual spike amplitudes are biased towards the mean of the cluster by this factor; 50 is a lot, 0 is no bias.

A list of all the adjustable parameters is in the example configuration file.

Integration with Phy GUI

Kilosort2 provides a results file called

rez
, where the first column of
rez.st
are the spike times and the second column are the cluster identities. It also provides a field
rez.good
which is 1 if the algorithm classified that cluster as a good single unit. To visualize the results of Kilosort2, you can use Phy, which also provides a manual clustering interface for refining the results of the algorithm. Kilosort2 automatically sets the "good" units in Phy based on a <20% estimated contamination rate with spikes from other neurons (computed from the refractory period violations relative to expected).

Because Phy is written in Python, you also need to install npy-matlab, to provide read/write functions from MATLAB to Python.

Detailed instructions for interpreting results are provided here. That documentation was developed for Kilosort1, so things will look a little different with Kilosort2.

Credits

Kilosort2 by Marius Pachitariu
GUI by Nick Steinmetz
eMouse simulation by Jennifer Colonell

Questions

Please create an issue for bugs / installation problems.

Licence

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.