mspass::seismic::PowerSpectrum Class Reference

#include <PowerSpectrum.h>

Inheritance diagram for mspass::seismic::PowerSpectrum:

Public Member Functions
	PowerSpectrum ()
template<class T >
	PowerSpectrum (const mspass::utility::Metadata &md, const std::vector< T > &d, const double dfin, const std::string nm, const double f0in, const double dtin, const int npts_in)
	PowerSpectrum (const PowerSpectrum &parent)
PowerSpectrum &	operator= (const PowerSpectrum &parent)
PowerSpectrum &	operator+= (const PowerSpectrum &other)
	Standard accumulation operator. More...
std::vector< double >	amplitude () const
	Compute amplitude spectrum from power spectrum. More...
double	power (const double f) const
	power at a given frequency. More...
double	frequency (const int sample_number) const
std::vector< double >	frequencies () const
size_t	nf () const
double	Nyquist () const
Public Member Functions inherited from mspass::seismic::BasicSpectrum
	BasicSpectrum ()
	BasicSpectrum (const double dfin, const double f0in, const double dtin, const int npts_in)
	BasicSpectrum (const BasicSpectrum &parent)
BasicSpectrum &	operator= (const BasicSpectrum &parent)
bool	live () const
bool	dead () const
void	kill ()
void	set_live ()
double	df () const
double	f0 () const
double	dt () const
	Return the original sample interval of data used to generate spectrum. More...
double	rayleigh () const
	Return the Rayleigh bin size for this spectrum. More...
int	timeseries_npts () const
int	sample_number (const double f) const
void	set_df (const double dfin)
void	set_f0 (const double f0in)
void	set_dt (const double dtin)
void	set_npts (const int npts_in)
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::string	spectrum_type
std::vector< double >	spectrum
mspass::utility::ErrorLogger	elog

Additional Inherited Members
Protected Attributes inherited from mspass::seismic::BasicSpectrum
double	dfval
double	f0val
double	parent_dt
double	parent_npts
bool	is_live
Protected Attributes inherited from mspass::utility::Metadata
std::map< std::string, boost::any >	md
std::set< std::string >	changed_or_set

Detailed Description

Class defining the concept of a power psectrum.

Constructor & Destructor Documentation

PowerSpectrum() [1/2]

mspass::seismic::PowerSpectrum::PowerSpectrum

(

)

Default constructor. Makes am empty, dead datum.

                            : BasicSpectrum(),Metadata(), elog()
{
  spectrum_type=string("UNDEFINED");
}

References spectrum_type.

PowerSpectrum() [2/2]

template<class T >

mspass::seismic::PowerSpectrum::PowerSpectrum	(	const mspass::utility::Metadata &	md,
		const std::vector< T > &	d,
		const double	dfin,
		const std::string	nm,
		const double	f0in,
		const double	dtin,
		const int	npts_in
	)

Standard constructor template.

This constructor is a template largely to allow vectors of data other than double as inputs. If the input is not double it is converted on input to an std::vector<double> container stored in the spectrum attribute.

Parameters

md	contents of this Metadata container are copied to the result.
d	vector of sample data to load into spectrum array.
dfin	frequency bin size (sample interval)
nm	name defining algorithm used to constuct this spectral estimate.
f0in	frequency of component 0 of input (default is 0.0).
dtin	parent sampell interval of data used to make this estimate
npts_in	number of points in parent time series used to compute this estimate.

Fully parameterized constructor template.

See class definition of PowerSpectrum for usage. Template to allow data vector of multiple types.

      : BasicSpectrum(dfin,f0in,dtin,npts_in),
          mspass::utility::Metadata(md),
            elog()
{
  spectrum_type=nm;
  spectrum.reserve(d.size());
  for(size_t k=0;k<d.size();++k)
    spectrum.push_back(static_cast<double>(d[k]));
  this->set_live();
};

References mspass::seismic::BasicSpectrum::set_live(), spectrum, and spectrum_type.

Member Function Documentation

amplitude()

vector< double > mspass::seismic::PowerSpectrum::amplitude

(

)

const

Compute amplitude spectrum from power spectrum.

The amplitude spectrum is sqrt of the power values. This is a convenience class to return the values in that form.

{
  vector<double> result;
  result.reserve(spectrum.size());
  for(int k=0;k<spectrum.size();++k)
    result.push_back(sqrt(spectrum[k]));
  return result;
}

References spectrum.

frequencies()

std::vector< double > mspass::seismic::PowerSpectrum::frequencies ( ) const

virtual

Return an std::vector container containing the frequency of each sample in the spectrum vector. Commonly necessary for plotting. Made virtual because nf method needs to be virtual.

Implements mspass::seismic::BasicSpectrum.

{
  vector<double> f;
  f.reserve(this->nf());
  for(auto i=0;i<this->nf();++i) f.push_back(this->f0val+this->dfval*static_cast<double>(i));
  return f;
}

References nf().

frequency()

double mspass::seismic::PowerSpectrum::frequency ( const int  sample_number ) const

inlinevirtual

Return frequency at a specified sample number. Virtual to allow subclasses to throw an error for illegal value.

Implements mspass::seismic::BasicSpectrum.

  {
    const std::string base_error("PowerSpectrum::frequency:  ");
    if(sample_number<0) throw mspass::utility::MsPASSError(base_error
        + "Sample number parameter passed cannot be negative");
    if(sample_number>=(this->nf())) throw mspass::utility::MsPASSError(base_error
        + "Sample number parameter passed xceeds range of spectrum array");
    return this->f0()+sample_number*this->df();
  };

References mspass::seismic::BasicSpectrum::df(), mspass::seismic::BasicSpectrum::f0(), nf(), and mspass::seismic::BasicSpectrum::sample_number().

nf()

size_t mspass::seismic::PowerSpectrum::nf ( ) const

inlinevirtual

Return the number of frequency bin.

Implements mspass::seismic::BasicSpectrum.

{return spectrum.size();};

References spectrum.

Nyquist()

double mspass::seismic::PowerSpectrum::Nyquist ( ) const

inlinevirtual

Return the nyquist frequency for this estimate.

Implements mspass::seismic::BasicSpectrum.

                         {
    return 1.0/(2.0*this->parent_dt);
  };

operator+=()

PowerSpectrum & mspass::seismic::PowerSpectrum::operator+=

(

const PowerSpectrum &

other

)

Standard accumulation operator.

Sometimes we need to sum power spectra. Type examplel would be total noise amplitude on a 3C seismogram or average noise amplitude in an array of instruments. This can be used to build such sum in the usual way. Add spectral elements sample by sample.

Exceptions

will	throw a MsPaSSError if the left and right side are not equal length of have different f0 of df values.

{
  /* Allow self accumulation - double values */
  if(this==(&other))
  {
    for(int k=0;k<this->nf();++k) spectrum[k]*=2.0;
  }
  else
  {
    if(this->nf() != other.nf())
    {
      stringstream ss;
      ss << "operator+=(accumulation) size mismatch of spectrum arrays"<<endl
        << "right hade side spectrum size="<<other.nf()<<endl
        << "left had side spectrum size="<<this->nf()<<endl;
      this->elog.log_error("PowerSpectrum::operator+-",
                     ss.str(),ErrorSeverity::Invalid);
      this->kill();
    }
    else if(this->f0() != other.f0())
    {
      stringstream ss;
      ss << "operator+=(accumulation) f0 mismatch of spectrum estimates"<<endl
        << "right hade side spectrum f0="<<other.f0()<<endl
        << "left had side spectrum f0="<<this->f0()<<endl;
      this->elog.log_error("PowerSpectrum::operator+-",
                     ss.str(),ErrorSeverity::Invalid);
      this->kill();
    }
    else if(this->df() != other.df())
    {
      stringstream ss;
      ss << "operator+=(accumulation) df mismatch of spectrum estimates"<<endl
        << "right hade side spectrum df="<<other.df()<<endl
        << "left had side spectrum df="<<this->df()<<endl;
      this->elog.log_error("PowerSpectrum::operator+-",
                     ss.str(),ErrorSeverity::Invalid);
      this->kill();
    }
    else
    {
      for(int k=0;k<this->nf();++k)
        spectrum[k] += other.spectrum[k];
    }
  }
  return *this;
}

References mspass::seismic::BasicSpectrum::df(), elog, mspass::seismic::BasicSpectrum::f0(), mspass::seismic::BasicSpectrum::kill(), mspass::utility::ErrorLogger::log_error(), nf(), and spectrum.

power()

double mspass::seismic::PowerSpectrum::power

(

const double

f

)

const

power at a given frequency.

Returns the power estimate at a specified frequency. Uses a linear interpolation between nearest neighbors. Returns the frequency exceeds the Nyquist silently returns 0.

Parameters

f	is the frequency for which amplitude is desired.

Exceptions

MsPASSErorr

object will be throw f f is less than 0.

{
  if(f<0.0) throw MsPASSError("PowerSpectrum::amplitude:  requested amplitude for a negative frequency which is assumed to be an erorr",
                ErrorSeverity::Invalid);
  int filow;
  filow=static_cast<int>((f-this->f0val)/this->dfval);
  /* Force 0 at Nyquist and above - this allows simple interpolation in else */
  if(filow>=(spectrum.size()-1))
     return 0.0;
  else
  {
    double slope=(spectrum[filow+1]-spectrum[filow])/this->dfval;
    double flow=this->f0val+((double)filow)*this->dfval;
    return spectrum[filow]+slope*(f-flow);
  }
}

References spectrum.

Member Data Documentation

elog

mspass::utility::ErrorLogger mspass::seismic::PowerSpectrum::elog

MsPASS Error logging class.

MsPASS uses an error logger to allow posting of error messages that go with the data. That approach is needed in map reduce to allow the error messages to be cleanly preserved.

spectrum

std::vector<double> mspass::seismic::PowerSpectrum::spectrum

Vector of spectral estimates. spectrum[0] == estimate at f0.

spectrum_type

std::string mspass::seismic::PowerSpectrum::spectrum_type

Descriptive name assigned by creator of algorithm used to generate it.

There are a number of different algorithms to generate power spectra. this name field should be used to set a unique name for a given algorithm.

---

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

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