Skip to content

1. The GUI

Jump to bottom
carsen-stringer edited this page Mar 3, 2024 · 8 revisions

NOTE: This Wiki is kept here for reference for previous versions of Kilosort. For updated information about Kilosort4, please refer to kilosort.readthedocs.io instead.

The GUI is intended as a launcher for Kilosort, to help you run it on your data without errors and to do some sanity checks that it is working properly. It does NOT include any functionality for manually curating/revising/editing the results of the algorithm, so it is not a replacement for Phy or for other careful manual inspection.

1. Installation and running the GUI

To install, first follow the instructions at the main page.

Next, navigate to the kilosort directory and run 'kilosort':

>> cd \my\kilosort2\directory\
>> kilosort

2. Loading a dataset

To get started, choose a dataset by clicking "select data file" in the upper left. The data file should be a raw binary file containing just the data matrix, size [nChannels x nTimepoints], with int16 datatype. For more on data files, see below.

After you select the file, Kilosort will try to load it using the default channel map and options.

You will probably need to set the Number of Channels and the Channel Map. If the channel map for your probe is not in the drop-down list, you have two options. First, you can make a channel map file by looking at /configFiles/createChannelMapFile.m and making a .mat file with your map in that way. Then you can select 'other' in the dropdown and choose it. Second, you can enter the information directly into the GUI by choosing 'new'. You will get a pop-up window that you can fill out. An example of a valid entry is in this screenshot:

3. Viewing data

The Probe View (middle) shows the layout of your probe as specified in the channel map. Green/yellow channels are ones selected currently for viewing in the Data View. Blue/red channels are not currently visible in Data View. Yellow/Red channels are excluded from analysis, and do not appear in Data View.

The Data View shows the data from your file as kilosort will see it. If you can't see spikes, there's a problem! Try moving around the dataset or re-scaling with controls below, or see troubleshooting.

In colormap-mode, the Data View has an image showing channels (y-axis) by time (x-axis) voltage values. In this mode, only one of the available datasets (raw, filtered, prediction, residual) can be seen at a time. Channels not selected for analysis (yellow on Probe View) are not displayed.

In traces-mode, the Data View shows a set of traces for the selected channels, spaced out along the y-axis. In this mode, the different available datasets can be overlaid. Channels not selected for analysis (yellow on Probe View) are shown in light grey.

The datasets are:

  • Raw data: the data straight from your file
  • Filtered: after preprocessing (whitening, common average referencing, temporal filtering) as specified in the options.
  • Prediction: based on Kilosort's results, what does it think the 'true' data looked like. Ideally, it should be a de-noised version of the filtered data.
  • Residual: the difference between Filtered and Prediction, i.e. anything Kilosort didn't get right.

Example data: colormap mode

Observe that the prediction contains spike shapes at places where you can see spikes in the data, and that the residual is empty, meaning that Kilosort has successfully fit all the spikes in the data.

Raw Filtered Predicted Residual

Example data: traces mode

Observe that the prediction (blue) looks like a de-noised version of the filtered data (green).

4. Controls for Viewing Data

Here is a detailed list of controls available:

for Data View (right)

  • Click main data plot - re-center the view on that timepoint/channel
  • Click on the grey timeline bar (bottom) - jump to that timepoint
  • c - Flip between colormap-mode and traces-mode
  • Scroll up/down - advance forward/backward in time
  • Ctrl + Scroll up/down - Colormap mode: make the data view contain fewer/more channels of data. Traces mode: Slide up/down the probe in the y-dimension.
  • Shift + Scroll up/down - zoom in/out in time
  • Alt + Scroll up/down - change the data scaling. In colormap mode, this means the color scale. In traces mode, it means the height/y-axis scaling. NOTE: after using this control, you may have to click on the plot or click somewhere in the figure window to enable other hotkeys (alt removes focus).
  • 1/2/3/4 - Colormap mode: flip back and forth between raw/filtered/predicted/residual datasets. Traces mode: each number toggles one of these datasets.
  • Up or Down arrow - In traces mode, add or remove visualized channels. Similar to Ctrl-Scroll in Colormap mode.
  • Right-click - toggle whether the nearest channel is enabled/disabled for analysis. In traces mode, it will turn grey and you can re-enable it the same way. In colormap mode, it will disappear so if you want to re-enable it, you will need to do so in Probe View or switch to traces mode.

for Probe View (middle)

  • Click - select channels to view that are nearest to where you click
  • Scroll up/down - zoom in/out on the probe view
  • Right-click on a channel - toggle whether this channel is enabled/disabled for analysis

5. Running kilosort

Before running, note that you can manually remove bad channels by right clicking them in either probe view or data view.

Click "Run all" in the bottom left. Note that while it is running, the gui will mostly be un-responsive. You will get status messages in the log box, and more detailed messages at the command window. Figures will appear as it works.

6. Troubleshooting

I can't see spikes in the data view, or something looks funny about what I see.

  • Make sure your data file is the correct type (see below).
  • Make sure you have the correct number of channels set. This is the number of rows in the data file, NOT necessarily the number of sites on your probe or the number of number of channels you want to analyze. If there appear to be diagonal bands in the data, this is a likely sign of incorrect channel number.
  • If the traces look flat or the image blank, try increasing the scaling (Alt+Scroll up).
  • If the traces look empty or just look like noise, try jumping around to different parts of the file (click timeline at the bottom) or zooming out in time (Shift+Scroll down).

My data file is of type XX. Can I use it?

If you can load your data into a Matlab matrix size [nChannels x nTimepoints] and can convert it to int16 datatype, then you can write it to an appropriate file, like this:

>> datI = int16(dat);
>> whos datI 
  Name        Size                  Bytes  Class    Attributes

  datI      385x30000            23100000  int16              

% This dataset is 385 channels by 30000 time samples.
>> fid = fopen('D:\my\path\myNewFile.bin', 'w'); 
>> fwrite(fid, datI, 'int16');
>> fclose(fid);

One of the hotkeys isn't working in the gui.

Try clicking somewhere (returning the focus to the window) and try again. Or, be patient for it to finish computing something. If not that, close and re-open the gui.

Some other problem.

Try resetting the GUI with the Reset GUI button at upper right and starting over. No? Create an issue with a detailed description.

Clone this wiki locally