elephant.spectral.multitaper_psd

elephant.spectral.multitaper_psd(signal, n_segments=1, len_segment=None, frequency_resolution=None, overlap=0.5, fs=1, nw=4, num_tapers=None, peak_resolution=None, axis=-1)[source]

Estimates power spectrum density (PSD) of a given ‘neo.AnalogSignal’ using Multitaper method

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

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

Time series data of which PSD is estimated. When signal is np.ndarray sampling frequency should be given through keyword argument fs. Signal should be passed as (n_channels, n_samples)

fsfloat, optional

Specifies the sampling frequency of the input time series Default: 1.0.

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

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.

axisint, optional

Axis along which the periodogram is computed. See Notes [2]. Default: last axis (-1).

Returns:
freqsnp.ndarray

Frequencies associated with power estimate in psd

psdnp.ndarray

PSD estimate of the time series in signal

Raises:
ValueError

If peak_resolution is None and num_tapers is not a positive number.

If frequency_resolution is too high for the given data size.

If frequency_resolution is None and len_segment is not a positive number.

If frequency_resolution is None and len_segment is greater than the length of data at axis.

If both frequency_resolution and len_segment are None and n_segments is not a positive number.

If both frequency_resolution and len_segment are None and n_segments is greater than the length of data at axis.

TypeError

If peak_resolution is None and num_tapers is not an int.

Notes

  1. There is a parameter hierarchy regarding n_segments and len_segment. The former parameter is ignored if the latter one is passed.

  2. 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.