/*****************************************************************************
*                                                                            *
*   FACOV.SPL   Copyright (C) 2000 DSP Development Corporation               *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Auto-covariance using FFT's
*                                                                            *
*   Revisions:    2 May 2000  RRR  Creation - from FREQ.MAC                  *
*                                                                            *
*****************************************************************************/

#if @HELP_FACOV

    FACOV

    Purpose: Auto-covariance using the FFT method

    Syntax:  FACOV(s, norm)

                  s - input series

               norm - optional integer, normalization method,

                      0: None,
                      1: Unity (-1 to 1)
                      2: Biased
                      3: Unbiased

                      defaults to 0: None


    Returns: A series

    Example:
             W1: gsin(1000, .001, 4)
             W3: acorr(w1)

             Performs the auto-covariance of a sinewave. The
             peaks of the result indicate the waveform is very similar
             to itself at the time intervals where the peaks occur, i.e.
             the waveform is periodic.

    Example:
             W1: gsin(1000, .001, 4)
             W2: gnorm(1000, .001)
             W3: facov(w1, 1)
             W4: facov(w2, 1)

             W3 displays the auto-covariance of a sinewave normalized
             to -1 and 1. W4 shows the normalized auto-covariance of
             random noise.

             The normalized maximum of both results 1.0 at time t == 0,
             indicating the expected perfect covariance at time t == 0
             (true for all series).

             The waveform of W4 displays only one distinct peak at t == 0,
             indicating that W2 is not correlated with itself and is
             non-periodic.

             Both waveforms display a triangular envelope due to the
             assumption that the input series is zero before the first
             sample and after the last sample.


    Remarks:
             The auto-covariance is used to determine how similar a
             series is to itself or if a series is periodic. FACOV
             performs covariance by computing the FFT of the input
             series.

             The output length L is:

                      L = 2 * length(s) + 1

             The zeroth lag component is the mid point of the series.

             The BIASED normalization divides the result by M, the
             length of the input series.

             The UNBIASED normalization divides the result by

                              M - abs(M - i - 1) + 1

             where i is the index of the result.

             See ACOV for the time domain implementation.


    See Also:
             Acorr
             Acov
             Conv
             Fconv
             Facorr
             Fxcorr
#endif


/* frequency domain auto-covariance */
facov(s1, norm)
{
        return(facorr(s1 - colmean(s1), norm));
}