def multi_taper_psd(
s, Fs=2 * np.pi, NW=None, BW=None, adaptive=False,
jackknife=True, low_bias=True, sides='default', NFFT=None
):
"""Returns an estimate of the PSD function of s using the multitaper
method. If the NW product, or the BW and Fs in Hz are not specified
by the user, a bandwidth of 4 times the fundamental frequency,
corresponding to NW = 4 will be used.
Parameters
----------
s : ndarray
An array of sampled random processes, where the time axis is assumed to
be on the last axis
Fs : float
Sampling rate of the signal
NW : float
The normalized half-bandwidth of the data tapers, indicating a
multiple of the fundamental frequency of the DFT (Fs/N).
Common choices are n/2, for n >= 4. This parameter is unitless
and more MATLAB compatible. As an alternative, set the BW
parameter in Hz. See Notes on bandwidth.
BW : float
The sampling-relative bandwidth of the data tapers, in Hz.
adaptive : {True/False}
Use an adaptive weighting routine to combine the PSD estimates of
different tapers.
jackknife : {True/False}
Use the jackknife method to make an estimate of the PSD variance
at each point.
low_bias : {True/False}
Rather than use 2NW tapers, only use the tapers that have better than
90% spectral concentration within the bandwidth (still using
a maximum of 2NW tapers)
sides : str (optional) [ 'default' | 'onesided' | 'twosided' ]
This determines which sides of the spectrum to return.
For complex-valued inputs, the default is two-sided, for real-valued
inputs, default is one-sided Indicates whether to return a one-sided
or two-sided
Returns
-------
(freqs, psd_est, var_or_nu) : ndarrays
The first two arrays are the frequency points vector and the
estimated PSD. The last returned array differs depending on whether
the jackknife was used. It is either
* The jackknife estimated variance of the log-psd, OR
* The degrees of freedom in a chi2 model of how the estimated
PSD is distributed about the true log-PSD (this is either
2*floor(2*NW), or calculated from adaptive weights)
Notes
-----
The bandwidth of the windowing function will determine the number
tapers to use. This parameters represents trade-off between frequency
resolution (lower main lobe BW for the taper) and variance reduction
(higher BW and number of averaged estimates). Typically, the number of
tapers is calculated as 2x the bandwidth-to-fundamental-frequency
ratio, as these eigenfunctions have the best energy concentration.
"""
# have last axis be time series for now
N = s.shape[-1]
M = int(np.product(s.shape[:-1]))
if BW is not None:
# BW wins in a contest (since it was the original implementation)
norm_BW = np.round(BW * N / Fs)
NW = norm_BW / 2.0
elif NW is None:
# default NW
NW = 4
# (else BW is None and NW is not None) ... all set
Kmax = int(2 * NW)
# if the time series is a complex vector, a one sided PSD is invalid:
if (sides == 'default' and np.iscomplexobj(s)) or sides == 'twosided':
sides = 'twosided'
elif sides in ('default', 'onesided'):
sides = 'onesided'
# Find the direct spectral estimators S_k(f) for k tapered signals..
# don't normalize the periodograms by 1/N as normal.. since the taper
# windows are orthonormal, they effectively scale the signal by 1/N
spectra, eigvals = tapered_spectra(
s, (NW, Kmax), NFFT=NFFT, low_bias=low_bias
)
NFFT = spectra.shape[-1]
K = len(eigvals)
# collapse spectra's shape back down to 3 dimensions
spectra.shape = (M, K, NFFT)
last_freq = NFFT // 2 + 1 if sides == 'onesided' else NFFT
# degrees of freedom at each timeseries, at each freq
nu = np.empty((M, last_freq))
if adaptive:
weights = np.empty((M, K, last_freq))
for i in range(M):
weights[i], nu[i] = utils.adaptive_weights(
spectra[i], eigvals, sides=sides
)
else:
# let the weights simply be the square-root of the eigenvalues.
# repeat these values across all n_chan channels of data
weights = np.tile(np.sqrt(eigvals), M).reshape(M, K, 1)
nu.fill(2 * K)
if jackknife:
jk_var = np.empty_like(nu)
for i in range(M):
jk_var[i] = utils.jackknifed_sdf_variance(
spectra[i], eigvals, sides=sides, adaptive=adaptive
)
# Compute the unbiased spectral estimator for S(f) as the sum of
# the S_k(f) weighted by the function w_k(f)**2, all divided by the
# sum of the w_k(f)**2 over k
# 1st, roll the tapers axis forward
spectra = np.rollaxis(spectra, 1, start=0)
weights = np.rollaxis(weights, 1, start=0)
sdf_est = mtm_cross_spectrum(
spectra, spectra, weights, sides=sides
)
sdf_est /= Fs
if sides == 'onesided':
freqs = np.linspace(0, Fs / 2, NFFT / 2 + 1)
else:
freqs = np.linspace(0, Fs, NFFT, endpoint=False)
out_shape = s.shape[:-1] + (len(freqs),)
sdf_est.shape = out_shape
if jackknife:
jk_var.shape = out_shape
return freqs, sdf_est, jk_var
else:
nu.shape = out_shape
return freqs, sdf_est, nu
def multi_taper_psd(s, Fs=2 * np.pi, BW=None, adaptive=False,
jackknife=True, low_bias=True, sides='default', NFFT=None):
"""Returns an estimate of the PSD function of s using the multitaper
method. If the NW product, or the BW and Fs in Hz are not specified
by the user, a bandwidth of 4 times the fundamental frequency,
corresponding to NW = 4 will be used.
Parameters
----------
s : ndarray
An array of sampled random processes, where the time axis is assumed to
be on the last axis
Fs: float
Sampling rate of the signal
BW: float
The bandwidth of the windowing function will determine the number
tapers to use. This parameters represents trade-off between frequency
resolution (lower main lobe BW for the taper) and variance reduction
(higher BW and number of averaged estimates).
adaptive : {True/False}
Use an adaptive weighting routine to combine the PSD estimates of
different tapers.
jackknife : {True/False}
Use the jackknife method to make an estimate of the PSD variance
at each point.
low_bias : {True/False}
Rather than use 2NW tapers, only use the tapers that have better than
90% spectral concentration within the bandwidth (still using
a maximum of 2NW tapers)
sides : str (optional) [ 'default' | 'onesided' | 'twosided' ]
This determines which sides of the spectrum to return.
For complex-valued inputs, the default is two-sided, for real-valued
inputs, default is one-sided Indicates whether to return a one-sided
or two-sided
Returns
-------
(freqs, psd_est, var_or_nu) : ndarrays
The first two arrays are the frequency points vector and the
estimatated PSD. The last returned array differs depending on whether
the jackknife was used. It is either
* The jackknife estimated variance of the log-psd, OR
* The degrees of freedom in a chi2 model of how the estimated
PSD is distributed about the true log-PSD (this is either
2*floor(2*NW), or calculated from adaptive weights)
"""
# have last axis be time series for now
N = s.shape[-1] if not NFFT else NFFT
rest_of_dims = s.shape[:-1]
s = s.reshape(int(np.product(rest_of_dims)), N)
# de-mean this sucker
s = utils.remove_bias(s, axis=-1)
# Get the number of tapers from the sampling rate and the bandwidth:
if BW is not None:
NW = BW / (2 * Fs) * N
else:
NW = 4
Kmax = int(2 * NW)
dpss, eigs = dpss_windows(N, NW, Kmax)
if low_bias:
keepers = (eigs > 0.9)
dpss = dpss[keepers]
eigs = eigs[keepers]
Kmax = len(dpss)
# if the time series is a complex vector, a one sided PSD is invalid:
if (sides == 'default' and np.iscomplexobj(s)) or sides == 'twosided':
sides = 'twosided'
elif sides in ('default', 'onesided'):
sides = 'onesided'
sig_sl = [slice(None)] * len(s.shape)
sig_sl.insert(-1, np.newaxis)
# tapered.shape is (..., Kmax, N)
tapered = s[sig_sl] * dpss
# Find the direct spectral estimators S_k(f) for k tapered signals..
# don't normalize the periodograms by 1/N as normal.. since the taper
# windows are orthonormal, they effectively scale the signal by 1/N
# XXX: scipy fft is faster
tapered_spectra = fftpack.fft(tapered)
last_freq = N / 2 + 1 if sides == 'onesided' else N
# degrees of freedom at each timeseries, at each freq
nu = np.empty((s.shape[0], last_freq))
if adaptive:
weights = np.empty(tapered_spectra.shape[:-1] + (last_freq,))
for i in xrange(s.shape[0]):
weights[i], nu[i] = utils.adaptive_weights(
tapered_spectra[i], eigs, sides=sides
)
else:
# let the weights simply be the square-root of the eigenvalues.
# repeat these values across all n_chan channels of data
n_chan = tapered.shape[0]
weights = np.tile(np.sqrt(eigs), n_chan).reshape(n_chan, Kmax, 1)
nu.fill(2 * Kmax)
if jackknife:
jk_var = np.empty_like(nu)
for i in xrange(s.shape[0]):
jk_var[i] = utils.jackknifed_sdf_variance(
tapered_spectra[i], eigs, sides=sides, adaptive=adaptive
)
# Compute the unbiased spectral estimator for S(f) as the sum of
# the S_k(f) weighted by the function w_k(f)**2, all divided by the
# sum of the w_k(f)**2 over k
# 1st, roll the tapers axis forward
tapered_spectra = np.rollaxis(tapered_spectra, 1, start=0)
weights = np.rollaxis(weights, 1, start=0)
sdf_est = mtm_cross_spectrum(
tapered_spectra, tapered_spectra, weights, sides=sides
)
if sides == 'onesided':
freqs = np.linspace(0, Fs / 2, N / 2 + 1)
else:
freqs = np.linspace(0, Fs, N, endpoint=False)
out_shape = rest_of_dims + (len(freqs),)
sdf_est.shape = out_shape
# XXX: always return nu and jk_var
if jackknife:
jk_var.shape = out_shape
return freqs, sdf_est, jk_var
else:
nu.shape = out_shape
return freqs, sdf_est, nu
def multi_taper_psd(s,
Fs=2 * np.pi,
NW=None,
BW=None,
adaptive=False,
jackknife=True,
low_bias=True,
sides='default',
NFFT=None):
"""Returns an estimate of the PSD function of s using the multitaper
method. If the NW product, or the BW and Fs in Hz are not specified
by the user, a bandwidth of 4 times the fundamental frequency,
corresponding to NW = 4 will be used.
Parameters
----------
s : ndarray
An array of sampled random processes, where the time axis is assumed to
be on the last axis
Fs : float
Sampling rate of the signal
NW : float
The normalized half-bandwidth of the data tapers, indicating a
multiple of the fundamental frequency of the DFT (Fs/N).
Common choices are n/2, for n >= 4. This parameter is unitless
and more MATLAB compatible. As an alternative, set the BW
parameter in Hz. See Notes on bandwidth.
BW : float
The sampling-relative bandwidth of the data tapers, in Hz.
adaptive : {True/False}
Use an adaptive weighting routine to combine the PSD estimates of
different tapers.
jackknife : {True/False}
Use the jackknife method to make an estimate of the PSD variance
at each point.
low_bias : {True/False}
Rather than use 2NW tapers, only use the tapers that have better than
90% spectral concentration within the bandwidth (still using
a maximum of 2NW tapers)
sides : str (optional) [ 'default' | 'onesided' | 'twosided' ]
This determines which sides of the spectrum to return.
For complex-valued inputs, the default is two-sided, for real-valued
inputs, default is one-sided Indicates whether to return a one-sided
or two-sided
Returns
-------
(freqs, psd_est, var_or_nu) : ndarrays
The first two arrays are the frequency points vector and the
estimated PSD. The last returned array differs depending on whether
the jackknife was used. It is either
* The jackknife estimated variance of the log-psd, OR
* The degrees of freedom in a chi2 model of how the estimated
PSD is distributed about the true log-PSD (this is either
2*floor(2*NW), or calculated from adaptive weights)
Notes
-----
The bandwidth of the windowing function will determine the number
tapers to use. This parameters represents trade-off between frequency
resolution (lower main lobe BW for the taper) and variance reduction
(higher BW and number of averaged estimates). Typically, the number of
tapers is calculated as 2x the bandwidth-to-fundamental-frequency
ratio, as these eigenfunctions have the best energy concentration.
"""
# have last axis be time series for now
N = s.shape[-1]
M = int(np.product(s.shape[:-1]))
if BW is not None:
# BW wins in a contest (since it was the original implementation)
norm_BW = np.round(BW * N / Fs)
NW = norm_BW / 2.0
elif NW is None:
# default NW
NW = 4
# (else BW is None and NW is not None) ... all set
Kmax = int(2 * NW)
# if the time series is a complex vector, a one sided PSD is invalid:
if (sides == 'default' and np.iscomplexobj(s)) or sides == 'twosided':
sides = 'twosided'
elif sides in ('default', 'onesided'):
sides = 'onesided'
# Find the direct spectral estimators S_k(f) for k tapered signals..
# don't normalize the periodograms by 1/N as normal.. since the taper
# windows are orthonormal, they effectively scale the signal by 1/N
spectra, eigvals = tapered_spectra(s, (NW, Kmax),
NFFT=NFFT,
low_bias=low_bias)
NFFT = spectra.shape[-1]
K = len(eigvals)
# collapse spectra's shape back down to 3 dimensions
spectra.shape = (M, K, NFFT)
last_freq = NFFT / 2 + 1 if sides == 'onesided' else NFFT
# degrees of freedom at each timeseries, at each freq
nu = np.empty((M, last_freq))
if adaptive:
weights = np.empty((M, K, last_freq))
for i in range(M):
weights[i], nu[i] = utils.adaptive_weights(spectra[i],
eigvals,
sides=sides)
else:
# let the weights simply be the square-root of the eigenvalues.
# repeat these values across all n_chan channels of data
weights = np.tile(np.sqrt(eigvals), M).reshape(M, K, 1)
nu.fill(2 * K)
if jackknife:
jk_var = np.empty_like(nu)
for i in range(M):
jk_var[i] = utils.jackknifed_sdf_variance(spectra[i],
eigvals,
sides=sides,
adaptive=adaptive)
# Compute the unbiased spectral estimator for S(f) as the sum of
# the S_k(f) weighted by the function w_k(f)**2, all divided by the
# sum of the w_k(f)**2 over k
# 1st, roll the tapers axis forward
spectra = np.rollaxis(spectra, 1, start=0)
weights = np.rollaxis(weights, 1, start=0)
sdf_est = mtm_cross_spectrum(spectra, spectra, weights, sides=sides)
sdf_est /= Fs
if sides == 'onesided':
freqs = np.linspace(0, Fs / 2, NFFT / 2 + 1)
else:
freqs = np.linspace(0, Fs, NFFT, endpoint=False)
out_shape = s.shape[:-1] + (len(freqs), )
sdf_est.shape = out_shape
if jackknife:
jk_var.shape = out_shape
return freqs, sdf_est, jk_var
else:
nu.shape = out_shape
return freqs, sdf_est, nu
