GExtremaFinder.hh

Go to the documentation of this file.

//======================================================================
/*! \file GExtremaFinder.hh
 *
 *  Include file for the class GExtremaFinder.
 */
//======================================================================

#ifndef G_EXTREMA_FINDER_HH
#define G_EXTREMA_FINDER_HH

//======================================================================

#include "GRealSampleFFT.hh"
#include "GLogMessage.hh"

//----------------------------------------------------------------------
/*! \class GExtremaFinder
 *
 *  This class performs a maxima / minima search on a sample
 *  of real data.
 *
 *  \par Extrema analysis
 *
 *
 *  \par Maxima analysis
 *
 *  The maxima analysis is performed from the results of the extrema
 *  analysis (maxima and minima).
 *
 *  The analysis selects the maxima and sets the corresponding information
 *  in dedicated arrays.
 *  The information is the following:
 *  - the number of maxima;
 *  - the raw data from maxima analysis:
 *    - <B>Values</B>: the signal amplitude at maxima positions;
 *    - <B>Positions</B>: the position of the maxima along signal axis;
 *    - <B>Bins</B>: the sample bins that contain a maximum;
 *  - a more detailed analysis of the maxima, analysing the signal over
 *    the full range from the preceeding to the following minimum:
 *    - <B>Centers</B>: total signal mean position for the maxima;
 *    - <B>Amplitudes</B>: integrated signal for the maxima;
 *    - <B>Averages</B>: average signal for the maxima;
 *    - the information about the maxima analysis zone: position and signal
 *      of the lower and upper limits of the zone asociated to the maxima.
 *
 *  For the maxima analysis, it is also possible to set a low signal
 *  threshold below which the data are not considered:
 *  - a maximum below this threshold is ignored;
 *  - the local maxima zone for integration / average is limited to a
 *    region where the signal does not drop below this threshold.
 *
 */
class GExtremaFinder
{
  //------------------------------------------------------------
  /*! \object_doc */
  GObjectV(GExtremaFinder);
  //------------------------------------------------------------

  protected:
    GRealSampleFFT  * sample_ptr;     ///< Pointer to the data sample to analyse
    bool              sample_local;   ///< Whether the sample is allocated by the class
    GRealSampleFFT  * deriv_ptr;      ///< Derivative of the data sample

    bool      analyzed;         ///< Whether the extrema have been analyzed

    u_int     alloc_size;       ///< Allocated size for arrays

    u_int     extr_num;         ///< Number of extrema
    double  * extr_val;         ///< Array of extrema values
    double  * extr_pos;         ///< Array of extrema positions
    u_int   * extr_bin;         ///< Array of bins with extrema
    bool    * extr_max;         ///< Array indicating if extrema are maxima (or minima)

    bool      max_thr_use;      ///< Use of a low signal threshold for maxima analysis
    double    max_thr_low;      ///< Low signal threshold for maxima analysis
    u_int     max_num;          ///< Number of maxima
    double  * max_val;          ///< Array of maxima values
    double  * max_pos;          ///< Array of maxima positions
    u_int   * max_bin;          ///< Array of bins with maxima
    double  * max_ctr;          ///< Array of maxima zone average positions
    double  * max_amp;          ///< Array of maxima zone sum amplitude
    double  * max_avg;          ///< Array of maxima zone average amplitude

    double  * max_prev_min_val; ///< Array of values of the minimum before maxima
    double  * max_next_min_val; ///< Array of values of the minimum after maxima
    double  * max_prev_min_pos; ///< Array of positions of the minimum before maxima
    double  * max_next_min_pos; ///< Array of positions of the minimum after maxima
    u_int   * max_prev_min_bin; ///< Array of positions of the minimum before maxima
    u_int   * max_next_min_bin; ///< Array of positions of the minimum after maxima

  public:
  /** @name Constructors, destructors, affectation */
  //@{
    // Constructors
    GExtremaFinder ( u_int n = 0, double * data = NULL, double bin = 1. );
    GExtremaFinder ( GRealSampleFFT * sptr );
    GExtremaFinder ( GRealSampleFFT & s );
    GExtremaFinder ( const GExtremaFinder & original );
    
    // Affectation
    GExtremaFinder & operator = ( const GExtremaFinder & original );

    // Destructors
    virtual ~GExtremaFinder ( );
  //@}

  //----------------------------------------------------------
  /** @name Initialisation and setting functions */
  //@{
  protected:
    virtual void  CopyData    ( const GExtremaFinder & original );

  public:
    virtual int   InitData    ( u_int n, double * data, double bin = 1. );
    virtual int   InitData    ( GRealSampleFFT * sptr );
    virtual int   InitData    ( GRealSampleFFT & s );
    virtual void  ResetData   ( );
    virtual void  ClearData   ( );
  //@}

  //----------------------------------------------------------
  /** @name Access to data */
  //@{
    bool              IsSampleLocal ( ) const;    // inline
    const GRealSampleFFT  * GetSample ( ) const;            // inline
          GRealSampleFFT  * GetSample ( );                  // inline
    const GRealSampleFFT  * GetDerivativeSample ( ) const;  // inline
          GRealSampleFFT  * GetDerivativeSample ( );        // inline

    u_int           GetExtremaNum       ( ) const;   // inline
    const double  * GetExtremaValues    ( ) const;   // inline
          double  * GetExtremaValues    ( );         // inline
    const double  * GetExtremaPositions ( ) const;   // inline
          double  * GetExtremaPositions ( );         // inline
    const u_int   * GetExtremaBins      ( ) const;   // inline
          u_int   * GetExtremaBins      ( );         // inline
    const bool    * GetExtremaMax       ( ) const;   // inline
          bool    * GetExtremaMax       ( );         // inline


    u_int           GetMaximaNum        ( ) const;   // inline
    const double  * GetMaximaValues     ( ) const;   // inline
          double  * GetMaximaValues     ( );         // inline
    const double  * GetMaximaPositions  ( ) const;   // inline
          double  * GetMaximaPositions  ( );         // inline
    const u_int   * GetMaximaBins       ( ) const;   // inline
          u_int   * GetMaximaBins       ( );         // inline
    const double  * GetMaximaCenters    ( ) const;   // inline
          double  * GetMaximaCenters    ( );         // inline
    const double  * GetMaximaAmplitudes ( ) const;   // inline
          double  * GetMaximaAmplitudes ( );         // inline
    const double  * GetMaximaAverages   ( ) const;   // inline
          double  * GetMaximaAverages   ( );         // inline

    double GetMaxValue     ( u_int i ) const;   // inline
    double GetMaxPosition  ( u_int i ) const;   // inline
    u_int  GetMaxBin       ( u_int i ) const;   // inline
    double GetMaxCenter    ( u_int i ) const;   // inline
    double GetMaxAmplitude ( u_int i ) const;   // inline
    double GetMaxAverage   ( u_int i ) const;   // inline

    u_int  GetMaxPrevMinBin ( u_int i ) const;   // inline
    u_int  GetMaxNextMinBin ( u_int i ) const;   // inline
    double GetMaxPrevMinPos ( u_int i ) const;   // inline
    double GetMaxNextMinPos ( u_int i ) const;   // inline
    double GetMaxPrevMinVal ( u_int i ) const;   // inline
    double GetMaxNextMinVal ( u_int i ) const;   // inline
 //@}

  //----------------------------------------------------------
  /** @name Extrema analysis */
  //@{
    virtual int Analyse ( );
    virtual int Analyse ( GRealSampleFFT * sptr );
    virtual int Analyse ( GRealSampleFFT & s );

    virtual int DifferentialThreshold ( double thr );

    virtual void  SetMaximaLowThreshold   ( double thr );   // inline
    virtual void  UnsetMaximaLowThreshold ( );              // inline
    virtual int AnalyseMaxima ( );
    virtual int AnalyseMaxima ( GRealSampleFFT & s );
    virtual int AnalyseMaxima ( GRealSampleFFT & s, double low_thr );
    virtual int AnalyseMaxima ( GRealSampleFFT & s, double low_thr, double dif_thr );
  //@}
};

//======================================================================
//  Inline functions
#include "icc/GExtremaFinder.icc"


//======================================================================
#endif