Basic_Time_Series.3

NAME

BasicTimeSeries - base class for various types of time series data

SYNOPSIS

#include "BasicTimeSeries.h"
using namespace SEISPP;
class BasicTimeSeries
{
public:
        bool live;
        double dt,t0;
        int ns;
        TimeReferenceType tref;
        bool is_gap(int);
        bool is_gap(double);
	bool is_gap(Timw_Window);
        void add_gap(TimeWindow tw);
        virtual void zero_gaps()=0;
	double time(int i);
	double endtime();
        int sample_number(double t);
	void ator(double tshift);
	void rtoa(double tshift);
};

SUPPORT

Contributed code: NO BRTT support.
THIS PIECE OF SOFTWARE WAS CONTRIBUTED BY THE ANTELOPE USER COMMUNITY. BRTT DISCLAIMS ALL OWNERSHIP, LIABILITY, AND SUPPORT FOR THIS PIECE OF SOFTWARE.

FOR HELP WITH THIS PIECE OF SOFTWARE, PLEASE CONTACT THE CONTRIBUTING AUTHOR.

DESCRIPTION

A number of types of data can be called a time series. The common concept to all time series objects is that a time series is a special way to represent a function of one independent variable. The "special" part is that the function being represented numerically by a time series object is being approximated by the values of the function defined on a regular, one-dimensional mesh of the independent variable. A regular mesh in one dimension is completely described by only two parameters: (1) the value of the independent variable (time) at the first sample of the actual data (the t0 variable in the BasicTimeSeries object definition), and (2) the sample interval (the dt variable in the BasicTimeSeries definition). I use the t label on both of these parameters since the independent variable is commonly viewed as a time variable. The user should recognize, however, that the concept is broader than data sampled by time alone and the most general definition is any physical quantity sampled at regular intervals.

The BasicTimeSeries is a base concept from which specific types of actual time series data can be viewed as a derived class. The reason this is useful is that the data for a particular time series type can thought of as a generalized vector of sample values. Inheritance provides a natural way to encapsulate and isolate this base concept from variations for special data types. Two derived classes from BasicTimeSeries can be found in the seispp library that illustrate this idea: (1) the TimeSeries object (man 3) defines a scalar valued time series, and (2) the ThreeComponentSeismogram (man 3) object defines a special seismology time series for three-components of ground motion. Note that others similar data objects that could be derived from a BasicTimeSeries are complex valued time series (see example below) or an n-vector time series.

This base class adds a few special parameters and functions that I viewed as a fundamental concept for all time series data that are either essential or useful depending on the context. The live variable is used for simple logical tests to mark data as valid or dead. As the name suggests a constructor should set this variable true if construction of valid data is successful. Conversely an application can mark a serious data problem by setting this field false to mark the contents as all bad. The tref variable is a switch (enum) that can take on only one of two values: "absolute" or "relative". To be more precise, here is the definition:


enum TimeReferenceType {absolute,relative};

This allows absolute time reference frames (commonly called epoch times in seismology) or relative time sampling in which the user should assume the application has it's own internal concept of a time reference.

The functions is_gap, add_gap, and zero_gaps are used to handle data gaps. is_gap checks for gaps at a specified sample number (the int version) or by time (the overloaded double version) returning true if the sample/time is a gap. The zero_gaps function sets the data for all times marked as a gap to zero. It is a pure virtual function as the definition zero depends upon the actual data in the vector of samples that define the actual time series to be represented. Since BasicTimeSeries is a base class this concept is rational, but the basic idea may seem strange to a newcomer.

Note that the interface hides the details of the gap implementation. The user should assume that areas marked as gaps can be zeroed without loss of information and that the problem of marking output data as a gap is to be solved differently. That is, defining gaps in an external representation of the data is a different problem (see trgaps(3) for a discourse on this subject and a general solution). Derived classes must be conscious of this problem in building constructors and in producing output functions that preserve gap information.

MEMBER FUNCTIONS

There are two inline functions called time and sample_number. The time function returns the time (independent variable) associated with sample number i and sample_time does the inverse (i.e. returns sample index associated with a given time.).

The functions ator and rtoa convert between absolute and relative time scales using the constant time shift tshift. ator converts from an absolute to relative time scale subtracting the constant tshift to define the new time scale. rtoa does the opposite changing from a relative to absolute scale. Since absolute times are conventionally always positive, tshift is added to produce the revised time scale. Both functions alter the tref variable. Both also take the attitude that if tref is already set to the requested conversion they do nothing. e.g. if tref is set as "relative" a call to ator will return immediately and do nothing.

EXAMPLE

A BasicTimeSeries is mostly a virtual base class, with a few core member functions. Here is an example of a bare bones implementation of a complex time series object:

class Complex_TimeSeries : public BasicTimeSeries
{
public:
	// complex data samples stored in an STL vector object
	vector<complex> y;
	// a few basic constructors
	Complex_TimeSeries(){y.reserve(0);};
	Complex_TimeSeries(int nsamp){y.reserve(nsamp)};
};

Note that by inheritance the dt, t0, etc. of the BasicTimeSeries become members of the derived Complex_TimeSeries object.

EXCEPTIONS

None of the member functions of a BasicTimeSeries will throw an exception. One can assume any useful derived class will potentially throw a number of possible exceptions.

LIBRARY

-lseispp

BUGS AND CAVEATS

The BasicTimeSeries object is not very useful by itself and exists primarily as a base class from which useful data objects can be derived. Those not familiar with inheritance in object oriented programming might consult books on the subject before questioning the wisdom of this definition.

AUTHOR

Gary L. Pavlis
Indiana University
pavlis@indiana.edu

Antelope User Group Contributed Software