/*****************************************************************************
*                                                                            *
*   STATSUM.SPL  Copyright (C) 2014 DSP Development Corporation              *
*                                 All Rights Reserved                        *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Computes summary statistics for one or more series          *
*                                                                            *
*   Revisions:   21 Jun 2014  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_STATSUM

    STATSUM

    Purpose: Computes summary statistics for one or more series.

    Syntax:  STATSUM(s1, s2, s3, ..., sN)

              sN - One or more series.

    Returns: A table, the summary statistics for each column of the input
             series.

    Example:
             W1: 1..10;
             W2: 1..100;
             W3: statsum(w1, w2)

             W3 contains a table similar to:

      Sample Size  Mean  Variance    Std. Deviation  Std. Error  Maximum  Minimum  Range  RMS
          10,       5.5,    9.167,      3.0277,       0.95743,     10,      1,       9,   6.2048 
         100,      50.5,  841.667,     29.0115,       2.90115,    100,      1,      99,  58.1679


    Remarks:
             If any input series contains more than one column, the summary
             statistics of each column is computed.
            
    See Also:
             Length
             Max
             Mean
             Min
             RMS
             Stats
             Stdev
#endif


/* summary statistics of 1 or more series */
statsum(argv)
{
        local s, j, cnt, stats;

        cnt   = argc;
        stats = {};

        loop (j = 1..cnt)
        {
                s = getargv(j);

                if (isarray(s))
                {
                        /* compute and append columns */
                        stats = ravel(stats, statsum_stats(s));
                }
        }

        /* label columns */
        if (length(stats) > 0)
        {
                stats = transpose(stats);

                setcomment(stats, "Sample Size",    1, 1);
                setcomment(stats, "Mean",           1, 2);
                setcomment(stats, "Variance",       1, 3);
                setcomment(stats, "Std. Deviation", 1, 4);
                setcomment(stats, "Std. Error",     1, 5);
                setcomment(stats, "Maximum",        1, 6);
                setcomment(stats, "Minimum",        1, 7);
                setcomment(stats, "Range",          1, 8);
                setcomment(stats, "RMS",            1, 9);
        }

        /* set to table */
        setplottype(stats, 0);
        setplotstyle(stats, 4);

        if (outargc == 0)
        {
                stats;
                tableview;
        }
        else
        {
                return(stats);
        }
}


/* compute individual summary statistics */
ITERATE statsum_stats(s)
{
        local stats, mean, std, var, len;

        (mean, std, var) = stats(s);
        len = length(s);

        stats = {len, mean, var, std, std / sqrt(len), max(s), min(s), max(s) - min(s), rms(s)};

        return(stats);
}