From a8c271257c9f684997d1a86e66f004c942ed4447 Mon Sep 17 00:00:00 2001 From: Mario Mulansky Date: Mon, 20 Oct 2014 11:57:43 +0200 Subject: changed readme from markdown to rst --- Readme.rst | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 Readme.rst (limited to 'Readme.rst') diff --git a/Readme.rst b/Readme.rst new file mode 100644 index 0000000..9f394e4 --- /dev/null +++ b/Readme.rst @@ -0,0 +1,166 @@ +PySpike +======= + +.. image:: https://travis-ci.org/mariomulansky/PySpike.svg?branch=master + :target: https://travis-ci.org/mariomulansky/PySpike + +PySpike is a Python library for the numerical analysis of spike train similarity. +Its core functionality is the implementation of the bivariate ISI_ [#]_ and SPIKE_ [#]_. +Additionally, it provides functions to compute multi-variate SPIKE and ISI distances, as well as averaging and general spike train processing. +All computation intensive parts are implemented in C via cython_ to reach a competitive performance (factor 100-200 over plain Python). + +All source codes are published under the BSD_License_. + +.. [#] Kreuz T, Haas JS, Morelli A, Abarbanel HDI, Politi A, *Measuring spike train synchrony.* J Neurosci Methods 165, 151 (2007) + +.. [#] Kreuz T, Chicharro D, Houghton C, Andrzejak RG, Mormann F, *Monitoring spike train synchrony.* J Neurophysiol 109, 1457 (2013) + +Requirements and Installation +----------------------------- + +To use PySpike you need Python installed with the following additional packages: + +- numpy +- scipy +- matplotlib +- cython +- nosetests (for running the tests) + +In particular, make sure that cython_ is configured properly and able to locate a C compiler. + +To install PySpike, simply download the source, e.g. from Github, and run the :code:`setup.py` script: + +.. code:: bash + + git clone https://github.com/mariomulansky/PySpike.git + cd PySpike + python setup.py build_ext --inplace + +Then you can run the tests using the `nosetests` test framework: + +.. code:: bash + + nosetests + +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 one-dimensional numpy arrays containing the sequence of spike times as double values. +The following code creates such a spike train with some arbitrary spike times: + +.. code:: python + + import numpy as np + + spike_train = np.array([0.1, 0.3, 0.45, 0.6, 0.9]) + +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 :code:`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", + time_interval=(0, 4000)) + +This function expects the name of the data file as first parameter, and additionally the time intervall of the spike train measurement can be provided as a pair of start- and end-time values. +If the time interval is provided (:code:`time_interval is not None`), auxiliary spikes at the start- and end-time of the interval are added to the spike trains. +Furthermore, the spike trains are ordered via :code:`np.sort` (disable this feature by providing :code:`sort=False` as a parameter to the load function). +As result, :code:`load_spike_trains_from_txt` returns a *list of arrays* containing the spike trains in the text file. + +If you load spike trains yourself, i.e. from data files with different structure, you can use the helper function :code:`add_auxiliary_spikes` to add the auxiliary spikes at the beginning and end of the observation interval. +Both the ISI and the SPIKE distance computation require the presence of auxiliary spikes, so make sure you have those in your spike trains: + +..code:: python + + spike_train = spk.add_auxiliary_spikes(spike_train, (T_start, T_end)) + # if you provide only a single value, it is interpreted as T_end, while T_start=0 + spike_train = spk.add_auxiliary_spikes(spike_train, T_end) + +Computing bi-variate distances +------------------------------ + +------------------------------ + +**Important note:** + + Spike trains are expected to be *ordered sequences*! + For performance reasons, the PySpike distance functions do not check if the spike trains provided are indeed ordered. + Make sure that all your spike trains are ordered. + If in doubt, use :code:`spike_train = np.sort(spike_train)` to obtain a correctly ordered spike train. + + Furthermore, the spike trains should have auxiliary spikes at the beginning and end of the observation interval. + You can ensure this by providing the :code:`time_interval` in the :code:`load_spike_trains_from_txt` function, or calling :code:`add_auxiliary_spikes` for your spike trains. + The spike trains must have *the same* observation interval! + +---------------------- + +ISI-distance +............ + +The following code loads some exemplary spike trains, computes the dissimilarity profile of the ISI-distance of the first two spike trains, 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", + time_interval=(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_profil.avrg()) + 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. +If you are only interested in the scalar ISI-distance and not the profile, you can simly use: + +.. code:: python + + isi_dist = spk.isi_distance(spike_trains[0], spike_trains[1]) + +Furthermore, PySpike provides the :code:`average_profile` function that can be used to compute the average profile of a list of given :code:`PieceWiseConstFunc` instances. + +.. code:: python + + avrg_profile = spk.average_profile([spike_train1, spike_train2]) + x, y = avrg_profile.get_plottable_data() + plt.plot(x, y, label="Average 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. +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 + + avrg_isi = avrg_profile.avrg() + +to obtain the final, scalar average ISI distance of the whole set (see also "Computing multi-variate distance" below). + +Computing multi-variate distances +--------------------------------- + + +Plotting +-------- + + +Averaging +--------- + + +.. _ISI: http://www.scholarpedia.org/article/Measures_of_spike_train_synchrony#ISI-distance +.. _SPIKE: http://www.scholarpedia.org/article/SPIKE-distance +.. _cython: http://www.cython.org +.. _BSD_License: http://opensource.org/licenses/BSD-2-Clause -- cgit v1.2.3