TSeries

In file TSeries/TSeries.hh:

class TSeries

Time series API.

Inheritance:

Public Fields
Public Methods

Documentation

The TSeries class holds a time series of arbitrarily typed data.

typedef unsigned long size_type

Vector length data type.

typedef unsigned long stat_type

Data Status Type.

typedef double math_type

Mathematical data type.

TSeries()

A time series object is initialized without a data vector.

TSeries(const TSeries& TS)

The argument series is duplicated into the new TSeries.

Parameters:: TS - Time series to be duplicated.

TSeries(const Time& t0, const Interval& dt)

A time series is created with a specified start time and sample interval, but no data.

Parameters:: t0 - Series start time.
dt - Step interval.

TSeries(const Time& t0, const Interval& dt, size_type NData, const float dData[]=0)

A float time series object is constructed and initialized from a float data array.

Parameters:: t0 - Series start time.
dt - Time interval between two successive samples.
NData - Number of data words.
dData - float array containing series data.

TSeries(const Time& t0, const Interval& dt, size_type NData, const short dData[])

A short time series object is constructed and initialized from a short data array.

Parameters:: t0 - Series start time.
dt - Time interval between two successive samples.
NData - Number of data words.
dData - short integer array containing series data.

TSeries(const Time& t0, const Interval& dt, size_type NData, const int dData[])

An integer time series object is constructed and initialized from a integer data array.

Parameters:: t0 - Series start time.
dt - Time interval between two successive samples.
NData - Number of data words.
dData - float array containing series data.

TSeries(const Time& t0, const Interval& dt, size_type NData, const double dData[])

A double float time series object is constructed and initialized from a double float data array.

Parameters:: t0 - Series start time.
dt - Time interval between two successive samples.
NData - Number of data words.
dData - double array containing series data.

TSeries(const Time& t0, const Interval& dt, size_type NData, const fComplex dData[])

A short time series object is constructed and initialized from a Complex data array.

Parameters:: t0 - Series start time.
dt - Time interval between two successive samples.
NData - Number of data words.
dData - Complex array containing series data.

TSeries(const Time& t0, const Interval& dt, size_type NData, const Chirp& func)

Construct a time series and initialize it from a specified signal template function.

Parameters:: t0 - Series start time.
dt - Time interval between two successive samples.
NData - Number of data words.
func - Template object based on a Chirp.

TSeries(const Time& t0, const Interval& dt, const DVector& data)

Construct a time series and initialize it from a specified data vector.

Parameters:: t0 - Series start time.
dt - Time interval between two successive samples.
data - Data vector.

TSeries(const Time& t0, const Interval& dt, DVector* data)

Construct a time series and initialize it from a specified data vector.

Parameters:: t0 - Series start time.
dt - Time interval between two successive samples.
data - Data vector.

explicit TSeries(const FSeries& fs)

Construct a time series from an FSeries by inverse fft.

Parameters:: fs - Frequency Series.

virtual ~TSeries()

Blow away the DVector.

TSeries& copy(const TSeries& in)

Convert and copy the argument TSeries to this TSeries using the existing DVector.

Returns:: reference to this time series.
Parameters:: in - Time series to be copied.

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

Write a formatted dump of the series contents to the specified output stream.

Returns:: reference to the specified output stream.
Parameters:: out - Output stream to receive the formatted TSeries dump.

TSeries decimate(size_type dec) const

A TSeries is decimated by the specified integer factor. The resulting series is returned. The first sample in the TSeries is included in the decimated TSeries.

Returns:: A decimated time series.
Parameters:: dec - Decimation factor.

void eraseStart(Interval dT)

Remove the data from the time interval \{t0, t0+dT\}. The time removed is rounded to the nearest integer number of samples.

Parameters:: dT - Time duration of the substring to be erased.

TSeries extract(const Time& t0, const Interval& dT=Interval(0.0)) const

A TSeries is returned containing the data from the time interval t0 - t0+dT. If dT == 0, all data after t0 will be returned.

Returns:: a TSeries containing the requested subset of the data.
Parameters:: t0 - Start time of the desired subset.
dT - Time duration of the desired subset.

void extend(const Time& t0)

The series is extended to the specified time by padding on the right with zeroes.

Parameters:: t0 - Desired series end-time.

size_type getBin(const Time& t) const

Get the bin index corresponding to the specified time. Note that the Time of the indexed sample is less than or equal to the specified time.

Returns:: Index of the bin with time t.

Time getBinT(size_type inx) const

Get the time corresponding to the specified bin number.

Returns:: Time corresponding to the specified bin.

fComplex getComplex(size_type index) const

The specified entry is converted to complex if necessary and returned.

Returns:: ith element value.
Parameters:: index - Index of the element to be returned.

size_type getData(size_type len, short* data) const

The TSeries data are copied to a short int data buffer pointed to by 'data'. The data will be converted to 'short int's if the data vector is of a different data type. A maximum of 'len' data words will be copied to the data buffer.

Returns:: The number of words copied.
Parameters:: len - Maximum number of words to copy.
data - Short integer array into which the data will be copied.

size_type getData(size_type len, int* data) const

The TSeries data are copied to an integer data buffer pointed to by 'data'. The data will be converted to floats if the data vector is of a different data type. A maximum of 'len' data words will be copied to the data buffer. getData() returns the number of words copied.

Returns:: Number of words copied.
Parameters:: len - Dimension of output array.
data - Array to receive series data.

size_type getData(size_type len, float* data) const

The TSeries data are copied to a float data buffer pointed to by 'data'. The data will be converted to floats if the data vector is of a different data type. A maximum of 'len' data words will be copied to the data buffer. getData() returns the number of words copied.

Returns:: Number of words copied.
Parameters:: len - Dimension of output array.
data - Array to receive series data.

size_type getData(size_type len, double* data) const

The TSeries data are copied to a double data buffer pointed to by 'data'. The data will be converted to floats if the data vector is of a different data type. A maximum of 'len' data words will be copied to the data buffer. getData() returns the number of words copied.

Returns:: Number of words copied.
Parameters:: len - Dimension of output array.
data - Array to receive series data.

size_type getData(size_type len, fComplex* data) const

The TSeries data are copied to a Complex buffer pointed to by 'data'. The data will be converted to fComplex if the data vector is of a different data type. A maximum of 'len' data words will be copied to the data buffer. getData() returns the number of words copied.

Returns:: Number of words copied.
Parameters:: len - Dimension of output array
data - Array to receive series data.

double getDouble(size_type index) const

The specified entry is converted to double precision if necessary and returned. If the series is complex, the real part of the indicated element is returned.

Returns:: ith element value.
Parameters:: index - Index of the element to be returned.

Time getEndTime(void) const

The GPS time of the last plus one is returned as a Time object.

Returns:: End time of the series.

double getF0(void) const

getF0 returns the heterodyne frequency used if the time series was frequency shifted.

Returns:: Frequency used to down-convert frequencies.

double getFNyquist(void) const

getFNyquist returns the positive Nyquist frequency of the TSeries.

Returns:: Maximum meaningful frequency.

Interval getInterval(void) const

Returns the total time duration of the time series.

Returns:: Time duration of the series.

const char* getName(void) const

Get a valid pointer to a zero-terminated string containing the series name. If the name is undefined a pointer to a null string is returned.

Returns:: a constant pointer to the series name string.

size_type getNSample(void) const

Returns the number of samples stored in the data vector.

Returns:: the number of samples.

Time getStartTime(void) const

Get the GPS time of the first sample represented as a Time object.

Returns:: Time of first sample.

Interval getTStep(void) const

The time bin width (the inverse of the sampling frequency) is returned as an Interval object.

Returns:: the sample time interval.

math_type getAverage(void) const

The average value of the data sequence is calculated. Zero is returned if the series is empty.

Returns:: Average data value.

fComplex getComplexAverage(void) const

The average value of the data sequence is calculated. Series elements are converted to compelx if necessary before being averaged. Zero is returned if the series is empty.

Returns:: Average data value.

math_type getMaximum(void) const

The maximum value of the data sequence is found. Zero is returned if the series is empty.

Returns:: Maximum data value.

math_type getMinimum(void) const

The minimum value in the sequence is found. Zero is returned if the series is empty.

Returns:: Minimum data value.

size_type getNBetween(math_type low, math_type high) const

Count the number of entries in the range low <= x < high.

Returns:: Number of entries greater than limit.
Parameters:: low - Lower limit.
high - Upper limit.

size_type getNGreater(math_type Limit) const

Count the number of entries greater than the specified value.

Returns:: Number of entries greater than limit.
Parameters:: low - Lower limit.

size_type getNLess(math_type Limit) const

Count the number of entries less than the specified value.

Returns:: Number of entries less than limit.

math_type getSigmaW(void) const

Get the effective bandwidth ratio imposed by any windowing.

Returns:: Window sigma.

stat_type getStatus(void) const

Get the status information word.

Returns:: Data status word.
Parameters:: high - Upper limit.

bool isComplex(void) const

Test if TSeries is empty.

Returns:: true if no data are available.

bool empty(void) const

Test if TSeries is empty.

Returns:: true if no data are available.

bool isGood(void) const

Test the data status. The data are considered good if the status word is zero.

Returns:: True if status indicates data are good.

const DVector* refDVect(void) const

Get a constant pointer to the data vector.

Returns:: a constant pointer to the data vector.

const void* refData(void) const

Get a constant reference to the data.

Returns:: a pointer to the data.

void* refData(void)

Get a reference to the data.

Returns:: a pointer to the data.

void appName(const char* name)

The specified character string is appended to the time series name string.

Parameters:: name - Constant pointer to a character array to be appended to the series name.

void combineStatus(stat_type stat)

Combine the data status word with the specified value.

Parameters:: stat - Status value.

int setData(const Time& t, const Interval& Step, const short* data, size_type N)

The supplied data are converted if necessary to the vector data type and copied to the series vector. If the vector is not defined, a vector of short integers will be created.

Returns:: 0 if successful.
Parameters:: t - New series start time.
Step - New series sample interval.
data - Short integer array containing new sample
N - Number of data words in 'data'

int setData(const Time& t, const Interval& Step, const int* data, size_type N)

The supplied data are converted if necessary to the vector data type and copied to the series vector. If the vector is not defined, a vector of floats will be created.

Returns:: 0 if successful.
Parameters:: t - New series start time.
Step - New series sample interval.
data - Float array containing new sample
N - Number of data words in 'data'

int setData(const Time& t, const Interval& Step, const float* data, size_type N)

The supplied data are converted if necessary to the vector data type and copied to the series vector. If the vector is not defined, a vector of floats will be created.

Returns:: 0 if successful.
Parameters:: t - New series start time.
Step - New series sample interval.
data - Float array containing new sample
N - Number of data words in 'data'

int setData(const Time& t, const Interval& Step, const double* data, size_type N)

The supplied data are converted if necessary to the vector data type and copied to the series vector. If the vector is not defined, a vector of floats will be created.

Returns:: 0 if successful.
Parameters:: t - New series start time.
Step - New series sample interval.
data - Float array containing new sample
N - Number of data words in 'data'

int setData(const Time& t, const Interval& Step, const fComplex* data, size_type N)

The supplied data are converted if necessary to the vector data type and copied to the series vector. If the vector is not defined, a vector of fComplex will be created.

Returns:: 0 if successful.
Parameters:: t - New series start time.
Step - New series sample interval.
data - fComplex array containing new sample
N - Number of data words in 'data'

void setF0(double f0)

Store the specified frequency in the TSeries central frequency field. The data sre left unmodified. The central frequency is defined as the true frequency of the bin that is apparently DC.

Parameters:: f0 - Frequency to which the TSeries heterodyne frequency will be set.

void setFNyquist(double fNy)

Define the Nyquist frequency of the TSeries. The nyquist frequency is set to 2/dT in the constructors and must be set as appropriate by any decimation filter.

Parameters:: fNy - Nyquist frequency of the TSeries.

void setName(const char* name)

The specified name is copied to the series name string.

Parameters:: constant - pointer to series name character array.

void setSigmaW(math_type sw)

Set the window effective bin width. This is the RMS of any windowing function used, i.e. sw = sqrt( Sum(i=0, N ; w(i)^2)/N) .

Parameters:: sw - Window RMS.

void setStatus(stat_type stat)

Set the data status word to the specified value.

Parameters:: stat - Status value.

int Append(const Time& t, const Interval& Step, const short* data, size_type N)

The specified data are converted if necessary to the series data type, and appended to the series. If data already exist in the vector, the end time of the existing data must match the start time of the new data. The step-size of the data to be appended must also match that of the existing data.

Returns:

0	successful
-1	start time isn't equal to the series end time
-2	sample intervals aren't equal

Parameters:

t - Start time of data to be appended to the series.
Step - sample interval of data to be appended to the series.
data - Short integer array containing the data to be appended.
N - Number of data words to be appended to the series.

int Append(const Time& TS, const Interval& Step, const int* data, size_type N)

Returns:

0	successful
-1	start time isn't equal to the current end time
-2	sample intervals aren't equal.

Parameters:

t - Start time of data to be appended to the series.
Step - sample interval of data to be appended to the series.
data - Float array containing the data to be appended.
N - Number of data words to be appended to the series.

int Append(const Time& TS, const Interval& Step, const float* data, size_type N)

Returns:

0	successful
-1	start time isn't equal to the current end time
-2	sample intervals aren't equal.

Parameters:

int Append(const Time& TS, const Interval& Step, const double* data, size_type N)

Returns:

0	successful
-1	start time isn't equal to the current end time
-2	sample intervals aren't equal.

Parameters:

int Append(const Time& TS, const Interval& Step, const fComplex* data, size_type N)

Returns:

0	successful
-1	start time isn't equal to the current end time
-2	sample intervals aren't equal.

Parameters:

t - Start time of data to be appended to the series.
Step - sample interval of data to be appended to the series.
data - Complex array containing the data to be appended.
N - Number of data words to be appended to the series.

int Append(const TSeries& t, size_type decim8=1)

The argument TSeries is optionally decimated and appended to the series. The starting time of the argument series must be equal to the end time of the existing data and the sample rate must be the same as the object sample rate. Decimation is not yet implemented.

Returns:

0	successful
-1	start time of TS not equal to the end time
-2	decimated sample rate isn't equal to the current rate.

Parameters:

TS - time series to be appended.
decim8 - decimation factor.

void Convert(int type)

The data vector is converted to the specified type. Valid types are those enumerated in DVector::DVType.

Parameters:: type - The type to which the series data are to be converted.

void ReSize(size_type len)

The data vector is extended to hold the specified number of data words. No action is taken if the vector can already hold the specified number of data words. The current data are copied if vector is reallocated.

Parameters:: len - Desired vector capacity in words.

void Clear(const Time& t0=Time(0), const Interval& dt=Interval(0.0))

The current data vector length is set to zero. The data vector remains allocated with the original storage capacity. The start time and sample interval may be reset or are placed in a "don't care" state. The series name is left unchanged.

Parameters:: t0 - New start time. By default the time is zeroed.
dt - New sample interval. By default the interval is zeroed.

TSeries fShift(math_type f0, math_type phi0=0) const

fShift up-converts (heterodynes) the time series by the specified frequency shift. The resulting data vector will be of fComplex type. The sign of the frequency shift is such that the DC bin is converted to the shift frequency. The TSeries f0 value is decreasedby an equal amount.

Returns:: A complex TSeries with the heterodyned data.
Parameters:: f0 - heterodyne frequency.
phi0 - Phase shift of the first sample (defaults to 0).

TSeries& operator=(const TSeries& ts)

The TSeries data are copied to the current TSeries. The current TSeries type and name remain unchanged.

Returns:: reference to the updated TSeries.
Parameters:: TS - Constant TSeries to be copied.

math_type operator*(const TSeries& y) const

Take a dot product of the two data vectors.

Returns:: Correlation coefficient ().

TSeries operator/(const TSeries& y) const

Divide two series on an element-by-element basis.

Returns:: Float seies containing the ratio of the arguments.
Parameters:: Divisor - series.

TSeries& operator+=(math_type bias)

The argument value is converted to the TSeries data type and added to each element of the time series.

Returns:: reference to the modified TSeries.
Parameters:: bias - Value added to each element.

TSeries& operator-=(math_type bias)

The argument value is converted to the TSeries data type and subtracted from each element of the time series.

Returns:: reference to the modified TSeries.
Parameters:: bias - Value subtracted from each element.

TSeries& operator*=(math_type scale)

Each element of the time series is multiplied by the rhs value. The result is converted to the series data type and replaces the original series.

Returns:: reference to the modified TSeries.
Parameters:: scale - Value used to multiply each element.

TSeries& operator/=(math_type scale)

Each element of the time series is divided by the rhs value. The result is converted to the series data type and replaces the original series.

Returns:: reference to the modified TSeries.
Parameters:: scale - Value used to divide each element.

TSeries& operator+=(const TSeries& rhs)

Each element of the time series is incremented by the corresponding element of the argument. The rhs argument must have the same sampling rate and contain a subset of the times in the series being added to. If the sample rates differ or the rhs time bins don't correspond exactly to existing time bins, a std::runtime_error exception is \ thrown.

Returns:: reference to the modified TSeries.
Parameters:: rhs - TSeries to be added to the current TSeries.

TSeries& operator-=(const TSeries& rhs)

Each element of the time series is decremented by the corresponding elements of the argument. The rhs argument must have the same sampling rate and contain a subset of the times in the series being added to. If the sample rates differ or the rhs time bins don't correspond exactly to existing time bins, a std::runtime_error exception is thrown.

Returns:: reference to the difference TSeries.
Parameters:: rhs - TSeries to be subtracted from the current TSeries.

DVector* refDVect(void)

Get a reference to the data vector.

Returns:: a pointer to the data vector.

int Contig(const Time& t, const Interval& Step)

Test for consistency with end of series

size_type overlap(const TSeries& ts, size_type& inx, size_type& inx1) const

Overlap finds the ranges of two time series that overlap in time

Direct child classes:: FixedLenTS

Author:: John G. Zweizig
Version:: 1.4; Last modified Aug 9, 2006

alphabetic index hierarchy of classes

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

generated by doc++

	TSeries () Default constructor.
	TSeries (const TSeries& TS) Copy Constructor.
	TSeries (const Time& t0, const Interval& dt) Dataless constructor.
	TSeries (const Time& t0, const Interval& dt, size_type NData, const float dData[]=0) Float data constructor.
	TSeries (const Time& t0, const Interval& dt, size_type NData, const short dData[]) Short integer data constructor.
	TSeries (const Time& t0, const Interval& dt, size_type NData, const int dData[]) Integer data constructor.
	TSeries (const Time& t0, const Interval& dt, size_type NData, const double dData[]) Double float data constructor.
	TSeries (const Time& t0, const Interval& dt, size_type NData, const fComplex dData[]) Complex data constructor.
	TSeries (const Time& t0, const Interval& dt, size_type NData, const Chirp& func) Signal template function constructor.
	TSeries (const Time& t0, const Interval& dt, const DVector& data) Signal template function constructor.
	TSeries (const Time& t0, const Interval& dt, DVector* data) Signal template function constructor.
explicit	TSeries (const FSeries& fs) FSeries constructor.
virtual	~TSeries () TSeries Destructor.
TSeries&	copy (const TSeries& in) Copy TSeries data.
std::ostream&	Dump (std::ostream& out) const Formatted dump of the TSeries data.
TSeries	decimate (size_type dec) const Decimate a Time Series.
void	eraseStart (Interval dT) Erase data from the start of a TSeries.
TSeries	extract (const Time& t0, const Interval& dT=Interval(0.0)) const Extract a subset of the data from a TSeries.
void	extend (const Time& t0) Extend a TSeries.
size_type	getBin (const Time& t) const Get bin index.
Time	getBinT (size_type inx) const Get bin time.
fComplex	getComplex (size_type index) const Get ith element as a complex number.
size_type	getData (size_type len, short* data) const Copy data to a short int output array.
size_type	getData (size_type len, int* data) const Copy data to an integer array
size_type	getData (size_type len, float* data) const Copy data to a float array
size_type	getData (size_type len, double* data) const Copy data to a double array
size_type	getData (size_type len, fComplex* data) const Copy data to a complex array.
double	getDouble (size_type index) const Get ith element as a double precision number.
Time	getEndTime (void) const Get the end Time of the series.
double	getF0 (void) const Get heterodyne frequency.
double	getFNyquist (void) const Get the Nyquist frequency.
Interval	getInterval (void) const Get series duration.
const char*	getName (void) const Get the series name.
size_type	getNSample (void) const Get the number of samples
Time	getStartTime (void) const Get the start time.
Interval	getTStep (void) const Get the sample time.
math_type	getAverage (void) const Average value of data.
fComplex	getComplexAverage (void) const Average value of data.
math_type	getMaximum (void) const Maximum data value.
math_type	getMinimum (void) const Minumim data value.
size_type	getNBetween (math_type low, math_type high) const Number of entries betwee two limits.
size_type	getNGreater (math_type Limit) const Entries greater than limit.
size_type	getNLess (math_type Limit) const Entries less than Limit.
math_type	getSigmaW (void) const Window sigma.
stat_type	getStatus (void) const Data status.
bool	isComplex (void) const Test for data.
bool	empty (void) const Test for data.
bool	isGood (void) const Test data status.
const DVector*	refDVect (void) const Get a reference to the data vector.
const void*	refData (void) const Get a constant reference to the data.
void*	refData (void) Get a reference to the data.
void	appName (const char* name) Append a string to the series name.
void	combineStatus (stat_type stat) Set the data status.
int	setData (const Time& t, const Interval& Step, const short* data, size_type N) Set the series data.
int	setData (const Time& t, const Interval& Step, const int* data, size_type N) Set the series data.
int	setData (const Time& t, const Interval& Step, const float* data, size_type N) Set the series data.
int	setData (const Time& t, const Interval& Step, const double* data, size_type N) Set the series data.
int	setData (const Time& t, const Interval& Step, const fComplex* data, size_type N) Set the series data.
void	setF0 (double f0) Set the heterodyne frequency.
void	setFNyquist (double fNy) Set the Nyquist frequency.
void	setName (const char* name) Name a series.
void	setSigmaW (math_type sw) Set the window sigma.
void	setStatus (stat_type stat) Set the data status.
int	Append (const Time& t, const Interval& Step, const short* data, size_type N) Append data to the time series.
int	Append (const Time& TS, const Interval& Step, const int* data, size_type N) Append data to the time series.
int	Append (const Time& TS, const Interval& Step, const float* data, size_type N) Append data to the time series.
int	Append (const Time& TS, const Interval& Step, const double* data, size_type N) Append data to the time series.
int	Append (const Time& TS, const Interval& Step, const fComplex* data, size_type N) Append data to the time series.
int	Append (const TSeries& t, size_type decim8=1) Concatenate two TSeries.
void	Convert (int type) Convert the data vector type.
void	ReSize (size_type len) Expand the data vector.
void	Clear (const Time& t0=Time(0), const Interval& dt=Interval(0.0)) Delete the series data.
TSeries	fShift (math_type f0, math_type phi0=0) const Up-convert (heterodyne) a time series.
TSeries&	operator= (const TSeries& ts) Assignment operator.
math_type	operator* (const TSeries& y) const Correlate two series.
TSeries	operator/ (const TSeries& y) const Divide series by another.
TSeries&	operator+= (math_type bias) Bias a TSeries.
TSeries&	operator-= (math_type bias) Bias a TSeries.
TSeries&	*operator=** (math_type scale) Scale a TSeries.
TSeries&	operator/= (math_type scale) Scale a TSeries.
TSeries&	operator+= (const TSeries& rhs) Add a TSeries.
TSeries&	operator-= (const TSeries& rhs) Subtract a TSeries.
DVector*	refDVect (void) Get a reference to the data vector.
int	Contig (const Time& t, const Interval& Step) Test for consistency with end of series
size_type	overlap (const TSeries& ts, size_type& inx, size_type& inx1) const Overlap finds the ranges of two time series that overlap in time

typedef unsigned long	size_type Length type;
typedef unsigned long	stat_type Status type;
typedef double	math_type Math type;

class TSeries

Inheritance:

Public Fields

Public Methods

Documentation