Requirements¶

• CPython 2.7 or 3.x.
• NumPy>=1.7.
• C++ development tools and Standard Library (package build-essential on Debian).
• Python development tools (package python-dev on Debian).

Installing via pip¶

To install the latest release, run:

pip install pymuvr

Testing¶

From the root directory of the source distribution, run:

python setup.py test

(requires setuptools). Alternatively, if pymuvr is already installed on your system, look for the copy of the test_pymuvr.py script installed alongside the rest of the pymuvr files and execute it. For example:

python /usr/lib/pythonX.Y/site-packages/pymuvr/test/test_pymuvr.py

A compact formalism for kernel-based multiunit spike train metrics¶

Consider a network with \(C\) cells. Let

be an observation of network activity, where

is the (ordered) set of times of the spikes emitted by cell \(i\). Let \(\mathcal{V}= \left\{\boldsymbol{v}^1, \boldsymbol{v}^2, \ldots, \boldsymbol{v}^C\right\}\) be another observation, different in general from \(\mathcal{U}\).

To compute a kernel based multiunit distance between \(\mathcal{U}\) and \(\mathcal{V}\), we map them to the tensor product space \(\mathcal{S} \doteq \mathbb{R}^C\bigotimes L_2(\mathbb{R}\rightarrow\mathbb{R})\) by defining

where we consider \(\mathbb{R}^C\) and \(L_2(\mathbb{R}\rightarrow\mathbb{R})\) to be equipped with the usual euclidean distances, consequently inducing an euclidean metric structure on \(\mathcal{S}\) too.

Conceptually, the set of vectors \(\left\{ |i\rangle \right\}_{i=1}^C \subset \mathbb{R}^C\) represents the different cells, while each \(|\boldsymbol{u}^i\rangle \in L_2(\mathbb{R}\rightarrow\mathbb{R})\) represents the convolution of a spike train of cell \(i\) with a real-valued feature function \(\phi: \mathbb{R}\rightarrow\mathbb{R}\),

In practice, we will never use the feature functions directly, but we will be only interested in the inner products of the \(|i\rangle\) and \(|\boldsymbol{u}\rangle\) vectors. We call \(c_{ij}\doteq\langle i|j \rangle=\langle i|j \rangle_{\mathbb{R}^C}=c_{ji}\) the multiunit mixing coefficient for cells \(i\) and \(j\), and \(\langle \boldsymbol{u}|\boldsymbol{v}\rangle=\langle \boldsymbol{u}|\boldsymbol{v}\rangle_{L_2}\) the single-unit inner product,

where \(\mathcal{K}(t_1,t_2)\doteq\int\textrm{d }\!t \left[\phi\left(t-t_1\right)\phi\left(t-t_2\right)\right]\) is the single-unit metric kernel, and where we have used the fact that the feature function \(\phi\) is real-valued. It follows immediately from the definition above that \(\langle \boldsymbol{u}|\boldsymbol{v}\rangle=\langle \boldsymbol{v}|\boldsymbol{u}\rangle\).

Note that, given a cell pair \((i,j)\) or a spike train pair \((\boldsymbol{u},\boldsymbol{v})\), \(c_{ij}\) does not depend on spike times and \(\langle \boldsymbol{u}|\boldsymbol{v}\rangle\) does not depend on cell labeling.

With this notation, we can define the multi-unit spike train distance as

where the multi-unit spike train inner product \(\langle \mathcal{V}|\mathcal{U}\rangle\) between \(\mathcal{U}\) and \(\mathcal{V}\) is just the natural bilinear operation induced on \(\mathcal{S}\) by the tensor product structure:

But \(c_{ij}=c_{ji}\) and \(\langle \boldsymbol{v}|\boldsymbol{u}\rangle=\langle \boldsymbol{u}|\boldsymbol{v}\rangle\), so

and

Now, normally we are interested in the particular case where \(c_{ij}\) is the same for all pair of distinct cells:

and under this assumption we can write

and

Rearranging the terms

Van Rossum-like metrics¶

In Van Rossum-like metrics, the feature function and the single-unit kernel are, for \(\tau\neq 0\),

where \(\theta\) is the Heaviside step function (with \(\theta(0)=1\)), and we have chosen to normalise \(\phi^{\textrm{VR}}_{\tau}\) so that

In the \(\tau\rightarrow 0\) limit,

In particular, the single-unit inner product now becomes

Examples¶

>>> import pymuvr
>>> # define two sets of observations for two cells
>>> observations_1 = [[[1.0, 2.3], # 1st observation, 1st cell
...                    [0.2, 2.5, 2.7]],            # 2nd cell
...                   [[1.1, 1.2, 3.0], # 2nd observation
...                    []],
...                   [[5.0, 7.8],
...                    [4.2, 6.0]]]
>>> observations_2 = [[[0.9],
...                    [0.7, 0.9, 3.3]],
...                   [[0.3, 1.5, 2.4],
...                    [2.5, 3.7]]]
>>> # set parameters for the metric
>>> cos = 0.1
>>> tau = 1.0
>>> # compute distances between all observations in set 1
>>> # and those in set 2
>>> pymuvr.dissimilarity_matrix(observations_1,
...                             observations_2,
...                             cos,
...                             tau,
...                             'distance')
array([[ 2.40281585,  1.92780957],
       [ 2.76008964,  2.31230263],
       [ 3.1322069 ,  3.17216524]])
>>> # compute inner products
>>> pymuvr.dissimilarity_matrix(observations_1,
...                             observations_2,
...                             cos,
...                             tau,
...                             'inner product')
array([[ 4.30817654,  5.97348384],
       [ 2.08532468,  3.85777053],
       [ 0.59639918,  1.10721323]])
>>> # compute all distances between observations in set 1
>>> pymuvr.square_dissimilarity_matrix(observations_1,
...                                    cos,
...                                    tau,
...                                    'distance')
array([[ 0.        ,  2.6221159 ,  3.38230952],
       [ 2.6221159 ,  0.        ,  3.10221811],
       [ 3.38230952,  3.10221811,  0.        ]])
>>> # compute inner products
>>> pymuvr.square_dissimilarity_matrix(observations_1,
...                                    cos,
...                                    tau,
...                                    'inner product')
array([[ 8.04054275,  3.3022304 ,  0.62735459],
       [ 3.3022304 ,  5.43940985,  0.23491838],
       [ 0.62735459,  0.23491838,  4.6541841 ]])

See the examples and test directories in the source distribution for more detailed examples of usage. These should also have been installed alongside the rest of the pymuvr files.

The script examples/benchmark_versus_spykeutils.py compares the performance of pymuvr with the pure Python/NumPy implementation of the multiunit Van Rossum distance in spykeutils.

Reference¶

pymuvr.dissimilarity_matrix(observations1, observations2, cos, tau, mode)¶

Return the bipartite (rectangular) dissimilarity matrix between the observations in the first and the second list.

Parameters:	observations1,observations2 (list) – Two lists of multi-unit spike trains to compare. Each observations parameter must be a thrice-nested list of spike times, with observations[i][j][k] representing the time of the kth spike of the jth cell of the ith observation. cos (float) – mixing parameter controlling the interpolation between labelled-line mode (cos=0) and summed-population mode (cos=1). It corresponds to the cosine of the angle between the vectors used for the euclidean embedding of the multiunit spike trains. tau (float) – time scale for the exponential kernel, controlling the interpolation between pure coincidence detection (tau=0) and spike count mode (very large tau). Note that setting tau=0 is always allowed, but there is a range (0, epsilon) of forbidden values that tau is not allowed to assume. The upper bound of this range is proportional to the absolute value of the largest spike time in observations, with the proportionality constant being system-dependent. As a rule of thumb tau and the spike times should be within 4 orders of magnitude of each other; for example, if the largest spike time is 10s a value of tau>1ms will be expected. An exception will be raised if tau falls in the forbidden range. mode (string) – type of dissimilarity measure to be computed. Must be either ‘distance’ or ‘inner product’.
Returns:	A len(observations1) x len(observations2) numpy array containing the dissimilarity (distance or inner product) between each pair of observations that can be formed by taking one observation from observations1 and one from observations2.
Return type:	numpy.ndarray
Raises:	IndexError – if the observations in observations1 and observations2 don’t have all the same number of cells. OverflowError – if tau falls in the forbidden interval.

pymuvr.square_dissimilarity_matrix(observations, cos, tau, mode)¶

Return the all-to-all (square) dissimilarity matrix for the given list of observations.

Parameters:	observations (list) – A list of multi-unit spike trains to compare. cos (float) – mixing parameter controlling the interpolation between labelled-line mode (cos=0) and summed-population mode (cos=1). tau (float) – time scale for the exponential kernel, controlling the interpolation between pure coincidence detection (tau=0) and spike count mode (very large tau). mode (string) – type of dissimilarity measure to be computed. Must be either ‘distance’ or ‘inner product’.
Returns:	A len(observations) x len(observations) numpy array containing the dissimilarity (distance or inner product) between all possible pairs of observations.
Return type:	numpy.ndarray
Raises:	IndexError – if the observations in observations don’t have all the same number of cells. OverflowError – if tau falls in the forbidden interval.

Effectively equivalent to dissimilarity_matrix(observations, observations, cos, tau), but optimised for speed. See pymuvr.dissimilarity_matrix() for details.

pymuvr.distance_matrix(trains1, trains2, cos, tau)¶

Return the bipartite (rectangular) distance matrix between the observations in the first and the second list.

Convenience function; equivalent to dissimilarity_matrix(trains1, trains2, cos, tau, "distance"). Refer to pymuvr.dissimilarity_matrix() for full documentation.

pymuvr.square_distance_matrix(trains, cos, tau)¶

Return the all-to-all (square) distance matrix for the given list of observations.

Convenience function; equivalent to square_dissimilarity_matrix(trains, cos, tau, "distance"). Refer to pymuvr.square_dissimilarity_matrix() for full documentation.