elephant.causality.granger.pairwise_spectral_granger¶
- elephant.causality.granger.pairwise_spectral_granger(signal_i, signal_j, fs=1, nw=4, num_tapers=None, peak_resolution=None, n_segments=1, len_segment=None, frequency_resolution=None, overlap=0.5, num_iterations=300, term_crit=1e-12)[source]¶
Determine spectral Granger Causality of two signals.
The spectral Granger Causality is obtained through the following steps:
Determine the cross spectrum of the two signals by applying
segmented_multitaper_cross_spectrum()to the joint signal. See the documentation of this function for the hierarchy of the parameters used for the estimation of the cross spectrum.Calculate the spectral factorization of the cross spectrum decomposing the cross spectrum into the covariance matrix and the transfer function.
Calculate the directional and instantaneous spectral Granger Causality from the power spectra, the transfer function and the covariance matrix (see e.g. Wen et al., 2013, Phil Trans R Soc, eq. 2.10 ff).
- Parameters:
- signal_ineo.AnalogSignal or pq.Quantity or np.ndarray
First time series data of the pair between which spectral Granger Causality is computed.
- signal_jneo.AnalogSignal or pq.Quantity or np.ndarray
Second time series data of the pair between which spectral Granger Causality is computed. The shapes and the sampling frequencies of signal_i and signal_j must be identical. When signal_i and signal_j are not neo.AnalogSignal, sampling frequency should be specified through the keyword argument fs. Otherwise, the default value is used (fs = 1.0).
- fsfloat, optional
Specifies the sampling frequency of the input time series Default: 1.0
- nwfloat, optional
Time bandwidth product Default: 4.0
- num_tapersint, optional
Number of tapers used in 1. to obtain estimate of PSD. By default, [2*nw] - 1 is chosen. Default: None
- peak_resolutionpq.Quantity float, optional
Quantity in Hz determining the number of tapers used for analysis. Fine peak resolution –> low numerical value –> low number of tapers High peak resolution –> high numerical value –> high number of tapers When given as a float, it is taken as frequency in Hz. Default: None.
- n_segmentsint, optional
Number of segments. The length of segments is adjusted so that overlapping segments cover the entire stretch of the given data. This parameter is ignored if len_segment or frequency_resolution is given. Default: 1
- len_segmentint, optional
Length of segments. This parameter is ignored if frequency_resolution is given. If None, it will be determined from other parameters. Default: None
- frequency_resolutionpq.Quantity or float, optional
Desired frequency resolution of the obtained spectral Granger Causality estimate in terms of the interval between adjacent frequency bins. When given as a float, it is taken as frequency in Hz. If None, it will be determined from other parameters. Default: None
- overlapfloat, optional
Overlap between segments represented as a float number between 0 (no overlap) and 1 (complete overlap). Default: 0.5 (half-overlapped)
- num_iterationsint
Number of iterations for algorithm to estimate spectral factorization. Default: 300
- term_critfloat
Termination criterion for iteration step in spectral matrix factorization Default: 1e-12
- Returns:
- freqsnp.ndarray
Frequencies associated with the spectral Granger Causality estimate.
- Causality
- A namedtuple with the following attributes:
- directional_causality_x_ynp.ndarray
Spectrally resolved Granger causality influence of signal_i, abbreviated by X, onto signal_j, abbreviated by Y.
- directional_causality_y_xnp.ndarray
Spectrally resolved Granger causality influence of signal_j, abbreviated by Y, onto signal_i, abbreviated by Y.
- instantaneous_causalitynp.ndarray
The remaining spectrally resolved channel interdependence not accounted for by the directional causalities (e.g. shared input to X, i.e. signal_i, and Y, i.e. signal_j).
- total_interdependencenp.ndarray
The sum of the former three metrics. It measures the dependence of X, i.e. signal_i and Y, i.e. signal_j. If the total interdependence is positive, X and Y are not independent.