Fixed Unitary Event Analysis plot

[dizcza]

• Fixes Viziphant UE plotting to handle triple correlations (and more) #24
• Fixes the unreported bug when Js values contain NaNs, leading to (possibly) shifted unitary event red marks. The fix was to change t_winpos[j] -> t_winpos[js_nonnan][j] so that sig_idx_win and t_winpos indices become aligned.
• Added an example to the documentation.
• Refactored the all-mighty code for axes plotting routines.

Requires NeuralEnsemble/elephant#387, which simplifies the API significantly by storing the input parameters.

Potential improvements, disregarded in this PR:

• rename Js_dict to a more meaningful name;
• use viziphant.events.add_event function to plot events instead of custom error-prone script, included in the function body.
• optimize axes[5] unitary events mask selection by stripping off the quantity units.

P.S. The build fails because, of course, it expects the changes in elephant to be already in the master branch.

[dizcza]

1. UEA elephant tutorial example.

For the comparison, see https://elephant.readthedocs.io/en/latest/tutorials/unitary_event_analysis.html

import matplotlib.pyplot as plt
import neo
import numpy as np
import quantities as pq

import elephant.unitary_event_analysis as ue
from viziphant.unitary_event_analysis import plot_ue

block = neo.io.NeoHdf5IO("dataset-1.h5").read_block()
sts1 = block.segments[0].spiketrains
sts2 = block.segments[1].spiketrains
spiketrains = np.stack((sts1, sts2), axis=1)

bin_size = 5 * pq.ms
winsize = 100 * pq.ms
winstep = 10 * pq.ms

Js_dict = ue.jointJ_window_analysis(spiketrains,
    bin_size=bin_size, winsize=winsize, winstep=winstep)

fig = plot_ue(spiketrains, Js_dict=Js_dict, significance_level=0.05)
plt.show()

[dizcza]

2. UEA workshop example

import matplotlib.pyplot as plt
import quantities as pq

import elephant.unitary_event_analysis as ue
from viziphant.unitary_event_analysis import plot_ue

winsize = 100 * pq.ms
binsize = 5 * pq.ms
winstep = 5 * pq.ms
method = 'analytic_TrialByTrial'

plot_params = {
    'events': {'TS-ON': [0 * pq.ms]},
    'unit_real_ids': [sts_for_uea[0][0].name[-5:],
                      sts_for_uea[0][1].name[-5:]],
    'hspace': 0.6,
    'figsize': (10, 12),
    'fsize': 12,
    'ms': 5,
    'lw': 1
}


uriana = ue.jointJ_window_analysis(sts_for_uea, bin_size=binsize,
                                   winsize=winsize, winstep=winstep,
                                   method=method, pattern_hash=[3])

fig = plot_ue(sts_for_uea, Js_dict=uriana, significance_level=0.05,
              **plot_params)

Left: new implementation.
Right: previous (master branch).

[dizcza]

3. UEA Poisson processes with 3 neurons

import matplotlib.pyplot as plt
import numpy as np
import quantities as pq

import viziphant
from elephant.spike_train_generation import homogeneous_poisson_process
from elephant.unitary_event_analysis import jointJ_window_analysis, \
    hash_from_pattern

np.random.seed(10)

spiketrains1 = [homogeneous_poisson_process(rate=20 * pq.Hz, t_stop=2 * pq.s)
                for _ in range(5)]
spiketrains2 = [homogeneous_poisson_process(rate=50 * pq.Hz, t_stop=2 * pq.s)
                for _ in range(5)]
spiketrains3 = [homogeneous_poisson_process(rate=20 * pq.Hz, t_stop=2 * pq.s)
                for _ in range(5)]

spiketrains = np.stack((spiketrains1, spiketrains2, spiketrains3), axis=1)
ue_dict = jointJ_window_analysis(spiketrains, bin_size=5 * pq.ms,
                                 win_size=100 * pq.ms, win_step=10 * pq.ms,
                                 pattern_hash=hash_from_pattern([1, 0, 1]))
viziphant.unitary_event_analysis.plot_ue(spiketrains, Js_dict=ue_dict,
                                         significance_level=0.34,
                                         unit_real_ids=['1', '2', '3'])
plt.show()

As you can see, one can easily deduce the unit of the intermediate raster plot (the top axis) by looking at the legend of the second axis.

[rjurkus]

The labels are not always visible in the figure. Perhaps one should consider adjusting the placement?

[dizcza]

I don't know how to fix this issue efficiently. Ideally, viziphant.event.add_event should be used. But currently, it's not possible.
Perhaps, this can be a separate PR once either of us comes up with an appropriate solution.