+multivariate example, docs for spike profile

3 files changed, 109 insertions, 15 deletions

diff --git a/Readme.rst b/Readme.rst
index 81ef338..b0128c0 100644
--- a/Readme.rst
+++ b/Readme.rst
@@ -26,7 +26,7 @@ To use PySpike you need Python installed with the following additional packages:
 - cython
 - nosetests (for running the tests)
 
-In particular, make sure that cython_ is configured properly and able to locate a C compiler.
+In particular, make sure that cython_ is configured properly and able to locate a C compiler, otherwise you will only be able to use the much slower plain Python implementations.
 
 To install PySpike, simply download the source, e.g. from Github, and run the :code:`setup.py` script:
 
@@ -124,7 +124,7 @@ The following code loads some exemplary spike trains, computes the dissimilarity
     plt.show()
 
 The ISI-profile is a piece-wise constant function, there the function :code:`isi_profile` returns an instance of the :code:`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 absolute average, which amounts to the final scalar ISI-distance.
+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 average, which amounts to the final scalar ISI-distance.
 If you are only interested in the scalar ISI-distance and not the profile, you can simly use:
 
 .. code:: python
@@ -135,11 +135,15 @@ Furthermore, PySpike provides the :code:`average_profile` function that can be u
 
 .. code:: python
 
-    avrg_profile = spk.average_profile([spike_train1, spike_train2])
+    isi_profile1 = spk.isi_profile(spike_trains[0], spike_trains[1])
+    isi_profile2 = spk.isi_profile(spike_trains[0], spike_trains[2])
+    isi_profile3 = spk.isi_profile(spike_trains[1], spike_trains[2])
+
+    avrg_profile = spk.average_profile([isi_profile1, isi_profile2, isi_profile3])
     x, y = avrg_profile.get_plottable_data()
-    plt.plot(x, y, label="Average profile")
+    plt.plot(x, y, label="Average ISI profile")
 
-Note the difference between the :code:`average_profile` function, which returns a :code:`PieceWiseConstFunc` (or :code:`PieceWiseLinFunc`, see below), and the :code:`avrg` member function above, that computes the integral over the time profile.
+Note the difference between the :code:`average_profile` function, which returns a :code:`PieceWiseConstFunc` (or :code:`PieceWiseLinFunc`, see below), and the :code:`avrg` member function above, that computes the integral over the time profile resulting in a single value.
 So to obtain overall average ISI-distance of a list of ISI profiles you can first compute the average profile using :code:`average_profile` and the use 
 
 .. code:: python
@@ -148,12 +152,50 @@ So to obtain overall average ISI-distance of a list of ISI profiles you can firs
 
 to obtain the final, scalar average ISI distance of the whole set (see also "Computing multi-variate distance" below).
 
-Computing multi-variate distances
----------------------------------
 
+SPIKE-distance
+..............
+
+To computation for the spike distance you use the function :code:`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",
+                                                  time_interval=(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_profil.avrg())
+    plt.show()
 
-Plotting
---------
+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 thusly represented by a :code:`PieceWiseLinFunc` object.
+Just like the :code:`PieceWiseconstFunc` for the ISI-profile, the :code:`PieceWiseLinFunc` provides a :code:`get_plottable_data` member function that returns array that can be used directly to plot the function.
+Furthermore, the :code:`avrg` member function returns the average of the profile defined as the overall SPIKE distance.
+
+Again, you can use
+
+.. code:: python
+
+    spike_dist = spk.spike_distance(spike_trains[0], spike_trains[1])
+
+to compute the SPIKE distance directly, if you are not interested in the profile at all.
+Furthmore, you can use the :code:`average_profile` function to compute an average profile of a list of SPIKE-profiles:
+
+.. code:: python
+    
+    avrg_profile = spk.average_profile([spike_profile1, spike_profile2, 
+                                        spike_profile3])
+    x, y = avrg_profile.get_plottable_data()
+    plt.plot(x, y, label="Average SPIKE profile")
+
+
+Computing multi-variate distances
+---------------------------------
 
 
 Averaging
diff --git a/examples/multivariate.py b/examples/multivariate.py
new file mode 100644
index 0000000..260b217
--- /dev/null
+++ b/examples/multivariate.py
@@ -0,0 +1,50 @@
+""" Example for the multivariate spike distance
+
+Copyright 2014, Mario Mulansky <mario.mulansky@gmx.net>
+
+"""
+from __future__ import print_function
+import time
+import pyspike as spk
+
+
+def time_diff_in_ms(start, end):
+    """ Returns the time difference end-start in ms.
+    """
+    return (end-start)*1000
+
+
+t_start = time.clock()
+
+# load the data
+time_loading = time.clock()
+spike_trains = spk.load_spike_trains_from_txt("PySpike_testdata.txt",
+                                              time_interval=(0, 4000))
+t_loading = time.clock()
+
+print("Number of spike trains: %d" % len(spike_trains))
+num_of_spikes = sum([len(spike_trains[i]) for i in xrange(len(spike_trains))])
+print("Number of spikes: %d" % num_of_spikes)
+
+# calculate the multivariate spike distance
+f = spk.spike_profile_multi(spike_trains)
+
+t_spike = time.clock()
+
+# print the average
+avrg = f.avrg()
+print("Spike distance from average: %.8f" % avrg)
+
+t_avrg = time.clock()
+
+# compute average distance directly, should give the same result as above
+spike_dist = spk.spike_distance_multi(spike_trains)
+print("Spike distance directly:     %.8f" % spike_dist)
+
+t_dist = time.clock()
+
+print("Loading:            %9.1f ms" % time_diff_in_ms(t_start, t_loading))
+print("Computing profile:  %9.1f ms" % time_diff_in_ms(t_loading, t_spike))
+print("Averaging:          %9.1f ms" % time_diff_in_ms(t_spike, t_avrg))
+print("Computing distance: %9.1f ms" % time_diff_in_ms(t_avrg, t_dist))
+print("Total:              %9.1f ms" % time_diff_in_ms(t_start, t_dist))
diff --git a/examples/plot.py b/examples/plot.py
index 6da7f49..59334c9 100644
--- a/examples/plot.py
+++ b/examples/plot.py
@@ -26,15 +26,17 @@ f = spk.isi_profile(spike_trains[0], spike_trains[1])
 x, y = f.get_plottable_data()
 
 plt.figure()
-plt.plot(x, np.abs(y), '--k')
+plt.plot(x, np.abs(y), '--k', label="ISI-profile")
 
-print("Average: %.8f" % f.avrg())
+print("ISI-distance: %.8f" % f.avrg())
 
 f = spk.spike_profile(spike_trains[0], spike_trains[1])
 x, y = f.get_plottable_data()
-print(x)
-print(y)
-#plt.figure()
-plt.plot(x, y, '-b')
+
+plt.plot(x, y, '-b', label="SPIKE-profile")
+
+print("SPIKE-distance: %.8f" % f.avrg())
+
+plt.legend(loc="upper left")
 
 plt.show()