template<typename realT>
class mx::sigproc::averagePeriodogram< realT >

Calculate the average periodogram of a time-series.

Implements the overlapped average periodogram, cf. pp 843 to 845 of [17]. A.k.a. Welch's method (https://en.wikipedia.org/wiki/Welch's_method).

This produces the variance normalized 1-sided PSD estimate of the periodogram.

Optionally includes a window (by default no window is used, which is equivalent to the rectangle window).

Optionally includes zero-padding, which is applied after windowing. This can be used to increase frequency resolution while still allowing overlapping.

Can also be used to calculate the unaveraged non-overlapped periodogram of the entire time series, with or without windowing and zero-padding.

Example:

 typedef float realT;
 
 mx::fftwEnvironment<realT> fftwEnv; //for efficient fft planning
 
 std::vector<realT> ts = getTimeSeries(); //Some function to populate ts.
 
 math::vectorMeanSub(ts); //The time series should be overall mean subtracted.
 
 realT dt = 0.1; //The sampling of ts is 0.1 seconds.
 
 averagePeriodogram<realT> avgPgram(2.0/dt, 4.0/dt, dt); //This sets the averaging length to 2 seconds (20 samples),
zero padding to 4 seconds, with a 1 second overlap (set automatically)
 
 avgPgram.win(window::hann); //Set the Hann window
 
 std::vector<realT> pgram = avgPgram(ts); //Calculate the half-overlapped periodogram estimate for ts.
 
 //Now output the periodogram estimate.  This will give two columns, the first frequency, the second power at that
frequency. for(size_t n=0; n< avgPgram.size(); ++n)
 {
    std::cout << avgPgram[n] << " " << pgram[n] << "\n";
 }

Definition at line 85 of file averagePeriodogram.hpp.

#include <sigproc/averagePeriodogram.hpp>

Public Member Functions
	averagePeriodogram (size_t avgLen)
	C'tor which sets up the optimum overlapped periodogram of the timeseries.

	averagePeriodogram (size_t avgLen, size_t padLen)
	C'tor which sets up the optimum overlapped periodogram of the timeseries with zero-padding.

	averagePeriodogram (size_t avgLen, size_t padLen, realT dt)

	averagePeriodogram (size_t avgLen, size_t padLen, size_t olap, realT dt)
	C'tor setting up an arbitrary overlap.

	~averagePeriodogram ()
	D'tor, frees all working memory.

void	dt (realT ndt)
	Set the sampling interval of the time-series.

realT	dt ()
	Get the sampling interval of the time-series.

realT	df ()
	Get the frequency interval of the periodogram.

int	resize (size_t avgLen)
	Resize the periodogram working memory, setting up the 1/2-overlapped optimum case.

int	resize (size_t avgLen, size_t padLen, size_t olap)
	Resize the periodogram working memory.

std::vector< realT > &	win ()
	Get a reference to the window vector.

void	win (void(*winFunc)(std::vector< realT > &))
	Set the window vector using a function.

void	resizeWin (bool setRect=true)
	Resize the window and, unless not desired, initialize to the rectangular window by setting all 1s.

void	operator() (realT pgram, const realT ts, size_t sz)
	Calculate the periodogram for a time-series.

void	operator() (std::vector< realT > &pgram, const std::vector< realT > &ts)
	Calculate the periodogram for a time-series.

std::vector< realT >	operator() (std::vector< realT > &ts)
	Calculate the periodogram for a time-series.

size_t	size ()
	Return the size of the periodogram.

realT	operator[] (size_t n)
	Get the frequency at a given point in the periodogram.

Protected Attributes
size_t	m_size { 0 }
	The size of the periodogram vector, calculated as m_avgLen/2 + 1;.

int	m_nOver { 0 }
	The number of overlapping segments. Calculated from m_avgLen and m_overlap;.

realT	m_df { 1 }
	The frequency sampling. This is used only for normalization and frequency scale output.

Configuration Parameters
size_t	m_avgLen { 0 }
	The number of samples in each periodogram estimate.

size_t	m_overlap { 0 }

size_t	m_padLen { 0 }
	The size of the periodogram estimate with zero-padding.

realT	m_dt { 1 }
	The time sampling. Only used for normalization and calculation of the frequency scale.

std::vector< realT >	m_win

Constructor & Destructor Documentation

◆ averagePeriodogram() [1/4]

template<typename realT >

mx::sigproc::averagePeriodogram< realT >::averagePeriodogram ( size_t avgLen )

explicit

C'tor which sets up the optimum overlapped periodogram of the timeseries.

Sets m_overlap = 0.5*m_avgLen. If you desire the non-overlapped case use the alternate constructor:

averagePeriogram p( avgLen, 0, dt);

Parameters

[in] avgLen The length of averaging in samples.

Definition at line 270 of file averagePeriodogram.hpp.

◆ averagePeriodogram() [2/4]

template<typename realT >

mx::sigproc::averagePeriodogram< realT >::averagePeriodogram	(	size_t	avgLen,
		size_t	padLen
	)

explicit

C'tor which sets up the optimum overlapped periodogram of the timeseries with zero-padding.

Sets m_overlap = 0.5*m_avgLen. If you desire the non-overlapped case use the alternate constructor:

averagePeriogram p( avgLen, 0, padLen, dt);

Parameters

[in]	avgLen	The length of averaging in samples.
[in]	padLen	[optional] the length of the padded sample. If 0 or omitted then no padding used.

Definition at line 277 of file averagePeriodogram.hpp.

◆ averagePeriodogram() [3/4]

template<typename realT >

mx::sigproc::averagePeriodogram< realT >::averagePeriodogram	(	size_t	avgLen,
		size_t	padLen,
		realT	dt
	)

C'tor which sets up the optimum overlapped periodogram of the timeseries with zero-padding and sets the sampling. Sets m_overlap = 0.5*m_avgLen. If you desire the non-overlapped case use the alternate constructor:

averagePeriogram p( avgLen, 0, dt);

Parameters

[in]	avgLen	The length of averaging in samples.
[in]	padLen	the length of the padded sample. Set to 0 for no padding.
[in]	dt	the sampling interval of the time-series

Definition at line 284 of file averagePeriodogram.hpp.

◆ averagePeriodogram() [4/4]

template<typename realT >

mx::sigproc::averagePeriodogram< realT >::averagePeriodogram	(	size_t	avgLen,
		size_t	padLen,
		size_t	olap,
		realT	dt
	)

C'tor setting up an arbitrary overlap.

Set olap to 0 for the unoverlapped case.

Parameters

[in]	avgLen	The number of samples in each periodgoram estimate.
[in]	padLen	the length of the padded sample. Set to 0 for no padding.
[in]	olap	The number of samples by which to overlap. This should almost always be 0.5*m_avgLen. Set 0 for the non-overlapped case.
[in]	dt	the sampling interval of the time-series

Definition at line 291 of file averagePeriodogram.hpp.

◆ ~averagePeriodogram()

template<typename realT >

mx::sigproc::averagePeriodogram< realT >::~averagePeriodogram ( )

D'tor, frees all working memory.

Definition at line 298 of file averagePeriodogram.hpp.

Member Function Documentation

◆ df()

template<typename realT >

realT mx::sigproc::averagePeriodogram< realT >::df ( )

Get the frequency interval of the periodogram.

Returns: m_df

Definition at line 325 of file averagePeriodogram.hpp.

◆ dt() [1/2]

template<typename realT >

realT mx::sigproc::averagePeriodogram< realT >::dt ( )

Get the sampling interval of the time-series.

Returns: m_dt

Definition at line 319 of file averagePeriodogram.hpp.

◆ dt() [2/2]

template<typename realT >

void mx::sigproc::averagePeriodogram< realT >::dt ( realT ndt )

Set the sampling interval of the time-series.

This also sets the frequency scale of the output.

Definition at line 312 of file averagePeriodogram.hpp.

◆ operator()() [1/3]

template<typename realT >

void mx::sigproc::averagePeriodogram< realT >::operator()	(	realT *	pgram,
		const realT *	ts,
		size_t	sz
	)

Calculate the periodogram for a time-series.

Parameters

[out]	pgram	a pre-allocated to size() array which will be populated with the periodogram of the time-series
[in]	ts	the time-series
[in]	sz	the length of the time-series array

Definition at line 401 of file averagePeriodogram.hpp.

References mx::sigproc::psdVar1sided(), and mx::math::vectorVariance().

◆ operator()() [2/3]

template<typename realT >

void mx::sigproc::averagePeriodogram< realT >::operator()	(	std::vector< realT > &	pgram,
		const std::vector< realT > &	ts
	)

Calculate the periodogram for a time-series.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

[out]	pgram	a vector which will be allocated and populated with the periodogram of the time-series
[in]	ts	the time-series

Definition at line 454 of file averagePeriodogram.hpp.

◆ operator()() [3/3]

template<typename realT >

std::vector< realT > mx::sigproc::averagePeriodogram< realT >::operator() ( std::vector< realT > & ts )

Calculate the periodogram for a time-series.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns: the periodogram as a vector.

Parameters

[in] ts the time-series

Definition at line 461 of file averagePeriodogram.hpp.

◆ operator[]()

template<typename realT >

realT mx::sigproc::averagePeriodogram< realT >::operator[] ( size_t n )

Get the frequency at a given point in the periodogram.

Returns: the frequency at point n in the periodogram.

Parameters

[in] n the point in the periodogram at which the frequency is desired

Definition at line 475 of file averagePeriodogram.hpp.

◆ resize() [1/2]

template<typename realT >

int mx::sigproc::averagePeriodogram< realT >::resize ( size_t avgLen )

Resize the periodogram working memory, setting up the 1/2-overlapped optimum case.

This sets the overlap to 0.5*avgLen.

Also performs fft planning.

Returns: 0 on success; -1 on error

Parameters

[in] avgLen The number of samples in each periodgoram estimate.

Definition at line 331 of file averagePeriodogram.hpp.

Referenced by mx::AO::analysis::fourierTemporalPSD< _realT, aosysT >::intensityPSD(), and mx::AO::analysis::speckleAmpPSD().

◆ resize() [2/2]

template<typename realT >

int mx::sigproc::averagePeriodogram< realT >::resize	(	size_t	avgLen,
		size_t	padLen,
		size_t	olap
	)

Resize the periodogram working memory.

Also performs fft planning.

Returns: 0 on success; -1 on error

Parameters

[in]	avgLen	The number of samples in each periodgoram estimate.
[in]	padLen	the length of the sample after zero-padding.
[in]	olap	The number of samples by which to overlap. This should almost always be 0.5*m_avgLen. Set 0 for the non-overlapped case.

Definition at line 337 of file averagePeriodogram.hpp.

References forward.

◆ resizeWin()

template<typename realT >

void mx::sigproc::averagePeriodogram< realT >::resizeWin ( bool setRect = true )

Resize the window and, unless not desired, initialize to the rectangular window by setting all 1s.

If setRect=false then the window is not initialized.

Parameters

[in] setRect [optional] if false, then the window is not initialized to 1

Definition at line 388 of file averagePeriodogram.hpp.

◆ size()

template<typename realT >

size_t mx::sigproc::averagePeriodogram< realT >::size ( )

Return the size of the periodogram.

Returns: the size of the periodogram estimate for the current setup.

Definition at line 469 of file averagePeriodogram.hpp.

Referenced by mx::AO::analysis::fourierTemporalPSD< _realT, aosysT >::intensityPSD(), and mx::AO::analysis::speckleAmpPSD().

◆ win() [1/2]

template<typename realT >

std::vector< realT > & mx::sigproc::averagePeriodogram< realT >::win ( )

Get a reference to the window vector.

This allows population of the window with any arbitrary function. You should call resizeWin() before using this to make sure that the vector has the correct length.

Returns: a reference to m_win.

Definition at line 375 of file averagePeriodogram.hpp.

Referenced by mx::AO::analysis::fourierTemporalPSD< _realT, aosysT >::intensityPSD(), and mx::AO::analysis::speckleAmpPSD().

◆ win() [2/2]

template<typename realT >

void mx::sigproc::averagePeriodogram< realT >::win ( void(*)(std::vector< realT > &) winFunc )

Set the window vector using a function.

This will resize m_win, and then call the function with m_win as the argument. For example to use the hann window defined signal_windows1D:

avgPgram.win( window::hann );

template<typename realT >

std::vector<realT> mx::sigproc::averagePeriodogram< realT >::m_win

protected

The window function. By default this is empty, which is equivalent to setting it to the rectangular window.

Definition at line 103 of file averagePeriodogram.hpp.

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

sigproc/averagePeriodogram.hpp

Public Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ averagePeriodogram() [1/4]

◆ averagePeriodogram() [2/4]

◆ averagePeriodogram() [3/4]

◆ averagePeriodogram() [4/4]

◆ ~averagePeriodogram()

Member Function Documentation

◆ df()

◆ dt() [1/2]

◆ dt() [2/2]

◆ operator()() [1/3]

◆ operator()() [2/3]

◆ operator()() [3/3]

◆ operator[]()

◆ resize() [1/2]

◆ resize() [2/2]

◆ resizeWin()

◆ size()

◆ win() [1/2]

◆ win() [2/2]

Member Data Documentation

◆ m_avgLen

◆ m_df

◆ m_dt

◆ m_nOver

◆ m_overlap

◆ m_padLen

◆ m_size

◆ m_win