mspass::algorithms::deconvolution::ScalarDecon Class Reference

Base class decon operator for single station 3C decon (receiver functions). More...

#include <ScalarDecon.h>

Inheritance diagram for mspass::algorithms::deconvolution::ScalarDecon:

Collaboration diagram for mspass::algorithms::deconvolution::ScalarDecon:

Public Member Functions
	ScalarDecon ()
	Construct an empty scalar deconvolution operator.
	ScalarDecon (const mspass::utility::Metadata &md)
	Construct from Metadata.
	ScalarDecon (const std::vector< double > &d, const std::vector< double > &w)
	Construct with loaded data and source-wavelet vectors.
	ScalarDecon (const ScalarDecon &parent)
	Copy constructor preserving loaded vectors and shaping wavelet.
int	load (const std::vector< double > &wavelet, const std::vector< double > &data)
	Load all data required for decon.
int	loaddata (const std::vector< double > &data)
int	loadwavelet (const std::vector< double > &wavelet)
virtual void	process ()=0
	Run the concrete scalar deconvolution algorithm.
ScalarDecon &	operator= (const ScalarDecon &parent)
	Assign loaded wavelet, data, and result vectors from parent.
std::vector< double >	getresult ()
	Return the current deconvolution result vector.
void	changeparameter (const mspass::utility::Metadata &md)
void	change_shaping_wavelet (const ShapingWavelet &nsw)
ShapingWavelet	get_shaping_wavelet () const
virtual mspass::seismic::CoreTimeSeries	output_shaping_wavelet ()
	Return the output shaping wavelet.
mspass::seismic::CoreTimeSeries	ideal_output ()
	Legacy alias for output_shaping_wavelet.
virtual mspass::seismic::CoreTimeSeries	actual_output ()=0
	Return the actual output of the deconvolution operator.
mspass::seismic::CoreTimeSeries	resolution_kernel ()
	Alias for actual_output using inverse-theory terminology.
virtual mspass::seismic::CoreTimeSeries	inverse_wavelet ()=0
	Return a FIR represention of the inverse filter.
virtual mspass::seismic::CoreTimeSeries	inverse_wavelet (double t0parent)=0
	Return a FIR inverse filter with a specified parent time origin.
virtual mspass::utility::Metadata	QCMetrics ()=0
	Return appropriate quality measures.
Public Member Functions inherited from mspass::algorithms::deconvolution::BasicDeconOperator
virtual	~BasicDeconOperator ()

Protected Member Functions
mspass::utility::Metadata	BasicQCMetrics (const std::string &operator_name, const bool processed)
	Build QC Metadata fields common to scalar deconvolution operators.

Protected Attributes
std::vector< double >	data
	Data vector to be deconvolved by concrete scalar methods.
std::vector< double >	wavelet
	Source-wavelet estimate used by concrete scalar methods.
std::vector< double >	result
	Deconvolved output vector produced by process.
ShapingWavelet	shapingwavelet
	Output shaping wavelet applied by scalar deconvolution methods.

Detailed Description

Base class decon operator for single station 3C decon (receiver functions).

A class of algorithms exist for computing so called receiver functions. Simple for this application means a method that is applied to a single station's data and computed in a scalar time series sense. Thus the interface assumes we want to always at least load an estimate of the source wavelet for deconvolution and the data to which it is to be applied.

The design of this interface was made more complicated by a design goal to allow application of different conventional methods as the first step in the generalized iterative method. The generalized method can select one of the children of this base class.

Constructor & Destructor Documentation

ScalarDecon() [1/4]

mspass::algorithms::deconvolution::ScalarDecon::ScalarDecon ( )

inline

Construct an empty scalar deconvolution operator.

: shapingwavelet() {};

ScalarDecon() [2/4]

mspass::algorithms::deconvolution::ScalarDecon::ScalarDecon

(

const mspass::utility::Metadata &

md

)

Construct from Metadata.

Initializes the shaping wavelet from md and reserves the data, wavelet, and result vectors using the operator_nfft value in md.

                                           : shapingwavelet(md) {
  try {
    /* This has to be defined or the shapingwavlet constructor will
     * fail in the current implementation */
    int nfft = GetIntRequired(md, "operator_nfft");
    wavelet.reserve(nfft);
    data.reserve(nfft);
    result.reserve(nfft);
  } catch (...) {
    throw;
  };
}

References data, result, and wavelet.

ScalarDecon() [3/4]

mspass::algorithms::deconvolution::ScalarDecon::ScalarDecon	(	const std::vector< double > &	d,
		const std::vector< double > &	w
	)

Construct with loaded data and source-wavelet vectors.

Parameters

d	data vector to be deconvolved.
w	source-wavelet estimate used by concrete deconvolution methods.

    : data(d), wavelet(w) {
  result.reserve(data.size());
}

References data, and result.

ScalarDecon() [4/4]

mspass::algorithms::deconvolution::ScalarDecon::ScalarDecon

(

const ScalarDecon &

parent

)

Copy constructor preserving loaded vectors and shaping wavelet.

    : data(parent.data), wavelet(parent.wavelet), result(parent.result),
      shapingwavelet(parent.shapingwavelet) {}

~ScalarDecon()

virtual mspass::algorithms::deconvolution::ScalarDecon::~ScalarDecon ( )

inlinevirtual

{};

Member Function Documentation

actual_output()

virtual mspass::seismic::CoreTimeSeries mspass::algorithms::deconvolution::ScalarDecon::actual_output ( )

pure virtual

Return the actual output of the deconvolution operator.

The actual output is defined as w^-1*w and is compable to resolution kernels in linear inverse theory. Although not required we would normally expect this function to be peaked at 0. Offsets from 0 would imply a bias.

Implemented in mspass::algorithms::deconvolution::FrequencyDomainGIDDecon, mspass::algorithms::deconvolution::LeastSquareDecon, mspass::algorithms::deconvolution::MultiTaperSpecDivDecon, mspass::algorithms::deconvolution::MultiTaperXcorDecon, mspass::algorithms::deconvolution::NoiseStableDecon, mspass::algorithms::deconvolution::TimeDomainGIDDecon, mspass::algorithms::deconvolution::TimeDomainLeastSquareDecon, and mspass::algorithms::deconvolution::WaterLevelDecon.

BasicQCMetrics()

Metadata mspass::algorithms::deconvolution::ScalarDecon::BasicQCMetrics ( const std::string &  operator_name, const bool  processed  )

protected

Build QC Metadata fields common to scalar deconvolution operators.

The returned Metadata records the operator name, whether processing has run, whether input vectors are loaded, the input and output vector sizes, and the shaping-wavelet type, sample interval, and FFT length.

                                                           {
  Metadata md;
  md.put("decon_operator", operator_name);
  md.put("decon_processed", processed);
  md.put("decon_input_loaded", !data.empty() && !wavelet.empty());
  md.put("decon_data_npts", static_cast<int>(data.size()));
  md.put("decon_wavelet_npts", static_cast<int>(wavelet.size()));
  md.put("decon_output_npts", static_cast<int>(result.size()));
  md.put("decon_shaping_wavelet_type", shapingwavelet.type());
  md.put("decon_shaping_wavelet_dt", shapingwavelet.sample_interval());
  md.put("decon_shaping_wavelet_nfft", shapingwavelet.size());
  return md;
}

References data, mspass::utility::Metadata::put(), result, mspass::algorithms::deconvolution::ShapingWavelet::sample_interval(), shapingwavelet, mspass::algorithms::deconvolution::ShapingWavelet::size(), mspass::algorithms::deconvolution::ShapingWavelet::type(), and wavelet.

change_shaping_wavelet()

void mspass::algorithms::deconvolution::ScalarDecon::change_shaping_wavelet

(

const ShapingWavelet &

nsw

)

Change the shaping wavelet that will be applied to output.

The suite of algorithms here use the concept of a shaping wavelet thoughout. The shaping wavelet for most applications should have a zero phase impulse response. This method changes the wavelet set with the operator.

                                                                  {
  shapingwavelet = nsw;
}

References shapingwavelet.

changeparameter()

void mspass::algorithms::deconvolution::ScalarDecon::changeparameter ( const mspass::utility::Metadata &  md )

virtual

This method does nothing, but needs to be defined to avoid gcc compile errors in programs using children of this class.

Implements mspass::algorithms::deconvolution::BasicDeconOperator.

Reimplemented in mspass::algorithms::deconvolution::TimeDomainGIDDecon, mspass::algorithms::deconvolution::TimeDomainLeastSquareDecon, and mspass::algorithms::deconvolution::WaterLevelDecon.

                                                    {
  shapingwavelet = ShapingWavelet(md);
}

References shapingwavelet.

get_shaping_wavelet()

ShapingWavelet mspass::algorithms::deconvolution::ScalarDecon::get_shaping_wavelet ( ) const

inline

getter for ShapingWavelet stored with the operator.

{ return this->shapingwavelet; };

References shapingwavelet.

getresult()

std::vector< double > mspass::algorithms::deconvolution::ScalarDecon::getresult ( )

inline

Return the current deconvolution result vector.

{ return result; };

References result.

ideal_output()

mspass::seismic::CoreTimeSeries mspass::algorithms::deconvolution::ScalarDecon::ideal_output ( )

inline

Legacy alias for output_shaping_wavelet.

Older MsPASS code called the output shaping wavelet "ideal_output". New code and documentation should prefer output_shaping_wavelet, which matches the terminology of Wang and Pavlis (2016).

                                             {
    return this->output_shaping_wavelet();
  };

References output_shaping_wavelet().

inverse_wavelet() [1/2]

virtual mspass::seismic::CoreTimeSeries mspass::algorithms::deconvolution::ScalarDecon::inverse_wavelet ( )

pure virtual

Return a FIR represention of the inverse filter.

After any deconvolution is computed one can sometimes produce a finite impulse response (FIR) respresentation of the inverse filter.

Implemented in mspass::algorithms::deconvolution::FrequencyDomainGIDDecon, mspass::algorithms::deconvolution::LeastSquareDecon, mspass::algorithms::deconvolution::MultiTaperSpecDivDecon, mspass::algorithms::deconvolution::MultiTaperXcorDecon, mspass::algorithms::deconvolution::NoiseStableDecon, mspass::algorithms::deconvolution::TimeDomainGIDDecon, mspass::algorithms::deconvolution::TimeDomainLeastSquareDecon, and mspass::algorithms::deconvolution::WaterLevelDecon.

inverse_wavelet() [2/2]

virtual mspass::seismic::CoreTimeSeries mspass::algorithms::deconvolution::ScalarDecon::inverse_wavelet ( double  t0parent )

pure virtual

Return a FIR inverse filter with a specified parent time origin.

Parameters

t0parent

time origin assigned to the returned CoreTimeSeries.

Implemented in mspass::algorithms::deconvolution::NoiseStableDecon, mspass::algorithms::deconvolution::TimeDomainLeastSquareDecon, mspass::algorithms::deconvolution::LeastSquareDecon, mspass::algorithms::deconvolution::MultiTaperSpecDivDecon, mspass::algorithms::deconvolution::MultiTaperXcorDecon, mspass::algorithms::deconvolution::WaterLevelDecon, mspass::algorithms::deconvolution::FrequencyDomainGIDDecon, and mspass::algorithms::deconvolution::TimeDomainGIDDecon.

load()

int mspass::algorithms::deconvolution::ScalarDecon::load	(	const std::vector< double > &	wavelet,
		const std::vector< double > &	data
	)

Load all data required for decon.

This method loads both the data vector and wavelet estimates as simple std::vectors. Timing must be maintained externally. This or the pair of methods loaddata and loadwavelet must be called before process. This method has a slight advantage in efficiency over successive calls to loaddata and loadwavelet for several reasons, but the difference is small.

Returns

always returns 0

                                                                      {
  wavelet = w;
  data = d;
  result.clear();
  return 0;
}

References data, result, and wavelet.

loaddata()

int mspass::algorithms::deconvolution::ScalarDecon::loaddata

(

const std::vector< double > &

data

)

Load only the data vector.

                                                 {
  data = d;
  result.clear();
  return 0;
}

References data, and result.

loadwavelet()

int mspass::algorithms::deconvolution::ScalarDecon::loadwavelet

(

const std::vector< double > &

wavelet

)

Load only the wavelet estimate.

                                                    {
  wavelet = w;
  result.clear();
  return 0;
}

References result, and wavelet.

operator=()

ScalarDecon & mspass::algorithms::deconvolution::ScalarDecon::operator=

(

const ScalarDecon &

parent

)

Assign loaded wavelet, data, and result vectors from parent.

                                                             {
  if (this != &parent) {
    wavelet = parent.wavelet;
    data = parent.data;
    result = parent.result;
  }
  return *this;
}

References data, result, and wavelet.

output_shaping_wavelet()

virtual mspass::seismic::CoreTimeSeries mspass::algorithms::deconvolution::ScalarDecon::output_shaping_wavelet ( )

inlinevirtual

Return the output shaping wavelet.

Wang and Pavlis (2016) call this wavelet ws(t). GID methods convolve the sparse impulse response with this wavelet to form the finite-duration receiver-function representation used for stacking and imaging.

Reimplemented in mspass::algorithms::deconvolution::TimeDomainLeastSquareDecon.

                                                               {
    return this->shapingwavelet.impulse_response();
  };

References mspass::algorithms::deconvolution::ShapingWavelet::impulse_response(), and shapingwavelet.

process()

virtual void mspass::algorithms::deconvolution::ScalarDecon::process ( )

pure virtual

Run the concrete scalar deconvolution algorithm.

Derived classes implement this method and store their deconvolved output in the result vector.

Implemented in mspass::algorithms::deconvolution::FrequencyDomainGIDDecon, mspass::algorithms::deconvolution::LeastSquareDecon, mspass::algorithms::deconvolution::MultiTaperSpecDivDecon, mspass::algorithms::deconvolution::MultiTaperXcorDecon, mspass::algorithms::deconvolution::NoiseStableDecon, mspass::algorithms::deconvolution::TimeDomainGIDDecon, mspass::algorithms::deconvolution::TimeDomainLeastSquareDecon, and mspass::algorithms::deconvolution::WaterLevelDecon.

QCMetrics()

virtual mspass::utility::Metadata mspass::algorithms::deconvolution::ScalarDecon::QCMetrics ( )

pure virtual

Return appropriate quality measures.

Each operator commonly has different was to measure the quality of the result. This method should return these in a generic Metadata object.

Implemented in mspass::algorithms::deconvolution::FrequencyDomainGIDDecon, mspass::algorithms::deconvolution::LeastSquareDecon, mspass::algorithms::deconvolution::MultiTaperSpecDivDecon, mspass::algorithms::deconvolution::MultiTaperXcorDecon, mspass::algorithms::deconvolution::NoiseStableDecon, mspass::algorithms::deconvolution::TimeDomainGIDDecon, mspass::algorithms::deconvolution::TimeDomainLeastSquareDecon, and mspass::algorithms::deconvolution::WaterLevelDecon.

resolution_kernel()

mspass::seismic::CoreTimeSeries mspass::algorithms::deconvolution::ScalarDecon::resolution_kernel ( )

inline

Alias for actual_output using inverse-theory terminology.

                                                  {
    return this->actual_output();
  };

References actual_output().

---

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

• /home/runner/work/mspass/mspass/cxx/include/mspass/algorithms/deconvolution/ScalarDecon.h
• /home/runner/work/mspass/mspass/cxx/src/lib/algorithms/deconvolution/ScalarDecon.cc