elephant.spectral.segmented_multitaper_cross_spectrum

elephant.spectral.segmented_multitaper_cross_spectrum(signals, n_segments=1, len_segment=None, frequency_resolution=None, overlap=0.5, fs=1.0, nw=4.0, num_tapers=None, peak_resolution=None, return_onesided=True)[source]

Estimates the cross spectrum of a given neo.AnalogSignal using the Multitaper method on segments of the data.

The segmented cross spectrum is obtained through the following steps:

  1. Cut the given data into several overlapping segments. The degree of overlap can be specified by parameter overlap (default is 0.5, i.e. segments are overlapped by the half of their length). The number and the length of the segments are determined according to the parameters n_segments, len_segment or frequency_resolution. By default, the data is not cut into segments.

  2. Calculate ‘num_tapers’ approximately independent estimates of the spectrum by multiplying the signal with the discrete prolate spheroidal functions (also known as Slepian function) and calculate the PSD of each tapered segment.

  3. Average the approximately independent estimates of each segment to decrease overall variance of the estimates.

  4. Average the obtained estimates for each segment.

The estimation is done by applying _segmented_apply_func to multitaper_cross_spectrum(). See the latter function for further documentation.

Parameters:
signalsneo.AnalogSignal or pq.Quantity or np.ndarray

Time series data of which CSD 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.

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 PSD 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)

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

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

return_onesidedbool, optional

If True, return a one-sided spectrum for real data. If False return a two-sided spectrum. Default: True

Returns:
freqsnp.ndarray

Frequencies associated with the cross spectrum estimate in cross_spec. If signals is an instance of neo.AnalogSignal or Quantity, 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, the returned values will have units attached to them (i.e. signals.units ** 2/Hz).

See also

multitaper_cross_spectrum()