/*****************************************************************************
*                                                                            *
*   XBLOCKSTD.SPL  Copyright (C) 2023 DSP Development Corporation            *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Calculates the block standard deviation with a duration     *
*                                                                            *
*   Revisions:    1 Aug 2023  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/

#if @HELP_XBLOCKSTD

    XBLOCKSTD

    Purpose: Calculates the moving block standard deviation of a series
             given a duration.

    Syntax:  XBLOCKSTD(series, xdur, dof)

                series - A series, the input series

                  xdur - A real, the X duration used to compute the integer
                         number of samples for the non-overlapping moving
                         interval.
 
                   dof - Optional. An integer, degrees of freedom
                         normalization.

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

                           1: Normalize by 1 / N

    Returns: A series or table.

    Example:
             W1: {1, 2, 4, 7};setdeltax(1/100)
             W2: blockstd(w1, 3)
             W3: xblockstd(w1, 0.02)

             W1 contains the input data with a sample rate of 100 Hz.

             W2 computes a 3 point moving block standard deviation.
             
             W3 computes the same moving block standard deviation except the
             block size is specified in terms of seconds. Since a 0.02 interval
             equates to 3 samples, both functions return the series:
             
             {1.528, 0}

    Example:
             W1: integ(gnorm(10000, 1/10000)) * 1000
             W2: blockstd(w1, 51)
             W3: xblockstd(w1, 0.005)
             W4: W2 - W3

             W1 synthesizes 10000 samples of data with a sample rate of 10kHz.

             W2 computes a 51 point moving block standard deviation.

             W3 computes a moving block standard deviation with an interval of
             0.005 seconds.

             Since a 0.005 interval equates to 51 samples, the two block
             standard deviation results are equal.

    Remarks:
             XBLOCKSTD computes a moving standard deviation with
             non-overlapping blocks of duration XDUR.

             The block duration XDUR is converted to the integer block
             interval N with:

               N = XDUR / deltax(s) + 1

             where XDUR >= deltax(s)

             See MOVAVG for more details on RAMPFLAG.

    See Also:
             Blockrms
             Blockstd
             Blockvar
             Movavg
             Movrms
             Var
             Xblockrms
             Xblockvar
#endif


/* centered block standard deviation given a duration used to compute the integer sample interval */
ITERATE xblockstd(s, xdur, dof = 0, flag1 = "", flag2 = "", flag3 = "")
{
        local y;

        /* call common driver function */
        y = xmovfun(s, __FUNC__, strextract(__FUNC__, 2, -1), xdur, nan, dof, flag1, flag2, flag3);

        return(y);
}