funcnet.coupling_analysis_pure_python

Provides classes for analyzing spatially embedded complex networks, handling multivariate data and generating time series surrogates.

Written by Jakob Runge. CMSI Method Reference: [Pompe2011]

class pyunicorn.funcnet.coupling_analysis_pure_python.CouplingAnalysisPurePython(dataarray, only_tri=False, silence_level=0)

Bases: object

Contains methods to calculate coupling matrices from large arrays of scalar time series.

Comprises linear and information theoretic measures, lagged and directed (causal) couplings.

__init__(dataarray, only_tri=False, silence_level=0)

Initialize an instance of CouplingAnalysisPurePython.

Possible choices for only_tri:

• “True” will calculate only the upper triangle of the coupling matrix, excluding the diagonal, assuming symmetry (not for directed measures)

• “False” will calculate the whole matrix (asymmetry somes from

  different integration ranges)

Parameters:

• dataarray (4D, 3D or 2D Numpy array [time, index, index] or [time, index]) – The time series array with time in first dimension

• only_tri (bool) – Symmetric/asymmetric assumption on coupling matrix.

• silence_level (int) – The inverse level of verbosity of the object.

__str__()

Return a string representation of the CouplingAnalysisPurePython object.

__weakref__

list of weak references to the object

_calculate_cc(array, corr_range, tau_max, lag_mode)

Returns the CC matrix.

Parameters:

• tau_max (int) – maximum lag in both directions, including last lag

• lag_mode (str) – output mode

Return type:

3D numpy array (float) [index, index, index]

Returns:

correlation matrix with different lag_mode choices

## lag_mode dict mode = self.lag_modi[lag_mode]

_calculate_mi(array, corr_range, bins, tau_max, lag_mode)

Returns the mi matrix.

Parameters:

• bins (int) – number of bins for estimating MI

• tau_max (int) – maximum lag in both directions, including last lag

• lag_mode (str) – output mode

Return type:

3D numpy array (float) [index, index, index]

Returns:

correlation matrix with different lag_mode choices

correlatedNoiseSurrogates(original)

Generates surrogates by Fourier transforming the original time series, randomizing the phases and then applying an inverse Fourier transform. Correlated noise surrogates share their power spectrum and autocorrelation function with the original time series.

Parameters:

original (2D array) – dim. 0 is index of time series, dim. 1 is time

Returns:

surrogate time series (same dimensions as original)

cross_correlation(tau_max=0, lag_mode='all')

Returns the normalized cross correlation from all pairs of nodes from a range of time lags.

The calculation ranges are shown below:

(-------------------------total_time--------------------------)
(---tau_max---)(---------corr_range------------)(---tau_max---)

CC is calculated about corr_range and with the other time series shifted by tau

Possible choices for lag_mode:

• “all” will return the full function for all lags, possible large memory need if only_tri is True, only the upper triangle contains the values, the lower one is zeros

• “sum” will return the sum over positive and negative lags seperatly, each inclunding tau=0 corrmat[0] is the positive sum, corrmat[1] the negative sum

• “max” will return only the maximum coupling (in corrmat[0]) and its lag (in corrmat[1])

Parameters:

• tau_max (int) – maximum lag in both directions, including last lag

• lag_mode (str) – the output mode

Return type:

3D numpy array (float) [index, index, index]

Returns:

correlation matrix with different lag_mode choices

mutual_information(bins=16, tau_max=0, lag_mode='all')

Returns the normalized mutual information from all pairs of nodes from a range of time lags.

MI = H_x + H_y - H_xy

Uses adaptive bins, where each marginal bin contains the same number of samples. Then the marginal entropies have equal probable distributions H_x = H_y = log(bins)

The calculation ranges are shown below:

(-------------------------total_time--------------------------)
(---tau_max---)(---------corr_range------------)(---tau_max---)

MI is calculated about corr_range and with the other time series shifted by tau

Possible choices for lag_mode:

• “all” will return the full function for all lags, possible large memory need if only_tri is True, only the upper triangle contains the values, the lower one is zeros

• “sum” will return the sum over positive and negative lags seperatly, each inclunding tau=0 corrmat[0] is the positive sum, corrmat[1] the negative sum

• “max” will return only the maximum coupling (in corrmat[0]) and its lag (in corrmat[1])

Parameters:

• bins (int) – number of bins for estimating MI

• tau_max (int) – maximum lag in both directions, including last lag

• lag_mode (str) – output mode

Return type:

3D numpy array (float) [index, index, index]

Returns:

correlation matrix with different lag_mode choices

mutual_information_edges(bins=16, tau=0, lag_mode='all')

Returns the normalized mutual information from all pairs of nodes from a range of time lags.

MI = H_x + H_y - H_xy

Uses adaptive bins, where each marginal bin contains the same number of samples. Then the marginal entropies have equal probable distributions H_x = H_y = log(bins)

The calculation ranges are shown below:

(-------------------------total_time--------------------------)
(---tau_max---)(---------corr_range------------)(---tau_max---)

MI is calculated about corr_range and with the other time series shifted by tau

Possible choices for lag_mode:

• “all” will return the full function for all lags, possible large memory need if only_tri is True, only the upper triangle contains the values, the lower one is zeros

• “sum” will return the sum over positive and negative lags seperatly, each inclunding tau=0 corrmat[0] is the positive sum, corrmat[1] the negative sum

• “max” will return only the maximum coupling (in corrmat[0]) and its lag (in corrmat[1])

Parameters:

• bins (int) – number of bins for estimating MI

• tau_max (int) – maximum lag in both directions, including last lag

• lag_mode (str) – output mode

Return type:

2D numpy array (float) [index, index]

Returns:

bin edges for zero lag

shuffled_surrogate_for_cc(fourier=False, tau_max=1, lag_mode='all')

Returns a correlation matrix calculated with an independently shuffled surrogate of the dataarray of length corr_range for all taus.

Parameters:

• corr_range (int) – length of sample

• tau_max (int) – maximum lag in both directions, including last lag

• lag_mode (str) – output mode

Return type:

3D numpy array (float) [index, index, index]

Returns:

correlation matrix with different lag_mode choices

shuffled_surrogate_for_mi(fourier=False, bins=16, tau_max=0, lag_mode='all')

Returns a shuffled surrogate of normalized mutual information from all pairs of nodes from a range of time lags.

Parameters:

• bins (int) – number of bins for estimating MI

• tau_max (int) – maximum lag in both directions, including last lag

• lag_mode (str) – output mode

Return type:

3D numpy array (float) [index, index, index]

Returns:

correlation matrix with different lag_mode choices

time_surrogate_for_cc(sample_range=100, tau_max=1, lag_mode='all')

Returns a joint shuffled surrogate of the full dataarray of length sample_range for all taus.

Used for time evolution analysis. First one initializes the CouplingAnalysis class with the full dataarray and then this function is called for every single surrogate.

Parameters:

• sample_range (int) – length of sample

• tau_max (int) – maximum lag in both directions, including last lag

• lag_mode (str) – output mode

Return type:

3D numpy array (float) [index, index, index]

Returns:

correlation matrix with different lag_mode choices

time_surrogate_for_mi(bins=16, sample_range=100, tau_max=1, lag_mode='all')

Returns a joint shuffled surrogate of the full dataarray of length sample_range for all taus.

Used for time evolution analysis. First one initializes the CouplingAnalysis class with the full dataarray and then this function is called for every single surrogate.

Parameters:

• sample_range (int) – length of sample

• bins (int) – number of bins for estimating MI

• tau_max (int) – maximum lag in both directions, including last lag

• lag_mode (str) – output mode

Return type:

3D numpy array (float) [index, index, index]

Returns:

correlation matrix with different lag_mode choices