Data Structures | Typedefs | Functions

src/time_frequency.h File Reference

STATUS: unstable Time-Frequency representation of time-series. More...

#include "definitions.h"
#include "complex.h"
#include "array.h"
#include "optarg.h"
#include <math.h>
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  Spectrogram
 Complex spectrogram (Time-Frequency-Representation) of a signal. More...

Typedefs

typedef Array *(* WindowFunction )(int, double)
 A Window Function.

Functions

Spectrogramspectrogram (const Array *sig, Spectrogram *spectgram, OptArgList *optargs)
 Easy interface for spectrogram calculation.
void spectrogram_free (Spectrogram *s)
 Free memory associated with Spectrogram.
Spectrogramspectrogram_init (int N_freq, int N_time)
 Initialize Spectrogram.
Arrayspectrogram_powerspectrum (const Spectrogram *spect)
 Calculate the powerspectrum for a Spectrogram.
Spectrogramspectrogram_stft (const Array *sig, double sampling_rate, const Array *Window, int N_freq, int N_time, double corner_freqs[2], int *timepoints, Spectrogram *spectgram)
 Calculate spectrogram of a signal (using STFT).
Arraywindow_dirichlet (int n, double noparam)
 Dirichlet (Rectangular) window.
Arraywindow_gaussian (int n, double sigma)
 Gaussian window.
Arraywindow_hamming (int n, double noparam)
 Hamming window.
Arraywindow_hanning (int n, double noparam)
 Hanning (Hann) window.
Arraywindow_kaiser (int n, double alpha)
 Kaiser Window.

Detailed Description

STATUS: unstable Time-Frequency representation of time-series.

A time-frequency represenation (TFR) of a signal displays the varying frequency content of a signal over time.

spectrogram.jpg
Todo:
add some docu here
Note:
the test-functions for this functionality are not excessive.

Definition in file time_frequency.h.


Typedef Documentation

typedef Array*(* WindowFunction)(int, double)

A Window Function.

Parameters:
n is the number of points in the window
param is a parameter depending on the choice of the window (e.g. sigma for gaussian)

Definition at line 51 of file time_frequency.h.


Function Documentation

Spectrogram* spectrogram ( const Array sig,
Spectrogram spectgram,
OptArgList optargs 
)

Easy interface for spectrogram calculation.

Parameters:
sig - data to be spectrogrammified (1D DOUBLE array)
spectgram - if NULL, own memory is alloated, else use this pointer.
optargs may contain:

  • sample_frequency=double of the signal, default is 500 (should really be provided!)
  • winfct=void* windowing function, default is window_hanning
  • timepoints=int* compute the spectrogram at selected time-points; this array is N_time long
  • winlength=int size of the window, default is MAX( SQR( sqrt(next_pow2( n ))-3 ), 5 )
  • winparam=double parameter for the window-function (e.g. sigma for gaussian); default=0.0
  • N_freq=int number of frequency bins, default is winlength*4
  • N_time=int number of time bins, default is n
  • corner_freqs=double* (array with two double entries), default is (0.0,250.0)

Definition at line 38 of file time_frequency.c.

void spectrogram_free ( Spectrogram s  ) 

Free memory associated with Spectrogram.

Definition at line 302 of file time_frequency.c.

Spectrogram* spectrogram_init ( int  N_freq,
int  N_time 
)

Initialize Spectrogram.

Parameters:
N_freq resolution (number of points) in frequency
N_time resolution in time
Returns:
a freshly allocated Spectrogram struct

Definition at line 282 of file time_frequency.c.

Array* spectrogram_powerspectrum ( const Spectrogram s  ) 

Calculate the powerspectrum for a Spectrogram.

Returns a s->N_time x s->N_freq matrix the absolute value squared of the complex numbers in spectrogram.

Parameters:
s - the spectrogram
Returns:
the powerspectrum for all time-points

Definition at line 264 of file time_frequency.c.

Spectrogram* spectrogram_stft ( const Array sig,
double  sampling_rate,
const Array Window,
int  N_freq,
int  N_time,
double  corner_freqs[2],
int *  timepoints,
Spectrogram spectgram 
)

Calculate spectrogram of a signal (using STFT).

This function is inspired by (read: 'was shamelessly ripped of from') the TIME-FREQUENCY TOOLBOX by Emmanuel Roy - Manuel DAVY (http://www-lagis.univ-lille1.fr/~davy/toolbox/Ctftbeng.html) It's a bit more efficient and uses different storage formats. It doesn't work on complex signals.

THE ALGORITHM

Given a signal to analyze in time and frequency, computes the Short Time Fourier Transform (STFT) :

\[ {STFT}(t,f) = \int x(s)h(t-s)e^{-2i\pi f s} ds \]

This function is complex valued. Its computation requires a window, which can be computed with one of the window_*() functions.

Parameters:
sig - data to be spectrogrammified (1D DOUBLE array)
sampling_rate - sampling frequency of signal
window - window for calculating the STFT (1D DOUBLE Array); get from window_*() functions
N_freq - number of frequency bins = number of rows in the TFR matrix (the next power of 2 is chosen for N_freq)
N_time - number of cols in the TFR matrix
corner_freqs - corner frequencies (lower, upper) for the returned spectrum at each time-sample in Hz; maximal would be {0, srate/2}
timepoints compute the spectrogram at selected time-points; this array is N_time long
spectgram - if NULL, own memory is alloated, else use this pointer.
Returns:
the spectrogram

Definition at line 144 of file time_frequency.c.

Array* window_dirichlet ( int  n,
double  noparam 
)

Dirichlet (Rectangular) window.

\[ w(x) = 1; \]

Parameters:
n - ODD number for window (else it is incremented by one)
noparam ignored (just for comparability to WindowFunction)
Returns:
1D DOUBLE array of size n

Definition at line 323 of file time_frequency.c.

Array* window_gaussian ( int  n,
double  sigma 
)

Gaussian window.

\[ w(n) = e^{-\frac{1}{2}\left( \frac{n-(N-1)/2}{\sigma(N-1)/2}\right)^2 } \]

with$ \sigma\le 0.5$

Parameters:
n - ODD number for window (else it is incremented by one)
sigma - gaussian std
Returns:
1D DOUBLE array of size n

Definition at line 349 of file time_frequency.c.

Array* window_hamming ( int  n,
double  noparam 
)

Hamming window.

\[ w(n) = 0.53836 - 0.46164 \cos\left( \frac{2\pi n}{N-1}\right) \]

Parameters:
n - ODD number for window (else it is incremented by one)
noparam ignored (just for comparability to WindowFunction)
Returns:
1D DOUBLE array of size n

Definition at line 374 of file time_frequency.c.

Array* window_hanning ( int  n,
double  noparam 
)

Hanning (Hann) window.

\[ w(n) = 0.5\left(1- \cos\left( \frac{2\pi n}{N-1}\right)\right) \]

Parameters:
n - ODD number for window (else it is incremented by one)
noparam ignored (just for comparability to WindowFunction)
Returns:
1D DOUBLE array of size n

Definition at line 399 of file time_frequency.c.

Array* window_kaiser ( int  n,
double  alpha 
)

Kaiser Window.

http://en.wikipedia.org/wiki/Kaiser_window

Parameters:
n - ODD number for window (else it is incremented by one)
alpha - parameter for window's steepness
Returns:
1D DOUBLE array of size n

Definition at line 423 of file time_frequency.c.