mspass::seismic::BasicTimeSeries Class Reference

Base class for time series objects. More...

#include <BasicTimeSeries.h>

Inheritance diagram for mspass::seismic::BasicTimeSeries:

Public Member Functions
	BasicTimeSeries ()
	BasicTimeSeries (const BasicTimeSeries &)
virtual	~BasicTimeSeries ()
	Virtual destructor. More...
double	time (const int i) const
int	sample_number (double t) const
double	endtime () const noexcept
bool	shifted () const
double	time_reference () const
void	force_t0_shift (const double t)
	Force a t0 shift value on data. More...
virtual void	ator (const double tshift)
virtual void	rtoa ()
virtual void	shift (const double dt)
bool	live () const
bool	dead () const
void	kill ()
void	set_live ()
double	dt () const
bool	time_is_UTC () const
bool	time_is_relative () const
TimeReferenceType	timetype () const
double	samprate () const
size_t	npts () const
double	t0 () const
virtual void	set_dt (const double sample_interval)
	Set the sample interval. More...
virtual void	set_npts (const size_t npts)
	Set the number of samples attribute for data. More...
virtual void	set_t0 (const double t0in)
	Set the data start time. More...
void	set_tref (const TimeReferenceType newtref)
	Force the time standard. More...
BasicTimeSeries &	operator= (const BasicTimeSeries &parent)

Protected Attributes
bool	mlive
double	mdt
double	mt0
size_t	nsamp
TimeReferenceType	tref
bool	t0shift_is_valid
double	t0shift

Detailed Description

Base class for time series objects.

This is a mostly abstract class defining data and methods shared by all data objects that are time series. In MsPASS time series means data sampled on a 1d, uniform grid defined by a sample rate, start time, and number of samples. Derived types can be scalar, vector, complex, or any data that is uniformly sampled.

The seispp version of this class had public attributes for key data are essential for defining any time series data (e.g. sample interval). This was revised in MsPASS to use getters and putters to provide a cleaner interface to python with pybind11.

Author

Gary L. Pavlis

Constructor & Destructor Documentation

BasicTimeSeries() [1/2]

mspass::seismic::BasicTimeSeries::BasicTimeSeries

(

)

Default constructor. Does essentially nothing since a BasicTimeSeries object has no data. Does initialize data to avoid run time checkers bitching about unitialized data, but values are meaningless when this constructor is called.

{
    mt0=0.0;
    tref=TimeReferenceType::Relative;
    mlive=false;
    mdt=1.0;
    nsamp=0;
    t0shift=0.0;
    t0shift_is_valid=false;
}

References mspass::seismic::Relative.

BasicTimeSeries() [2/2]

mspass::seismic::BasicTimeSeries::BasicTimeSeries

(

const BasicTimeSeries &

tsin

)

Standard copy constructor.

{
    mt0=tsin.mt0;
    tref=tsin.tref;
    mlive=tsin.mlive;
    mdt=tsin.mdt;
    nsamp=tsin.nsamp;
    t0shift=tsin.t0shift;
    t0shift_is_valid=tsin.t0shift_is_valid;
}

References mdt, mlive, mt0, nsamp, and tref.

~BasicTimeSeries()

virtual mspass::seismic::BasicTimeSeries::~BasicTimeSeries ( )

inlinevirtual

Virtual destructor.

A base class with virtual members like this requires this incantation to avoid some odd conflicts. This particular one was added to make the boost::serialization code work properly. The geeky details for why this is necessary can be found in Scott Meyers book "Effective C++"

{};

Member Function Documentation

ator()

void mspass::seismic::BasicTimeSeries::ator ( const double  tshift )

virtual

Absolute to relative time conversion. Sometimes we want to convert data from absolute time (epoch times) to a relative time standard. Examples are conversions to travel time using an event origin time or shifting to an arrival time reference frame. This operation simply switches the tref variable and alters t0 by tshift.

Parameters

tshift

- time shift applied to data before switching data to relative time mode.

Reimplemented in mspass::seismic::TimeSeriesWGaps.

{
    /* dead traces should to totally ignored */
    if(!(this->mlive)) return;
    if(tref==TimeReferenceType::Relative) return;
    t0shift=tshift;
    mt0 -= tshift;
    tref=TimeReferenceType::Relative;
    t0shift_is_valid=true;
}

References mspass::seismic::Relative.

dead()

bool mspass::seismic::BasicTimeSeries::dead ( ) const

inline

Return true if the data have been marked bad (killed) - inverse of live()

{return !(this->mlive);};

References mlive.

dt()

double mspass::seismic::BasicTimeSeries::dt ( ) const

inline

Return the data sample interval.

{return this->mdt;};

References mdt.

endtime()

double mspass::seismic::BasicTimeSeries::endtime ( ) const

inlinenoexcept

Returns the end time (time associated with last data sample) of this data object.

        {
          return(mt0 + (static_cast<double>(nsamp) - 1.0)*mdt);
        };

References mdt, mt0, and nsamp.

force_t0_shift()

void mspass::seismic::BasicTimeSeries::force_t0_shift ( const double  t )

inline

Force a t0 shift value on data.

This is largely an interface routine for constructors that need to handle data in relative time that are derived from an absolute base. It can also be used to fake processing routines that demand data be in absolute time when the original data were not. It was added for MsPASS to support reads and writes to MongoDB where we want to be able to read and write data that had been previously time shifted (e.g. ArrivalTimeReference).

Parameters

t	is the time shift to force

    {
        this->t0shift=t;
        t0shift_is_valid=true;
    };

kill()

void mspass::seismic::BasicTimeSeries::kill ( )

inline

Mark these data bad.

{this->mlive=false;};

References mlive.

live()

bool mspass::seismic::BasicTimeSeries::live ( ) const

inline

Returns true of data are marked valid (live).

{return this->mlive;};

References mlive.

npts()

size_t mspass::seismic::BasicTimeSeries::npts ( ) const

inline

Return the number of points in the data series.

{return nsamp;};

References nsamp.

operator=()

BasicTimeSeries & mspass::seismic::BasicTimeSeries::operator=

(

const BasicTimeSeries &

parent

)

Standard assignment operator.

{
    if (this!=&parent)
    {
        mt0=parent.mt0;
        tref=parent.tref;
        mlive=parent.mlive;
        mdt=parent.mdt;
        nsamp=parent.nsamp;
        t0shift=parent.t0shift;
        t0shift_is_valid=parent.t0shift_is_valid;
    }
    return *this;
}

References mdt, mlive, mt0, nsamp, and tref.

rtoa()

void mspass::seismic::BasicTimeSeries::rtoa ( )

virtual

Relative to absolute time conversion. Sometimes we want to convert data from relative time to to an UTC time standard. An example would be converting segy shot data to something that could be processed like earthquake data in a css3.0 database.

This method returns data previously converted to relative back to UTC using the internally stored time shift attribute.

Reimplemented in mspass::seismic::TimeSeriesWGaps.

{
    /* dead traces should to totally ignored */
    if(!(this->mlive)) return;
    const string base_error("BasicTimeSeries::rtoa() t0shift for conversion is not defined.");
    if(tref==TimeReferenceType::UTC) return;
    /* A rather odd test for a nonzero.   We use 100 s assuming no active
     * source data would use a shift longer than that unless it really did
     * have an UTC time standard. Also assumes we'll never use data from
     * the first 2 minutes of 1960.*/
    if(t0shift_is_valid || (t0shift>100.0) )
    {
        mt0 += t0shift;
        tref=TimeReferenceType::UTC;
        t0shift_is_valid=false;
    t0shift=0.0;
    }
    else
        throw MsPASSError(base_error + "time shift to return to UTC time is not defined",ErrorSeverity::Invalid);
}

References mspass::seismic::UTC.

sample_number()

int mspass::seismic::BasicTimeSeries::sample_number ( double  t ) const

inline

Inverse of time function. That is, it returns the integer position of a given time t within a time series. The returned number is not tested for validity compared to the data range. This is the callers responsibility as this is a common error condition that should not require the overhead of an exception.

        {
            return(round((t-mt0)/mdt));
        };

References mdt, and mt0.

samprate()

double mspass::seismic::BasicTimeSeries::samprate ( ) const

inline

Return sample rate.

    {
        return 1.0/mdt;
    }

References mdt.

set_dt()

virtual void mspass::seismic::BasicTimeSeries::set_dt ( const double  sample_interval )

inlinevirtual

Set the sample interval.

This is a simple setter for the sample interval attribute. It is virtual because children may want to do more than just set the attribute in this base class. In MsPASS that means keeping the Metadata attributes that define sample interval in sync with the data. Aliases further complicate that issue so it is not trivial. Other data objects that could be derived form this base could have similar issues.

Parameters

sample_interval

is the new data sample interval to be used.

Reimplemented in mspass::seismic::CoreTimeSeries, and mspass::seismic::CoreSeismogram.

    {
        mdt=sample_interval;
    };

References mdt.

set_live()

void mspass::seismic::BasicTimeSeries::set_live ( )

inline

Inverse of kill - marks data live overriding anything set before. Use to resurrect data improperly killed (useful only for interactive editing) or creating data pieces outside constructors.

{this->mlive=true;};

References mlive.

set_npts()

virtual void mspass::seismic::BasicTimeSeries::set_npts ( const size_t  npts )

inlinevirtual

Set the number of samples attribute for data.

This is a simple setter for the number of samples attribute. It is virtual because children may want to do more than just set the attribute in this base class. In MsPASS that means keeping the Metadata attributes that define the number of points in sync with the data. Aliases further complicate that issue so it is not trivial. Other data objects that could be derived form this base could have similar issues.

Parameters

npts	is the new number of points to set.

Reimplemented in mspass::seismic::CoreTimeSeries, and mspass::seismic::CoreSeismogram.

    {
        nsamp=npts;
    };

References npts(), and nsamp.

set_t0()

virtual void mspass::seismic::BasicTimeSeries::set_t0 ( const double  t0in )

inlinevirtual

Set the data start time.

This is a simple setter for the start time attribute. It is virtual because children may want to do more than just set the attribute in this base class. In MsPASS that means keeping the Metadata attributes that define t0 in sync with the data. Aliases further complicate that issue so it is not trivial. Other data objects that could be derived form this base could have similar issues.

Parameters

t0in	is the new data sample interval to be used.

Reimplemented in mspass::seismic::CoreTimeSeries, and mspass::seismic::CoreSeismogram.

    {
        mt0=t0in;
    };

References mt0.

set_tref()

void mspass::seismic::BasicTimeSeries::set_tref ( const TimeReferenceType  newtref )

inline

Force the time standard.

Time series data may have multiple concepts of what the time standard is. In MsPASS the allowed values currently are UTC and relative defined by the TimeReferenceType enum class. Other implementations might need to use some other standard (e.g. raw gps time is not utc). This method allows forcing a standard. It is not recommended for normal use, but only as a brutal solution for assembling a data object outside normal constructors.

Parameters

newtref

is the new time standard to set for these data.

    {
        tref=newtref;
    };

References tref.

shift()

void mspass::seismic::BasicTimeSeries::shift ( const double  dt )

virtual

Shift the reference time.

Sometimes we need to shift the reference time t0. An example is a moveout correction. This method shifts the reference time by dt. Note a positive dt means data aligned to zero will be shifted left because relative time is t-t0.

Reimplemented in mspass::seismic::TimeSeriesWGaps.

{
    try {
        double oldt0shift=t0shift;
        this->rtoa();
        this->ator(oldt0shift+dt);
    } catch(...) {
        throw;
    };
}

shifted()

bool mspass::seismic::BasicTimeSeries::shifted ( ) const

inline

Return true if a time shift has been applied to the data. Never true if data were never in an absolute time frame (i.e.UTC)

    {
        return t0shift_is_valid;
    };

t0()

double mspass::seismic::BasicTimeSeries::t0 ( ) const

inline

Return time of first data sample. An epoch time or relative time depending on TimeReferenceType private variable tref

{return this->mt0;};

References mt0.

time()

double mspass::seismic::BasicTimeSeries::time ( const int  i ) const

inline

Get the time of sample i. It is common to need to ask for the time of a given sample. This standardizes this common operation in an obvious way.

Parameters

i	- sample number to compute time for.

        {
            return(mt0+mdt*static_cast<double>(i));
        };

References mdt, and mt0.

time_is_UTC()

bool mspass::seismic::BasicTimeSeries::time_is_UTC ( ) const

inline

Test if the time standard is UTC.

    {
        if(tref==TimeReferenceType::UTC)
          return true;
        else
          return false;
    };

References tref, and mspass::seismic::UTC.

time_reference()

double mspass::seismic::BasicTimeSeries::time_reference

(

)

const

Return the reference time.

We distinguish relative and UTC time by a time shift constant stored with the object. This returns the time shift to return data to an epoch time.

Exceptions

SeisppError

object if the request is not rational. That is this request only makes sense if the data began with an absolute time and was converted with the ator method. Some cross checks are made for consistency that can throw an error in this condition.

{
    const string base_error("BasicTimeSeries::time_reference method: ");
    if(tref==TimeReferenceType::UTC)
        throw MsPASSError(base_error
                          + "data have UTC time set so requesting the reference"
                          + " time make no sense - likely a coding error",
                          ErrorSeverity::Fatal);
    if(t0shift_is_valid)
        return(t0shift);
    else
        throw MsPASSError(base_error
                          + "cannot return time reference as it is marked invalid",
                          ErrorSeverity::Invalid);
}

References mspass::seismic::UTC.

Member Data Documentation

mdt

double mspass::seismic::BasicTimeSeries::mdt

protected

Sample interval.

mlive

bool mspass::seismic::BasicTimeSeries::mlive

protected

Boolean defining if a data object has valid data or is to be ignored. Data processing often requires data to be marked bad but keep the original data around in case an error was made. This boolean allows this capability.

mt0

double mspass::seismic::BasicTimeSeries::mt0

protected

Data start time. That is the time of the first sample of data.

nsamp

size_t mspass::seismic::BasicTimeSeries::nsamp

protected

Number of data samples in this data object.

tref

TimeReferenceType mspass::seismic::BasicTimeSeries::tref

protected

Time reference standard for this data object. Defined by enum Time_Reference this currently is only one of two things. When set as "UTC" the time standard is an epoch time. When set as "relative" time has no relationship to any external standard but are relative to some arbitrary reference that must ascertained by the algorithm by some other means (in seispp this is normally done through a metadata object). A classic example is multichannel data where channels have a time relative to a shot time.

---

The documentation for this class was generated from the following files:

• /home/runner/work/mspass/mspass/cxx/include/mspass/seismic/BasicTimeSeries.h
• /home/runner/work/mspass/mspass/cxx/src/lib/seismic/BasicTimeSeries.cc