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


#if @HELP_PHASESPEC

    PHASESPEC

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

    Syntax:  PHASESPEC(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 phase of the N point normalized 
             complex spectrum of the input.

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

             W2 contains 500 real values between 0 and 500 Hz.  W3
             contains 1000 values with frequency values between 0 to
             1000 Hz. W4 contains 1000 values between -500 and 500 Hz. 
             In all cases, the amplitude values range from -2*pi to
             2*pi.

    Remarks:
             PHASESPEC computes the phase 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:

             phasespec(s) = phase(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.

             See AMPSPEC to display the complex amplitude spectrum.

             See MAGSPEC to display the magnitude 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
             phase
             spectrum
#endif


/* returns phase of the complex amplitude spectrum - |FFT(s) / L| */
ITERATE phasespec(s, N, type)
{
        local p;

        p = phase(ampspec(s, N, type, __FUNC__));

        return(p);
}