wonambi.trans.frequency module

Module to compute frequency representation.

wonambi.trans.frequency.band_power(data, freq, scaling='power', n_fft=None, detrend=None, array_out=False)[source]

Compute power or energy acoss a frequency band, and its peak frequency. Power is estimated using the mid-point rectangle rule. Input can be ChanTime or ChanFreq.

Parameters:

data (instance of ChanTime or ChanFreq) – data to be analyzed, one trial only
freq (tuple of float) – Frequencies for band of interest. Power will be integrated across this band, inclusively, and peak frequency determined within it. If a value is None, the band is unbounded in that direction.
input_type (str) – ‘time’ or ‘spectrum’
scaling (str) – ‘power’ or ‘energy’, only used if data is ChanTime
n_fft (int) – length of FFT. if shorter than input signal, signal is truncated; if longer, signal is zero-padded to length
array_out (bool) – if True, will return two arrays instead of two dict.

Returns:

dict of float, or ndarray – keys are channels, values are power or energy
dict of float, or ndarray – keys are channels, values are respective peak frequency

wonambi.trans.frequency.frequency(data, output='spectraldensity', scaling='power', sides='one', taper=None, halfbandwidth=3, NW=None, duration=None, overlap=0.5, step=None, detrend='linear', n_fft=None, log_trans=False, centend='mean')[source]

Compute the power spectral density (PSD, output=’spectraldensity’, scaling=’power’), or energy spectral density (ESD, output=’spectraldensity’, scaling=’energy’) or the complex fourier transform (output=’complex’, sides=’two’)

Parameters:

data (instance of ChanTime) – one of the datatypes
detrend (str) – None (no detrending), ‘constant’ (remove mean), ‘linear’ (remove linear trend)
output (str) – ‘spectraldensity’ or ‘csd’ or ‘complex’ ‘spectraldensity’ meaning the autospectrum or auto-spectral density, a special case of ‘csd’ (cross-spectral density), where the signal is cross-correlated with itself if ‘csd’, both channels in data are used as input
sides (str) – ‘one’ or ‘two’, where ‘two’ implies negative frequencies
scaling (str) – ‘power’ (units: V ** 2 / Hz), ‘energy’ (units: V ** 2), ‘fieldtrip’, ‘chronux’
taper (str) – Taper to use, commonly used tapers are ‘boxcar’, ‘hann’, ‘dpss’
halfbandwidth (int) – (only if taper=’dpss’) Half bandwidth (in Hz), frequency smoothing will be from +halfbandwidth to -halfbandwidth
NW (int) – (only if taper=’dpss’) Normalized half bandwidth (NW = halfbandwidth * dur). Number of DPSS tapers is 2 * NW - 1. If specified, NW takes precedence over halfbandwidth
duration (float, in s) – If not None, it divides the signal in epochs of this length (in seconds) and then average over the PSD / ESD (not the complex result)
overlap (float, between 0 and 1) – The amount of overlap between epochs (0.5 = 50%, 0.95 = almost complete overlap).
step (float, in s) – step in seconds between epochs (alternative to overlap)
n_fft (int) – Length of FFT, in samples. If less than input axis, input is cropped. If longer than input axis, input is padded with zeros. If None, FFT length set to axis length.
log_trans (bool) – If True, spectral values will be natural log-transformed. The transformation is applied before averaging (or taking the median).
centend (str) – (only if duration is not None). Central tendency measure to use, either mean (arithmetic) or median.

Returns:

instance of ChanFreq – If output=’complex’, there is an additional dimension (‘taper’) which is useful for ‘dpss’ but it’s also present for all the other tapers.

Raises:

TypeError – If the data does not have a ‘time’ axis. It might work in the future on other axes, but I cannot imagine how.
ValueError – If you use duration (to create multiple epochs) and output=’complex’, because it does not average the complex output of multiple epochs.

Notes

See extensive notes at wonambi.trans.frequency._fft

It uses sampling frequency as specified in s_freq, it does not recompute the sampling frequency based on the time axis.

Use of log or median for Welch’s method is included based on recommendations from Izhikevich et al., bioRxiv, 2018.

wonambi.trans.frequency.morlet(freq, s_freq, ratio=5, sigma_f=None, dur_in_sd=4, dur_in_s=None, normalization='wonambi', zero_mean=False)[source]

Create a Morlet wavelet.

Parameters:

freq (float) – central frequency of the wavelet
s_freq (int) – sampling frequency
ratio (float) – ratio for a wavelet family ( = freq / sigma_f)
sigma_f (float) – standard deviation of the wavelet in frequency domain
dur_in_sd (float) – duration of the wavelet, given as number of the standard deviation in the time domain, in one side.
dur_in_s (float) – total duration of the wavelet, two-sided (i.e. from start to finish)
normalization (str) – ‘wonambi’ (default) returns an amplitude of 1 in frequency-domain for a sine wave of amplitude 1 in the time-domain; ‘juniper’ returns amplitude which is dependent on sampling frequency; ‘area’ normalizes the area of the Gaussian envelope to be 1; ‘peak’ normalizes the peak of the Gaussian envelope to be 1. Note that the frequency-domain values for ‘area’ and ‘peak’ will depend on the carrier frequency of the wavelet (they depend on sigma_f).
zero_mean (bool) – make sure that the wavelet has zero mean (only relevant if ratio < 5)

Returns:

ndarray – vector containing the complex Morlet wavelets

Notes

‘ratio’ and ‘sigma_f’ are mutually exclusive. If you use ‘sigma_f’, the standard deviation stays the same for all the frequency. It’s more common to specify a constant ratio for the wavelet family, so that the frequency resolution changes with the frequency of interest.

‘dur_in_sd’ and ‘dur_in_s’ are mutually exclusive. ‘dur_in_s’ specifies the total duration (from start to finish) of the window. ‘dur_in_sd’ calculates the total duration as the length in standard deviations in the time domain: dur_in_s = dur_in_sd * 2 * sigma_t, with sigma_t = 1 / (2 * pi * sigma_f)

wonambi.trans.frequency.timefrequency(data, method='morlet', **options)[source]

Compute the power spectrum over time.

Parameters:

data (instance of ChanTime) – data to analyze
method (str) – the method to compute the time-frequency representation, such as ‘morlet’ (wavelet using complex morlet window), ‘spectrogram’ (corresponds to ‘spectraldensity’ in frequency()), ‘stft’ (short-time fourier transform, corresponds to ‘complex’ in frequency())
options (dict) – options depend on the method used, see below.

Returns:

instance of ChanTimeFreq – data in time-frequency representation. The exact output depends on the method. Using ‘morlet’, you get a complex output at each frequency where the wavelet was computed.

Examples

The data in ChanTimeFreq are complex and they should stay that way. You can also get the magnitude or power the easy way using Math.

>>> from wonambi.trans import math, timefreq
>>> tf = timefreq(data, foi=(8, 10))
>>> tf_abs = math(tf, operator_name='abs')
>>> tf_abs.data[0][0, 0, 0]
1737.4662329214384)

Notes

It uses sampling frequency as specified in s_freq, it does not recompute the sampling frequency based on the time axis.

For method ‘morlet’, the following options should be specified:

foindarray or list or tuple: vector with frequency of interest
ratiofloat: ratio for a wavelet family ( = freq / sigma_f)
sigma_ffloat: standard deviation of the wavelet in frequency domain
dur_in_sdfloat: duration of the wavelet, given as number of the standard deviation in the time domain, in one side.
dur_in_sfloat: total duration of the wavelet, two-sided (i.e. from start to finish)
normalizationstr: ‘area’ means that energy is normalized to 1, ‘peak’ means that the peak of the wavelet is set at 1, ‘max’ is a normalization used by nitime where the max value of the output of the convolution remains the same even if you change the sigma_f.
zero_meanbool: make sure that the wavelet has zero mean (only relevant if ratio < 5)

For method ‘spectrogram’ or ‘stft’, the following options should be specified:

duratonint: duration of the window to compute the power spectrum, in s
overlapint: amount of overlap (0 -> no overlap, 1 -> full overlap)