/*****************************************************************************
*                                                                            *
*   ROWSTDEV.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_ROWSTDEV

    ROWSTDEV

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

    Syntax:  ROWSTDEV(series, mode, checknan)

                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

              checknan - Optional. An integer flag, scan series for NaN.

                          0: do not scan
                          1: scan (default)

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

    Example:
             W1: ravel(1..12, 3)
             W2: rowstdev(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))

             By default, the input is scanned for NaN values and they are
             removed. For slightly faster processing, set CHECKNAN to 0 if
             the data is known not to contain NaNs.

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

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


/* row-wise standard deviation */
rowstdev(a, mode, checknan)
{
        local m, sd;

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

                checknan = 1;
        }

        if (numcols(a) == 1)
        {
                sd = zeros(length(a), 1, deltax(a));
        }
        else
        {
                /* divisor */
                m = (mode > 0) ? 0 : 1;

                if (checknan)
                {
                        /* strip NaN */
                        a = removena(a);
                }

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

        return(sd);
}