changed readme from markdown to rst

3 files changed, 169 insertions, 134 deletions

diff --git a/Readme.md b/Readme.md
deleted file mode 100644
index be42c4a..0000000
--- a/Readme.md
+++ /dev/null
@@ -1,131 +0,0 @@
-# PySpike

-

-[![Build Status](https://travis-ci.org/mariomulansky/PySpike.svg?branch=master)](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](http://www.scholarpedia.org/article/Measures_of_spike_train_synchrony#ISI-distance) [1] and [SPIKE](http://www.scholarpedia.org/article/SPIKE-distance) [2] distance. 

-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](http://www.cython.org) to reach a competitive performance (factor 100-200 over plain Python).

-

-All source codes are published under the [BSD License](http://opensource.org/licenses/BSD-2-Clause).

-

->[1] Kreuz T, Haas JS, Morelli A, Abarbanel HDI, Politi A, *Measuring spike train synchrony.* J Neurosci Methods 165, 151 (2007)

-

->[2] 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](http://www.cython.org) is configured properly and able to locate a C compiler.

-

-To install PySpike, simply download the source, e.g. from Github, and run the `setup.py` script:

-

-    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:

-

-    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 `/path/to/PySpike` to the `$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:

-    

-    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](https://github.com/mariomulansky/PySpike/blob/master/examples/PySpike_testdata.txt).

-To quickly obtain spike trains from such files, PySpike provides the function `load_spike_trains_from_txt`.

-

-    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 (`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 `np.sort` (disable this feature by providing `sort=False` as a parameter to the load function).

-As result, `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 `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:

-

-    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 `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 `time_interval` in the `load_spike_trains_from_txt` function, or calling `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:

-

-    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 `isi_profile` returns an instance of the `PieceWiseConstFunc` class.

-As shown above, this class allows you to obtain arrays that can be used to plot the function with `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:

-

-     isi_dist = spk.isi_distance(spike_trains[0], spike_trains[1])

-

-Furthermore, PySpike provides the `average_profile` function that can be used to compute the average profile of a list of given `PieceWiseConstFunc` instances.

-

-    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 `average_profile` function, which returns a `PieceWiseConstFunc` (or `PieceWiseLinFunc`, see below), and the `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 `average_profile` and the use 

-

-    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

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 <https://github.com/mariomulansky/PySpike/blob/master/examples/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
diff --git a/doc/index.rst b/doc/index.rst
index b94c162..bc05b60 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -3,10 +3,10 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to PySpike's documentation!
-===================================
+.. include:: ../Readme.rst
 
-Reference:
+Reference
+===================================
 
 .. toctree::
    :maxdepth: 2