/*****************************************************************************
*                                                                            *
*   NUTTALL.SPL   Copyright (C) 2021 DSP Development Corporation             *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:       Randy Race                                                 *
*                                                                            *
*   Synopsis:     Multiplies a series with a Blackman-Nuttall Window         *
*                                                                            *
*   Revisions:    18 Oct 2021  RRR  Creation                                 *
*                                                                            *
*****************************************************************************/


#if @HELP_NUTTALL

    NUTTALL

    Purpose: Multiplies a series with a Blackman-Nuttall window

    Syntax:  NUTTALL(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. Conforms 
                                      to ISO standard.
   Alternate Syntax:  
             
             NUTTALL(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. Conforms 
                                      to ISO standard.

    Returns: A series or array

    Example:
             W1: gsin(1000, .001, 45)
             W2: spectrum(nuttall(W1))
             W3: spectrum(nuttall(W1, 1))

             The MAX of W2 == 0.359 and the MAX of W3 == 1.0. The amplitude
             of the spectrum in W3 has been corrected to take into account
             amplitude effects of the Hamming window.

   Example:
             nuttall(1000, "periodic")

             returns a 1000 point periodic Blackman-Nuttall window.

    Remarks:
             If the input is an integer rather than a series, the N
             point Blackman-Nuttall window is returned.

             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 = nuttall(s) * rms(s) / rms(nuttall(s))

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

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

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

             where win is the windowing function.

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

             "Symmetric" 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. "Periodic" or
             "iso" conforms to the ISO 18431-1 standard for windowing
             functions.

             See GNUTTALL for more details on the Blackman-Nuttall window.

    See Also:
             Flattop
             Gblackman
             Gnuttall
             Hamming
             Hanning
             Kaiser
             Winfunc
#endif


/* multiply a series with a Blackman-Nuttall window */
SERIES nuttall(s, ampflag, sym)
{
        return(winfunc(10, s, ampflag, sym));
}