Das2Psd Struct Reference

#include <das2/dft.h>

---

Detailed Description

A power spectral density estimator (periodogram).

This is a wrapper around the FFTW (Fastest Fourier Transform in the West) library to handle memory management, normalization and windowing.

Public Member Functions
Das2Psd *	new_Psd (size_t uLen, bool bCenter, const char *sWindow)
	Create a new Power Spectral Density Calculator.
void	del_Das2Psd (Das2Psd *pThis)
	Free a Power Spectral Density calculator.
ErrorCode	Psd_calculate (Das2Psd *pThis, const double *pReal, const double *pImg, size_t uLen)
	Calculate a Power Spectral Density (periodogram).
ErrorCode	Psd_calculate_f (Das2Psd *pThis, const float *pReal, const float *pImg, size_t uLen)
	The floating point array input analog of Psd_calaculate().
double	Psd_powerRatio (const Das2Psd *pThis, double *pInput, double *pOutput)
	Provide a comparison of the input power and the output power.
const double *	Psd_get (const Das2Psd *pThis, size_t *pLen)
	Get the amplitude magnitude vector from a calculation.

---

Member Function Documentation

Das2Psd * new_Psd	(	size_t	uLen,
		bool	bCenter,
		const char *	sWindow
	)

Create a new Power Spectral Density Calculator.

This estimator uses the equations given in Numerical Recipes in C, section 13.4, but not any of the actual Numerical Recipes source code.

Parameters:

	uLen	The length of the input complex series
	bCenter	If true, input values will be centered on the Mean value. This shifts-out the DC component from the input.
	sWindow	A named window to use for the data. Possible values are: "hann" - Use a hann window as defined at http://en.wikipedia.org/wiki/Hann_function NULL - Use a square window. (i.e. 'multiply' all data by 1.0)

Returns:

A new Power Spectral Density estimator allocated on the heap

void del_Das2Psd

(

Das2Psd *

pThis

)

Free a Power Spectral Density calculator.

Parameters:

pThis

ErrorCode Psd_calculate	(	Das2Psd *	pThis,
		const double *	pReal,
		const double *	pImg,
		size_t	uLen
	)

Calculate a Power Spectral Density (periodogram).

Using the calculation plan setup in the constructor, calculate a discrete Fourier transform. When this function is called internal storage of any previous DFT calculations (if any) are over written.

Parameters:

	pThis	The PSD calculator object
	pReal	A "time domain" input vector of length uLen
	pImg	The imaginary (or quadrature phase) input vector of length uLen. For a purely real signal this vector is NULL.
	uLen	The number of reals in the input signal. If this value changes between successive calls to this function for the same PSD object then you're code will take a performance hit.

Returns:

0 (DAS_OKAY) if the calculation was successful, a non-zero error code otherwise

ErrorCode Psd_calculate_f	(	Das2Psd *	pThis,
		const float *	pReal,
		const float *	pImg,
		size_t	uLen
	)

The floating point array input analog of Psd_calaculate().

Internal calculations are still handled in double precision.

double Psd_powerRatio	(	const Das2Psd *	pThis,
		double *	pInput,
		double *	pOutput
	)

Provide a comparison of the input power and the output power.

During the Psd_calculate() call the average magnitude of the input vector is saved along with the average magnitude of the output vector (divided by the Window summed and squared). These two measures of power should always be close to each other when using a hann window. When using a NULL window they should be almost identical, to within rounding error. The two measures are:

              N-1
          1  ----   2      2
  Pin =  --- \    r    +  i
          N  /     n       n
             ----
              n=0

                N-1
           1   ----   2      2
  Pout =  ---  \    R    +  I
          Wss  /     k       k
               ----
                k=0
 

where Wss collapses to N**2 when a NULL (square) window is used. The reason that the Pout has an extra factor of N in the denominator is due to the following identity for the discrete Fourier transform (Parseval's theorem):

     N-1                   N-1
    ----   2    2      1  ----  2    2
    \     r  + i   =  --- \    R  + I
    /      n    n      N  /     n    n
    ----                  ----
     n=0                   k=0

Where r and i are the real and imaginary input amplitudes, and R and I are the DFT real and imaginary output values.

Parameters:

	pThis	A PSD calculator for which Psd_calculate has been called
	pInput	A pointer to store the input power. If NULL, the input power will no be saved separately.
	pOutput	A pointer to store the output power. If NULL, the output power will no be saved separately.

Returns:

The ratio of Power Out divided by Power In. (Gain).

const double * Psd_get	(	const Das2Psd *	pThis,
		size_t *	pLen
	)

Get the amplitude magnitude vector from a calculation.

Scale the stored DFT so that it preserves amplitude, and get the magnitude. For real-valued inputs (complex pointer = 0) the 'positive' and 'negative' frequencies are combined. For complex input vectors this is not the case since all DFT output amplitudes are unique. Stated another way, for complex input signals components above the Nyquist frequency have meaningful information.

Parameters:

	pThis	The DFT calculator object which has previously been called to calculate a result.
	pLen	The vector length. In general this is *NOT* the same as the input time series length. For real-value input signals (complex input is NULL, this is N/2 + 1. For complex input signals this is N.

Returns:

A pointer to an internal holding bin for the real signal magnitude values.

Warning:

: If Psd_calculate() is called again, this pointer can be invalidated. If a permanent result is needed after subsequent Dft_calculate() calls, copy these data to another buffer.

---

The documentation for this struct was generated from the following file:

• das2/dft.h