libtfr

Interface to libtfr spectrogram library using numpy.

Spectrograms are returned as 2D arrays with frequency indexed by row and time by column. Signals are assumed to be real; therefore real power spectrograms with a transform size of N have N/2+1 rows, corresponding to frequencies from 0 to Nyquist. The number of time points in the spectrogram is (M - W + 1)/S, where M is the length of the signal, S is the shift (S), and the analysis window size is W (this may be less than or equal to N). Only time points corresponding to window positions that completely overlap with the signal are returned. Power spectra and spectrograms are not normalized; they are just the absolute values of the complex FFT results. To get the power spectrum, divide by the square of the sum of the window. To get the power spectral density, divide by the sampling rate times the sum of the square of the window function.

SPDX-License-Identifier: GPL-2.0-or-later

class mfft:

Computes multi-tapered transforms of real signals. Instantiate with factory functions.

mfft()

Not callable. Use mfft_dpss or mfft_precalc to construct a transform.

def tapers_fft(self, scale):

The FFT of the transform's tapers.

Arguments:

scale: positive factor to rescale the tapers by before transforming

Returns:

Complex array, dimension (ntapers, nreal).

def tapers_interpolate(self, t, t0, dt):

Interpolate the transform's tapers at specified times.

The time support of the tapers is given by a start time and a sampling interval.

Arguments:

t: times at which to interpolate
t0: start time of the tapers
dt: sampling interval of the tapers

Returns:

2D array, dimension (ntapers, t.size).

def mtfft(self, s):

Compute the complex multitaper FFT of a real-valued signal.

Arguments:

s: input data (1D time series)

Returns:

Complex array, dimension (nreal, ntapers).

def mtfft_pt(self, t, dt, t0):

Compute the complex multitaper FFT of a point process.

Arguments:

t: event times (1D array)
dt: sampling interval of the window
t0: start time of the window

Returns:

Complex array, dimension (nreal, ntapers).

def mtpsd(self, s, adapt=True):

Compute the power spectral density of a signal using multitaper methods.

Arguments:

s: input data (1D time series)
adapt: with more than one taper, compute the adaptive spectrum

Returns:

1D real power spectrum of length nreal. Not normalized; see the module docstring for how to scale it.

def mtspec(self, s, step, adapt=True):

Compute the spectrogram of a signal using multitaper methods.

Arguments:

s: input data (1D time series)
step: number of samples to advance between frames
adapt: with more than one taper, compute the adaptive spectrum

Returns:

Real power spectrogram, dimension (nreal, nframes). Not normalized; see the module docstring for how to scale it.

def mtstft(self, s, step):

Compute the short-time Fourier transform of a signal using multiple tapers.

Arguments:

s: input data (1D time series)
step: number of samples to advance between frames

Returns:

Complex STFT, dimension (nreal, nframes, ntapers).

def mtstft_pt(self, t, dt, step, t0, tN):

Compute the complex multitaper STFT of a point process.

Arguments:

t: event times (1D array)
dt: implied sampling interval of the signal, which sets the frequency resolution
step: time interval between frames
t0: start time of the signal
tN: stop time of the signal

Returns:

A tuple of the complex STFT, dimension (nreal, nframes, ntapers), and the number of events in each frame, length nframes.

ntapers

The number of tapers used by the transform.

nfft

The number of points in the transform.

npoints

The number of points in each taper, which may be less than nfft.

nreal

The number of frequency bins in the spectrum of a real signal, nfft/2 + 1.

tapers

A copy of the transform's tapers, dimension (ntapers, npoints).

def mfft_dpss(nfft, nw, ntapers, npoints=0):

Initialize an mfft transform using DPSS tapers.

This is the standard multitaper transform.

Arguments:

nfft: number of points in the transform
nw: time-bandwidth parameter
ntapers: number of tapers to generate
npoints: number of points in each taper; defaults to nfft

Returns:

An mfft transform object.

def mfft_precalc(nfft, tapers, weights=None):

Copy pre-calculated tapers or window functions into an mfft transform.

Use this for window functions libtfr does not generate itself, such as a Hanning window.

Arguments:

nfft: number of points in the transform
tapers: taper array, either (npoints,) or (ntapers, npoints)
weights: weight for each taper; defaults to equal weights

Returns:

An mfft transform object.

Raises:

ValueError: if the number of weights does not match the number of tapers

def tfr_spec(s, N, step, Np, K=6, tm=6.0, flock=0.01, tlock=5, fgrid=None):

Compute the time-frequency reassignment spectrogram of a signal.

Arguments:

s: input signal (real)
N: number of frequency points
step: number of samples to advance between frames
Np: window size; must be odd and no larger than N
K: number of tapers to use
tm: time support of the tapers
flock: frequency locking parameter. Power is not reassigned further than this, in normalized frequency
tlock: time locking parameter, in frames
fgrid: output frequency bins, monotonically increasing. Defaults to a linear scale with N points, with Nyquist at 1.0

Returns:

Power spectrogram, dimension (N/2+1, nframes), or (fgrid.size, nframes) if fgrid is given.

Raises:

ValueError: if Np is larger than N, or is even
RuntimeError: if the transform cannot be initialized

def hermf(N, M=6, tm=6.0):

Compute a set of orthogonal Hermite functions.

These are the tapers used for multi-taper reassigned spectrograms.

Arguments:

N: number of points in the window; must be odd
M: maximum order of the set of functions
tm: half-time support

Returns:

A tuple of three (M, N) arrays: the Hermite functions, their first derivatives, and their time multiples.

Raises:

ValueError: if N is even

def dpss(N, NW, k):

Compute discrete prolate spheroidal sequences.

These are the tapers used for multitaper power spectrum estimation.

Arguments:

N: number of points in the window
NW: time-bandwidth product. Must be an integer or half-integer; typical choices are 2, 5/2, 3, 7/2 or 4
k: number of DPSS vectors to generate. Must be less than N, and vectors beyond NW*2 - 1 are not numerically stable

Returns:

A tuple of the tapers, shape (k, N), and their concentration values, length k.

Raises:

ValueError: if the parameters are invalid
RuntimeError: if the eigenvalue solver fails

def log_fgrid(fmin, fmax, N, Fs=None):

Generate a logarithmic frequency grid between fmin and fmax.

Arguments:

fmin: first frequency
fmax: last frequency
N: number of points
Fs: sampling frequency. If given, the grid is returned as relative frequencies; must be greater than fmax

Returns:

1D array of N frequencies.

def fgrid(Fs, nfft, fpass=None):

Calculate the frequency grid associated with an FFT computation.

Arguments:

Fs: sampling frequency of the data
nfft: number of points in the FFT
fpass: lower and upper frequencies of interest, [fmin, fmax), in the same units as Fs. Defaults to all frequencies up to Nyquist

Returns:

A tuple of the frequencies and the indices of those frequencies within the full frequency grid.

Example:

With Fs=1000 and nfft=1048, an FFT of a real signal generates 512 frequencies between 0 and 500 Hz. With fpass=(0, 100), the returned indices are those of the frequencies below 100 Hz.

Adapted from Chronux 1_50.

def tgrid(S, Fs, shift):

Calculate the time grid associated with an STFT.

Spectrograms generated by libtfr omit frames that extend past the edge of the signal. Those frames can only be excluded here if the taper size is known, and that size may be adjusted silently by the Hermite and DPSS taper functions to keep the number of points even or odd. So the two forms of this function differ: given a signal length, the full grid is returned, including unsupported frames; given a spectrogram, the grid is truncated to match it.

Arguments:

S: length of the signal in samples, or the 2D spectrogram array (frequency x time)
Fs: sampling frequency of the data
shift: number of samples shifted between frames

Returns:

1D array of frame start times.

Raises:

ValueError: if S is a 1D array, which is ambiguous

def dynamic_range(S, dB):

Compress a spectrogram's dynamic range.

Values more than dB below the peak of S are clamped to that threshold. S is on a linear scale.

Arguments:

S: input spectrogram or spectrum
dB: dynamic range to rescale to

Returns:

A copy of S after thresholding.

ITYPE = <class 'numpy.int32'>

DTYPE = <class 'numpy.float64'>

CTYPE = <class 'numpy.complex128'>