### From BRTT

## Contents |

### 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: NO BRTT support -- please contact 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

### SEE ALSO

TimeSeries(3), ThreeComponentSeismogram(3), http://geology.indiana.edu/pavlis/software/seispp/html/index.html

### 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