/*****************************************************************************
*                                                                            *
*   SKEW.SPL     Copyright (C) 2007 DSP Development Corporation              *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Calculates the skew of a distribution                       *
*                                                                            *
*   Revisions:    6 Feb 2007  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/

#if @HELP_SKEW

    SKEW

    Purpose: Calculates the skewness of a series.

    Syntax:  SKEW(s, bias)

                   s - the input series

              biased - Optional, an integer.  Bias calculation,

                         0: compute unbiased population estimate (default)
                         1: biased estimate

    Returns: A scalar, the skewness of the series

    Example:
             W1: {3, 4, 5, 2, 3, 4, 5, 6, 4, 7}
             W2: {skew(w1)}
             W3: {skew(w1, 1)}

             W2 == {0.359453}, the unbiased or population skew.
             W3 == {0.303193}, the biased skew.

    Remarks:
             Skewness characterizes the degree of asymmetry of a
             distribution around its mean.  Positive skewness indicates
             a distribution with an asymmetric tail extending toward
             more positive values.  Negative skewness indicates a
             distribution with an asymmetric tail extending toward more
             negative values.

             By default, SKEW calculates the unbiased or population skewness
             as used in SAS, SPSS, and Excel. To calculate the biased
             skew, set the BIASED flag to 1.

             For multi-column data, SKEW returns the skewness of each
             column.

    See Also:
             Kurtosis
             Stdev
#endif


/* biased or unbiased skewness */
ITERATE skew(s, biased, vardef)
{
        local k, n;

        if (argc < 3)
        {
                if (argc < 2)
                {
                        if (argc < 1)
                        {
                                s = refseries(w0);
                        }
                        if (not(isarray(s)))
                        {
                                biased = s;
                                s      = refseries(w0);
                        }
                        else
                        {
                                biased = 0;
                        }
                }
                
                vardef = (biased) ? 1 : 0;
        }

        n = length(s);

        /* base calculation */
        k = sum(((s - mean(s)) / std(s, vardef)) ^ 3);

        if (biased)
        {
                k /= n;
        }
        else
        {
                if (n > 2)
                {
                        k *= n / ((n - 1) * (n - 2));
                }
                else
                {
                        k = nan;
                }
        }

        return(k);
}