Usage¶

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.