Macros
#define	LIBTFR_VERSION "2.2.0"

Typedefs
typedef double	cmplx_t[2]
	An interleaved real/imaginary pair: [0] is the real part, [1] the imaginary.

typedef struct mfft_s	mfft
	Opaque pointer type for multitaper fft transforms.

Functions
mfft *	mtm_init (int nfft, int npoints, int ntapers)
	Initialize a multitaper mtm transform and allocate memory for tapers/window functions.

mfft *	mtm_init_dpss (int nfft, int npoints, double nw, int ntapers)
	Initialize a mtfft transform using DPSS tapers (i.e.

mfft *	mtm_init_herm (int nfft, int npoints, int order, double tm)
	Initialize mtfft transform for reassigned spectrogram (i.e.

void	mtm_copy (mfft mtmh, const double tapers, const double *weights)
	Copy pre-calculated tapers/window functions (e.g.

void	mtm_destroy (mfft *mtm)
	Frees up the mfft structure and dependent data.

int	mtm_nfft (mfft const *mtm)

int	mtm_npoints (mfft const *mtm)

int	mtm_ntapers (mfft const *mtm)

int	mtm_nreal (mfft const *mtm)

int	mtm_nframes (mfft const *mtm, int signal_size, int step_size)

double const *	mtm_buffer (mfft const *mtm)

double const *	mtm_tapers (mfft const *mtm)

void	mtm_tapers_fft (mfft *mtm, double scale)
	Compute FFT of the tapers.

void	mtm_tapers_interp (mfft const mtm, double out, double const *times, int ntimes, double t0, double dt)
	Compute interpolation of tapers.

double	mtfft (mfft mtm, double const data, int nbins)
	Compute multitaper FFT of a real-valued signal.

void	mtpower (mfft const mtm, double pow, double sigpow)
	Extract power spectrum from multiple taper FFT.

void	mtcomplex (mfft const mtm, cmplx_t out)
	Extract complex multitaper transform of signal from transform object.

void	mtm_spec (mfft mtm, double spec, const double *samples, int nsamples, int shift, int adapt)
	Compute a multitaper spectrogram by stepping through a signal.

void	mtm_zspec (mfft mtm, cmplx_t spec, const double *samples, int nsamples, int shift)
	Compute a multitaper complex spectrogram by stepping through a signal.

void	tfr_spec (mfft mtm, double spec, const double samples, int nsamples, int k, int shift, double flock, int tlock, int nfreq, const double fgrid)
	Compute a time-frequency reassignment spectrogram by stepping through a signal.

int	dpss (double tapers, double lambda, int npoints, double nw, int k)
	Computes discrete prolate spherical sequences.

int	hermf (int N, int M, double tm, double h, double Dh, double *Th)
	Computes a set of orthogonal Hermite functions.

void	tfr_displacements (mfft const mtm, double q, double tdispl, double fdispl)
	Compute the power spectrum and the time/frequency displacement.

void	tfr_reassign (double spec, const double q, const double tdispl, const double fdispl, int N, int nfreq, const double *fgrid, double dt, double qthresh, double flock, int tminlock, int tmaxlock)
	Assign power from a spectrum to a spectrogram based on time-frequency displacements.

Detailed Description

Author: C Daniel Meliza

Date: Mon Mar 7 2016

Macro Definition Documentation

◆ LIBTFR_VERSION

#define LIBTFR_VERSION "2.2.0"

Typedef Documentation

◆ cmplx_t

typedef double cmplx_t[2]

An interleaved real/imaginary pair: [0] is the real part, [1] the imaginary.

This is layout-compatible with C99 double _Complex, MSVC's _Dcomplex, and numpy's complex128, so the binary interface is unchanged. It is spelled as an array rather than a native complex type because MSVC's C compiler does not implement C99 _Complex, and indexing works identically on every compiler. Do not reintroduce <complex.h> here – keeping it out means a stray complex expression in the library sources fails to build on Linux/macOS too, instead of only on Windows.

◆ mfft

typedef struct mfft_s mfft

Opaque pointer type for multitaper fft transforms.

Function Documentation

◆ dpss()

int dpss	(	double *	tapers,
		double *	lambda,
		int	npoints,
		double	nw,
		int	k
	)

Computes discrete prolate spherical sequences.

These are used in the multitaper method power spectrum calculations.

Parameters

npoints	the number of points in the window
nw	the time-bandwidth product. Must be an integer or half-integer (typical choices are 2, 5/2, 3, 7/2, or 4)
k	how many DPSS vectors to return (up to npoints but k>nw*2-1 are not stable)
tapers	(output) k DPSS sequences in order of decreasing eigenvalue (size k*npoints)
lambda	(output) k eigenvalues associated with each taper

Returns: 0 for success, -1 for invalid parameters (NW >= npoints/2, npoints < 0, k < 0, etc), -2 for failed eigenvalue solver (shouldn't ever happen)

◆ hermf()

int hermf	(	int	N,
		int	M,
		double	tm,
		double *	h,
		double *	Dh,
		double *	Th
	)

Computes a set of orthogonal Hermite functions.

Used in computing multi-taper reassigned spectrograms

Parameters

N	the number of points in the window (must be odd)
M	the maximum order of the set of functions
tm	half-time support
h	(output) hermite functions (MxN)
Dh	(output) first derivative of h (MxN)
Th	(output) time multiple of h (MxN)

Returns: The actual number of points in the tapers

From the Time-Frequency Toolkit, P. Flandrin & J. Xiao, 2005

◆ mtcomplex()

void mtcomplex	(	mfft const *	mtm,
		cmplx_t *	out
	)

Extract complex multitaper transform of signal from transform object.

Parameters

mtm	mfft structure after running mtfft
out	(output) complex transform of signal. Needs to be preallocated with dimensions at least ntapers by nfft

◆ mtfft()

double mtfft	(	mfft *	mtm,
		double const *	data,
		int	nbins
	)

Compute multitaper FFT of a real-valued signal.

Note that this can be used for single taper FFTs, if the mfft structure has been initialized with a single window. The result is stored in the mfft buffer in half-complex format with dimension ntapers x nfft. Use mtpower or mtcomplex to extract the transformed signal.

Parameters

mtm	the mfft transform structure
data	input data (double-precision floating points)
nbins	the number of time points in the signal

Returns: total power in signal (used in computing adaptive power spectra)

◆ mtm_buffer()

double const * mtm_buffer ( mfft const * mtm )

◆ mtm_copy()

void mtm_copy	(	mfft *	mtmh,
		const double *	tapers,
		const double *	weights
	)

Copy pre-calculated tapers/window functions (e.g.

hanning) into a mtfft transform. Size of arrays must match memory allocated by the transform.

Parameters

mtmh	the transform to copy the tapers into
tapers	pointer to ntapers*npoints array of windowing functions
weights	weights for tapers; if NULL, assign weight of 1.0 to each taper

◆ mtm_destroy()

void mtm_destroy ( mfft * mtm )

Frees up the mfft structure and dependent data.

Note that references to the tapers are considered to be owned by the structure, so if they were calculated elsewhere do not attempt to access them after calling this function.

Parameters

mtm	the structure to release

◆ mtm_init()

mfft * mtm_init	(	int	nfft,
		int	npoints,
		int	ntapers
	)

Initialize a multitaper mtm transform and allocate memory for tapers/window functions.

Parameters

nfft	number of points in the transform
npoints	number of points in the tapers (windows)
ntapers	number of tapers

Returns: pointer to mfft_params structure (owned by caller)

◆ mtm_init_dpss()

mfft * mtm_init_dpss	(	int	nfft,
		int	npoints,
		double	nw,
		int	ntapers
	)

Initialize a mtfft transform using DPSS tapers (i.e.

for a standard multitaper transform)

Parameters

nfft	number of points in the transform
npoints	number of points in the tapers
nw	time-frequency parameter
ntapers	number of tapers to keep

Returns: pointer to mfft structure (owned by caller)

◆ mtm_init_herm()

mfft * mtm_init_herm	(	int	nfft,
		int	npoints,
		int	order,
		double	tm
	)

Initialize mtfft transform for reassigned spectrogram (i.e.

using hermitian function tapers)

Parameters

nfft	the number of points in the fourier transform
npoints	the number of points in the window; controls the time-frequency resolution (must be odd)
order	the maximum order of hermite functions to use. actual # of tapers is 3 times this
tm	time support for the tapers. If 0 or less, use the default of 6

Returns: pointer to mfft structure

◆ mtm_nfft()

int mtm_nfft ( mfft const * mtm )

◆ mtm_nframes()

int mtm_nframes	(	mfft const *	mtm,
		int	signal_size,
		int	step_size
	)

◆ mtm_npoints()

int mtm_npoints ( mfft const * mtm )

◆ mtm_nreal()

int mtm_nreal ( mfft const * mtm )

◆ mtm_ntapers()

int mtm_ntapers ( mfft const * mtm )

◆ mtm_spec()

void mtm_spec	(	mfft *	mtm,
		double *	spec,
		const double *	samples,
		int	nsamples,
		int	shift,
		int	adapt
	)

Compute a multitaper spectrogram by stepping through a signal.

This function 'fills' a spectrogram by calculating the PSD for each frame in the signal.

Parameters

mtm	mfft structure; needs to be initialized with tapers
samples	input signal
nsamples	number of points in input buffer
shift	number of samples to shift in each frame
adapt	if true, use adaptive averaging between tapers (otherwise 'high-res')
spec	(output) spectrogram, dimension (nsamples-npoints+1)/shift by nfft/2+1 needs to be allocated and zero-filled before calling

◆ mtm_tapers()

double const * mtm_tapers ( mfft const * mtm )

◆ mtm_tapers_fft()

void mtm_tapers_fft	(	mfft *	mtm,
		double	scale
	)

Compute FFT of the tapers.

This function is used in calculating the FFT of a point process. The result is stored in the mfft buffer in half-complex format with dimension ntapers x nfft. Use mtcomplex to extract the transformed tapers.

Parameters

mtm	parameters for the transform
scale	positive number to rescale the tapers before transform

◆ mtm_tapers_interp()

void mtm_tapers_interp	(	mfft const *	mtm,
		double *	out,
		double const *	times,
		int	ntimes,
		double	t0,
		double	dt
	)

Compute interpolation of tapers.

This function calculates taper values at arbitrary values using linear interpolation. It's used when calculating a windowed FFT of a point process. The value of the tapers outside the support is assumed to be zero.

Parameters

mtm	the mfft transform structure
out	(output) the interpolated values. Must be preallocated with dimension ntapers x ntimes
times	a series of times at which to evaluate the tapers
ntimes	the number of time points
t0	the start time of the tapers
dt	the time resolution of the tapers

◆ mtm_zspec()

void mtm_zspec	(	mfft *	mtm,
		cmplx_t *	spec,
		const double *	samples,
		int	nsamples,
		int	shift
	)

Compute a multitaper complex spectrogram by stepping through a signal.

This function 'fills' a spectrogram by calculating the complex FFT for each taper and for each frame in the signal.

Parameters

mtm	mfft structure; needs to be initialized with tapers
samples	input signal
nsamples	number of points in input buffer
shift	number of samples to shift in each frame
spec	(output) spectrogram, dimension (nsamples-npoints+1)/shift by (ntapers) by (nfft). Must be allocated and zero-filled.

◆ mtpower()

void mtpower	(	mfft const *	mtm,
		double *	pow,
		double	sigpow
	)

Extract power spectrum from multiple taper FFT.

The 'high-res' method is simply a weighted average of the estimates for each taper. The 'adaptive' method attempts to fit the contribution from each taper to match the total power in the signal.

Parameters

mtm	mfft structure after running mtfft
pow	(output) power spectral density (linear scale) of the signal. Needs to be preallocated, with dimensions at least nfft/2 + 1;
sigpow	total power in the signal. If zero or less, uses high-res method

◆ tfr_displacements()

void tfr_displacements	(	mfft const *	mtm,
		double *	q,
		double *	tdispl,
		double *	fdispl
	)

Compute the power spectrum and the time/frequency displacement.

Parameters

mtm	mfft object with computed FFT transforms; assumes that there are 3x tapers as the order of the multitaper transform (K)
q	(output) power spectrum (NFFT/2+1 x K)
tdispl	(output) time displacements (NFFT/2+1 x K)
fdispl	(output) frequency displacements (NFFT/2+1 x K)

◆ tfr_reassign()

void tfr_reassign	(	double *	spec,
		const double *	q,
		const double *	tdispl,
		const double *	fdispl,
		int	N,
		int	nfreq,
		const double *	fgrid,
		double	dt,
		double	qthresh,
		double	flock,
		int	tminlock,
		int	tmaxlock
	)

Assign power from a spectrum to a spectrogram based on time-frequency displacements.

The time-frequency reassignment spectrogram is built up through calls to this function for each time frame. The spectrum in q contributes to a range of time bins in spec which is limited by the tminlock and tmaxlock parameters. This in turn controls how the memory pointed to by *spec is accessed. At the edges of the spectrogram tminlock and tmaxlock need to be adjusted to avoid accessing invalid memory locations. Note that the units are frames, to make allocating the memory a bit easier.

The bin resolution of the output spectrogram is controlled by the nfreq and dt parameters. A spectrogram with arbitrary frequency bins (e.g. logarithmic) can be generated by specifying an array fgrid[nfreq], which must contain positive, monotonically increasing frequency values; energy is assigned to the nearest value in the grid (i.e. the grid specifies center frequencies)

Inputs:

Parameters

q	power spectrum (N points)
tdispl	time displacements (N points)
fdispl	frequency displacements (N points)
N	number of points in input spectrums
nfreq	number of frequency bins in output spectrum
fgrid	array of output frequency bins (optional; see below)
dt	spacing between columns of output spectrogram (samples)
qthresh	frequency bins with q<=qthresh are not assigned (unstable)
flock	maximum frequency displacement (radians; 0.01-0.02 is a good value; 0 to disable)
tminlock	maximum negative time displacement (number of FRAMES)
tmaxlock	maximum positive time displacement (number of FRAMES)
spec	(output) spectrogram (nfreq by >(tmaxlock+tminlock)) pre-allocate with zeros

◆ tfr_spec()

void tfr_spec	(	mfft *	mtm,
		double *	spec,
		const double *	samples,
		int	nsamples,
		int	k,
		int	shift,
		double	flock,
		int	tlock,
		int	nfreq,
		const double *	fgrid
	)

Compute a time-frequency reassignment spectrogram by stepping through a signal.

This function 'fills' a spectrogram by calculating the displaced PSD for each frame in the signal.

Parameters

mtm	mfft structure; needs to be initialized with hermite tapers
samples	input signal
nsamples	number of points in input buffer
k	which taper to use; -1 for all tapers
shift	number of samples to shift in each frame
flock	frequency locking parameter (normalized frequency units)
tlock	time locking parameter (in frames)
nfreq	output frequency resolution; if <= 0, defaults to nfft/2+1
fgrid	output frequency grid; if NULL, defaults to linear scale from 0 to 0.5 (normalized freq)
spec	(output) spectrogram, dimension (nsamples-npoints+1)/shift by nfft/2+1 needs to be allocated and zero-filled before calling

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ LIBTFR_VERSION

Typedef Documentation

◆ cmplx_t

◆ mfft

Function Documentation

◆ dpss()

◆ hermf()

◆ mtcomplex()

◆ mtfft()

◆ mtm_buffer()

◆ mtm_copy()

◆ mtm_destroy()

◆ mtm_init()

◆ mtm_init_dpss()

◆ mtm_init_herm()

◆ mtm_nfft()

◆ mtm_nframes()

◆ mtm_npoints()

◆ mtm_nreal()

◆ mtm_ntapers()

◆ mtm_spec()

◆ mtm_tapers()

◆ mtm_tapers_fft()

◆ mtm_tapers_interp()

◆ mtm_zspec()

◆ mtpower()

◆ tfr_displacements()

◆ tfr_reassign()

◆ tfr_spec()