FSeries

class FSeries

Frequency series class.

Public Classes
enum DSMode: Data Storage mode.

Public Fields
typedef fComplex Complex: Complex data type.
typedef unsigned long size_t: Length data type.

Public Methods
FSeries(void): Default constructor.
FSeries(const FSeries& FS): Copy constructor.
FSeries(double f0, double fBin, Time t0=Time(0), Interval dT=Interval(0.0)): Data constructor.
FSeries(double f0, double dF, Time t0, Interval dT, size_t NData, const float dData[]): Data constructor.
FSeries(double f0, double dF, Time t0, Interval dT, size_t NData, const Complex dData[]): Data constructor.
FSeries(const TSeries& tData): FFT constructor.
FSeries(double f0, double dF, size_t NData, const Chirp& func): Template constructor.
~FSeries(void): FSeries Destructor.
FSeries extract(double f0, double dF) const: Get a substring of the FSeries.
Time getStartTime(void) const: Get the start time.
Time getEndTime(void) const: Get the End time.
double getLowFreq(void) const: Get the minimum frequency.
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_t getNStep(void) const: Get the number of frequency steps.
const void* refData(void) const: Get a pointer to the series data.
const DVector* refDVect() const: Data Vector reference.
std::ostream& Dump(std::ostream& out) const: Dump the contents of the FSeries to an output stream.
size_t getData(size_t len, Complex* data) const: Get complex series data.
size_t getData(size_t len, float* data) const: Get float series data.
bool isDoubleSided(void) const: Test for double sided storage.
bool isEmpty(void) const: Test for empty series.
bool isSingleSided(void) const: Test for double sided storage.
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 te data vector.
void setT0(const Time& t0): Set the start time.
void setName(const char* name): Set the series name.
void setData(size_t len, const float* data): Overwrite the series with float data.
void setData(size_t len, const Complex* data): Overwrite the series with Complex data.
void setData(const TSeries& data): Replace the series with an FFT of a TSeries.
void ReSize(size_t len): Increase the data vector storage.
void tDerivative(void): Time derivative.
void tIntegral(void): Time integral.
FSeries& operator =(const FSeries& rhs): Assignment operator.
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 *(const FSeries& rhs) const: Inner product of two series.
Complex operator)(double freq) const: Get the amplitude at a specified frequency.
void evolve(const Interval& dT): Evolve the Frequency series in time.

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_t

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 Fo-Fmax in bins 0 - (N/2-1) and Fmin - (Fo-dF) in bins N/2 - 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 fBin, Time t0=Time(0), Interval dT=Interval(0.0))

Construct an FSeries with a specified start frequency, frequency bin and time epoch. No data vector is allocated.

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.

FSeries(double f0, double dF, Time t0, Interval dT, size_t 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_t 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(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_t 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.

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)

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.

Time getEndTime(void) const

Returns the End time as specified in the sourrce 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.

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_t 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.

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() 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.

size_t getData(size_t 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_t getData(size_t 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.

bool isDoubleSided(void) const

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

Returns:: true if double sided.

bool isEmpty(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.

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 te data vector.

void setT0(const Time& t0)

The series start time is set to 't0'.

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

void setName(const char* name)

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

Parameters:: name - Series name.

void setData(size_t 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_t 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(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 ReSize(size_t 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.

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 +=(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 *(const FSeries& rhs) const

Each entry of the lhs series is multiplied by the corresponding rhs entry (conjugated in complex series), and the products are summed.

Returns:: The inner product value.
Parameters:: rhs - Multiplier FSeries

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.

This class has no child classes.

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

alphabetic index hierarchy of classes

generated by doc++

class FSeries

Public Classes

Public Fields

Public Methods

Documentation