diff options
Diffstat (limited to 'Readme.rst')
| -rw-r--r-- | Readme.rst | 202 |
1 files changed, 10 insertions, 192 deletions
@@ -19,12 +19,12 @@ All source codes are available on `Github <https://github.com/mariomulansky/PySp .. [#] Kreuz T, Chicharro D, Houghton C, Andrzejak RG, Mormann F, *Monitoring spike train synchrony.* J Neurophysiol 109, 1457 (2013) `[pdf] <http://wwwold.fi.isc.cnr.it/users/thomas.kreuz/images/Kreuz_JNeurophysiol_2013_SPIKE-distance.pdf>`_ -.. [#] 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 ----------------------------- -With version 0.2.0, the :class:`.SpikeTrain` class has been introduced to represent spike trains. +With version 0.2.0, the :code:`SpikeTrain` class has been introduced to represent spike trains. This is a breaking change in the function interfaces. Hence, programs written for older versions of PySpike (0.1.x) will not run with newer versions. @@ -72,63 +72,11 @@ Then you can run the tests using the `nosetests` test framework: Finally, you should make PySpike's installation folder known to Python to be able to import pyspike in your own projects. Therefore, add your :code:`/path/to/PySpike` to the :code:`$PYTHONPATH` environment variable. -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 <https://github.com/mariomulansky/PySpike/blob/master/examples/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 -............ +Examples +----------------------------- -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: +The following code loads some exemplary spike trains, computes the dissimilarity profile of the ISI-distance of the first two :code:`SpikeTrain` s, and plots it with matplotlib: .. code:: python @@ -143,109 +91,8 @@ The following code loads some exemplary spike trains, computes the dissimilarity 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: +The following example computes the multivariate ISI-, SPIKE- and SPIKE-Sync-profile for a list of spike trains using the :code:`isi_profile_multi`, :code:`spike_profile_multi`, :code:`spike_sync_profile_multi` functions: .. code:: python @@ -255,36 +102,7 @@ The following example computes the multivariate ISI-, SPIKE- and SPIKE-Sync-prof 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() - +More examples with detailed descriptions can be found in the `tutorial section <http://mariomulansky.github.io/PySpike/#tutorial>`_. =============================================================================== @@ -298,10 +116,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 |