/*****************************************************************************
*                                                                            *
*   ROWSTD.SPL  Copyright (C) 2009, 2014 DSP Development Corporation       *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:       Randy Race                                                 *
*                                                                            *
*   Synopsis:     Calculates the standard deviation of each row of a series  *
*                                                                            *
*   Revisions:    12 Jul 2009  RRR  Creation                                 *
*                 18 Aug 2014  RRR  removena                                 *
*                                                                            *
*****************************************************************************/

#if @HELP_ROWSTD

    ROWSTD

    Purpose: Calculates the standard deviation of each row of a multi-column series.

    Syntax:  ROWSTD(series, mode)

              series - The input series or table

                mode - Optional. An integer. The normalization mode. 
                       For N = length(series):

                        0: Normalize by 1/(N-1)  (default)
                        1: Normalize by 1/N

    Returns: A one column series with the same number of rows as the input series. 

    Example:
             W1: ravel(1..12, 3)
             W2: rowstd(w1)

             Returns {3.872983, 3.872983, 3.872983}, the standard deviation of
             each row of W1.
 
    Remarks:
             If s is the input series and N the length of the series,
             the basic form of the sample standard deviation (mode == 0)
             is:

                stdev(s) = sqrt(sum((s - mean(s))^2/(N-1)))

             The population standard deviation (mode == 1) is defined as:

                stdev(s) = sqrt(sum((s - mean(s))^2/N))

             ROWSTD computes the standard deviation of each row of a multi-column
             series.

             ROWSTD does not assume each column of the series contains the
             same number of rows.
            
    See Also:
             Colstdev
             Rowstdev
             Stats
             Stderr
             Stdev
#endif


rowstd(a, mode)
{
        local m, sd;

        if (argc < 2)
        {
                if (argc < 1) error(sprintf("%s - input series required", __FUNC__));
                
                mode = 0;
        }

        if (numcols(a) == 1)
        {
                sd = zeros(length(a), 1, deltax(a));
        }
        else
        {
                a = removena(a);

                /* mean of each row replicated as a table */
                m = repmat(rowavg(a), 1, numcols(a));

                /* standard deviation calculation */
                sd = sqrt(rowsum((a - m)^2) / (rowlen(a) - 1));

                if (mode > 0)
                {
                        /* re-normalize to 1/N */
                        sd = sqrt(sd * sd * (rowlen(a) - 1) / rowlen(a));
                }
        }

        return(sd);
}