/*---------------------------------------------------------------------------*
 *                                   IT++			             *
 *---------------------------------------------------------------------------*
 * Copyright (c) 1995-2001 by Tony Ottosson, Thomas Eriksson, Pål Frenger,   *
 * Tobias Ringström, and Jonas Samuelsson.                                   *
 *                                                                           *
 * Permission to use, copy, modify, and distribute this software and its     *
 * documentation under the terms of the GNU General Public License is hereby *
 * granted. No representations are made about the suitability of this        *
 * software for any purpose. It is provided "as is" without expressed or     *
 * implied warranty. See the GNU General Public License for more details.    *
 *---------------------------------------------------------------------------*/

/*! 
  \file 
  \brief Definitions of signal processing functions
  \author Tony Ottosson, Thomas Eriksson, Pål Frenger, and Tobias Ringström

  1.9

  2003/06/04 10:38:31
*/
 
#ifndef __sigfun_h
#define __sigfun_h

#include "base/vec.h"
#include "base/transforms.h"

namespace itpp {

  /*! \defgroup sigproc Signal Processing Functions
   */
  //!@{

  /*! 
    \brief Cross-correlation calculation

    \c z=xcorr(x,y,max_lag), where \a x and \a y are length \a M vectors \a (M>1), returns the length \c 2*max_lag+1 
    cross-correlation sequence \a z. (lags: \c -max_lag,...,0,...,max_lag)

    For \c max_lag=-1 the cross-correlation sequence is of length \c 2*M-1, i.e., the cross-correlation for all possible lags.

    Scaling options \a scaleopt:
    \arg \a none \c => No scaling of the cross-correlation vector
    \arg \a biased \c => Scales the cross-correlation vector by \c 1/M
    \arg \a unbiased \c => Scales the cross-correlation vector by \c 1/(M-abs(lag))
    \arg \a coeff \c => Normalises the cross-correlation to 1 for zero lag.

    \note \c max_lag \c <= \c M-1
    \note If \c x and \c y are of different length, the shortest one is zero-padded

    \param x (Input) Vector of samples
    \param y (Input) Vector of samples
    \param out (Output) The cross correlation between \a x and \a y.
    \param max_lag (Input) Maximum lag for which the cross-correlation is calculated. The output vector is of size \c 2*maxlag+1. 
    Default value: \c max_lag=-1 calculates the cross-correlations for all possible lags
    \param scaleopt (Input) Indicates how the cross-correlation function should be scaled. Default value: \c "none" indicates that no scaling is done
  */
  void xcorr(vec &x, vec &y, vec &out, const int max_lag=-1, const string scaleopt="none");

  /*! 
    \brief Cross-correlation calculation

    \c z=xcorr(x,y,max_lag), where \a x and \a y are length \a M vectors \a (M>1), returns the length \c 2*max_lag+1 
    cross-correlation sequence \a z. (lags: \c -max_lag,...,0,...,max_lag)

    For \c max_lag=-1 the cross-correlation sequence is of length \c 2*M-1, i.e., the cross-correlation for all possible lags.

    Scaling options \a scaleopt:
    \arg \a none \c => No scaling of the cross-correlation vector
    \arg \a biased \c => Scales the cross-correlation vector by \c 1/M
    \arg \a unbiased \c => Scales the cross-correlation vector by \c 1/(M-abs(lag))
    \arg \a coeff \c => Normalises the cross-correlation to 1 for zero lag.

    \note \c max_lag \c <= \c M-1
    \note If \c x and \c y are of different length, the shortest one is zero-padded

    \param x (Input) Vector of samples
    \param y (Input) Vector of samples
    \param max_lag (Input) Maximum lag for which the cross-correlation is calculated. The output vector is of size \c 2*maxlag+1. 
    Default value: \c max_lag=-1 calculates the cross-correlations for all possible lags
    \param scaleopt (Input) Indicates how the cross-correlation function should be scaled. Default 
    value: \c "none" indicates that no scaling is done
    \returns The cross correlation between \a x and \a y.
  */
  vec xcorr(vec &x, vec &y, const int max_lag=-1, const string scaleopt="none");

  /*! 
    \brief Auto-correlation calculation

    \c z=xcorr(x,max_lag), where \a x and is a length \a M vector \a (M>1), returns the length \c 2*max_lag+1 auto-correlation 
    sequence \a z. (lags: \c -max_lag,...,0,...,max_lag)

    For \c max_lag=-1 the auto-correlation sequence is of length \c 2*M-1, i.e., the cross correlation for all possible lags.

    Scaling options \a scaleopt:
    \arg \a none \c => No scaling of the auto-correlation vector
    \arg \a biased \c => Scales the auto-correlation vector by \c 1/M
    \arg \a unbiased \c => Scales the auto-correlation vector by \c 1/(M-abs(lag))
    \arg \a coeff \c => Normalises the auto-correlation so that \c acf(x)=1 for zero lag.

    \note \c max_lag \c <= \c M-1

    \param x (Input) Vector of samples
    \param out (Output) The auto-correlation of \a x.
    \param max_lag (Input) Maximum lag for which the auto-correlation is calculated. The output vector is of size \c 2*maxlag+1. 
    Default value \c max_lag=-1 calculates the auto-correlations for all possible lags
    \param scaleopt (Input) Indicates how the auto-correlation function should be scaled. 
    Default value: \c "none" indicates that no scaling is done
  */
  void xcorr(const vec &x, vec &out, const int max_lag=-1, const string scaleopt="none");

  /*! 
    \brief Auto-correlation calculation

    \c z=xcorr(x,max_lag), where \a x and is a length \a M vector \a (M>1), returns the length \c 2*max_lag+1 auto-correlation 
    sequence \a z. (lags: \c -max_lag,...,0,...,max_lag)

    For \c max_lag=-1 the auto-correlation sequence is of length \c 2*M-1, i.e., the cross correlation for all possible lags.

    Scaling options \a scaleopt:
    \arg \a none \c => No scaling of the auto-correlation vector
    \arg \a biased \c => Scales the auto-correlation vector by \c 1/M
    \arg \a unbiased \c => Scales the auto-correlation vector by \c 1/(M-abs(lag))
    \arg \a coeff \c => Normalises the auto-correlation so that \c acf(x)=1 for zero lag.

    \note \c max_lag \c <= \c M-1

    \param x (Input) Vector of samples
    \param max_lag (Input) Maximum lag for which the auto-correlation is calculated. The output vector is of size \c 2*maxlag+1. 
    Default value \c max_lag=-1 calculates the auto-correlations for all possible lags.
    \param scaleopt (Input) Indicates how the auto-correlation function should be scaled. 
    Default value: \c "none" indicates that no scaling is done.
    \returns The auto-correlation of \a x.
  */
  vec xcorr(const vec &x, const int max_lag=-1, const string scaleopt="none");

  //! Covariance calculation.  Set is_zero_mean if m already has zero mean.
  mat cov(const mat &m, bool is_zero_mean=false);

  //vec cov(const vec &x, short order);

  //! Power spectrum calculation using the Welch method and a Hanning window.
  vec spectrum(const vec &v, int nfft=256, int noverlap=0);

  //! Power spectrum calculation using the Welch method and the supplied window w.
  vec spectrum(const vec &v, const vec &w, int noverlap=0);

  //! Power spectrum calculation of a filter with transfer function a(z)
  vec filter_spectrum(const vec &a, int nfft=256);

  //! Power spectrum calculation of a filter with transfer function a(z)/b(z)
  vec filter_spectrum(const vec &a, const vec &b, int nfft=256);

  //!@}

} //namespace itpp

#endif // __sigfun_h