FSeries

In file FSeries/FSeries.hh:

class FSeries

Frequency series class.

Inheritance:

Public Classes
Public Fields
Public Methods

Documentation

The FSeries class is used to represent a series in the frequency domain, e.g. the Fourier transform coefficients of a given signal. The coefficient normalization is set such that the magnitude squared gives a meaningful power spectral density (psd). The Fourier coefficients should are normalized so that the measured power of a flat spectrum is independent of bin size i.e. the amplitude coefficient must be be in units of root-seconds. Two tests for correct normalization:

The total power in a fourier series is equal to the of the original time series (Parseval's theorem) i.e. for Y = fft(X)
The power density () of a sinusoid is equal to where A is the amplitude of the sinusoid, and dT is the total time covered by the time series (inverse of the frequency spacing).
Note that the amplitude is defined to give the correct power density without adding positive and negative frequencies in double-ended FSeries.

typedef fComplex Complex

Data type used to hold complex fourier coefficients.

typedef unsigned long size_type

Data type used to hold vector lengths.

enum DSMode

Enumerate data storage modes. Single sided series are stored linearly from Fo-Fnyquist in increasing bins. Double sided series are stored with Fmin -> Fo -> Fmax in bins 0 -> N-1.

FSeries(void)

Construct an empty FSeries.

FSeries(const FSeries& fs)

Construct an FSeries and initialize it from another FSeries.

Parameters:: FS - Fseries to be copied.

FSeries(double f0, double dF, Time t0, Interval dT, size_type NData, const float dData[])

Construct an FSeries with a specified frequency offset, frequency bin and float input data.

Parameters:: f0 - Lowest frequency to be contained by the FSeries (in Hz)
fBin - Frequency step between adjacent elements (in Hz)
t0 - Start time of the data represented by the FSeries
dT - Time interval of the data represented by the FSeries.
dData - Float data to be loaded into the FSeries.

FSeries(double f0, double dF, Time t0, Interval dT, size_type NData, const Complex dData[])

Construct an FSeries with a specified frequency offset, frequency bin and Complex input data.

Parameters:: f0 - Lowest frequency to be contained by the FSeries (in Hz)
fBin - Frequency step between adjacent elements (in Hz)
t0 - Start time of the data represented by the FSeries
dT - Time interval of the data represented by the FSeries.
dData - Complex data to be loaded into the FSeries.

FSeries(double f0, double dF, Time t0, Interval dT, const DVector& dv)

Construct an FSeries with a specified frequency offset, frequency bin and data vector. The data vector is cloned for the TSeries.

Parameters:: f0 - Lowest frequency to be contained by the FSeries (in Hz)
fBin - Frequency step between adjacent elements (in Hz)
t0 - Start time of the data represented by the FSeries
dT - Time interval of the data represented by the FSeries.
dv - DVector to be loaded into the FSeries.

FSeries(double f0, double dF, Time t0=Time(0), Interval dT=0, DVector* dv=0)

Construct an FSeries with a specified frequency offset, frequency bin and data vector. Ownership of the data vector is passed to the FSeries.

Parameters:: f0 - Lowest frequency to be contained by the FSeries (in Hz)
fBin - Frequency step between adjacent elements (in Hz)
t0 - Start time of the data represented by the FSeries
dT - Time interval of the data represented by the FSeries.
dv - DVector to be loaded into the FSeries.

FSeries(const TSeries& tData)

Construct an FSeries. Intialized it from the FFT of a time series. The normalization of the series is as described for setData(TSeries&).

Parameters:: tData - Time series from which the FSeries will be constructed.

FSeries(double f0, double dF, size_type NData, const Chirp& func)

Construct an FSeries. Intialize it from a Chirp template.

~FSeries(void)

Destroy a series object.

Parameters:: f0 - Lowest frequency to be contained by the FSeries (in Hz)
dF - Frequency step between adjacent elements (in Hz)
NData - Number of points to be put in the Series.
func - Wave function template.

void extend(double fmax)

Pad the FSeries to the specified maximum frequency.

Parameters:: fmax - New maximum frequency (in Hz)

FSeries extract(double f0, double dF) const

Returns an FSeries containing a subset of the parent FSeries.

Returns:: The specified sub-series
Parameters:: f0 - Lowest frequency to be extracted from the FSeries (in Hz)
dF - Frequency interval to be extracted (in Hz)

size_type getData(size_type len, Complex* data) const

Optionally convert and copy the first 'len' entries of a series to a complex array.

Returns:: The number of entries copied
Parameters:: len - Maximum number of words to be copied.
data - Complex buffer into which the data will be copied.

size_type getData(size_type len, float* data) const

Optionally convert and copy the first 'len' entries of a series to a float array. If the FSeries is complex, only the real part of the data are returned.

Returns:: The number of entries copied
Parameters:: len - Maximum number of entries to be copied.
data - Float buffer into which the data will be copied.

Interval getDt(void) const

Returns the time interval as specified in the sourrce data.

Returns:: The time interval of the data summarized by this series.

Time getEndTime(void) const

Returns the End time as specified in the source data.

Returns:: The end time of the data summarized by this series.

double getLowFreq(void) const

Returns the minimum frequency covered by the data.

Returns:: Lowest frequency represented in the FSeries in Hz.

size_type getLength(void) const

Get the Number of data words

double getHighFreq(void) const

Returns the maximum (Nyquist) frequency of the data.

Returns:: Highest frequency represented in the FSeries in Hz.

double getCenterFreq(void) const

Returns the center frequency of the data (the low frequency for single sided storage).

Returns:: Highest frequency represented in the FSeries in Hz.

double getFStep(void) const

Returns the Frequency interval between two adjacent points of the FSeries.

Returns:: The frequency interval in Hz.

const char* getName(void) const

Returns a pointer to the frequency series name.

Returns:: A constant pointer to the series name.

size_type getNStep(void) const

Returns the number of frequency steps. Note that the number of data points is in fact one greater than the number of steps because both the f=0 and f=Nyquist entries are included.

Returns:: the number of frequency steps.

Time getStartTime(void) const

Returns the start time as specified in the source data.

Returns:: The start time of the data summarized by this series.

FSeries interpolate(double fmin, double fmax, double df, bool logar=false) const

Interpolate the current FSeries in the specified frequency range (fMin - fMax) at points separated by the specified frequency spacing (df). The returned FSeries is a single sided series starting at f=0 with the specified spacing and points up to (but not including) fMax. It is non-zero only in the specified range. No interpolation is performed if the requested frequency step is an integer multiple of the current step. If interpolation is necessary, it may be performed either linearly or logarithmically as specified by the logar parameter.

Returns:: Interpolated frequency series.
Parameters:: fMin - Minimum non-zero frequency of returned series
fMin - Maximum frequency of returned series
df - Frequency step of returned series.
logar - If true, logarithmic interpolation.

const void* refData(void) const

Returns a pointer to the data or NULL if the DVector hasn't been defined.

Returns:: Constant pointer to the data storage area.

const DVector* refDVect(void) const

Get the data vector pointer

Returns:: A pointer to the series data vector.

std::ostream& Dump(std::ostream& out) const

A formatted dump of the FSeries header and data are written to the output stream.

Returns:: The I/O stream passed to the function.
Parameters:: I - /O stream to which the formatted dump is to be written.

bool isDoubleSided(void) const

Test if fourrier coefficients are stored in (full) double-sided format.

Returns:: true if double sided.

bool empty(void) const

Test if FSeries is empty.

Returns:: true if empty..

bool isSingleSided(void) const

Test if fourrier coefficients are stored in (full) double-sided format.

Returns:: true if double sided.

bool null(void) const

Test if FSeries DVector is unassigned.

Returns:: true if null.

float Power(float fmin=0.0, float fmax=0.0) const

The spectral power is calculated in the band from 'fmin' to 'fmax'. Because of the normalization used, Power is only summed over positive frequencies. If fmin or fmax is not specified, it is replaced by the minimum or maximum frequency of the series, respectively. The specified frequency limits are rounded to the series frequency bins to avoid interpolation.

Parameters:: fmin - Minimum frequency over which the Power is summed.
fmax - Maximum frequency over which the Power is summed.

void appName(const char* name)

The specified string is appended to the existing series name.

Parameters:: name - String to be apended to the series name.

void clear(void)

Clear the data vector.

void setData(size_type len, const float* data)

The float data in 'data' are optionally converted to the data vector type and then used to overwrite the series data.

Parameters:: len - Number of data words to be written to the FSeries.
data - A float array holding data to be written to the FSeries.

void setData(size_type len, const Complex* data)

The Complex data in 'data' are optionally converted to the data vector type and then used to overwrite the series data.

Parameters:: len - Number of data words to be written to the FSeries.
data - A Complex array with the data to be written to the FSeries.

void setData(DVector* data)

The current data are cleared and the DVector 'data' is taken over by the FSeries.

Parameters:: data - A DVector to be adopted by the FSeries.

void setData(const TSeries& data)

A time series is Fourier transformed and the result is stored in the FSeries. The series is normalized to make the measured power of a flat distribution independent of the binsize i.e. the (unfolded) DFT in the range 0<f<Fny is multiplied by: 2*sqrt(dt*N)/N where N is the number of TSeries samples and dt is the time between samples. The resulting FSeries contains int((N+1)/2) frequency coefficients.

Parameters:: data - Time series to be transformed and stored in the FSeries.

void setName(const char* name)

The series name is set to the 'name' string.

Parameters:: name - Series name.

void setTimeSpan(const Time& t0, Interval dT)

The series time span is set.

Parameters:: t0 - Start time of the data from which the FSeries is derived.
dT - Interval over which the data were derived or valid.

void setT0(const Time& t0)

The series start time is set to 't0'. This is obsolescent.

Parameters:: t0 - Start time of the data from which the FSeries is derived.

void ReSize(size_type len)

The data vector length is increased to accomodate at least the specified number of entries. If sufficient storage has already been allocated, no action is taken.

Returns:: Desired minimum storage length in words.

void tDerivative(void)

The frequency series is replaced by its time derivative, calculated by multiplying each coefficient by 2*pi*i*f.

void tIntegral(void)

The frequency series is replaced by its indefinite time integral, calculated by multiplying each coefficient by 2*pi*i*f.

Complex cdot(const FSeries& fs) const

Sum the product of the frequency series and the complex conjugate of the argument.

FSeries& operator =(const FSeries& rhs)

The frequency information, Time information and data of the lhs series are replaced by those of the rhs series. The data are converted to the the type of the lhs series if necessary.

Returns:: a reference to the updated lhs FSeries.
Parameters:: rhs - The series to be copied.

FSeries& operator +=(double bias)

The rhs constant is added to the lhs series on a element by element basis. The result replaces the original contents of the lhs series.

Returns:: a reference to the updated lhs FSeries.
Parameters:: bias - The constant to be added.

FSeries& operator +=(const FSeries& rhs)

The rhs series is added to the lhs series on a element by element basis. The result replaces the original contents of the lhs series.

Returns:: a reference to the updated lhs FSeries.
Parameters:: rhs - The series to be added.

FSeries& operator -=(const FSeries& rhs)

The rhs series is subtracted from the lhs series on a element by element basis. The result replaces the original contents of the lhs series.

Returns:: a reference to the updated lhs FSeries.
Parameters:: rhs - The series to be subtracted.

FSeries& operator *=(double scale)

Each element of the lhs series is multiplied by a scale factor.

Returns:: a reference to the updated lhs FSeries.
Parameters:: scale - The scale factor.

FSeries& operator *=(const FSeries& fs)

Each element of the lhs series is multiplied by the corresponding element of the argument series.

Returns:: a reference to the updated lhs FSeries.
Parameters:: fs - The multiplier series.

FSeries& operator /=(const FSeries& fs)

Each element of the lhs series is divided by the corresponding element of the argument series.

Returns:: a reference to the updated lhs FSeries.
Parameters:: fs - The divisor series.

Complex operator)(double freq) const

The complex amplitude at the closest bin is returned.

Returns:: Complex value of the series at the specified frequency.
Parameters:: Frequency - in Hz at which the series is to be evaluated.

void evolve(const Interval& dT)

The zero time of the series is shifted by 'dT'. This is implemented by multiplying each element by exp(i*dT*f). The Start-time field of the series is left unchanged.

Parameters:: Time - interval over which the series is to be evolved.

size_type getBin(double f) const

Calculate the bin number closest to a given frequency. The returned bin number is always valid, i.e. 0 <= bin < length. If the frequency is less than mF0 (including negative frequencies in a single sided series) bin 0 is returned.

double getBinF(size_type bin) const

Calculate the frequency of a given bin

This class has no child classes.

Author:: J. Zweizig
Version:: 1.3; Modified October 26, 1999

alphabetic index hierarchy of classes

Please send questions and comments to zweizig_j@ligo.caltech.edu

generated by doc++

	FSeries (void) Default constructor.
	FSeries (const FSeries& fs) Copy constructor.
	FSeries (double f0, double dF, Time t0, Interval dT, size_type NData, const float dData[]) Data constructor.
	FSeries (double f0, double dF, Time t0, Interval dT, size_type NData, const Complex dData[]) Data constructor.
	FSeries (double f0, double dF, Time t0, Interval dT, const DVector& dv) Data constructor.
	FSeries (double f0, double dF, Time t0=Time(0), Interval dT=0, DVector* dv=0) Data constructor.
	FSeries (const TSeries& tData) FFT constructor.
	FSeries (double f0, double dF, size_type NData, const Chirp& func) Template constructor.
	~FSeries (void) FSeries Destructor.
void	extend (double fmax) Extend the FSeries.
FSeries	extract (double f0, double dF) const Get a substring of the FSeries.
size_type	getData (size_type len, Complex* data) const Get complex series data.
size_type	getData (size_type len, float* data) const Get float series data.
Interval	getDt (void) const Get the time interval.
Time	getEndTime (void) const Get the End time.
double	getLowFreq (void) const Get the minimum frequency.
size_type	getLength (void) const Get the Number of data words
double	getHighFreq (void) const Get the maximum Frequency.
double	getCenterFreq (void) const Get the maximum Frequency.
double	getFStep (void) const Get the frequency step.
const char*	getName (void) const Get the series name.
size_type	getNStep (void) const Get the number of frequency steps.
Time	getStartTime (void) const Get the start time.
FSeries	interpolate (double fmin, double fmax, double df, bool logar=false) const Interpolate the FSeries points
const void*	refData (void) const Get a pointer to the series data.
const DVector*	refDVect (void) const Data Vector reference.
std::ostream&	Dump (std::ostream& out) const Dump the contents of the FSeries to an output stream.
bool	isDoubleSided (void) const Test for double sided storage.
bool	empty (void) const Test for empty series.
bool	isSingleSided (void) const Test for double sided storage.
bool	null (void) const Test for null series.
float	Power (float fmin=0.0, float fmax=0.0) const Get the power in a band.
void	appName (const char* name) Append a string to the series name.
void	clear (void) Clear the data vector.
void	setData (size_type len, const float* data) Overwrite the series with float data.
void	setData (size_type len, const Complex* data) Overwrite the series with Complex data.
void	setData (DVector* data) Overwrite the series with the specified data vector.
void	setData (const TSeries& data) Replace the series with an FFT of a TSeries.
void	setName (const char* name) Set the series name.
void	setTimeSpan (const Time& t0, Interval dT) Set the time span.
void	setT0 (const Time& t0) Set the start time.
void	ReSize (size_type len) Increase the data vector storage.
void	tDerivative (void) Time derivative.
void	tIntegral (void) Time integral.
Complex	cdot (const FSeries& fs) const complex convolution.
FSeries&	operator = (const FSeries& rhs) Assignment operator.
FSeries&	operator += (double bias) Bias an FSeries.
FSeries&	operator += (const FSeries& rhs) Add two FSeries.
FSeries&	operator -= (const FSeries& rhs) Subtract a series.
FSeries&	*operator =** (double scale) Scale a series.
FSeries&	*operator =** (const FSeries& fs) Multiply a series by another.
FSeries&	operator /= (const FSeries& fs) Divide a series by another.
Complex	operator) (double freq) const Get the amplitude at a specified frequency.
void	evolve (const Interval& dT) Evolve the Frequency series in time.
size_type	getBin (double f) const Calculate the bin number closest to a given frequency
double	getBinF (size_type bin) const Calculate the frequency of a given bin

typedef fComplex	Complex Complex data type.
typedef unsigned long	size_type Length data type.

class FSeries

Inheritance:

Public Classes

Public Fields

Public Methods

Documentation