updated docs

10 files changed, 196 insertions, 194 deletions

diff --git a/Readme.rst b/Readme.rst
index 03441fc..e80c0f7 100644
--- a/Readme.rst
+++ b/Readme.rst
@@ -19,6 +19,14 @@ All source codes are available on `Github <https://github.com/mariomulansky/PySp
 
 .. [#] Kreuz T, Mulansky M and Bozanic N, *SPIKY: A graphical user interface for monitoring spike train synchrony*, tbp (2015)
 
+Important Changelog
+-----------------------------
+
+With version 0.2.0, the :class:`.SpikeTrain` class has been introduced to represent spike trains.
+This is a breaking change in the function interfaces.
+Hence, programs written for older versions of PySpike (0.1.x) will not run with newer versions.
+
+
 Requirements and Installation
 -----------------------------
 
@@ -65,14 +73,16 @@ Therefore, add your :code:`/path/to/PySpike` to the :code:`$PYTHONPATH` environm
 Spike trains
 ------------
 
-In PySpike, spike trains are represented by one-dimensional numpy arrays containing the sequence of spike times as double values.
+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 = np.array([0.1, 0.3, 0.45, 0.6, 0.9])
+    spike_train = SpikeTrain(np.array([0.1, 0.3, 0.45, 0.6, 0.9], [0.0, 1.0]))
 
 Loading from text files
 .......................
@@ -80,7 +90,7 @@ 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`.
+To quickly obtain spike trains from such files, PySpike provides the function :func:`.load_spike_trains_from_txt`.
 
 .. code:: python
 
@@ -88,22 +98,13 @@ To quickly obtain spike trains from such files, PySpike provides the function :c
     import pyspike as spk
     
     spike_trains = spk.load_spike_trains_from_txt("SPIKY_testdata.txt", 
-                                                  time_interval=(0, 4000))
+                                                  edges=(0, 4000))
 
 This function expects the name of the data file as first parameter.
-Additionally, the time interval 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 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, :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:
+As result, :func:`.load_spike_trains_from_txt` returns a *list of arrays* containing the spike trains in the text file.
 
-.. 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 bivariate distances profiles
 ---------------------------------------
@@ -114,19 +115,18 @@ Computing bivariate distances profiles
 
     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 `load_spike_trains_from_txt` function with the parameter `is_sorted=False`.
-    If in doubt, use :code:`spike_train = np.sort(spike_train)` to obtain a correctly sorted 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!
+    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
 ............
 
-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:
+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:
 
 .. code:: python
 
@@ -134,18 +134,18 @@ The following code loads some exemplary spike trains, computes the dissimilarity
     import pyspike as spk
     
     spike_trains = spk.load_spike_trains_from_txt("PySpike_testdata.txt",
-                                                  time_interval=(0, 4000))
+                                                  edges=(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_profile.avrg())
     plt.show()
 
-The ISI-profile is a piece-wise constant function, and hence the function :code:`isi_profile` returns an instance of the :code:`PieceWiseConstFunc` class.
+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 :code:`PieceWiseConstFunc` function.
+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.
-In the above example, the following code computes the ISI-distances obtained from averaging the ISI-profile over four different intervals:
+For the above example, the following code computes the ISI-distances obtained from averaging the ISI-profile over four different intervals:
 
 .. code:: python
 
@@ -168,7 +168,7 @@ where :code:`interval` is optional, as above, and if omitted the ISI-distance is
 SPIKE-distance
 ..............
 
-To compute for the spike distance profile you use the function :code:`spike_profile` instead of :code:`isi_profile` above. 
+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
@@ -177,7 +177,7 @@ But the general approach is very similar:
     import pyspike as spk
     
     spike_trains = spk.load_spike_trains_from_txt("PySpike_testdata.txt",
-                                                  time_interval=(0, 4000))
+                                                  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')
@@ -185,9 +185,9 @@ But the general approach is very similar:
     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 :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 arrays 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.
+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
@@ -217,9 +217,9 @@ SPIKE synchronization
 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 :code:`DiscreteFunction`.
+Therefore, it is represented by a :class:`.DiscreteFunction`.
 
-To compute for the spike synchronization profile, PySpike provides the function :code:`spike_sync_profile`.
+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
@@ -228,11 +228,11 @@ The general handling of the profile, however, is similar to the other profiles a
     import pyspike as spk
     
     spike_trains = spk.load_spike_trains_from_txt("PySpike_testdata.txt",
-                                                  time_interval=(0, 4000))
+                                                  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 :code:`spike_sync` function can be used:
+For the direct computation of the overall spike synchronization value within some interval, the :func:`.spike_sync` function can be used:
 
 .. code:: python
    
@@ -243,23 +243,23 @@ 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:
+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:
 
 .. code:: python
 
     spike_trains = spk.load_spike_trains_from_txt("PySpike_testdata.txt",
-                                                  time_interval=(0, 4000))
+                                                  edges=(0, 4000))
     avrg_isi_profile = spk.isi_profile_multi(spike_trains)
     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: :code:`isi_distance_multi`, :code:`spike_distance_multi` and :code:`spike_sync_multi`, that return the scalar overall multivariate ISI- and SPIKE-distance as well as the SPIKE-Synchronization value.
+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.
+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
diff --git a/doc/pyspike.rst b/doc/pyspike.rst
index 6aa36e7..a6dc1a0 100644
--- a/doc/pyspike.rst
+++ b/doc/pyspike.rst
@@ -1,60 +1,64 @@
 pyspike package
 ===============
 
-Submodules
-----------
 
-pyspike.isi_distance module
+Classes
 ----------------------------------------
 
-.. automodule:: pyspike.isi_distance
+SpikeTrain
+........................................
+.. automodule:: pyspike.SpikeTrain
     :members:
     :undoc-members:
     :show-inheritance:
 
-pyspike.spike_distance module
-----------------------------------------
-
-.. automodule:: pyspike.spike_distance
+PieceWiseConstFunc
+........................................
+.. automodule:: pyspike.PieceWiseConstFunc
     :members:
     :undoc-members:
     :show-inheritance:
 
-pyspike.spike_sync module
-----------------------------------------
-
-.. automodule:: pyspike.spike_sync
+PieceWiseLinFunc
+........................................
+.. automodule:: pyspike.PieceWiseLinFunc
     :members:
     :undoc-members:
     :show-inheritance:
 
-pyspike.PieceWiseConstFunc module
-----------------------------------------
-
-.. automodule:: pyspike.PieceWiseConstFunc
+DiscreteFunc
+........................................
+.. automodule:: pyspike.DiscreteFunc
     :members:
     :undoc-members:
     :show-inheritance:
 
-pyspike.PieceWiseLinFunc module
-----------------------------------------
+Functions
+----------
 
-.. automodule:: pyspike.PieceWiseLinFunc
+ISI-distance
+........................................
+.. automodule:: pyspike.isi_distance
     :members:
     :undoc-members:
     :show-inheritance:
 
-pyspike.DiscreteFunc module
-----------------------------------------
-
-.. automodule:: pyspike.DiscreteFunc
+SPIKE-distance
+........................................
+.. automodule:: pyspike.spike_distance
     :members:
     :undoc-members:
     :show-inheritance:
 
-pyspike.spikes module
-----------------------------------------
+SPIKE-synchronization
+........................................
+.. automodule:: pyspike.spike_sync
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
+Helper functions
+........................................
 .. automodule:: pyspike.spikes
     :members:
     :undoc-members:
diff --git a/pyspike/DiscreteFunc.py b/pyspike/DiscreteFunc.py
index bd13e1f..33b7a81 100644
--- a/pyspike/DiscreteFunc.py
+++ b/pyspike/DiscreteFunc.py
@@ -1,11 +1,7 @@
-"""
-Class representing discrete functions.
+# Class representing discrete functions.
+# Copyright 2014-2015, Mario Mulansky <mario.mulansky@gmx.net>
+# Distributed under the BSD License
 
-Copyright 2014-2015, Mario Mulansky <mario.mulansky@gmx.net>
-
-Distributed under the BSD License
-
-"""
 from __future__ import print_function
 
 import numpy as np
@@ -174,7 +170,7 @@ class DiscreteFunc(object):
 
     def avrg(self, interval=None):
         """ Computes the average of the interval sequence:
-        :math:`a = 1/N sum f_n` where N is the number of intervals.
+        :math:`a = 1/N \\sum f_n` where N is the number of intervals.
 
         :param interval: averaging interval given as a pair of floats, a
                          sequence of pairs for averaging multiple intervals, or
diff --git a/pyspike/PieceWiseConstFunc.py b/pyspike/PieceWiseConstFunc.py
index dc57ab1..41998ef 100644
--- a/pyspike/PieceWiseConstFunc.py
+++ b/pyspike/PieceWiseConstFunc.py
@@ -1,11 +1,7 @@
-"""
-Class representing piece-wise constant functions.
+# Class representing piece-wise constant functions.
+# Copyright 2014-2015, Mario Mulansky <mario.mulansky@gmx.net>
+# Distributed under the BSD License
 
-Copyright 2014-2015, Mario Mulansky <mario.mulansky@gmx.net>
-
-Distributed under the BSD License
-
-"""
 from __future__ import print_function
 
 import numpy as np
@@ -103,7 +99,7 @@ class PieceWiseConstFunc(object):
 
     def avrg(self, interval=None):
         """ Computes the average of the piece-wise const function:
-        :math:`a = 1/T int_0^T f(x) dx` where T is the length of the interval.
+        :math:`a = 1/T \int_0^T f(x) dx` where T is the length of the interval.
 
         :param interval: averaging interval given as a pair of floats, a
                          sequence of pairs for averaging multiple intervals, or
diff --git a/pyspike/PieceWiseLinFunc.py b/pyspike/PieceWiseLinFunc.py
index bc0aa2a..f2442be 100644
--- a/pyspike/PieceWiseLinFunc.py
+++ b/pyspike/PieceWiseLinFunc.py
@@ -1,11 +1,7 @@
-"""
-Class representing piece-wise linear functions.
+# Class representing piece-wise linear functions.
+# Copyright 2014-2015, Mario Mulansky <mario.mulansky@gmx.net>
+# Distributed under the BSD License
 
-Copyright 2014-2015, Mario Mulansky <mario.mulansky@gmx.net>
-
-Distributed under the BSD License
-
-"""
 from __future__ import print_function
 
 import numpy as np
@@ -123,7 +119,7 @@ class PieceWiseLinFunc:
 
     def avrg(self, interval=None):
         """ Computes the average of the piece-wise linear function:
-        :math:`a = 1/T int_0^T f(x) dx` where T is the length of the interval.
+        :math:`a = 1/T \int_0^T f(x) dx` where T is the interval length.
 
         :param interval: averaging interval given as a pair of floats, a
                          sequence of pairs for averaging multiple intervals, or
diff --git a/pyspike/SpikeTrain.py b/pyspike/SpikeTrain.py
index d586fe0..a02b7ab 100644
--- a/pyspike/SpikeTrain.py
+++ b/pyspike/SpikeTrain.py
@@ -1,9 +1,6 @@
-""" Module containing the class representing spike trains for PySpike.
-
-Copyright 2015, Mario Mulansky <mario.mulansky@gmx.net>
-
-Distributed under the BSD License
-"""
+# Module containing the class representing spike trains for PySpike.
+# Copyright 2015, Mario Mulansky <mario.mulansky@gmx.net>
+# Distributed under the BSD License
 
 import numpy as np
 
@@ -11,15 +8,22 @@ import numpy as np
 class SpikeTrain(object):
     """ Class representing spike trains for the PySpike Module."""
 
-    def __init__(self, spike_times, edges):
-        """ Constructs the SpikeTrain
+    def __init__(self, spike_times, edges, is_sorted=True):
+        """ Constructs the SpikeTrain.
+
         :param spike_times: ordered array of spike times.
         :param edges: The edges of the spike train. Given as a pair of floats
-        (T0, T1) or a single float T1, where then T0=0 is assumed.
+                      (T0, T1) or a single float T1, where then T0=0 is
+                      assumed.
+        :param is_sorted: If `False`, the spike times will sorted by `np.sort`.
+
         """
 
         # TODO: sanity checks
-        self.spikes = np.array(spike_times, dtype=float)
+        if is_sorted:
+            self.spikes = np.array(spike_times, dtype=float)
+        else:
+            self.spikes = np.sort(np.array(spike_times, dtype=float))
 
         try:
             self.t_start = float(edges[0])
@@ -27,3 +31,20 @@ class SpikeTrain(object):
         except:
             self.t_start = 0.0
             self.t_end = float(edges)
+
+    def sort(self):
+        """ Sorts the spike times of this spike train using `np.sort`
+        """
+        self.spikes = np.sort(self.spikes)
+
+    def copy(self):
+        """ Returns a copy of this spike train.
+        Use this function if you want to create a real (deep) copy of this
+        spike train. 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.
+
+        :return: :class:`.SpikeTrain` copy of this spike train.
+
+        """
+        return SpikeTrain(self.spikes.copy(), [self.t_start, self.t_end])
diff --git a/pyspike/isi_distance.py b/pyspike/isi_distance.py
index cb8ef54..aeab0df 100644
--- a/pyspike/isi_distance.py
+++ b/pyspike/isi_distance.py
@@ -1,11 +1,6 @@
-"""
-
-Module containing several functions to compute the ISI profiles and distances
-
-Copyright 2014-2015, Mario Mulansky <mario.mulansky@gmx.net>
-
-Distributed under the BSD License
-"""
+# Module containing several functions to compute the ISI profiles and distances
+# Copyright 2014-2015, Mario Mulansky <mario.mulansky@gmx.net>
+# Distributed under the BSD License
 
 from pyspike import PieceWiseConstFunc
 from pyspike.generic import _generic_profile_multi, _generic_distance_matrix
@@ -15,16 +10,16 @@ from pyspike.generic import _generic_profile_multi, _generic_distance_matrix
 # isi_profile
 ############################################################
 def isi_profile(spike_train1, spike_train2):
-    """ Computes the isi-distance profile :math:`S_{isi}(t)` of the two given
-    spike trains. Retruns the profile as a PieceWiseConstFunc object. The S_isi
-    values are defined positive S_isi(t)>=0.
+    """ Computes the isi-distance profile :math:`I(t)` of the two given
+    spike trains. Retruns the profile as a PieceWiseConstFunc object. The
+    ISI-values are defined positive :math:`I(t)>=0`.
 
     :param spike_train1: First spike train.
-    :type spike_train1: :class:`pyspike.SpikeTrain`
+    :type spike_train1: :class:`.SpikeTrain`
     :param spike_train2: Second spike train.
-    :type spike_train2: :class:`pyspike.SpikeTrain`
-    :returns: The isi-distance profile :math:`S_{isi}(t)`
-    :rtype: :class:`pyspike.function.PieceWiseConstFunc`
+    :type spike_train2: :class:`.SpikeTrain`
+    :returns: The isi-distance profile :math:`I(t)`
+    :rtype: :class:`.PieceWiseConstFunc`
 
     """
     # check whether the spike trains are defined for the same interval
@@ -54,20 +49,20 @@ Falling back to slow python backend.")
 # isi_distance
 ############################################################
 def isi_distance(spike_train1, spike_train2, interval=None):
-    """ Computes the isi-distance I of the given spike trains. The
+    """ Computes the ISI-distance :math:`D_I` of the given spike trains. The
     isi-distance is the integral over the isi distance profile
-    :math:`S_{isi}(t)`:
+    :math:`I(t)`:
 
-    .. math:: I = \int_{T_0}^{T_1} S_{isi}(t) dt.
+    .. math:: D_I = \\int_{T_0}^{T_1} I(t) dt.
 
     :param spike_train1: First spike train.
-    :type spike_train1: :class:`pyspike.SpikeTrain`
+    :type spike_train1: :class:`.SpikeTrain`
     :param spike_train2: Second spike train.
-    :type spike_train2: :class:`pyspike.SpikeTrain`
+    :type spike_train2: :class:`.SpikeTrain`
     :param interval: averaging interval given as a pair of floats (T0, T1),
                      if None the average over the whole function is computed.
     :type interval: Pair of floats or None.
-    :returns: The isi-distance I.
+    :returns: The isi-distance :math:`D_I`.
     :rtype: double
     """
     return isi_profile(spike_train1, spike_train2).avrg(interval)
@@ -79,15 +74,17 @@ def isi_distance(spike_train1, spike_train2, interval=None):
 def isi_profile_multi(spike_trains, indices=None):
     """ computes the multi-variate isi distance profile for a set of spike
     trains. That is the average isi-distance of all pairs of spike-trains:
-    S_isi(t) = 2/((N(N-1)) sum_{<i,j>} S_{isi}^{i,j},
+
+    .. math:: <I(t)> = \\frac{2}{N(N-1)} \\sum_{<i,j>} I^{i,j},
+
     where the sum goes over all pairs <i,j>
 
-    :param spike_trains: list of :class:`pyspike.SpikeTrain`
+    :param spike_trains: list of :class:`.SpikeTrain`
     :param indices: list of indices defining which spike trains to use,
                     if None all given spike trains are used (default=None)
     :type state: list or None
-    :returns: The averaged isi profile :math:`<S_{isi}>(t)`
-    :rtype: :class:`pyspike.function.PieceWiseConstFunc`
+    :returns: The averaged isi profile :math:`<I(t)>`
+    :rtype: :class:`.PieceWiseConstFunc`
     """
     average_dist, M = _generic_profile_multi(spike_trains, isi_profile,
                                              indices)
@@ -101,16 +98,18 @@ def isi_profile_multi(spike_trains, indices=None):
 def isi_distance_multi(spike_trains, indices=None, interval=None):
     """ computes the multi-variate isi-distance for a set of spike-trains.
     That is the time average of the multi-variate spike profile:
-    I = \int_0^T 2/((N(N-1)) sum_{<i,j>} S_{isi}^{i,j},
+
+    .. math:: D_I = \\int_0^T \\frac{2}{N(N-1)} \\sum_{<i,j>} I^{i,j},
+
     where the sum goes over all pairs <i,j>
 
-    :param spike_trains: list of spike trains
+    :param spike_trains: list of :class:`.SpikeTrain`
     :param indices: list of indices defining which spike trains to use,
                     if None all given spike trains are used (default=None)
     :param interval: averaging interval given as a pair of floats, if None
                      the average over the whole function is computed.
     :type interval: Pair of floats or None.
-    :returns: The time-averaged isi distance :math:`I`
+    :returns: The time-averaged multivariate ISI distance :math:`D_I`
     :rtype: double
     """
     return isi_profile_multi(spike_trains, indices).avrg(interval)
@@ -122,7 +121,7 @@ def isi_distance_multi(spike_trains, indices=None, interval=None):
 def isi_distance_matrix(spike_trains, indices=None, interval=None):
     """ Computes the time averaged isi-distance of all pairs of spike-trains.
 
-    :param spike_trains: list of :class:`pyspike.SpikeTrain`
+    :param spike_trains: list of :class:`.SpikeTrain`
     :param indices: list of indices defining which spike trains to use,
                     if None all given spike trains are used (default=None)
     :type indices: list or None
@@ -130,7 +129,7 @@ def isi_distance_matrix(spike_trains, indices=None, interval=None):
                      the average over the whole function is computed.
     :type interval: Pair of floats or None.
     :returns: 2D array with the pair wise time average isi distances
-              :math:`I_{ij}`
+              :math:`D_{I}^{ij}`
     :rtype: np.array
     """
     return _generic_distance_matrix(spike_trains, isi_distance,
diff --git a/pyspike/spike_distance.py b/pyspike/spike_distance.py
index 8d03d70..cc620d4 100644
--- a/pyspike/spike_distance.py
+++ b/pyspike/spike_distance.py
@@ -1,11 +1,6 @@
-"""
-
-Module containing several functions to compute SPIKE profiles and distances
-
-Copyright 2014-2015, Mario Mulansky <mario.mulansky@gmx.net>
-
-Distributed under the BSD License
-"""
+# Module containing several functions to compute SPIKE profiles and distances
+# Copyright 2014-2015, Mario Mulansky <mario.mulansky@gmx.net>
+# Distributed under the BSD License
 
 from pyspike import PieceWiseLinFunc
 from pyspike.generic import _generic_profile_multi, _generic_distance_matrix
@@ -15,16 +10,16 @@ from pyspike.generic import _generic_profile_multi, _generic_distance_matrix
 # spike_profile
 ############################################################
 def spike_profile(spike_train1, spike_train2):
-    """ Computes the spike-distance profile S_spike(t) of the two given spike
-    trains. Returns the profile as a PieceWiseLinFunc object. The S_spike
-    values are defined positive S_spike(t)>=0.
+    """ Computes the spike-distance profile :math:`S(t)` of the two given spike
+    trains. Returns the profile as a PieceWiseLinFunc object. The SPIKE-values
+    are defined positive :math:`S(t)>=0`.
 
     :param spike_train1: First spike train.
-    :type spike_train1: :class:`pyspike.SpikeTrain`
+    :type spike_train1: :class:`.SpikeTrain`
     :param spike_train2: Second spike train.
-    :type spike_train2: :class:`pyspike.SpikeTrain`
-    :returns: The spike-distance profile :math:`S_{spike}(t)`.
-    :rtype: :class:`pyspike.function.PieceWiseLinFunc`
+    :type spike_train2: :class:`.SpikeTrain`
+    :returns: The spike-distance profile :math:`S(t)`.
+    :rtype: :class:`.PieceWiseLinFunc`
 
     """
     # check whether the spike trains are defined for the same interval
@@ -56,15 +51,15 @@ Falling back to slow python backend.")
 # spike_distance
 ############################################################
 def spike_distance(spike_train1, spike_train2, interval=None):
-    """ Computes the spike-distance S of the given spike trains. The
-    spike-distance is the integral over the isi distance profile S_spike(t):
+    """ Computes the spike-distance :math:`D_S` of the given spike trains. The
+    spike-distance is the integral over the isi distance profile :math:`S(t)`:
 
-    .. math:: S = \int_{T_0}^{T_1} S_{spike}(t) dt.
+    .. math:: D_S = \int_{T_0}^{T_1} S(t) dt.
 
     :param spike_train1: First spike train.
-    :type spike_train1: :class:`pyspike.SpikeTrain`
+    :type spike_train1: :class:`.SpikeTrain`
     :param spike_train2: Second spike train.
-    :type spike_train2: :class:`pyspike.SpikeTrain`
+    :type spike_train2: :class:`.SpikeTrain`
     :param interval: averaging interval given as a pair of floats (T0, T1),
                      if None the average over the whole function is computed.
     :type interval: Pair of floats or None.
@@ -81,15 +76,17 @@ def spike_distance(spike_train1, spike_train2, interval=None):
 def spike_profile_multi(spike_trains, indices=None):
     """ Computes the multi-variate spike distance profile for a set of spike
     trains. That is the average spike-distance of all pairs of spike-trains:
-    :math:`S_spike(t) = 2/((N(N-1)) sum_{<i,j>} S_{spike}^{i, j}`,
+
+    .. math:: <S(t)> = \\frac{2}{N(N-1)} \\sum_{<i,j>} S^{i, j}`,
+
     where the sum goes over all pairs <i,j>
 
-    :param spike_trains: list of spike trains
+    :param spike_trains: list of :class:`.SpikeTrain`
     :param indices: list of indices defining which spike trains to use,
                     if None all given spike trains are used (default=None)
     :type indices: list or None
-    :returns: The averaged spike profile :math:`<S_{spike}>(t)`
-    :rtype: :class:`pyspike.function.PieceWiseLinFunc`
+    :returns: The averaged spike profile :math:`<S>(t)`
+    :rtype: :class:`.PieceWiseLinFunc`
 
     """
     average_dist, M = _generic_profile_multi(spike_trains, spike_profile,
@@ -104,17 +101,20 @@ def spike_profile_multi(spike_trains, indices=None):
 def spike_distance_multi(spike_trains, indices=None, interval=None):
     """ Computes the multi-variate spike distance for a set of spike trains.
     That is the time average of the multi-variate spike profile:
-    S_{spike} = \int_0^T 2/((N(N-1)) sum_{<i,j>} S_{spike}^{i, j} dt
+
+    .. math::  D_S = \\int_0^T \\frac{2}{N(N-1)} \\sum_{<i,j>}
+               S^{i, j} dt
+
     where the sum goes over all pairs <i,j>
 
-    :param spike_trains: list of :class:`pyspike.SpikeTrain`
+    :param spike_trains: list of :class:`.SpikeTrain`
     :param indices: list of indices defining which spike trains to use,
                     if None all given spike trains are used (default=None)
     :type indices: list or None
     :param interval: averaging interval given as a pair of floats, if None
                      the average over the whole function is computed.
     :type interval: Pair of floats or None.
-    :returns: The averaged spike distance S.
+    :returns: The averaged multi-variate spike distance :math:`D_S`.
     :rtype: double
     """
     return spike_profile_multi(spike_trains, indices).avrg(interval)
@@ -126,7 +126,7 @@ def spike_distance_multi(spike_trains, indices=None, interval=None):
 def spike_distance_matrix(spike_trains, indices=None, interval=None):
     """ Computes the time averaged spike-distance of all pairs of spike-trains.
 
-    :param spike_trains: list of :class:`pyspike.SpikeTrain`
+    :param spike_trains: list of :class:`.SpikeTrain`
     :param indices: list of indices defining which spike trains to use,
                     if None all given spike trains are used (default=None)
     :type indices: list or None
@@ -134,7 +134,7 @@ def spike_distance_matrix(spike_trains, indices=None, interval=None):
                      the average over the whole function is computed.
     :type interval: Pair of floats or None.
     :returns: 2D array with the pair wise time average spike distances
-              :math:`S_{ij}`
+              :math:`D_S^{ij}`
     :rtype: np.array
     """
     return _generic_distance_matrix(spike_trains, spike_distance,
diff --git a/pyspike/spike_sync.py b/pyspike/spike_sync.py
index 8ddd32c..9d2e363 100644
--- a/pyspike/spike_sync.py
+++ b/pyspike/spike_sync.py
@@ -1,12 +1,7 @@
-"""
-
-Module containing several functions to compute SPIKE-Synchronization profiles
-and distances
-
-Copyright 2014-2015, Mario Mulansky <mario.mulansky@gmx.net>
-
-Distributed under the BSD License
-"""
+# Module containing several functions to compute SPIKE-Synchronization profiles
+# and distances
+# Copyright 2014-2015, Mario Mulansky <mario.mulansky@gmx.net>
+# Distributed under the BSD License
 
 from functools import partial
 from pyspike import DiscreteFunc
@@ -27,7 +22,7 @@ def spike_sync_profile(spike_train1, spike_train2, max_tau=None):
     :param spike_train2: Second spike train.
     :type spike_train2: :class:`pyspike.SpikeTrain`
     :param max_tau: Maximum coincidence window size. If 0 or `None`, the
-    coincidence window has no upper bound.
+                    coincidence window has no upper bound.
     :returns: The spike-distance profile :math:`S_{sync}(t)`.
     :rtype: :class:`pyspike.function.DiscreteFunction`
 
@@ -77,12 +72,13 @@ def spike_sync(spike_train1, spike_train2, interval=None, max_tau=None):
     :param spike_train2: Second spike train.
     :type spike_train2: :class:`pyspike.SpikeTrain`
     :param interval: averaging interval given as a pair of floats (T0, T1),
-                     if None the average over the whole function is computed.
+                     if `None` the average over the whole function is computed.
     :type interval: Pair of floats or None.
     :param max_tau: Maximum coincidence window size. If 0 or `None`, the
-    coincidence window has no upper bound.
+                    coincidence window has no upper bound.
     :returns: The spike synchronization value.
-    :rtype: double
+    :rtype: `double`
+
     """
     return spike_sync_profile(spike_train1, spike_train2,
                               max_tau).avrg(interval)
@@ -103,7 +99,7 @@ def spike_sync_profile_multi(spike_trains, indices=None, max_tau=None):
                     if None all given spike trains are used (default=None)
     :type indices: list or None
     :param max_tau: Maximum coincidence window size. If 0 or `None`, the
-    coincidence window has no upper bound.
+                    coincidence window has no upper bound.
     :returns: The multi-variate spike sync profile :math:`<S_{sync}>(t)`
     :rtype: :class:`pyspike.function.DiscreteFunction`
 
@@ -130,9 +126,10 @@ def spike_sync_multi(spike_trains, indices=None, interval=None, max_tau=None):
                      the average over the whole function is computed.
     :type interval: Pair of floats or None.
     :param max_tau: Maximum coincidence window size. If 0 or `None`, the
-    coincidence window has no upper bound.
+                    coincidence window has no upper bound.
     :returns: The multi-variate spike synchronization value SYNC.
     :rtype: double
+
     """
     return spike_sync_profile_multi(spike_trains, indices,
                                     max_tau).avrg(interval)
@@ -153,10 +150,11 @@ def spike_sync_matrix(spike_trains, indices=None, interval=None, max_tau=None):
                      the average over the whole function is computed.
     :type interval: Pair of floats or None.
     :param max_tau: Maximum coincidence window size. If 0 or `None`, the
-    coincidence window has no upper bound.
+                    coincidence window has no upper bound.
     :returns: 2D array with the pair wise time spike synchronization values
               :math:`SYNC_{ij}`
     :rtype: np.array
+
     """
     dist_func = partial(spike_sync, max_tau=max_tau)
     return _generic_distance_matrix(spike_trains, dist_func,
diff --git a/pyspike/spikes.py b/pyspike/spikes.py
index 9401b6e..35d8533 100644
--- a/pyspike/spikes.py
+++ b/pyspike/spikes.py
@@ -1,11 +1,6 @@
-""" spikes.py
-
-Module containing several function to load and transform spike trains
-
-Copyright 2014, Mario Mulansky <mario.mulansky@gmx.net>
-
-Distributed under the BSD License
-"""
+# Module containing several function to load and transform spike trains
+# Copyright 2014, Mario Mulansky <mario.mulansky@gmx.net>
+# Distributed under the BSD License
 
 import numpy as np
 from pyspike import SpikeTrain
@@ -15,21 +10,18 @@ from pyspike import SpikeTrain
 # spike_train_from_string
 ############################################################
 def spike_train_from_string(s, edges, sep=' ', is_sorted=False):
-    """ Converts a string of times into a  :class:`pyspike.SpikeTrain`.
+    """ Converts a string of times into a  :class:`.SpikeTrain`.
 
     :param s: the string with (ordered) spike times.
     :param edges: interval defining the edges of the spike train.
-    Given as a pair of floats (T0, T1) or a single float T1, where T0=0 is
-    assumed.
+                  Given as a pair of floats (T0, T1) or a single float T1,
+                  where T0=0 is assumed.
     :param sep: The separator between the time numbers, default=' '.
     :param is_sorted: if True, the spike times are not sorted after loading,
                       if False, spike times are sorted with `np.sort`
-    :returns:  :class:`pyspike.SpikeTrain`
+    :returns: :class:`.SpikeTrain`
     """
-    if not(is_sorted):
-        return SpikeTrain(np.sort(np.fromstring(s, sep=sep)), edges)
-    else:
-        return SpikeTrain(np.fromstring(s, sep=sep), edges)
+    return SpikeTrain(np.fromstring(s, sep=sep), edges, is_sorted)
 
 
 ############################################################
@@ -40,7 +32,7 @@ def load_spike_trains_from_txt(file_name, edges,
     """ Loads a number of spike trains from a text file. Each line of the text
     file should contain one spike train as a sequence of spike times separated
     by `separator`. Empty lines as well as lines starting with `comment` are
-    neglected. The `interval` represents the start and the end of the
+    neglected. The `edges` represents the start and the end of the
     spike trains.
 
     :param file_name: The name of the text file.
@@ -51,7 +43,7 @@ def load_spike_trains_from_txt(file_name, edges,
     :param separator: The character used to seprate the values in the text file
     :param comment: Lines starting with this character are ignored.
     :param sort: If true, the spike times are order via `np.sort`, default=True
-    :returns: list of spike trains
+    :returns: list of :class:`.SpikeTrain`
     """
     spike_trains = []
     spike_file = open(file_name, 'r')
@@ -70,7 +62,7 @@ def load_spike_trains_from_txt(file_name, edges,
 def merge_spike_trains(spike_trains):
     """ Merges a number of spike trains into a single spike train.
 
-    :param spike_trains: list of arrays of spike times
+    :param spike_trains: list of :class:`.SpikeTrain`
     :returns: spike train with the merged spike times
     """
     # get the lengths of the spike trains
@@ -110,7 +102,7 @@ def generate_poisson_spikes(rate, interval):
                      to the spike train at the beginning and end of this
                      interval, if they are not yet present.
     :type interval: pair of doubles or double
-    :returns: Poisson spike train as a :class:`pyspike.SpikeTrain`
+    :returns: Poisson spike train as a :class:`.SpikeTrain`
     """
     try:
         T_start = interval[0]