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:
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;
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
Average the approximately independent estimates of each segment to decrease overall variance of the estimates
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
There is a parameter hierarchy regarding n_segments and len_segment. The former parameter is ignored if the latter one is passed.
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.