/******************************************************************************/
/*                                                                            */
/*                                  EVENT.HH                                  */
/*                                                                            */
/******************************************************************************/

// Shourov K. Chatterji
// shourov@ligo.caltech.edu
// $Id: event.hh,v 1.2 2007/03/12 09:10:53 shourov Exp $

/*                      Protect against double inclusion                      */
/*                      --------------------------------                      */

#ifndef EVENT_HH
#define EVENT_HH

/*                            Include header files                            */
/*                            --------------------                            */

#include <cmath>
#include <string>
#include <sstream>
#include <iomanip>
#include <iostream>

/*                           Begin namespace event                            */
/*                           ---------------------                            */

namespace event {

/*                            Constant definitions                            */
/*                            --------------------                            */

static const double ignore = -1.0;

/*                     Declare externally defined classes                     */
/*                     ----------------------------------                     */

class CoincidentEvent;

/*                             Begin class Event                              */
/*                             -----------------                              */

class Event {

/*                      Public interface of class Event                       */
/*                      -------------------------------                       */

public:

  /*                Constructor and destructor declarations                   */
  /*                ---------------------------------------                   */

  // default event constructor
  Event();

  // default event destructor
  virtual ~Event();

  // event copy constructor
  Event(const Event& event);

  // event assignment operator
  Event& operator=(const Event& event);

  // event constructor from coincident event
  Event(const CoincidentEvent& coincidentEvent);

  // full event constructor
  Event(double centerTime, double centerFrequency,
        double duration, double bandwidth,
        double normalizedEnergy, double incoherentEnergy = 0.0,
        std::string miscellaneous = "");

  /*                      Mutator method declarations                         */
  /*                      ---------------------------                         */

  // set properties of event
  void set(double centerTime, double centerFrequency,
           double duration, double bandwidth,
           double normalizedEnergy, double incoherentEnergy = 0.0,
           std::string miscellaneous = "");

  // set center time of event
  void setCenterTime(double centerTime);

  // set center frequency of event
  void setCenterFrequency(double centerFrequency);

  // set duration of event
  void setDuration(double duration);

  // set bandwidth of event
  void setBandwidth(double bandwidth);

  // set normalized energy of event
  void setNormalizedEnergy(double normalizedEnergy);

  // set incoherent energy of event
  void setIncoherentEnergy(double incoherentEnergy);

  // set miscellaneous properties of event
  void setMiscellaneous(std::string miscellaneous);

  // shift central time
  void timeShift(double timeShift);

  /*                      Accessor method declarations                        */
  /*                      ----------------------------                        */

  // get center time of event
  double getCenterTime() const;

  // get center frequency of event
  double getCenterFrequency() const;

  // get duration of event
  double getDuration(double durationInflation = 1.0) const;

  // get bandwidth of event
  double getBandwidth(double bandwidthInflation = 1.0) const;

  // get normalized energy of event
  double getNormalizedEnergy() const;

  // get incoherent energy of event
  double getIncoherentEnergy() const;

  // get miscellaneous properties of event
  std::string getMiscellaneous() const;

  // get start time of event
  double getStartTime(double durationInflation = 1.0) const;

  // get stop time of event
  double getStopTime(double durationInflation = 1.0) const;

  // get low frequency of event
  double getLowFrequency(double bandwidthInflation = 1.0) const;

  // get high frequency of event
  double getHighFrequency(double bandwidthInflation = 1.0) const;

  // get quality factor of event
  double getQualityFactor(double bandwidthInflation = 1.0) const;

  // get time-frequency area of event
  double getTimeFrequencyArea(double durationInflation = 1.0,
                              double bandwidthInflation = 1.0) const;

  // get signal to noise ratio
  double getSignalToNoiseRatio() const;

  // get negative natural logarithm of event significance
  double getLogSignificance(double precision = 0.001) const;

  /*			  Friend function declarations                        */
  /*			  ----------------------------                        */

  // write event to output stream
  friend std::ostream& operator<<(std::ostream& ostream, const Event& event);

  // read event from input stream
  friend std::istream& operator>>(std::istream& istream, Event& event);

/*                     Protected interface of class Event                     */
/*                     ----------------------------------                     */

protected:

/*                      Private interface of class Event                      */
/*                      --------------------------------                      */

private:

  /*                            State variables                               */
  /*                            ---------------                               */

  // center time of event
  double centerTime;

  // center frequency of event
  double centerFrequency;

  // duration of event
  double duration;

  // bandwidth of event
  double bandwidth;

  // normalized energy of event
  double normalizedEnergy;

  // incoherent energy of event
  double incoherentEnergy;

  // other miscellaneous information
  std::string miscellaneous;

/*                              End class Event                               */
/*                              ---------------                               */

};

/*			Non-member function declarations                      */
/*			--------------------------------                      */

// write event to output stream
std::ostream& operator<<(std::ostream& ostream, const Event& event);

// read event from input stream
std::istream& operator>>(std::istream& istream, Event& event);

// negative natural logarithm of significance
double logSignificance(double normalizedEnergy, double timeFrequencyArea,
                       double precision = 0.01);

/*                   Constructor and destructor definitions                   */
/*                   --------------------------------------                   */

// default event constructor
inline
Event::Event()
  : centerTime(0.0), centerFrequency(0.0),
    duration(0.0), bandwidth(0.0),
    normalizedEnergy(0.0), incoherentEnergy(0.0),
    miscellaneous("")
{
}

// default event destructor
inline
Event::~Event()
{
}

// event copy constructor
inline
Event::Event(const Event& event)
  : centerTime(event.centerTime), centerFrequency(event.centerFrequency),
    duration(event.duration), bandwidth(event.bandwidth),
    normalizedEnergy(event.normalizedEnergy),
    incoherentEnergy(event.incoherentEnergy),
    miscellaneous(event.miscellaneous)
{
}

// event assignment operator
inline
Event&
Event::operator=(const Event& event)
{
  if (this != &event) {
    centerTime = event.centerTime;
    centerFrequency = event.centerFrequency;
    duration = event.duration;
    bandwidth = event.bandwidth;
    normalizedEnergy = event.normalizedEnergy;
    incoherentEnergy = event.incoherentEnergy;
    miscellaneous = event.miscellaneous;
  }
  return *this;
}

// full event constructor
inline
Event::Event(double centerTime, double centerFrequency,
             double duration, double bandwidth,
             double normalizedEnergy, double incoherentEnergy,
             std::string miscellaneous)
  : centerTime(centerTime), centerFrequency(centerFrequency),
    duration(duration), bandwidth(bandwidth),
    normalizedEnergy(normalizedEnergy), incoherentEnergy(incoherentEnergy),
    miscellaneous(miscellaneous)
{
}

/*                         Mutator method definitions                         */
/*                         --------------------------                         */

// set properties of event
inline
void
Event::set(double centerTime, double centerFrequency,
           double duration, double bandwidth,
           double normalizedEnergy, double incoherentEnergy,
           std::string miscellaneous)
{
  this->centerTime = centerTime;
  this->centerFrequency = centerFrequency;
  this->duration = duration;
  this->bandwidth = bandwidth;
  this->normalizedEnergy = normalizedEnergy;
  this->incoherentEnergy = incoherentEnergy;
  this->miscellaneous = miscellaneous;
}

// set center time of event
inline
void
Event::setCenterTime(double centerTime)
{
  this->centerTime = centerTime;
}

// set center frequency of event
inline
void
Event::setCenterFrequency(double centerFrequency)
{
  this->centerFrequency = centerFrequency;
}

// set duration of event
inline
void
Event::setDuration(double duration)
{
  this->duration = duration;
}

// set bandwidth of event
inline
void
Event::setBandwidth(double bandwidth)
{
  this->bandwidth = bandwidth;
}

// set normalized energy of event
inline
void
Event::setNormalizedEnergy(double normalizedEnergy)
{
  this->normalizedEnergy = normalizedEnergy;
}

// set incoherent energy of event
inline
void
Event::setIncoherentEnergy(double incoherentEnergy)
{
  this->incoherentEnergy = incoherentEnergy;
}

// set miscellaneous properties of event
inline
void
Event::setMiscellaneous(std::string miscellaneous)
{
  this->miscellaneous = miscellaneous;
}

// shift central time
inline
void
Event::timeShift(double timeShift)
{
  centerTime += timeShift;
}

/*                        Accessor method definitions                         */
/*                        ---------------------------                         */

// get center time of event
inline
double
Event::getCenterTime() const
{
  return centerTime;
}

// get center frequency of event
inline
double
Event::getCenterFrequency() const
{
  return centerFrequency;
}

// get duration of event
inline
double
Event::getDuration(double durationInflation) const
{
  return durationInflation * duration;
}

// get bandwidth of event
inline
double
Event::getBandwidth(double bandwidthInflation) const
{
  return bandwidthInflation * bandwidth;
}

// get normalized energy of event
inline
double
Event::getNormalizedEnergy() const
{
  return normalizedEnergy;
}

// get incoherent energy of event
inline
double
Event::getIncoherentEnergy() const
{
  return incoherentEnergy;
}

// get miscellaneous properties of event
inline
std::string
Event::getMiscellaneous() const
{
  return miscellaneous;
}

// get start time of event
inline
double
Event::getStartTime(double durationInflation) const
{
  return centerTime - durationInflation * duration / 2;
}

// get stop time of event
inline
double
Event::getStopTime(double durationInflation) const
{
  return centerTime + durationInflation * duration / 2;
}

// get low frequency of event
inline
double
Event::getLowFrequency(double bandwidthInflation) const
{
  return centerFrequency - bandwidthInflation * bandwidth / 2;
}

// get high frequency of event
inline
double
Event::getHighFrequency(double bandwidthInflation) const
{
  return centerFrequency + bandwidthInflation * bandwidth / 2;
}

// get quality factor of event
inline
double
Event::getQualityFactor(double bandwidthInflation) const
{
  if (bandwidth == 0.0) {
    return 0.0;
  }
  else {
    return 2 * sqrt(M_PI) * centerFrequency / bandwidth;
  }
}

// get time-frequency area of event
inline
double
Event::getTimeFrequencyArea(double durationInflation,
                            double bandwidthInflation) const
{
  return duration * bandwidth * durationInflation * bandwidthInflation;
}

// get signal to noise ratio
inline
double
Event::getSignalToNoiseRatio() const
{
  if (normalizedEnergy < 0.5) {
    return 0.0;
  }
  else {
    return sqrt(2 * normalizedEnergy - 1);
  }
}

// get negative natural logarithm of event significance
inline
double
Event::getLogSignificance(double precision) const
{
  return logSignificance(normalizedEnergy, duration * bandwidth,
                         precision);
}

/*			Non-member function definitions                       */
/*			-------------------------------                       */

// write event to output stream
inline
std::ostream&
operator<<(std::ostream& ostream, const Event& event)
{
  std::ios_base::fmtflags originalFlags = ostream.flags();
  std::streamsize originalPrecision = ostream.precision();
  char originalFill = ostream.fill();
  ostream.flags(std::ios_base::dec | std::ios_base::showpoint);
  ostream << std::setfill('0');
  ostream << std::right;
  ostream << std::fixed;
  ostream << std::setw(19) << std::setprecision(9) << event.centerTime;
  ostream << " ";
  ostream << std::scientific;
  ostream << std::setw(9) << std::setprecision(3) << event.centerFrequency;
  ostream << " ";
  ostream << std::setw(9) << std::setprecision(3) << event.duration;
  ostream << " ";
  ostream << std::setw(9) << std::setprecision(3) << event.bandwidth;
  ostream << " ";
  ostream << std::setw(9) << std::setprecision(3) << event.normalizedEnergy;
  if ((event.incoherentEnergy > 0.0) || !event.miscellaneous.empty()) {
    ostream << " ";
    ostream << std::setw(9) << std::setprecision(3) << event.incoherentEnergy;
  }
  ostream << std::left;
  if (!event.miscellaneous.empty()) {
    ostream << " ";
    ostream << event.miscellaneous;
  }
  ostream << std::endl;
  ostream.flags(originalFlags);
  ostream.precision(originalPrecision);
  ostream.fill(originalFill);
  return ostream;
}

// read event from input stream
inline
std::istream&
operator>>(std::istream& istream, Event& event)
{
  std::string string;
  std::istringstream istringstream;
  std::getline(istream, string, '\n');
  istringstream.str(string);
  istringstream >> event.centerTime;
  istringstream >> event.centerFrequency;
  istringstream >> event.duration;
  istringstream >> event.bandwidth;
  istringstream >> event.normalizedEnergy;
  if (istringstream.fail()) {
    istream.setstate(std::ios_base::failbit);
    return istream;
  }
  istringstream >> std::ws;
  if (istringstream.eof()) {
    event.incoherentEnergy = 0.0;
    event.miscellaneous = "";
    return istream;
  }
  istringstream >> event.incoherentEnergy;
  istringstream >> std::ws;
  if (istringstream.eof()) {
    event.miscellaneous = "";
    return istream;
  }
  getline(istringstream, event.miscellaneous, '\n');
  if (istringstream.fail()) {
    istream.setstate(std::ios_base::failbit);
  }
  return istream;
}

// negative natural logarithm of significance
double
logSignificance(double normalizedEnergy, double timeFrequencyArea,
                double precision)
{
  if (timeFrequencyArea == 1.0) {
    return normalizedEnergy;
  }
  int maximumTerms = 10;
  double sum = 1;
  double numerator = 1;
  double denominator = 1;
  double ratio;
  double term;
  for (term = 1; term <= maximumTerms; term++) {
    numerator *= (timeFrequencyArea - term) * (timeFrequencyArea > term);
    denominator *= normalizedEnergy;
    ratio = numerator / denominator;
    sum += ratio;
    if (ratio < precision * sum) {
      break;
    }
  }
  if (term > maximumTerms) {
    std::cerr << "warning: logSignificance: maximum number of terms exceeded"
              << std::endl;
    return ignore;
  }
  double logSignificance = normalizedEnergy -
                           (timeFrequencyArea - 1) * log(normalizedEnergy) -
                           log(sum) + lgamma(timeFrequencyArea);
  return logSignificance;
}

/*                            End namespace event                             */
/*                            -------------------                             */

}

/*                  End protection against double inclusion                   */
/*                  ---------------------------------------                   */

#endif