KiloSort - hasselmonians/knowledge-base GitHub Wiki

Kilo-sort is an automated spike-sorting toolbox built for MATLAB. It runs in C++ under-the-hood and can be accelerated with graphical-processing unit (GPU) acceleration. The ideal environment for kilo-sort is on the shared computing cluster (SCC) since jobs there can take advantage of the powerful GPUs and computing nodes. Kilo-sort can also be run locally, and contains a graphical user interface (GUI) for that purpose.

Installing

GPU acceleration comes from NVIDIA's proprietary CUDA system. If you do not have an NVIDIA graphics card, then you cannot use this feature. I think kilo-sort will still run, but it will be at least 100x slower.

Windows 10 installation

  1. Install MATLAB R2018a or later. It is inadvisable to use earlier versions, though may still be possible. You need the Parallel Computing and Signal Processing toolboxes.

  2. Install CUDA 9.0 from here. Do not install any other versions. If you are using an older version of MATLAB, you may need an older version of CUDA. If you are using a newer version of MATLAB, you need a newer version of CUDA too. Check here.

  3. Install Visual Studio 2013 Community from here. You should do this after MATLAB is installed.

  4. In MATLAB, set up the compiler. Run

mex -setup C++

You should see an output that lists different compilers. It may look something like this:

To choose a different C++ compiler, select one from the following:
MinGW64 Compiler (C++)  mex -setup:'C:\Program Files\MATLAB\R2018a\bin\win64\mexopts\mingw64_g++.xml' C++
MinGW64 Compiler with Windows 10 SDK or later (C++)  mex -setup:'C:\Program Files\MATLAB\R2018a\bin\win64\mexopts\mingw64_g++_sdk10+.xml' C++
Microsoft Visual C++ 2013  mex -setup:'C:\Program Files\MATLAB\R2018a\bin\win64\mexopts\msvcpp2013.xml' C++

You want to choose the Visual C++ 2013 version. In MATLAB you want something similar to this.

mex -setup:'C:\Program Files\MATLAB\R2018a\bin\win64\mexopts\msvcpp2013.xml' C++

  1. Now you are ready to get kilo-sort. You should download and unzip from here or clone the git repository. Put it somewhere sane.

  2. In MATLAB, compile kilo-sort:

cd C:\my\github\directory\KiloSort\CUDA
mexGPUall

Here, C:\my\github\directory\KiloSort\CUDA is a proxy for wherever you saved Kilosort. You will need to go into the Kilosort2\CUDA folder by navigating there using the graphical menu or the cd command. It is fine if you get a bunch of warnings. If you have the wrong version of CUDA, you should get an error about that here. If you see "Mex completed successfully", you have succeeded.

GNU/Linux & macOS installation

The process is very similar. You will need MATLAB with the required toolboxes, and you will need CUDA, which is an enormous pain. You need to install the correct version for the correct distribution, and if you do not have any NVIDIA graphics cards, you cannot use it.

Getting the compiler to work with MATLAB is a lot easier though. See my advice here and for troubleshooting, here.

If you want GPU acceleration (which I think is mandatory right now), you need CUDA. Check here to see which version is compatible with your version of MATLAB.

Using kilo-sort via GUI

From MATLAB, type:

kilosort

You may want to add the kilo-sort folder to your MATLAB path to facilitate this.

% don't use if you cloned via git, it will add useless .git folders to your path
addpath(genpath('myPath2KiloSort'))

Where 'myPath2KiloSort' is the full path to the KiloSort2 folder.

When you use the kilosort command, it should open a GUI. Their documentation on how to use the GUI is very solid.

Using kilo-sort via script

  1. Make a copy of master_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 kilo-sort.

  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.fproc (this file will not exist yet - kilosort will create it), and ops.root), 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 master_kilosort 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).

Adjusting kilo-sort parameters

A list of all parameters is in the StandardConfig_MOVEME.m script.

If you put this configuration file elsewhere (such as in another repository for a project you're working on), you can tailor the parameters to the conditions of your experimental setup.

Output from kilo-sort

Kilo-sort will spit out a results rez file that can be loaded into Phy or analyzed separately. It is compatible with CMBHOME.

Integration with Phy GUI

Phy is a GUI used for manual post-hoc sorting and data visualization.

Phy is written in Python. You will need to install:

  1. Phy
  2. npy-matlab for Python x MATLAB interoperability.
  3. phy-contrib

Naturally, you will also need Python. Take care installing packages in Python.

You should be working in a virtual environment either from Anaconda, the virtualenv community package or the default venv module.

The people behind Phy have pretty good instructions on how to do this.

Once you have Phy and its add-ons/dependencies set up, take a look at the template gui documentation.

To test if Phy is working correctly, and to learn how to use the GUI, the developers have provided some sample data to analyze. Download link.

Using kilo-sort on the cluster

Kilo-sort on the shared computing cluster is straightforward. Login to the cluster and then either run a script through qsub or start an interactive session using qrsh.

$ qrsh -l gpus=0.5 -l gpu_c=3.5 -pe omp 2
$ ssc-centos7
$ module load matlab
$ module load cuda/9.0

Then spin up an interactive MATLAB session:

matlab -nodisplay

Then, set up the compiler:

mex -setup C++
mexGPUall

Kilo-sort can now be used from the cluster. Note that kilo-sort must be installed somewhere on the cluster. There is an up-to-date version which can be added with

addpath(genpath('/projectnb/hasselmogrp/ahoyland/KiloSort2'))

Kilo-sort is compatible with RatCatcher.