cSPIKE
Source Code - cSPIKE
Matlab command line library
Overview
Download: cSPIKE.zip
(Version 1.5, June 30, 2023, Copyright: Eero Satuvuori, Thomas Kreuz)
cSPIKE is an easy to use spike train analysis software. It is run on Matlab command line and it uses MEX files with C++ backends for speed. cSPIKE implements functions such as ISI-distance [1], SPIKE-distance [2], SPIKE synchronization [3] and their adaptive variants [4] as well as basic plot functions for plotting spike trains and profiles.
Version 1.3 also contains the complementary directional method SPIKE-order and Spike Train Order [5] and two algorithms for population analysis [6]. See below for examples.
Version 1.5 adds all the functions that were already present for ISI- and SPIKE-distance also for the rate-independent SPIKE-distance [4]. It also contains a new file "cSPIKE_test.m" that shows on simple example spike train sets how to calculate and plot all the relevant distance values, profiles, and matrices as well as sort spike trains from leader to follower and plot the results.
[1] Kreuz T, Haas JS, Morelli A, Abarbanel HDI, Politi A:
Measuring spike train synchrony
J Neurosci Methods 165, 151 (2007) [PDF]
[2] Kreuz T, Chicharro D, Houghton C, Andrzejak RG, Mormann F:
Monitoring spike train synchrony
J Neurophysiol 109, 1457 (2013) [PDF]
[3] Kreuz T, Mulansky M, Bozanic N:
SPIKY: A graphical user interface for monitoring spike train synchrony
JNeurophysiol 113, 3432 and arXiv [PDF] (2015) [PDF]
[4] Satuvuori E, Mulansky M, Bozanic N, Malvestio I, Zeldenrust F, Lenk K, Kreuz T:
Measures of spike train synchrony for data with multiple time-scales
JNeurosci Methods 287, 25 and arXiv [PDF] (2017) [PDF]
[5] Kreuz T, Satuvuori E, Pofahl M, Mulansky M:
Leaders and followers: Quantifying consistency in spatio-temporal propagation patterns
New J. Phys., 19, 043028 and arXiv [PDF] (2017) [PDF]
[6] Satuvuori E, Mulansky M, Daffertshofer A, Kreuz T:
Using spike train distances to identify the most discriminative neuronal subpopulation
JNeurosci Methods, 308, 354 and arXiv [PDF] (2018) [PDF]
Installation:
cSPIKE allows easy incorporation as a part of a Matlab program. All you need to do is, in this order, extract the files into your project folder, compile the MEX files and set the work path (see below).
1. Compiling MEX files:
In order to build the MEX files and the C++ backends you need a C++ compiler in your Matlab. Here are few links that could help:
What you need to build MEX files
About compilers for Matlab R2016a
Once you have your C++ compiler go to the folder cSPIKEmex and run the script MEX_compile. This will compile your MEX files and C++ backends in the folder. The process may take few minutes.
As a summary you need to:
1) Extract the cSPIKE to folder of your choise
2) Install a C++ compiler for your Matlab
3) Compile your MEX files and C++ backends
4) Add the folder cSPIKEmex to your work path
5) Get to cSPIKE main folder and create your first SpikeTrainSet
Known problems:
1. In case you are using Matlab 2018b or newer and you get some error messages with the MEX-compilation please check this link for assistance:
https://se.mathworks.com/help/matlab/matlab_external/what-if-i-do-not-upgrade.html
2. If you get an error message while compiling that involves the two variable types "char16_t" and "unsigned short" you have a compiler incompatibility with the code. This is the likely fix:
i) In file “MEX_compile” set the variable problem to 1 (typically it should work with problem either set to 0 or to 1).
ii) In file "mexAdaptiveSPIKESynchroProfile.cpp" change in line 66 notion "int NOST = profile1.size();" with " const long unsigned int NOST = profile1.size();"
This should fix the issue without changing the functionality of the code.
2. Setting work path:
The MEX files are located in cSPIKEmex folder and in order to run cSPIKE you need to include that folder into your work path. The easiest way to do so is to call this script at the beginning of your program:
>> initializecSPIKE
This will not only add the MEX-folder but also two other folders containing the SPIKE-order (SpikeTrainOrder) and the population analysis (PopulationAnalysis) to the work path.
Now cSPIKE is ready to be used.
Using cSPIKE:
cSPIKE is built around the main class of SpikeTrainSet. The class requires your spike time data in the form of a cell array in which each cell is a series of spike times. Each array of spike times needs to be a double precision row vector. This cell array together with the recording start and end times form a SpikeTrainSet. You can create your SpikeTrainSet object as:
STS = SpikeTrainSet(MyCellArrayOfSpikes,recordingStartTime,recordingEndTime)
Once the spike train set object has been created you can start calling the various functions. Please refer to the documentation (in particular this link here) and papers for detailed information. Also you can see a short description of all the functions by typing
>> help SpikeTrainSet
Not all of cSPIKE functionalities are decribed here but we discuss are few of the more important functions. The example data used here can be found in the main folder of cSPIKE (file "ExampleSet.mat").
The cell matrix ExampleSet consists of three spike trains with 15 random spikes evenly distributed between 0 and 20. To use cSPIKE we initialize cSPIKE and create a SpikeTrainSet with this information:
>> InitializecSPIKE;
>> STS = SpikeTrainSet(ExampleSet,0,20);
We can calculate the ISI-distance for the whole data set:
>> STS.ISIdistance()
ans =
0.5264
ISI-distance from time 13 to time 15:
>> STS.ISIdistance(13,15)
ans =
0.5417
Adaptive ISI-Distance from time 13 to time 15 with automated threshold:
>> STS.AdaptiveISIdistance(13,15)
ans =
0.5285
And with threshold of 0.1:
>> STS.AdaptiveISIdistance(13,15,0.1)
ans =
0.5417
cSPIKE also includes fast MEX files for calculating pairwise distance matrices where each index is a spike train number. Because the distances are symmetric, the matrix is symmetric as well:
>> STS.SPIKEdistanceMatrix()
ans =
0 0.2626 0.3191
0.2626 0 0.3101
0.3191 0.3101 0
You can also call the methods for the SpikeTrainSet by giving a method the SpikeTrainSet as first parameter. The following calls are identical:
>> STS.SPIKEdistance();
>> SPIKEdistance(STS);
>> STS.ISIdistance(13,15)
>> ISIdistance(STS,13,15)
In addition to the distance measures, the SpikeTrainSet provides the profiles for the ISI- and SPIKE-distances. Once called, the method returns a Profile-object with three main methods. You can plot the profile to current axis with the optional colour and opacity(alpha) given:
>> Profile = STS.SPIKEdistanceProfile(13,15)
Profile.Plot(colour, alpha);
>> Profile.Plot();
You can also get separately the X-values of the profile and the Y-values of the profile as double arrays:
>> Profile.PlotProfileX
ans =
Columns 1 through 4
13.0000 13.1020 13.1020 13.5941
Columns 5 through 8
13.5941 13.9815 13.9815 14.1873
Columns 9 through 10
14.1873 15.0000
>> Profile.PlotProfileY
ans =
Columns 1 through 4
0.4532 0.4535 0.4061 0.4012
Columns 5 through 8
0.3869 0.3183 0.4433 0.3685
Columns 9 through 10
0.3330 0.0566
These are vectors of equal length with each index corresponding a point in the graph.
The SpikeTrainSet can also plot the spike trains to current axis with optional colour and spike width of your choise:
STS.plotSpikeTrainSet(colour, width)
>> STS.plotSpikeTrainSet()
Spike Train Order
Recently we have added the newly introduced method to sort spike trains from leader to follower to cSPIKE. The function call is very simple. In order to perform the basic analysis, the SpikeTrainSet is built as before. Then the analysis is called as
[initialIteration,optimalIteration,synf] = STS.SpikeTrainOrderWithSurrogates(numberOfSurrogates)
The optional parameter numberOfSurrogates lets you do the test based on a number of surrogates you want. The default value is 19 for 5% confidence.
The return values are two stuctures, where the output is stored and an array containing the F values of the surrogates. Please see the paper "Leaders and Followers: Quantifying consistency in spatio-temporal propagation patterns" for more details. Also the cSPIKE package contains an example for how to create an analysis using the structure in file SpikeTrainOrderExample.m. that produces the following figure.
Population analysis
Our latest addition to cSPIKE are these recently introduced algorithms to find in a population of neurons among all possible subpopulations the one that distinguishes a given set of stimuli best. The analysis can be performed in two ways, either assuming a summed population coding or following the labelled line hypothesis. To get started have a look at the file 'population_main.m' in the folder 'PopulationAnalysis'. Please note that this part of cSPIKE is still in some kind of 'alpha mode'. The functions should work correctly but we did not yet have the time to perform software optimization and proper beta-testing. If you encounter any problems please just contact us.
For more information on the population analysis please refer to:
Satuvuori E, Mulansky M, Daffertshofer A, Kreuz T:
Using spike train distances to identify the most discriminative neuronal subpopulation