From f982bb4870de078b77f0c9fa3230128f8dfe640c Mon Sep 17 00:00:00 2001 From: Mario Mulansky Date: Mon, 11 May 2015 12:10:30 +0200 Subject: +tutorial, reference, contributors order --- Contributors.txt | 6 +- Readme.rst | 8 +-- doc/tutorial.rst | 213 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 220 insertions(+), 7 deletions(-) create mode 100644 doc/tutorial.rst diff --git a/Contributors.txt b/Contributors.txt index 0d4afee..83563c7 100644 --- a/Contributors.txt +++ b/Contributors.txt @@ -3,10 +3,10 @@ Python/C Programming: Scientific Methods: - Thomas Kreuz -- Nebojsa D. Bozanic -- Mario Mulansky -- Conor Houghton - Daniel Chicharro +- Conor Houghton +- Nebojsa Bozanic +- Mario Mulansky The work on PySpike was supported by the European Comission through the Marie diff --git a/Readme.rst b/Readme.rst index b8858f5..daacbea 100644 --- a/Readme.rst +++ b/Readme.rst @@ -17,7 +17,7 @@ All source codes are available on `Github `_ -.. [#] Kreuz T, Mulansky M and Bozanic N, *SPIKY: A graphical user interface for monitoring spike train synchrony*, tbp (2015) +.. [#] Kreuz T, Mulansky M and Bozanic N, *SPIKY: A graphical user interface for monitoring spike train synchrony*, J Neurophysiol, in press (2015) Important Changelog ----------------------------- @@ -114,10 +114,10 @@ Curie Initial Training Network* `Neural Engineering Transformative Technologies **Scientific Methods:** - Thomas Kreuz - - Nebojsa D. Bozanic - - Mario Mulansky - - Conor Houghton - Daniel Chicharro + - Conor Houghton + - Nebojsa Bozanic + - Mario Mulansky .. _ISI: http://www.scholarpedia.org/article/Measures_of_spike_train_synchrony#ISI-distance .. _SPIKE: http://www.scholarpedia.org/article/SPIKE-distance diff --git a/doc/tutorial.rst b/doc/tutorial.rst new file mode 100644 index 0000000..f7fc20b --- /dev/null +++ b/doc/tutorial.rst @@ -0,0 +1,213 @@ +Spike trains +------------ + +In PySpike, spike trains are represented by :class:`.SpikeTrain` objects. +A :class:`.SpikeTrain` object consists of the spike times given as `numpy` arrays as well as the edges of the spike train as :code:`[t_start, t_end]`. +The following code creates such a spike train with some arbitrary spike times: + +.. code:: python + + import numpy as np + from pyspike import SpikeTrain + + spike_train = SpikeTrain(np.array([0.1, 0.3, 0.45, 0.6, 0.9], [0.0, 1.0])) + +Loading from text files +....................... + +Typically, spike train data is loaded into PySpike from data files. +The most straight-forward data files are text files where each line represents one spike train given as an sequence of spike times. +An exemplary file with several spike trains is `PySpike_testdata.txt `_. +To quickly obtain spike trains from such files, PySpike provides the function :func:`.load_spike_trains_from_txt`. + +.. code:: python + + import numpy as np + import pyspike as spk + + spike_trains = spk.load_spike_trains_from_txt("SPIKY_testdata.txt", + edges=(0, 4000)) + +This function expects the name of the data file as first parameter. +Furthermore, the time interval of the spike train measurement (edges of the spike trains) should be provided as a pair of start- and end-time values. +Furthermore, the spike trains are sorted via :code:`np.sort` (disable this feature by providing :code:`is_sorted=True` as a parameter to the load function). +As result, :func:`.load_spike_trains_from_txt` returns a *list of arrays* containing the spike trains in the text file. + + +Computing bivariate distances profiles +--------------------------------------- + +**Important note:** + +------------------------------ + + Spike trains are expected to be *sorted*! + For performance reasons, the PySpike distance functions do not check if the spike trains provided are indeed sorted. + Make sure that all your spike trains are sorted, which is ensured if you use the :func:`.load_spike_trains_from_txt` function with the parameter `is_sorted=False` (default). + If in doubt, use :meth:`.SpikeTrain.sort()` to ensure a correctly sorted spike train. + + If you need to copy a spike train, use the :meth:`.SpikeTrain.copy()` method. + Simple assignment `t2 = t1` does not create a copy of the spike train data, but a reference as `numpy.array` is used for storing the data. + +------------------------------ + +ISI-distance +............ + +The following code loads some exemplary spike trains, computes the dissimilarity profile of the ISI-distance of the first two :class:`.SpikeTrain` s, and plots it with matplotlib: + +.. code:: python + + import matplotlib.pyplot as plt + import pyspike as spk + + spike_trains = spk.load_spike_trains_from_txt("PySpike_testdata.txt", + edges=(0, 4000)) + isi_profile = spk.isi_profile(spike_trains[0], spike_trains[1]) + x, y = isi_profile.get_plottable_data() + plt.plot(x, y, '--k') + print("ISI distance: %.8f" % isi_profile.avrg()) + plt.show() + +The ISI-profile is a piece-wise constant function, and hence the function :func:`.isi_profile` returns an instance of the :class:`.PieceWiseConstFunc` class. +As shown above, this class allows you to obtain arrays that can be used to plot the function with :code:`plt.plt`, but also to compute the time average, which amounts to the final scalar ISI-distance. +By default, the time average is computed for the whole :class:`.PieceWiseConstFunc` function. +However, it is also possible to obtain the average of a specific interval by providing a pair of floats defining the start and end of the interval. +For the above example, the following code computes the ISI-distances obtained from averaging the ISI-profile over four different intervals: + +.. code:: python + + isi1 = isi_profile.avrg(interval=(0, 1000)) + isi2 = isi_profile.avrg(interval=(1000, 2000)) + isi3 = isi_profile.avrg(interval=[(0, 1000), (2000, 3000)]) + isi4 = isi_profile.avrg(interval=[(1000, 2000), (3000, 4000)]) + +Note, how also multiple intervals can be supplied by giving a list of tuples. + +If you are only interested in the scalar ISI-distance and not the profile, you can simply use: + +.. code:: python + + isi_dist = spk.isi_distance(spike_trains[0], spike_trains[1], interval) + +where :code:`interval` is optional, as above, and if omitted the ISI-distance is computed for the complete spike trains. + + +SPIKE-distance +.............. + +To compute for the spike distance profile you use the function :func:`.spike_profile` instead of :code:`isi_profile` above. +But the general approach is very similar: + +.. code:: python + + import matplotlib.pyplot as plt + import pyspike as spk + + spike_trains = spk.load_spike_trains_from_txt("PySpike_testdata.txt", + edges=(0, 4000)) + spike_profile = spk.spike_profile(spike_trains[0], spike_trains[1]) + x, y = spike_profile.get_plottable_data() + plt.plot(x, y, '--k') + print("SPIKE distance: %.8f" % spike_profile.avrg()) + plt.show() + +This short example computes and plots the SPIKE-profile of the first two spike trains in the file :code:`PySpike_testdata.txt`. +In contrast to the ISI-profile, a SPIKE-profile is a piece-wise *linear* function and is therefore represented by a :class:`.PieceWiseLinFunc` object. +Just like the :class:`.PieceWiseConstFunc` for the ISI-profile, the :class:`.PieceWiseLinFunc` provides a :meth:`.PieceWiseLinFunc.get_plottable_data` member function that returns arrays that can be used directly to plot the function. +Furthermore, the :meth:`.PieceWiseLinFunc.avrg` member function returns the average of the profile defined as the overall SPIKE distance. +As above, you can provide an interval as a pair of floats as well as a sequence of such pairs to :code:`avrg` to specify the averaging interval if required. + +Again, you can use + +.. code:: python + + spike_dist = spk.spike_distance(spike_trains[0], spike_trains[1], interval) + +to compute the SPIKE distance directly, if you are not interested in the profile at all. +The parameter :code:`interval` is optional and if neglected the whole spike train is used. + + +SPIKE synchronization +..................... + +**Important note:** + +------------------------------ + + SPIKE-Synchronization measures *similarity*. + That means, a value of zero indicates absence of synchrony, while a value of one denotes the presence of synchrony. + This is exactly opposite to the other two measures: ISI- and SPIKE-distance. + +---------------------- + + +SPIKE synchronization is another approach to measure spike synchrony. +In contrast to the SPIKE- and ISI-distance, it measures similarity instead of dissimilarity, i.e. higher values represent larger synchrony. +Another difference is that the SPIKE synchronization profile is only defined exactly at the spike times, not for the whole interval of the spike trains. +Therefore, it is represented by a :class:`.DiscreteFunction`. + +To compute for the spike synchronization profile, PySpike provides the function :func:`.spike_sync_profile`. +The general handling of the profile, however, is similar to the other profiles above: + +.. code:: python + + import matplotlib.pyplot as plt + import pyspike as spk + + spike_trains = spk.load_spike_trains_from_txt("PySpike_testdata.txt", + edges=(0, 4000)) + spike_profile = spk.spike_sync_profile(spike_trains[0], spike_trains[1]) + x, y = spike_profile.get_plottable_data() + +For the direct computation of the overall spike synchronization value within some interval, the :func:`.spike_sync` function can be used: + +.. code:: python + + spike_sync = spk.spike_sync(spike_trains[0], spike_trains[1], interval) + + +Computing multivariate profiles and distances +---------------------------------------------- + +To compute the multivariate ISI-profile, SPIKE-profile or SPIKE-Synchronization profile f a set of spike trains, PySpike provides multi-variate version of the profile function. +The following example computes the multivariate ISI-, SPIKE- and SPIKE-Sync-profile for a list of spike trains using the :func:`.isi_profile_multi`, :func:`.spike_profile_multi`, :func:`.spike_sync_profile_multi` functions: + +.. code:: python + + spike_trains = spk.load_spike_trains_from_txt("PySpike_testdata.txt", + edges=(0, 4000)) + avrg_isi_profile = spk.isi_profile_multi(spike_trains) + avrg_spike_profile = spk.spike_profile_multi(spike_trains) + avrg_spike_sync_profile = spk.spike_sync_profile_multi(spike_trains) + +All functions take an optional parameter :code:`indices`, a list of indices that allows to define the spike trains that should be used for the multivariate profile. +As before, if you are only interested in the distance values, and not in the profile, PySpike offers the functions: :func:`.isi_distance_multi`, :func:`.spike_distance_multi` and :func:`.spike_sync_multi`, that return the scalar overall multivariate ISI- and SPIKE-distance as well as the SPIKE-Synchronization value. +Those functions also accept an :code:`interval` parameter that can be used to specify the begin and end of the averaging interval as a pair of floats, if neglected the complete interval is used. + +Another option to characterize large sets of spike trains are distance matrices. +Each entry in the distance matrix represents a bivariate distance (similarity for SPIKE-Synchronization) of two spike trains. +The distance matrix is symmetric and has zero values (ones) at the diagonal and is computed with the functions :func:`.isi_distance_matrix`, :func:`.spike_distance_matrix` and :func:`.spike_sync_matrix`. +The following example computes and plots the ISI- and SPIKE-distance matrix as well as the SPIKE-Synchronization-matrix, with different intervals. + +.. code:: python + + spike_trains = spk.load_spike_trains_from_txt("PySpike_testdata.txt", 4000) + + plt.figure() + isi_distance = spk.isi_distance_matrix(spike_trains) + plt.imshow(isi_distance, interpolation='none') + plt.title("ISI-distance") + + plt.figure() + spike_distance = spk.spike_distance_matrix(spike_trains, interval=(0,1000)) + plt.imshow(spike_distance, interpolation='none') + plt.title("SPIKE-distance") + + plt.figure() + spike_sync = spk.spike_sync_matrix(spike_trains, interval=(2000,4000)) + plt.imshow(spike_sync, interpolation='none') + plt.title("SPIKE-Sync") + + plt.show() + -- cgit v1.2.3