summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMario Mulansky <mario.mulansky@gmx.net>2015-05-04 11:37:49 +0200
committerMario Mulansky <mario.mulansky@gmx.net>2015-05-04 11:37:49 +0200
commit7e3648264eb3f96257909e53939a70f2fa79f1be (patch)
treeec92ad6ab2017fd8b0a7cecc71038fc92e53435a
parentd5995b82d0de1c5b448823b4acd4efe7d5d47eb4 (diff)
restructured docs
moved tutorial from Readme to separate section. Readme now contains only two basic examples
-rw-r--r--Changelog4
-rw-r--r--Readme.rst192
-rw-r--r--doc/index.rst8
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 <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
@@ -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 <http://mariomulansky.github.io/PySpike/#tutorial>`_.
===============================================================================
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`
-