/*****************************************************************************
*                                                                            *
*   FLATTOPWIN.SPL  Copyright (C) 2010 DSP Development Corporation           *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:       Randy Race                                                 *
*                                                                            *
*   Synopsis:     Multiplies series with an alternative flattop window       *
*                                                                            *
*   Revisions:    13 Jul 2010  RRR  Creation                                 *
*                                                                            *
*****************************************************************************/


#if @HELP_FLATTOPWIN

    FLATTOPWIN

    Purpose: Multiplies a series with an alternative 4 point flattop window

    Syntax:  FLATTOPWIN(s, ampflag, "sym")

                    s - A series or array

              ampflag - Optional, an integer, the correction factor.
 
                         0: do not correct amplitude (default)
                         1: correct amplitude
                         2: correct RMS 
                         3: correct mean squared amplitude

                "sym" - Optional. A string, the symmetry mode.

                         "symmetric" : Starting and ending points are equal
                                       (default).

                          "periodic" : Periodically extended window.

   Alternate Syntax:  
             
             FLATTOPWIN(N, ampflag, "sym")

                    N - An integer, the length of the window.

              ampflag - Optional, an integer, the correction factor.

                         0: do not correct amplitude (default)
                         1: correct amplitude
                         2: correct RMS 
                         3: correct mean squared amplitude

                "sym" - Optional. A string, the symmetry mode.

                         "symmetric" : Starting and ending points are equal
                                       (default).

                          "periodic" : Periodically extended window.

    Returns: A series or array

    Example:
             W1: gsin(1000, .001, 45)
             W2: spectrum(flattopwin(W1))

             The MAX of W2 == 1.0 at 45 Hertz.

    Example:
             flattopwin(1000, "periodic")

             returns a 1000 point periodic flattop window.

    Remarks:
             The flattop window preserves the amplitude characteristics of
             the input series at the expense of frequency domain "smearing".

             If the input is an integer rather than a series, the N
             point flattop window is returned.
             
             FLATTOPWIN creates a symmetric 4 point flattop window using the
             following formula:

             w[k]  = 0.21557895 - 0.416631580 * cos(2*pi*(k-1)/(N-1))
                                + 0.277263168 * cos(4*pi*(k-1)/(N-1))
                                - 0.083578967 * cos(6*pi*(k-1)/(N-1))
                                + 0.006947368 * cos(8*pi*(k-1)/(N-1))

             The periodic form is computed with:

             w[k]  = 0.21557895 - 0.416631580 * cos(2*pi*(k-1)/N)
                                + 0.277263168 * cos(4*pi*(k-1)/N)
                                - 0.083578967 * cos(6*pi*(k-1)/N)
                                + 0.006947368 * cos(8*pi*(k-1)/(N-1))

             If ampflag == 1, the correction factor is the mean of
             the spectral window. This assures that the spectrum of a
             sinusoid of amplitude 1.0 has a peak of 1.0.

             If ampflag == 2, the correction is applied as follows:

             w = flattopwin(s) * rms(s) / rms(flattopwin(s))

             sqrt(area(psd(w))) == rms(s)    approximately

             If ampflag == 3, the correction is applied as follows:

             w = flattopwin(s) / sqrt(win * win / length(win))

             where win is the windowing function.

             The "sym" flag controls the window symmetry as follows: 

             "Symmetric" (the default) sets the first and last points
             to be equal.  An N point symmetric window can be
             constructed by creating an N-1 point periodic window and
             setting the Nth point to the value of the first point.

             "Periodic" or "iso" creates a periodic window function
             useful in spectrum analysis applications.

             FLATTOPWIN does not conform to the ISO 18431-1 standard.

             See FLATTOP to create a flattop window that conforms to
             the ISO 18431-1 standard for windowing functions.

    See Also:
             flattop
             gflattop
             hamming
             hanning
             kaiser
             winfunc
#endif


/* multiply a series with a flattop window */
SERIES flattopwin(s, ampflag, sym)
{
        (s, ampflag, sym) = flattopwin_parse_args(s, ampflag, sym);
        
        return(winfunc(6, s, ampflag, 2, sym));
}


/* input args */
flattopwin_parse_args(s, ampflag, sym)
{
        local temp;

        if (argc < 3)
        {
                if (argc < 2)
                {
                        if (argc < 1) error("flattopwin - input series required");
                        
                        ampflag = 0;
                }
                
                sym = "symmetric";
        }
        
        if (isstring(ampflag))
        {
                temp    = ampflag;
                ampflag = (isstring(sym)) ? 0 : sym;
                sym     = temp;
        }
        
        return(s, ampflag, sym);
}