From 7e3648264eb3f96257909e53939a70f2fa79f1be Mon Sep 17 00:00:00 2001 From: Mario Mulansky Date: Mon, 4 May 2015 11:37:49 +0200 Subject: restructured docs moved tutorial from Readme to separate section. Readme now contains only two basic examples --- Changelog | 4 ++ Readme.rst | 192 ++-------------------------------------------------------- doc/index.rst | 8 ++- 3 files changed, 15 insertions(+), 189 deletions(-) diff --git a/Changelog b/Changelog index 2ac065b..209b138 100644 --- a/Changelog +++ b/Changelog @@ -1,3 +1,7 @@ +PySpike v0.2.1: + * addition of __version__ attribute + * restructured docs, Readme now only contains basic examples + PySpike v0.2: * introduction of SpikeTrain class. Breaking interface change of diff --git a/Readme.rst b/Readme.rst index e80c0f7..1094332 100644 --- a/Readme.rst +++ b/Readme.rst @@ -70,63 +70,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 `_. -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 @@ -141,109 +89,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 @@ -253,36 +100,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 `_. =============================================================================== diff --git a/doc/index.rst b/doc/index.rst index bc05b60..f34690b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -5,6 +5,11 @@ .. include:: ../Readme.rst +Tutorial +=================================== + +.. include:: tutorial.rst + Reference =================================== @@ -14,9 +19,8 @@ Reference pyspike Indices and tables -================== +=================================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` - -- cgit v1.2.3