mspass::seismic::CoreTimeSeries Class Reference

Scalar time series data object. More...

#include <CoreTimeSeries.h>

Inheritance diagram for mspass::seismic::CoreTimeSeries:

Public Member Functions
	CoreTimeSeries ()
	CoreTimeSeries (const size_t nsin)
	CoreTimeSeries (const BasicTimeSeries &bts, const Metadata &md)
	CoreTimeSeries (const CoreTimeSeries &)
void	set_dt (const double sample_interval)
	Set the sample interval. More...
void	set_npts (const size_t npts)
	Set the number of samples attribute for data. More...
void	sync_npts ()
	Sync the number of samples attribute with actual data size. More...
void	set_t0 (const double t0in)
	Set the data start time. More...
CoreTimeSeries &	operator= (const CoreTimeSeries &parent)
CoreTimeSeries &	operator+= (const CoreTimeSeries &d)
	Summation operator. More...
const CoreTimeSeries	operator+ (const CoreTimeSeries &other) const
CoreTimeSeries &	operator*= (const double)
CoreTimeSeries &	operator-= (const CoreTimeSeries &d)
	Subtraction operator. More...
const CoreTimeSeries	operator- (const CoreTimeSeries &other) const
double	operator[] (size_t const sample) const
Public Member Functions inherited from mspass::seismic::BasicTimeSeries
	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
void	set_tref (const TimeReferenceType newtref)
	Force the time standard. More...
BasicTimeSeries &	operator= (const BasicTimeSeries &parent)
Public Member Functions inherited from mspass::utility::Metadata
	Metadata ()
	Metadata (std::ifstream &ifs, const std::string form=std::string("pf"))
	Metadata (const Metadata &mdold)
virtual	~Metadata ()
Metadata &	operator= (const Metadata &mdold)
Metadata &	operator+= (const Metadata &rhs) noexcept
const Metadata	operator+ (const Metadata &other) const
double	get_double (const std::string key) const override
int	get_int (const std::string key) const override
long	get_long (const std::string key) const
std::string	get_string (const std::string key) const override
bool	get_bool (const std::string key) const override
template<typename T >
T	get (const std::string key) const
template<typename T >
T	get (const char *key) const
	Generic get interface for C char array. More...
boost::any	get_any (const std::string key) const
std::string	type (const std::string key) const
template<typename T >
void	put (const std::string key, T val) noexcept
template<typename T >
void	put (const char *key, T val) noexcept
void	put (const std::string key, const double val) override
void	put (const std::string key, const int val) override
void	put (const std::string key, const bool val) override
void	put (const std::string key, const std::string val) override
void	put (const char *key, const char *val)
void	put (std::string key, const char *val)
void	put_object (const std::string key, const pybind11::object val)
void	put_int (const std::string key, const int val)
void	put_string (const std::string key, const std::string val)
void	put_bool (const std::string key, const bool val)
void	put_double (const std::string key, const double val)
void	put_long (const std::string key, const long val)
void	append_chain (const std::string key, const std::string val, const std::string separator=std::string(":"))
std::set< std::string >	modified () const
void	clear_modified ()
	Mark all data as unmodified. More...
std::set< std::string >	keys () const noexcept
bool	is_defined (const std::string key) const noexcept
void	erase (const std::string key)
std::size_t	size () const noexcept
std::map< std::string, boost::any >::const_iterator	begin () const noexcept
std::map< std::string, boost::any >::const_iterator	end () const noexcept
void	change_key (const std::string oldkey, const std::string newkey)
	Change the keyword to access an attribute. More...

Public Attributes
std::vector< double >	s

Additional Inherited Members
Protected Attributes inherited from mspass::seismic::BasicTimeSeries
bool	mlive
double	mdt
double	mt0
size_t	nsamp
TimeReferenceType	tref
bool	t0shift_is_valid
double	t0shift
Protected Attributes inherited from mspass::utility::Metadata
std::map< std::string, boost::any >	md
std::set< std::string >	changed_or_set

Detailed Description

Scalar time series data object.

This data object extends BasicTimeSeries mainly by adding a vector of scalar data. It uses a Metadata object to contain auxiliary parameters that aren't essential to define the data object, but which are necessary for some algorithms.

Author

Gary L. Pavlis

Constructor & Destructor Documentation

CoreTimeSeries() [1/4]

mspass::seismic::CoreTimeSeries::CoreTimeSeries

(

)

Default constructor. Initializes object data to zeros and sets the initial STL vector size to 0 length.

                               : BasicTimeSeries(), Metadata()
{
    s.reserve(0);
    this->set_dt(1.0);
    this->set_t0(0.0);
    this->set_npts(0);
}

References s, set_dt(), set_npts(), and set_t0().

CoreTimeSeries() [2/4]

mspass::seismic::CoreTimeSeries::CoreTimeSeries

(

const size_t

nsin

)

Similar to the default constructor but creates a vector of data with nsin samples and initializes all samples to 0.0. This vector can safely be accessed with the vector index operator (i.e. operator []). A corollary is that push_back or push_front applied to this vector will alter it's length so use this only if the size of the data to fill the object is already known.

                                                : BasicTimeSeries(), Metadata()
{
  /* IMPORTANT:  this constructor assumes BasicTimeSeries initializes the
  equivalent of:
  set_dt(1.0)
  set_t0(0.0)
  set_tref(TimeReferenceType::Relative)
  this->kill() - i.e. marked dead
 
  It further assumes current api where set_npts allocates and initializes s
  to nsin zeros */
  this->CoreTimeSeries::set_npts(nsin);
}

References set_npts().

CoreTimeSeries() [3/4]

mspass::seismic::CoreTimeSeries::CoreTimeSeries	(	const BasicTimeSeries &	bts,
		const Metadata &	md
	)

Partially construct from components.

There are times one wants to use the Metadata area as a template to flesh out a CoreTimeSeries as what might be called skin and bones: skin is Metadata and bones as BasicTimeSeries data. This constructor initializes those two base classes but does not fully a valid data vector. It only attempts to fetch the number of points expected for the data vector using the npts metadata (integer) key (i.e. it sets npts to md.get_int("npts")). It then creates the data vector of that length and initialzies it to all zeros.

    : BasicTimeSeries(bd), Metadata(md)
{
  /* this assumes set_npts initializes the vector containers, s, to zeros
  AND that BasicTimeSeries constructor initializes ns (npts) to the value
  desired. */
  this->CoreTimeSeries::set_npts(this->nsamp);
}

References mspass::seismic::BasicTimeSeries::nsamp, and set_npts().

CoreTimeSeries() [4/4]

mspass::seismic::CoreTimeSeries::CoreTimeSeries

(

const CoreTimeSeries &

tsi

)

Standard copy constructor.

                                                        :
    BasicTimeSeries(tsi),
    Metadata(tsi)
{
    if(mlive)
    {
        s=tsi.s;
    }
    else if(tsi.s.size()>0)
    {
      /* This is needed to preserve the contents of data vector when something
      marks the data dead, but one wants to restore it later.  Classic example
      is an interactive trace editor.  Found mysterious errors can occur
      without this features. */
        s=tsi.s;
    }
    /* Do nothing if the parent s is empty as std::vector will be properly
    initialized*/
}

References mspass::seismic::BasicTimeSeries::mlive, and s.

Member Function Documentation

operator*=()

CoreTimeSeries & mspass::seismic::CoreTimeSeries::operator*=

(

const double

scale

)

Multiply data by a scalar.

{
  dscal(this->npts(),scale,&(this->s[0]),1);
  return *this;
}

References mspass::seismic::BasicTimeSeries::npts(), and s.

operator+()

const CoreTimeSeries mspass::seismic::CoreTimeSeries::operator+

(

const CoreTimeSeries &

other

)

const

Addition operator.

This operator is implemented in a standard way utilizing operator+=. For data with irregular start and end times that has an important consequence; the operator is not communative. i.e given x an y z=x+y will not yield the same result as z=y+x.

{
  CoreTimeSeries result(*this);
  result += other;
  return result;
}

operator+=()

CoreTimeSeries & mspass::seismic::CoreTimeSeries::operator+=

(

const CoreTimeSeries &

d

)

Summation operator.

Summing data from signals of irregular length requires handling potential mismatches in size and overlap. This behaves the way a += operator should logically behave in that situation. That is, because the lhs is where the sum is being accumulated, the size is always controlled by the left hand side of the operator. Any portions of the right hand side that are outside the t0 to endtime() of the left hand side are silently discarded. If the start time of the right hand side is greater than t0 or the endtime is less than endtime of the lhs there will be discontinuties in the sum there the ends of the rhs are inside the range of the lhs.

Parameters

d	is other signal to add to this.

Exceptions

MsPASSError

can be thrown if lhs and rhs do not have matching time standards.

{
    int i,iend,jend;
    size_t i0;
    size_t j,j0;
    // Sun's compiler complains about const objects without this.
    CoreTimeSeries& d=const_cast<CoreTimeSeries&>(data);
    // Silently do nothing if d is marked dead
    if(!d.mlive) return(*this);
    // Silently do nothing if d does not overlap with data to contain sum
    if( (d.endtime()<mt0)
            || (d.mt0>(this->endtime())) ) return(*this);
    if(d.tref!=(this->tref))
        throw MsPASSError("CoreTimeSeries += operator cannot handle data with inconsistent time base\n",
                          ErrorSeverity::Invalid);
    /* this defines the range of left and right hand sides to be summed */
    i=d.sample_number(this->mt0);
    if(i<0)
    {
      j0=this->sample_number(d.t0());
      i0=0;
    }
    else
    {
      j0=0;
      i0=i;
    }
    iend=d.sample_number(this->endtime());
    jend=this->sample_number(d.endtime());
    if(iend>=(d.npts()))
    {
        iend=d.npts()-1;
    }
    if(jend>=this->npts())
    {
      jend=this->npts()-1;
    }
    //cout << "i0="<<i0<<" j0="<<j0<<" iend="<<iend<<" jend="<<jend<<endl;
    /*  Now do the actual sum using the computed ranges */
    for(i=i0,j=j0; i<=iend && j<=jend; ++i,++j)
        this->s[j]+=d.s[i];
    return(*this);
}

References mspass::seismic::BasicTimeSeries::endtime(), mspass::seismic::BasicTimeSeries::mlive, mspass::seismic::BasicTimeSeries::mt0, mspass::seismic::BasicTimeSeries::npts(), s, mspass::seismic::BasicTimeSeries::sample_number(), mspass::seismic::BasicTimeSeries::t0(), and mspass::seismic::BasicTimeSeries::tref.

operator-()

const CoreTimeSeries mspass::seismic::CoreTimeSeries::operator-

(

const CoreTimeSeries &

other

)

const

Subtraction operator.

This operator is implemented in a standard way utilizing operator-=. For data with irregular start and end times that has an important consequence; the operator is not communative. i.e given x an y z=x-y will not yield the same result as z=-(y-x).

{
  CoreTimeSeries result(*this);
  result -= other;
  return result;
}

operator-=()

CoreTimeSeries & mspass::seismic::CoreTimeSeries::operator-=

(

const CoreTimeSeries &

d

)

Subtraction operator.

Differencing data from signals of irregular length requires handling potential mismatches in size and overlap. This behaves the way a -= operator should logically behave in that situation. That is, because the lhs is where the sum is being accumulated, the size is always controlled by the left hand side of the operator. Any portions of the right hand side that are outside the t0 to endtime() of the left hand side are silently discarded. If the start time of the right hand side is greater than t0 or the endtime is less than endtime of the lhs there will be discontinuties in the sum there the ends of the rhs are inside the range of the lhs.

Parameters

d	is other signal to subract from this.

Exceptions

MsPASSError

can be thrown if lhs and rhs do not have matching time standards.

{
    int i,iend,jend;
    size_t i0;
    size_t j,j0;
    // Sun's compiler complains about const objects without this.
    CoreTimeSeries& d=const_cast<CoreTimeSeries&>(data);
    // Silently do nothing if d is marked dead
    if(!d.mlive) return(*this);
    // Silently do nothing if d does not overlap with data to contain sum
    if( (d.endtime()<mt0)
            || (d.mt0>(this->endtime())) ) return(*this);
    if(d.tref!=(this->tref))
        throw MsPASSError("CoreTimeSeries += operator cannot handle data with inconsistent time base\n",
                          ErrorSeverity::Invalid);
    /* this defines the range of left and right hand sides to be summed */
    i=d.sample_number(this->mt0);
    if(i<0)
    {
      j0=this->sample_number(d.t0());
      i0=0;
    }
    else
    {
      j0=0;
      i0=i;
    }
    iend=d.sample_number(this->endtime());
    jend=this->sample_number(d.endtime());
    if(iend>=(d.npts()))
    {
        iend=d.npts()-1;
    }
    if(jend>=this->npts())
    {
      jend=this->npts()-1;
    }
    //cout << "i0="<<i0<<" j0="<<j0<<" iend="<<iend<<" jend="<<jend<<endl;
    /*  Now do the actual sum using the computed ranges */
    for(i=i0,j=j0; i<=iend && j<=jend; ++i,++j)
        this->s[j]-=d.s[i];
    return(*this);
}

References mspass::seismic::BasicTimeSeries::endtime(), mspass::seismic::BasicTimeSeries::mlive, mspass::seismic::BasicTimeSeries::mt0, mspass::seismic::BasicTimeSeries::npts(), s, mspass::seismic::BasicTimeSeries::sample_number(), mspass::seismic::BasicTimeSeries::t0(), and mspass::seismic::BasicTimeSeries::tref.

operator=()

CoreTimeSeries & mspass::seismic::CoreTimeSeries::operator=

(

const CoreTimeSeries &

parent

)

Standard assignment operator.

{
    if(this!=&tsi)
    {
        this->BasicTimeSeries::operator=(tsi);
        this->Metadata::operator=(tsi);
        s=tsi.s;
    }
    return(*this);
}

References mspass::seismic::BasicTimeSeries::operator=(), mspass::utility::Metadata::operator=(), and s.

operator[]()

double mspass::seismic::CoreTimeSeries::operator[]

(

size_t const

sample

)

const

Extract a sample from data vector with range checking. Because the data vector is public in this interface this operator is simply an alterative interface to this->s[sample].

Exceptions

SeisppError

exception if the requested sample is outside the range of the data. Note this includes an implicit "outside" defined when the contents are marked dead.

Parameters

sample

is the integer sample number of data desired.

{
    if(!mlive)
        throw MsPASSError(string("CoreTimeSeries operator[]: attempting to access data marked as dead"),
                          ErrorSeverity::Invalid);
    if( (i<0) || (i>=s.size()) )
    {
        throw MsPASSError(
            string("CoreTimeSeries operator[]:  request for sample outside range of data"),
            ErrorSeverity::Invalid);
    }
    return(s[i]);
}

References mspass::seismic::BasicTimeSeries::mlive, and s.

set_dt()

void mspass::seismic::CoreTimeSeries::set_dt ( const double  sample_interval )

virtual

Set the sample interval.

This method is complicated by the need to sync the changed value with Metadata. That is further complicated by the need to support aliases for the keys used to defined dt in Metadata. That is handled by first setting the internal dt value and then going through a fixed list of valid alias keys for dt. Any that exist are changed. If none were previously defined the unique name (see documentation) is added to Metadata.

Parameters

sample_interval

is the new data sample interval to be used.

Reimplemented from mspass::seismic::BasicTimeSeries.

{
  this->BasicTimeSeries::set_dt(sample_interval);
  /* This is the unique name - we always set it.
  Feb 2021 - changed to used const string value set in keywords.h*/
  this->put(SEISMICMD_dt,sample_interval);
  /* these are hard coded aliases for sample_interval */
  std::set<string> aliases;
  std::set<string>::iterator aptr;
  aliases.insert("dt");
  for(aptr=aliases.begin();aptr!=aliases.end();++aptr)
  {
    if(this->is_defined(*aptr))
    {
      this->put(*aptr,sample_interval);
    }
  }
}

References mspass::utility::Metadata::is_defined(), mspass::seismic::SEISMICMD_dt(), and mspass::seismic::BasicTimeSeries::set_dt().

set_npts()

void mspass::seismic::CoreTimeSeries::set_npts ( const size_t  npts )

virtual

Set the number of samples attribute for data.

This method is complicated by the need to sync the changed value with Metadata. That is further complicated by the need to support aliases for the keys used to defined npts in Metadata. That is handled by first setting the internal npts value (actually ns) and then going through a fixed list of valid alias keys for npts. Any that exist are changed. If none were previously defined the unique name (see documentation) is added to Metadata.

This attribute has an additional complication compared to other setter that are overrides from BasicTimeSeries. That is, the number of points define the data buffer size to hold the sample data. To guarantee the buffer size and the internal remain consistent this method clears any existing content of the vector s and initializes npts points to 0.0. Note this means if one is using this to assemble a data object in pieces you MUST call this method before loading any data or it will be cleared and you will mysteriously find the data are all zeros.

Parameters

npts	is the new number of points to set.

Reimplemented from mspass::seismic::BasicTimeSeries.

{
  this->BasicTimeSeries::set_npts(npts);
  /* This is the unique name - we always set it. Cast is necessary to
  avoid type mismatch in python for unsigned.
  Changed Feb 2021 to use key defined in in keywords.h*/
  this->put(SEISMICMD_npts,(long int)npts);
  /* these are hard coded aliases for sample_interval */
  std::set<string> aliases;
  std::set<string>::iterator aptr;
  aliases.insert("nsamp");
  aliases.insert("wfdisc.nsamp");
  for(aptr=aliases.begin();aptr!=aliases.end();++aptr)
  {
    if(this->is_defined(*aptr))
    {
      this->put(*aptr,(long int)npts);
    }
  }
  /* this method has the further complication that npts sets the size of the
  data buffer.  We clear it an initialize it to 0 to be consistent with
  how constructors handle this. */
  std::vector<double>().swap(this->s);  //  Clear the memory allocation of s
  this->s.reserve(npts);
  for(size_t i=0;i<npts;++i)this->s.push_back(0.0);
}

References mspass::utility::Metadata::is_defined(), mspass::seismic::BasicTimeSeries::npts(), s, mspass::seismic::SEISMICMD_npts(), and mspass::seismic::BasicTimeSeries::set_npts().

set_t0()

void mspass::seismic::CoreTimeSeries::set_t0 ( const double  t0in )

virtual

Set the data start time.

This method is complicated by the need to sync the changed value with Metadata. That is further complicated by the need to support aliases for the keys used to defined npts in Metadata. That is handled by first setting the internal t0 value and then going through a fixed list of valid alias keys for it. Any that exist are changed. If none were previously defined the unique name (see documentation) is added to Metadata.

This is a dangerous method to use on real data as it can mess up the time if not handled correctly. It should be used only when that sharp knife is needed such as in assembling data outside of constructors in a test program.

Parameters

t0in	is the new data sample interval to be used.

Reimplemented from mspass::seismic::BasicTimeSeries.

{
  this->BasicTimeSeries::set_t0(t0in);
  /* This is the unique name - we always set it.
  Changed Feb 2021 to use const string value defined in keywords.h*/
  this->put(SEISMICMD_t0,t0in);
  /* these are hard coded aliases for sample_interval */
  std::set<string> aliases;
  std::set<string>::iterator aptr;
  aliases.insert("t0");
  aliases.insert("time");
  for(aptr=aliases.begin();aptr!=aliases.end();++aptr)
  {
    if(this->is_defined(*aptr))
    {
      this->put(*aptr,t0in);
    }
  }
}

References mspass::utility::Metadata::is_defined(), mspass::seismic::SEISMICMD_t0(), and mspass::seismic::BasicTimeSeries::set_t0().

sync_npts()

void mspass::seismic::CoreTimeSeries::sync_npts

(

)

Sync the number of samples attribute with actual data size.

This method syncs the npts attribute with the actual size of the vector s. It also syncs aliases in the same way as the set_npts method.

{
  if(nsamp != this->s.size()) {
    this->BasicTimeSeries::set_npts(this->s.size());
    /* This is the unique name - we always set it.  The weird
    cast is necessary to avoid type mismatch with unsigned
    Changed Feb 2021 to use key defined in keywords.h*/
    this->put(SEISMICMD_npts,(long int)nsamp);
    /* these are hard coded aliases for sample_interval */
    std::set<string> aliases;
    std::set<string>::iterator aptr;
    aliases.insert("nsamp");
    aliases.insert("wfdisc.nsamp");
    for(aptr=aliases.begin();aptr!=aliases.end();++aptr)
    {
        if(this->is_defined(*aptr))
        {
          this->put(*aptr,(long int)nsamp);
        }
    }
  }
}

References mspass::utility::Metadata::is_defined(), mspass::seismic::BasicTimeSeries::nsamp, s, mspass::seismic::SEISMICMD_npts(), and mspass::seismic::BasicTimeSeries::set_npts().

Member Data Documentation

s

std::vector<double> mspass::seismic::CoreTimeSeries::s

Actual data stored as an STL vector container. Note the STL guarantees the data elements of vector container are contiguous in memory like FORTRAN vectors. As a result things like the BLAS can be used with data object by using a syntax like this: if d is a CoreTimeSeries object, the address of the first sample of the data is &(d.s[0]).

---

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

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