/*****************************************************************************
*                                                                            *
*   MAGSPEC.SPL   Copyright (C) 2010 DSP Development Corporation             *
*                             All Rights Reserved                            *
*                                                                            *
*   Author:       Randy Race                                                 *
*                                                                            *
*   Synopsis:     magnitude of N point normalized complex amplitude spectrum *
*                                                                            *
*   Revisions:    18 Jul 2010  RRR  Creation                                 *
*                                                                            *
*****************************************************************************/


#if @HELP_MAGSPEC

    MAGSPEC

    Purpose: Calculates the magnitide of the N point complex amplitude spectrum.

    Syntax:  MAGSPEC(s, N, type)

                     s - The input series or array.

                    N  - An optional integer, the amplitude spectrum length.
                         Defaults to the length of the input series.

                  type - Optional. A string, the output type.
                            "single" : single sided display (default)
                            "double" : double sided display
                            "shift"  : double sided display shifted about 0 Hz.

    Returns: A real series or array, the magnitude of the N point normalized 
             complex spectrum of the input.

    Example:
             W1: gcos(1000, 1/1000, 100)
             W2: magspec(w1)
             W3: magspec(w1, "double")
             W4: magspec(w1, "shift")

             W2 contains 500 complex values with a peak at 100 Hz. W3 contains
             1000 values with peaks at 100 Hz and 900 Hz. W4 contains 1000
             values with peaks at -100 Hz and +100 Hz. In all cases, the 
             magnitude of the peak values is 0.5, 1/2 the amplitude of the
             input cosine.

    Example:
             W1: gsqr(1000, 1/1000, 4)
             W2: magspec(w1, "shift")
             W3: {mean(mag(w1)^2)}
             W4: {sum(w2^2)}

             W3 == W4 == 0.5 verifying a form of Paresval's Theorem. 

    Remarks:
             MAGSPEC computes the magnitude of N equally spaced samples
             of the normalized complex amplitude spectrum by using the
             FFT. The raw FFT values are normalized by the length of
             the input series such that:

             magspec(s) = mag(fft(s)) / length(s)

             For a sampling rate Fs, the default single sided amplitude 
             spectrum displays N/2 frequency values from 0 to Fs/2. The
             double sided amplitude spectrum, "double", displays N values
             from 0 to Fs and the shifted spectrum, "shift", displays
             N values from -Fs/2 to Fs/2.

             Unlike SPECTRUM, MAGSPEC does not scale the values between
             0 and Fs/2 by 2.  Thus, the single sided amplitude
             spectrum of a 1 volt sinusoid of frequency F shows a peak
             of 0.5 at frequency F and the double sided shifted amplitude
             spectrum shows peaks of 0.5 located at -F and +F.

             The "double" sided or "shift" amplitude spectrum obeys a
             form of Parseval's Theorem such that:

             mean(mag(s)^2) == sum(magspec(s)^2)

             See AMPSPEC to display the complex amplitude spectrum.

             See PHASESPEC to display the phase spectrum.

             See SPECTRUM to compute a normalized frequency spectrum such
             that a 1 volt sinusoid at frequency F displays a peak of
             1 at frequency F.


    See Also:
             ampspec
             fft
             magspec
             phasespec
             spectrum
#endif


/* returns magnitude of the complex amplitude spectrum - |FFT(s) / L| */
ITERATE magspec(s, N, type)
{
        local m;

        m = mag(ampspec(s, N, type, __FUNC__));

        return(m);
}