mspass::seismic::DataGap Class Reference

Container defining invalid time spans for gappy seismic data. More...

#include <DataGap.h>

Inheritance diagram for mspass::seismic::DataGap:

Public Member Functions
	DataGap ()
	DataGap (const std::list< mspass::algorithms::TimeWindow > &twlist)
	DataGap (const DataGap &parent)
virtual	~DataGap ()
bool	is_gap (const double ttest)
bool	has_gap (const mspass::algorithms::TimeWindow twin)
bool	has_gap ()
void	add_gap (const mspass::algorithms::TimeWindow tw)
std::list< mspass::algorithms::TimeWindow >	get_gaps () const
void	clear_gaps ()
	Clear gaps.
int	number_gaps () const
DataGap	subset (const mspass::algorithms::TimeWindow tw) const
void	translate_origin (double time_of_new_origin)
DataGap &	operator= (const DataGap &parent)
DataGap &	operator+= (const DataGap &other)

Protected Attributes
std::set< mspass::algorithms::TimeWindow, mspass::algorithms::TimeWindowCmp >	gaps
	Holds data gap definitions. We use an STL set object to define data gaps for any time series object derived from this base class. The set is keyed by a TimeWindow which allows a simple, fast way to define a time range with invalid data.

Detailed Description

Container defining invalid time spans for gappy seismic data.

DataGap stores TimeWindow intervals in a set so algorithms can query whether samples or windows overlap known gaps.

Constructor & Destructor Documentation

DataGap() [1/3]

mspass::seismic::DataGap::DataGap ( )

inline

Default construtor. Does nothing but create empty gap container.

{};

DataGap() [2/3]

mspass::seismic::DataGap::DataGap

(

const std::list< mspass::algorithms::TimeWindow > &

twlist

)

Construct with an initial list of TimeWindows defining gaps.

                                                       {
  for (auto twptr = twlist.begin(); twptr != twlist.end(); ++twptr)
    gaps.insert(*twptr);
}

References gaps.

DataGap() [3/3]

mspass::seismic::DataGap::DataGap ( const DataGap &  parent )

inline

Copy constructor.

: gaps(parent.gaps) {};

~DataGap()

virtual mspass::seismic::DataGap::~DataGap ( )

inlinevirtual

Virtual destructor for gap-aware derived classes.

{};

Member Function Documentation

add_gap()

void mspass::seismic::DataGap::add_gap

(

const mspass::algorithms::TimeWindow

tw

)

Adds a gap to the gap definitions for this data object. Sometimes an algorithm detects or needs to create a gap (e.g. a mute, or a constructor). This function provides a common mechanism to define such a gap in the data.

                                         {
  auto insert_result = this->gaps.insert(tw);
  if (!insert_result.second) {
    /* We land here if tw overlaps or duplicates something already in
     * the gaps container.  first in this case contains an iterator to
     * the potential duplicate.  We have to resolve which to keep*/
    TimeWindow old_tw(*insert_result.first);
    TimeWindow new_tw;
    if (tw.start < old_tw.start)
      new_tw.start = tw.start;
    else
      new_tw.start = old_tw.start;
    if (tw.end > old_tw.end)
      new_tw.end = tw.end;
    else
      new_tw.end = old_tw.end;
    gaps.erase(insert_result.first);
    gaps.insert(new_tw);
  }
}

References mspass::algorithms::TimeWindow::end, gaps, and mspass::algorithms::TimeWindow::start.

clear_gaps()

void mspass::seismic::DataGap::clear_gaps ( )

inline

Clear gaps.

It is sometimes necessary to clear gap definitions. This is particularly important when a descendent of this class is cloned and then morphed into something else. This method clears the entire content. This class assumes gaps are an immutable property of recorded data. A subclass could be used to add that functionality.

                    {
    if (!gaps.empty())
      gaps.clear();
  };

References gaps.

get_gaps()

std::list< TimeWindow > mspass::seismic::DataGap::get_gaps

(

)

const

Getter returns a list of TimeWindows defining a set of gaps.

                                            {
  std::list<TimeWindow> result;
  for (auto sptr = this->gaps.begin(); sptr != this->gaps.end(); ++sptr)
    result.push_back(*sptr);
  return result;
}

References gaps.

has_gap() [1/2]

bool mspass::seismic::DataGap::has_gap ( )

inline

Global test to see if data has any gaps defined. Gap processing is expensive and we need this simple method to test to see if the associated object has any gaps defined.

Returns

true if the associated object has any gaps defined.

{ return (!gaps.empty()); };

References gaps.

has_gap() [2/2]

bool mspass::seismic::DataGap::has_gap

(

const mspass::algorithms::TimeWindow

twin

)

Checks if a given data segment has a gap. For efficiency it is often useful to ask if a whole segment of data is free of gaps. Most time series algorithms cannot process through data gaps so normal practice would be to drop data with any gaps in a requested time segment.

Returns

true if time segment has any data gaps

Parameters

twin	time window of data to test defined by a TimeWindow object

                                           {
  if (gaps.empty())
    return false;
  if (gaps.find(twin) == gaps.end())
    return (false);
  else
    return (true);
}

References gaps.

is_gap()

bool mspass::seismic::DataGap::is_gap

(

const double

ttest

)

Checks if data at time ttest is a gap or valid data. This function is like the overloaded version with an int argument except it uses a time instead of sample number for the query.

Parameters

ttest

- time to be tested.

                                       {
  const double dt(
      0.001); // used to define small time interval smaller than most sampling
  if (gaps.empty())
    return false;
  TimeWindow twin;
  twin.start = ttest - dt * 0.5;
  twin.end = ttest + dt * 0.5;
  if (gaps.find(twin) == gaps.end())
    return false;
  else
    return true;
}

References mspass::algorithms::TimeWindow::end, gaps, and mspass::algorithms::TimeWindow::start.

number_gaps()

int mspass::seismic::DataGap::number_gaps ( ) const

inline

Return number of defined gaps.

{ return gaps.size(); };

References gaps.

operator+=()

DataGap & mspass::seismic::DataGap::operator+=

(

const DataGap &

other

)

Add contents of another DataGap container to this one.

                                                  {
  for (auto ptr = parent.gaps.begin(); ptr != parent.gaps.end(); ++ptr)
    this->add_gap(*ptr);
  return *this;
}

References add_gap(), and gaps.

operator=()

DataGap & mspass::seismic::DataGap::operator=

(

const DataGap &

parent

)

Standard assignment operator.

                                                 {
  if (this != (&parent)) {
    gaps = parent.gaps;
  }
  return *this;
}

References gaps.

subset()

DataGap mspass::seismic::DataGap::subset

(

const mspass::algorithms::TimeWindow

tw

)

const

Return the subset of gaps within a specified time interval.

Parameters

tw	TimeWindow defining range to be returned. Note overlaps with the edge will be returned with range outside the range defined by tw. If the tw is larger than the range of the current content returns a copy of itself.

                                                 {
  /* This could be implemented with the set equal_range method
   * but these objects are expected to normally be very small
   * and it is a lot clearer what this algorithm does.
   * */
  DataGap result;
  std::list<TimeWindow> gaplist = this->get_gaps();
  for (auto twptr = gaplist.begin(); twptr != gaplist.end(); ++twptr) {
    if (((twptr->end) > tw.start) && ((twptr->start) < tw.end)) {
      result.add_gap(*twptr);
    }
  }
  return result;
}

References add_gap(), mspass::algorithms::TimeWindow::end, get_gaps(), and mspass::algorithms::TimeWindow::start.

translate_origin()

void mspass::seismic::DataGap::translate_origin

(

double

time_of_new_origin

)

Shift the times of all gaps by a value.

When used with a TimeSeries or Seismogram the concept of UTC versus relative time requires shifting the time origin. This method should be used in that context or any other context where the data origin is shifted. The number passed as shift is subtracted from all the window start and end times that define data gaps.

                                                 {
  std::set<TimeWindow, TimeWindowCmp> translated_gaps;
  for (auto ptr = this->gaps.begin(); ptr != this->gaps.end(); ++ptr) {
    TimeWindow tw(*ptr);
    tw.start -= origin_time;
    tw.end -= origin_time;
    translated_gaps.insert(tw);
  }
  this->clear_gaps();
  for (auto ptr = translated_gaps.begin(); ptr != translated_gaps.end(); ++ptr)
    this->add_gap(*ptr);
}

References add_gap(), clear_gaps(), mspass::algorithms::TimeWindow::end, gaps, and mspass::algorithms::TimeWindow::start.

---

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

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