path: root/src/loris/Fundamental.h

#ifndef INCLUDE_FUNDAMENTAL_H
#define INCLUDE_FUNDAMENTAL_H
/*
 * This is the Loris C++ Class Library, implementing analysis, 
 * manipulation, and synthesis of digitized sounds using the Reassigned 
 * Bandwidth-Enhanced Additive Sound Model.
 *
 * Loris is Copyright (c) 1999-2010 by Kelly Fitz and Lippold Haken
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY, without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 *
 * Fundamental.h
 *
 * Definition of classes for computing an estimate of time-varying
 * fundamental frequency from either a sequence of samples or a
 * collection of Partials using a frequency domain maximum likelihood 
 * algorithm adapted from Quatieri's speech signal processing textbook. 
 *
 * Kelly Fitz, 25 March 2008
 * loris@cerlsoundgroup.org
 *
 * http://www.cerlsoundgroup.org/Loris/
 *
 */

#include "LinearEnvelope.h"
#include "PartialList.h"
#include "F0Estimate.h" 

#include <memory>
#include <vector>

//  begin namespace
namespace Loris {

class ReassignedSpectrum;

// ---------------------------------------------------------------------------
//  class FundamentalEstimator
//
//! Base class for fundamental estimation, common storage for member
//! variable parameters, type definitions, and constants.

class FundamentalEstimator
{
public:

//  -- types --

    typedef F0Estimate value_type;

//  -- constants --    

    enum {
    
        DefaultAmpFloor = -60,          //! the default absolute amplitude threshold in dB
        
        DefaultAmpRange = 30,           //! the default floating amplitude threshold in dB
    
        DefaultFreqCeiling = 4000,      //! the default frequency threshold in Hz
    
        DefaultPrecisionOver100 = 10,   //! the default frequency precision in 1/100 Hz

        DefaultMinConfidencePct = 90    //! the default required percent confidence to
                                        //! return an estimate (100 is absolute confidence)
    };
    

//  -- lifecycle --

protected:

    //! Construct a new estimator with specified precision and
    //! other parameters given default values.
    //!
    //! The specified precision is used to terminate the iterative
    //! estimation procedure. 
    //!
    //! \param precisionHz is the precision in Hz with which the 
    //! fundamental estimates will be made.
    FundamentalEstimator( double precisionHz );
                                                        
public: 

    //! Destructor    
    virtual ~FundamentalEstimator( void );    


    //  compiler-generated copy and assignment are OK

  
//  -- parameter access --

    //! Return the absolute amplitude threshold in (negative) dB, 
    //! below which spectral peaks will not be considered in the 
    //! estimation of the fundamental (default is 30 dB).            
    double ampFloor( void ) const;

    //!	Return the amplitude range in dB, 
    //! relative to strongest peak in a frame, floating
    //! amplitude threshold (negative) below which spectral
    //! peaks will not be considered in the estimation of 
    //! the fundamental (default is 30 dB).	
    double ampRange( void ) const;

    //! Return the frequency ceiling in Hz, the
    //! frequency threshold above which spectral
    //! peaks will not be considered in the estimation of 
    //! the fundamental (default is 10 kHz).            
    double freqCeiling( void ) const;

    //! Return the precision of the estimate in Hz, the
    //! fundamental frequency will be estimated to 
    //! within this range (default is 0.1 Hz).
    double precision( void ) const;
     
//  -- parameter mutation --

    //! Set the absolute amplitude threshold in (negative) dB, 
    //! below which spectral peaks will not be considered in the 
    //! estimation of the fundamental (default is 30 dB).            
    //! 
    //! \param x is the new value of this parameter.            
    void setAmpFloor( double x );

    //!	Set the amplitude range in dB, 
    //! relative to strongest peak in a frame, floating
    //! amplitude threshold (negative) below which spectral
    //! peaks will not be considered in the estimation of 
    //! the fundamental (default is 30 dB).	
    //! 
    //! \param x is the new value of this parameter.            
    void setAmpRange( double x );

    //! Set the frequency ceiling in Hz, the
    //! frequency threshold above which spectral
    //! peaks will not be considered in the estimation of 
    //! the fundamental (default is 10 kHz). Must be
    //! greater than the lower bound.
    //! 
    //! \param x is the new value of this parameter.            
    void setFreqCeiling( double x );

    //! Set the precision of the estimate in Hz, the
    //! fundamental frequency will be estimated to 
    //! within this range (default is 0.1 Hz).
    //! 
    //! \param x is the new value of this parameter.            
    void setPrecision( double x );


protected:

//  -- parameter member variables --


    double m_precision;         //! in Hz, fundamental frequency will be estimated to 
                                //! within this range (default is 0.1 Hz)
                                
    double m_ampFloor;          //! absolute amplitude threshold below which spectral
                                //! peaks will not be considered in the estimation of 
                                //! the fundamental (default is equivalent to 60 dB
                                //! quieter than a full scale sinusoid)
    
    double m_ampRange;          //! floating amplitude threshold relative to the peak
                                //! having the largest magnitude below which spectral
                                //! peaks will not be considered in the estimation of 
                                //! the fundamental (default is equivalent to 30 dB)
        
    double m_freqCeiling;       //! in Hz, frequency threshold above which spectral
                                //! peaks will not be considered in the estimation of 
                                //! the fundamental (default is 10 kHz)      


};  //  end of base class FundamentalEstimator



// ---------------------------------------------------------------------------
//  class FundamentalFromSamples
//
//! Class FundamentalFromSamples represents an algorithm for 
//! time-varying fundamental frequency estimation based on
//! time-frequency reassigned spectral analysis of a sequence
//! of samples. This class is adapted from the Analyzer class 
//! (see Analyzer.h), and performs the same spectral analysis 
//! and peak extraction, but does not form Partials.
//! 
//! For more information about Reassigned Bandwidth-Enhanced 
//! Analysis and the Reassigned Bandwidth-Enhanced Additive Sound 
//! Model, refer to the Loris website: www.cerlsoundgroup.org/Loris/.
//
class FundamentalFromSamples : public FundamentalEstimator
{
//  -- public interface --

public:

//  -- lifecycle --

    //! Construct a new estimator configured with the given  
    //! analysis window width (main lobe, zero-to-zero). All other 
    //! spectrum analysis parameters are computed from the specified 
    //! window width. 
    //!
    //! The specified precision is used to terminate the iterative
    //! estimation procedure. If unspecified, the default value,
    //! DefaultPrecisionOver100 * 100 is used. 
    //! 
    //! \param  windowWidthHz is the main lobe width of the Kaiser
    //!         analysis window in Hz.
    //!
    //! \param  precisionHz is the precision in Hz with which the 
    //!         fundamental estimates will be made.    
    FundamentalFromSamples( double winWidthHz, 
                            double precisionHz = DefaultPrecisionOver100 * 0.01 );
                            
                            

    //! Destructor    
    ~FundamentalFromSamples( void );

//  -- fundamental frequency estimation --

    //  buildEnvelope
    //
    //! Construct a linear envelope from fundamental frequency 
    //! estimates taken at the specified interval in seconds
    //! starting at tbeg (seconds) and ending before tend (seconds).
    //! 
    //! \param  samps is the beginning of a sequence of samples
    //! \param  sampsEnd is the end of the sequence of samples
    //! \param  sampleRate is the sampling rate (in Hz) associated
    //!         with the sequence of samples (used to compute frequencies
    //!         in Hz, and to convert the time from seconds to samples)
    //! \param  tbeg is the beginning of the time interval (in seconds)
    //! \param  tend is the end of the time interval (in seconds)
    //! \param  interval is the time between breakpoints in the
    //!         fundamental frequency envelope (in seconds)
    //! \param  lowerFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \param  upperFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \param  confidenceThreshold is the minimum confidence level
    //!         resuired for a fundamental frequency estimate to be
    //!         added to the envelope. Lower confidence estimates are
    //!         not added, the envelope returned will not contain
    //!         breakpoints at times associated with low confidence 
    //!         estimates
    //! \return a LinearEnvelope composed of breakpoints corresponding to
    //!         the fundamental frequency estimates at samples of the span
    //!         tbeg to tend at the specified sampling interval, only estimates
    //!         having confidence level exceeding the specified confidence
    //!         threshold are added to the envelope    
    LinearEnvelope buildEnvelope( const double * sampsBeg, 
                                  const double * sampsEnd, 
                                  double sampleRate, 
                                  double tbeg, double tend, 
                                  double interval,
                                  double lowerFreqBound, double upperFreqBound, 
                                  double confidenceThreshold );
                                 
    //  buildEnvelope
    //
    //! Construct a linear envelope from fundamental frequency 
    //! estimates taken at the specified interval in seconds
    //! starting at tbeg (seconds) and ending before tend (seconds).
    //! 
    //! \param  samps is the beginning of a sequence of samples
    //! \param  nsamps is the length of the sequence of samples
    //! \param  sampleRate is the sampling rate (in Hz) associated
    //!         with the sequence of samples (used to compute frequencies
    //!         in Hz, and to convert the time from seconds to samples)
    //! \param  tbeg is the beginning of the time interval (in seconds)
    //! \param  tend is the end of the time interval (in seconds)
    //! \param  interval is the time between breakpoints in the
    //!         fundamental frequency envelope (in seconds)
    //! \param  lowerFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \param  upperFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \param  confidenceThreshold is the minimum confidence level
    //!         resuired for a fundamental frequency estimate to be
    //!         added to the envelope. Lower confidence estimates are
    //!         not added, the envelope returned will not contain
    //!         breakpoints at times associated with low confidence 
    //!         estimates
    //! \return a LinearEnvelope composed of breakpoints corresponding to
    //!         the fundamental frequency estimates at samples of the span
    //!         tbeg to tend at the specified sampling interval, only estimates
    //!         having confidence level exceeding the specified confidence
    //!         threshold are added to the envelope    
    LinearEnvelope buildEnvelope( const double * sampsBeg, 
                                  unsigned long nsamps,
                                  double sampleRate, 
                                  double tbeg, double tend, 
                                  double interval,
                                  double lowerFreqBound, double upperFreqBound, 
                                  double confidenceThreshold )
    {
        return buildEnvelope( sampsBeg, sampsBeg + nsamps, sampleRate, 
                              tbeg, tend, interval, 
                              lowerFreqBound, upperFreqBound,
                              confidenceThreshold );
    }


    //  buildEnvelope
    //
    //! Construct a linear envelope from fundamental frequency 
    //! estimates taken at the specified interval in seconds
    //! starting at tbeg (seconds) and ending before tend (seconds).
    //! 
    //! \param  samps is the sequence of samples
    //! \param  sampleRate is the sampling rate (in Hz) associated
    //!         with the sequence of samples (used to compute frequencies
    //!         in Hz, and to convert the time from seconds to samples)
    //! \param  tbeg is the beginning of the time interval (in seconds)
    //! \param  tend is the end of the time interval (in seconds)
    //! \param  interval is the time between breakpoints in the
    //!         fundamental frequency envelope (in seconds)
    //! \param  lowerFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \param  upperFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \param  confidenceThreshold is the minimum confidence level
    //!         resuired for a fundamental frequency estimate to be
    //!         added to the envelope. Lower confidence estimates are
    //!         not added, the envelope returned will not contain
    //!         breakpoints at times associated with low confidence 
    //!         estimates
    //! \return a LinearEnvelope composed of breakpoints corresponding to
    //!         the fundamental frequency estimates at samples of the span
    //!         tbeg to tend at the specified sampling interval, only estimates
    //!         having confidence level exceeding the specified confidence
    //!         threshold are added to the envelope    
    LinearEnvelope buildEnvelope( const std::vector< double > & samps, 
                                  double sampleRate, 
                                  double tbeg, double tend, 
                                  double interval,
                                  double lowerFreqBound, double upperFreqBound, 
                                  double confidenceThreshold )
    {
        return buildEnvelope( &samps[0], &samps[0] + samps.size(), sampleRate, 
                              tbeg, tend, interval, 
                              lowerFreqBound, upperFreqBound,
                              confidenceThreshold );
    }

                                 
    //  estimateAt
    //
    //! Return an estimate of the fundamental frequency computed 
    //! at the specified time. The F0Estimate returned stores the
    //! estimate of the fundamental frequency (in Hz) and the 
    //! relative confidence (from 0 to 1) associated with that
    //! estimate.
    //!
    //! \param  sampsBeg is the beginning of a sequence of samples
    //! \param  sampsEnd is the end of the sequence of samples
    //! \param  sampleRate is the sampling rate (in Hz) associated
    //!         with the sequence of samples (used to compute frequencies
    //!         in Hz, and to convert the time from seconds to samples)
    //! \param  time is the time in seconds at which to attempt to estimate
    //!         the fundamental frequency
    //! \param  lowerFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \param  upperFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \return the estimate of fundamental frequency in Hz and the 
    //!         confidence associated with that estimate (see 
    //!         F0Estimate.h)
    
    value_type estimateAt( const double * sampsBeg, 
                           const double * sampsEnd, 
                           double sampleRate, 
                           double time,
                           double lowerFreqBound, double upperFreqBound );

    //  estimateAt
    //
    //! Return an estimate of the fundamental frequency computed 
    //! at the specified time. The F0Estimate returned stores the
    //! estimate of the fundamental frequency (in Hz) and the 
    //! relative confidence (from 0 to 1) associated with that
    //! estimate.
    //!
    //! \param  samps is the beginning of a sequence of samples
    //! \param  nsamps is the length of the sequence of samples
    //! \param  sampleRate is the sampling rate (in Hz) associated
    //!         with the sequence of samples (used to compute frequencies
    //!         in Hz, and to convert the time from seconds to samples)
    //! \param  time is the time in seconds at which to attempt to estimate
    //!         the fundamental frequency
    //! \param  lowerFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \param  upperFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \return the estimate of fundamental frequency in Hz and the 
    //!         confidence associated with that estimate (see 
    //!         F0Estimate.h)
    
    value_type estimateAt( const double * sampsBeg, 
                           unsigned long nsamps,
                           double sampleRate, 
                           double time,
                           double lowerFreqBound, double upperFreqBound )
    {
        return estimateAt( sampsBeg, sampsBeg + nsamps, sampleRate, 
                           time, lowerFreqBound, upperFreqBound );
    }
                           
    //  estimateAt
    //
    //! Return an estimate of the fundamental frequency computed 
    //! at the specified time. The F0Estimate returned stores the
    //! estimate of the fundamental frequency (in Hz) and the 
    //! relative confidence (from 0 to 1) associated with that
    //! estimate.
    //!
    //! \param  samps is the sequence of samples
    //! \param  sampleRate is the sampling rate (in Hz) associated
    //!         with the sequence of samples (used to compute frequencies
    //!         in Hz, and to convert the time from seconds to samples)
    //! \param  time is the time in seconds at which to attempt to estimate
    //!         the fundamental frequency
    //! \param  lowerFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \param  upperFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \return the estimate of fundamental frequency in Hz and the 
    //!         confidence associated with that estimate (see 
    //!         F0Estimate.h)
    
    value_type estimateAt( const std::vector< double > & samps, 
                           double sampleRate, 
                           double time,
                           double lowerFreqBound, double upperFreqBound )
    {
        return estimateAt( &samps[0], &samps[0] + samps.size(), sampleRate, 
                           time, lowerFreqBound, upperFreqBound );
    }
                              


//  -- spectral analysis parameter access/mutation --

    //! Return the frequency-domain main lobe width (in Hz measured 
    //! between zero-crossings) of the analysis window used in spectral
    //! analysis.               
    double windowWidth( void ) const;
    
    //! Set the frequency-domain main lobe width (in Hz measured 
    //! between zero-crossings) of the analysis window used in spectral
    //! analysis.   
    //! 
    //! \param  w is the new main lobe width in Hz            
    void setWindowWidth( double w );         

    

//  -- private auxiliary functions --

private: 

    //  buildSpectrumAnalyzer
    //
    //! Construct the ReassignedSpectrum that will be used to perform
    //! spectral analysis from which peak frequencies and amplitudes 
    //! will be drawn. This construction is performed in a lazy fashion,
    //! and needs to be done again when certain of the parameters change.
    //!
    //! \param  srate is the sampling frequency in Hz, needed to compute
    //!         analysis window parameters    
    void buildSpectrumAnalyzer( double srate );
        

    //  collectFreqsAndAmps
    //
    //! Perform spectral analysis on a sequence of samples, using
    //! an analysis window centered at the specified time in seconds.
    //! Collect the frequencies and amplitudes of the peaks and return
    //! them in the vectors provided. 
    //!
    //! \param  samps is the beginning of a sequence of samples
    //! \param  nsamps is the length of the sequence of Partials
    //! \param  sampleRate is the sampling rate (in Hz) associated
    //!         with the sequence of samples (used to compute frequencies
    //!         in Hz, and to convert the time from seconds to samples)
    //! \param  frequencies is a vector in which to store a sequence of
    //!         frequencies to be used to estimate the most likely 
    //!         fundamental frequency
    //! \param  amplitudes is a vector in which to store a sequence of
    //!         amplitudes to be used to estimate the most likely 
    //!         fundamental frequency
    //! \param  time is the time in seconds at which to collect frequencies
    //!         and amplitudes of spectral peaks
    
    void collectFreqsAndAmps( const double * samps,
                              unsigned long nsamps,
                              double sampleRate,
                              std::vector< double > & frequencies, 
                              std::vector< double > & amplitudes,
                              double time );


//  -- private member variables --

    std::auto_ptr< ReassignedSpectrum > m_spectrum;
                                //! the spectrum analyzer 
                                
    double m_cacheSampleRate;   //! the sample rate used to construct the 

    double m_windowWidth;       //! the width of the main lobe of the window to 
                                //! be used in spectral analysis, in Hz
    
//  disallow these until they are implemented

    FundamentalFromSamples( const FundamentalFromSamples & );
    FundamentalFromSamples & operator= ( const FundamentalFromSamples & );

};   //  end of class FundamentalFromSamples



// ---------------------------------------------------------------------------
//  class FundamentalFromPartials
//
//! Class FundamentalFromPartials represents an algorithm for 
//! time-varying fundamental frequency estimation from instantaneous
//! Partial amplitudes and frequencies based on a likelihood
//!	estimator adapted from Quatieri's Speech Signal Processing text

class FundamentalFromPartials : public FundamentalEstimator
{
//  -- public interface --

public:

//  -- lifecycle --

    //! Construct a new estimator.
    //!
    //! The specified precision is used to terminate the iterative
    //! estimation procedure. If unspecified, the default value,
    //! DefaultPrecisionOver100 * 100 is used. 
    //!
    //! \param precisionHz is the precision in Hz with which the 
    //! fundamental estimates will be made.    
    FundamentalFromPartials( double precisionHz = DefaultPrecisionOver100 * 0.01 );
                                                        

    //! Destructor    
    ~FundamentalFromPartials( void );
    
    //! Construct a copy of an estimator. Nothing much to do since this class
    //! has no data members.
    FundamentalFromPartials( const FundamentalFromPartials & );
    
    //! Pass the assignment opertion up to the base class.
    FundamentalFromPartials & operator= ( const FundamentalFromPartials & );

//  -- fundamental frequency estimation --

    //  buildEnvelope
    //
    //! Construct a linear envelope from fundamental frequency 
    //! estimates taken at the specified interval in seconds 
    //! starting at tbeg (seconds) and ending before tend (seconds).
    //!
    //! \param  begin_partials is the beginning of a sequence of Partials
    //! \param  end_partials is the end of a sequence of Partials
    //! \param  tbeg is the beginning of the time interval (in seconds)
    //! \param  tend is the end of the time interval (in seconds)
    //! \param  interval is the time between breakpoints in the
    //!         fundamental frequency envelope (in seconds)
    //! \param  lowerFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \param  upperFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \param  confidenceThreshold is the minimum confidence level
    //!         resuired for a fundamental frequency estimate to be
    //!         added to the envelope. Lower confidence estimates are
    //!         not added, the envelope returned will not contain
    //!         breakpoints at times associated with low confidence 
    //!         estimates
    //! \return a LinearEnvelope composed of breakpoints corresponding to
    //!         the fundamental frequency estimates at samples of the span
    //!         tbeg to tend at the specified sampling interval, only estimates
    //!         having confidence level exceeding the specified confidence
    //!         threshold are added to the envelope
    LinearEnvelope buildEnvelope( PartialList::const_iterator begin_partials, 
                                  PartialList::const_iterator end_partials,
                                  double tbeg, double tend, 
                                  double interval,
                                  double lowerFreqBound, double upperFreqBound, 
                                  double confidenceThreshold );
                                  
    //  buildEnvelope
    //
    //! Construct a linear envelope from fundamental frequency 
    //! estimates taken at the specified interval in seconds 
    //! starting at tbeg (seconds) and ending before tend (seconds).
    //!
    //! \param  partials is the sequence of Partials
    //! \param  tbeg is the beginning of the time interval (in seconds)
    //! \param  tend is the end of the time interval (in seconds)
    //! \param  interval is the time between breakpoints in the
    //!         fundamental frequency envelope (in seconds)
    //! \param  lowerFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \param  upperFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \param  confidenceThreshold is the minimum confidence level
    //!         resuired for a fundamental frequency estimate to be
    //!         added to the envelope. Lower confidence estimates are
    //!         not added, the envelope returned will not contain
    //!         breakpoints at times associated with low confidence 
    //!         estimates
    //! \return a LinearEnvelope composed of breakpoints corresponding to
    //!         the fundamental frequency estimates at samples of the span
    //!         tbeg to tend at the specified sampling interval, only estimates
    //!         having confidence level exceeding the specified confidence
    //!         threshold are added to the envelope                                        
    LinearEnvelope buildEnvelope( const PartialList & partials, 
                                  double tbeg, double tend, 
                                  double interval,
                                  double lowerFreqBound, double upperFreqBound, 
                                  double confidenceThreshold )
    {
        return buildEnvelope( partials.begin(), partials.end(),
                              tbeg, tend, interval,
                              lowerFreqBound, upperFreqBound,
                              confidenceThreshold );
    }
    
                                 
    //  estimateAt
    //
    //! Return an estimate of the fundamental frequency computed 
    //! at the specified time. The F0Estimate returned stores the
    //! estimate of the fundamental frequency (in Hz) and the 
    //! relative confidence (from 0 to 1) associated with that
    //! estimate.
    //!
    //! \param  begin_partials is the beginning of a sequence of Partials
    //! \param  end_partials is the end of a sequence of Partials
    //! \param  time is the time in seconds at which to attempt to estimate
    //!         the fundamental frequency
    //! \param  lowerFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \param  upperFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \return the estimate of fundamental frequency in Hz and the 
    //!         confidence associated with that estimate (see 
    //!         F0Estimate.h)
    value_type estimateAt( PartialList::const_iterator begin_partials, 
                           PartialList::const_iterator end_partials,
                           double time,
                           double lowerFreqBound, double upperFreqBound );
                           
    //  estimateAt
    //
    //! Return an estimate of the fundamental frequency computed 
    //! at the specified time. The F0Estimate returned stores the
    //! estimate of the fundamental frequency (in Hz) and the 
    //! relative confidence (from 0 to 1) associated with that
    //! estimate.
    //!
    //! \param  partials is the sequence of Partials
    //! \param  time is the time in seconds at which to attempt to estimate
    //!         the fundamental frequency
    //! \param  lowerFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \param  upperFreqBound is the lower bound on the fundamental
    //!         frequency estimate (in Hz)
    //! \return the estimate of fundamental frequency in Hz and the 
    //!         confidence associated with that estimate (see 
    //!         F0Estimate.h)
    value_type estimateAt( const PartialList & partials, 
                           double time,
                           double lowerFreqBound, double upperFreqBound )
    {
            return estimateAt( partials.begin(), partials.end(),
                               time,
                               lowerFreqBound, upperFreqBound );
    }



//  -- private auxiliary functions --

private: 

    //  collectFreqsAndAmps
    //
    //! Collect the frequencies and amplitudes of a range of partials 
    //! at the specified time and return them in the vectors provided. 
    //!
    //! \param  begin_partials is the beginning of a sequence of Partials
    //! \param  end_partials is the end of a sequence of Partials
    //! \param  frequencies is a vector in which to store a sequence of
    //!         frequencies to be used to estimate the most likely 
    //!         fundamental frequency
    //! \param  amplitudes is a vector in which to store a sequence of
    //!         amplitudes to be used to estimate the most likely 
    //!         fundamental frequency
    //! \param  time is the time in seconds at which to collect frequencies
    //!         and amplitudes of the Partials
    void collectFreqsAndAmps( PartialList::const_iterator begin_partials, 
                              PartialList::const_iterator end_partials,
                              std::vector< double > & frequencies, 
                              std::vector< double > & amplitudes,
                              double time );



};   //  end of class FundamentalFromPartials



}   //  end of namespace Loris

#endif  // ndef INCLUDE_FUNDAMENTAL_H