elephant.spectral.multitaper_cross_spectrum¶
- elephant.spectral.multitaper_cross_spectrum(signals, fs=1.0, nw=4.0, num_tapers=None, peak_resolution=None, return_onesided=True, attach_units=True)[source]¶
Estimates the cross spectrum of a given neo.AnalogSignal using the Multitaper method.
The cross spectrum is obtained through the following steps:
Obtain approximately independent estimates of the spectrum for each signal by multiplying it with tapering functions (obtained as the discrete prolate spheroidal functions, also known as slepian functions) and calculating the cross spectrum for the tapered signals. The number of tapering functions (and hence the number of the estimates) is specified by the parameter num_tapers.
Average the approximately independent estimates of each tapered instance of the signal to decrease overall variance of the estimates.
- Parameters:
- signalsneo.AnalogSignal or pq.Quantity or np.ndarray
Time series data of which PSD is estimated. When signal is np.ndarray or pq.Quantity, it needs to be passed as a 2-dimensional array of shape (n_channels, n_samples), and the data sampling frequency should be given through the keyword argument fs.
- fsfloat, optional
Specifies the sampling frequency of the input time series Default: 1.0
- nwfloat, optional
Time-halfbandwidth product. This parameter can be used to determine the number of tapers following the equation:
num_tapers = 2*nw - 1
It can be determined by multiplying the duration of the signal with the desired half-peak resolution frequency:
n_samples/fs * peak_resolution/2.
Default: 4.0
- num_tapersint, optional
Number of tapers used in step 2 (see above) to obtain estimate of PSD. By default, [2*nw] - 1 is chosen. Default: None (see Notes [1])
- 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 (see Notes [1])
- return_onesidedbool, optional
If True, return a one-sided spectrum for real data. If False return a two-sided spectrum. Default: True
- attach_unitsbool, optional
If True and signals is instance of pq.Quantity, units are attached to the estimated cross spectrum. Default: True
- Returns:
- freqsnp.ndarray
Frequencies associated with cross spectrum estimate in cross_spec. If signals is an instance of neo.AnalogSignal or Quantity and the attach_units is set to True, the returned values will have units of Hz.
- cross_specnp.ndarray
Estimate of the cross spectrum of time series in signals. If signals is an instance of neo.AnalogSignal or Quantity and the attach_units is set to True, the returned values will have units attached to them (i.e. signals.units ** 2/Hz).
- Raises:
- ValueError
If peak_resolution is None and num_tapers is not a positive number.
- TypeError
If peak_resolution is None and num_tapers is not an int.
Notes
There is a parameter hierarchy regarding nw, num_tapers and peak_resolution. If peak_resolution is provided, it determines both nw and the num_tapers. Specifying num_tapers has an effect only if peak_resolution is not provided.