diff --git a/elephant/functional_connectivity.py b/elephant/functional_connectivity.py index dc5e764cc..11f7f14ef 100644 --- a/elephant/functional_connectivity.py +++ b/elephant/functional_connectivity.py @@ -1,7 +1,7 @@ """ -Functions for analysing and estimating firing-patterns and connectivity among neurons -in order to better understand the underlying neural-networks and information-flow -between neurons. +Functions for analysing and estimating firing patterns and connectivity among +neurons in order to better understand the underlying neural networks and +information flow between neurons. Network connectivity estimation @@ -19,7 +19,7 @@ :keyprefix: functional_connectivity- -:copyright: Copyright 2014-2023 by the Elephant team, see `doc/authors.rst`. +:copyright: Copyright 2014-2024 by the Elephant team, see `doc/authors.rst`. :license: Modified BSD, see LICENSE.txt for details. """ diff --git a/elephant/functional_connectivity_src/total_spiking_probability_edges.py b/elephant/functional_connectivity_src/total_spiking_probability_edges.py index b1964aa0b..0e6a1762f 100644 --- a/elephant/functional_connectivity_src/total_spiking_probability_edges.py +++ b/elephant/functional_connectivity_src/total_spiking_probability_edges.py @@ -16,45 +16,45 @@ def total_spiking_probability_edges( normalize: bool = False, ): r""" - Use total spiking probability edges (TSPE) to estimate - the functional connectivity and delay-times of a neural-network. + Estimate the functional connectivity and delay times of a neural network + using Total Spiking Probability Edges (TSPE). This algorithm uses a normalized cross correlation between pairs of - spiketrains at different delay-times to get a cross-correlogram. - Afterwards a series of convolutions with multiple edge-filters - on the cross-correlogram are preformed, in order to estimate the + spike trains at different delay times to get a cross-correlogram. + Afterwards, a series of convolutions with multiple edge filters + on the cross-correlogram are performed, in order to estimate the connectivity between neurons and thus allowing the discrimination between inhibitory and excitatory effects. - The default window-sizes and max-delay were optimized using - in-silico generated spiketrains. + The default window sizes and maximum delay were optimized using + in-silico generated spike trains. *Background:* - - On an excitatory connection the spikerate increases and decreases again + - On an excitatory connection the spike rate increases and decreases again due to the refractory period which results in local maxima in the - cross-correlogram followed by downwards slope + cross-correlogram followed by downwards slope. - - On an inhibitory connection the spikerate decreases and after refractory - period, increases again which results in lokal minima surrounded by high + - On an inhibitory connection the spike rate decreases and after refractory + period, increases again which results in local minima surrounded by high values in the cross-correlogram. - - An Edge-Filter can be used to interpret the cross-correlogram and - accentuate the lokal Maxima and Minima + - An edge filter can be used to interpret the cross-correlogram and + accentuate the local maxima and minima *Procedure:* - 1) Compute normalized cross-correlation :math:`NCC` of spiketrains of all - Neuronpairs - 2) Convolve :math:`NCC` with Edge-Filter :math:`g_{i}` to compute - :math:`SPE` - 3) Convolve :math:`SPE` with corresponding Running-Total-Filter + 1) Compute normalized cross-correlation :math:`NCC` of spike trains of all + neuron pairs. + 2) Convolve :math:`NCC` with edge filter :math:`g_{i}` to compute + :math:`SPE`. + 3) Convolve :math:`SPE` with corresponding running total filter :math:`h_{i}` to account for different lengths after convolution with - Edge-Filter + edge filter. 4) Compute :math:`TSPE` using the sum of all :math:`SPE` for all different - filterpairs - 5) Compute connectivitymatrix by using the index of the tspe-values with - the highest absolute values + filter pairs. + 5) Compute the connectivity matrix by using the index of the TSPE values + with the highest absolute values. *Normalized Cross-Correlation:* @@ -63,47 +63,75 @@ def total_spiking_probability_edges( NCC_{XY}(d) = \frac{1}{N} \sum_{i=-\infty}^{\infty}{ \frac{ (y_{(i)} - \bar{y}) \cdot (x_{(i-d)} - \bar{x}) }{ \sigma_x \cdot \sigma_y }} - *Spiking Probability Edges* + *Edge Filter* .. math :: - SPE_{X \rightarrow Y(d)} = NCC_{XY}(d) * g(i) - *Total Spiking Probability Edges:* - - .. math :: - TSPE_{X \rightarrow Y}(d) = \sum_{n=1}^{N_a \cdot N_b \cdot N_c} - {SPE_{X \rightarrow Y}^{(n)}(d) * h(i)^{(n)} } - - :cite:`functional_connectivity-de_blasi19_169` - - Parameters - ---------- - spike_trains : (N, ) elephant.conversion.BinnedSpikeTrain - A binned spike train containing all neurons for connectivity estimation - surrounding_window_sizes : List[int], default = [3, 4, 5, 6, 7, 8] - Array of window-sizes for the surrounding area of the point of - interest. - observed_window_sizes : List[int], default = [2, 3, 4, 5, 6] - Array of window-sizes for the observed area - crossover_window_sizes : List[int], default = [0] - Array of window-sizes for the crossover between surrounding and - observed window. - max_delay : int, default = 25 - Defines the max delay when performing the normalized crosscorrelations. - Value depends on the bin-size of the BinnedSpikeTrain. - On a bin-size of *1ms* a value of *25* corresponds to *25ms* - normalize : bool, optional - Normalize the output [experimental] - - Returns - ------- - connectivity_matrix : (N, N) np.ndarray - Square Matrix of the connectivity estimation between neurons. - Positive values describe an excitatory connection while - negative values describe an inhibitory connection. - delay_matrix : (N, N) np.ndarray - Square Matrix of the delay_times between neuron-activity. - """ + g_{(i)} = \begin{cases} + - \frac{1}{a} & 0 \lt i \leq a \ \ + \frac{2}{b} & a+c \lt i \leq a + b + c \ \ + - \frac{1}{a} & a+b+2c \lt i \leq 2a + b + 2c \ \ + 0 & \mathrm{otherwise} + \end{cases} + + where :math:`a` is the parameter `surrounding_window_size`, :math:`b` + `observed_window_size`, and :math:`c` is the parameter + `crossover_window_size`. + + +*Spiking Probability Edges* + +.. math :: + SPE_{X \rightarrow Y(d)} = NCC_{XY}(d) * g(i) + +*Total Spiking Probability Edges:* + +.. math :: + TSPE_{X \rightarrow Y}(d) = \sum_{n=1}^{N_a \cdot N_b \cdot N_c} + {SPE_{X \rightarrow Y}^{(n)}(d) * h(i)^{(n)} } + +:cite:`functional_connectivity-de_blasi19_169` + +Parameters +---------- +spike_trains : (N, ) elephant.conversion.BinnedSpikeTrain + A binned spike train containing all neurons for connectivity estimation +surrounding_window_sizes : List[int] + Array of window sizes for the surrounding area of the point of + interest. This corresponds to parameter `a` of the edge filter in + :cite:`functional_connectivity-de_blasi19_169`. Value is given in units of + the number of bins according to the binned spike trains `spike_trains`. + Default: [3, 4, 5, 6, 7, 8] +observed_window_sizes : List[int] + Array of window sizes for the observed area. This corresponds to + parameter `b` of the edge filter and the length of the running filter + as defined in :cite:`functional_connectivity-de_blasi19_169`. Value is given + in units of the number of bins according to the binned spike trains + `spike_trains`. + Default: [2, 3, 4, 5, 6] +crossover_window_sizes : List[int] + Array of window sizes for the crossover between surrounding and + observed window. This corresponds to parameter `c` of the edge filter in + :cite:`functional_connectivity-de_blasi19_169`. Value is given in units of + the number of bins according to the binned spike trains `spike_trains`. + Default: [0] +max_delay : int + Defines the max delay when performing the normalized cross-correlations. + Value is given in units of the number of bins according to the binned spike + trains `spike_trains`. + Default: 25 +normalize : bool, optional + Normalize the output [experimental]. Default: False. + +Returns +------- +connectivity_matrix : (N, N) np.ndarray + Square matrix of the connectivity estimation between neurons. + Positive values describe an excitatory connection while + negative values describe an inhibitory connection. +delay_matrix : (N, N) np.ndarray + Square matrix of the estimated delay times between neuron activities. +""" if not surrounding_window_sizes: surrounding_window_sizes = [3, 4, 5, 6, 7, 8] @@ -120,14 +148,14 @@ def total_spiking_probability_edges( surrounding_window_sizes, observed_window_sizes, crossover_window_sizes ) - # Calculate normalized cross corelation for different delays - # The delay range ranges from 0 to max-delay and includes + # Calculate normalized cross-correlation for different delays. + # The delay range is from 0 to max_delay and includes # padding for the filter convolution max_padding = max(surrounding_window_sizes) + max(crossover_window_sizes) delay_times = list(range(-max_padding, max_delay + max_padding)) NCC_d = normalized_cross_correlation(spike_trains, delay_times=delay_times) - # Normalize to counter network-bursts + # Normalize to counter network bursts if normalize: for delay_time in delay_times: NCC_d[:, :, delay_time] /= np.sum( @@ -179,7 +207,7 @@ def normalized_cross_correlation( Normalized cross correlation using std deviation Computes the normalized_cross_correlation between all - Spiketrains inside a BinnedSpikeTrain-Object at a given delay_time + spike trains inside a `BinnedSpikeTrain` object at a given delay time. The underlying formula is: @@ -189,7 +217,7 @@ def normalized_cross_correlation( \cdot \sigma_y}}} The subtraction of mean-values is omitted, since it offers little added - accuracy but increases the compute-time immensely. + accuracy but increases the compute-time considerably. """ n_neurons, n_bins = spike_trains.shape @@ -264,7 +292,8 @@ def generate_edge_filter( g_{(i)} = \begin{cases} - \frac{1}{a} & 0 \lt i \leq a \\ \frac{2}{b} & a+c \lt i \leq a + b + c \\ - - \frac{1}{a} & a+b+2c \lt i \leq 2a + b + 2c + - \frac{1}{a} & a+b+2c \lt i \leq 2a + b + 2c \ \ + 0 & \mathrm{otherwise} \end{cases} """