/*****************************************************************************
*                                                                            *
*   MOVVARIANCE.SPL   Copyright (C) 2022 DSP Development Corporation         *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Calculates the moving variance                              *
*                                                                            *
*   Revisions:    9 Nov 2022  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/

#if @HELP_MOVVARIANCE

    MOVVARIANCE

    Purpose: Calculates the "moving" variance of a series.

    Syntax:  MOVVARIANCE(series, n, rampflag, dof)

                series - A series, the input.

                     n - An integer, the block size.

              rampflag -  An integer, endpoint handling.

                           0: do not ramp up/down endpoints

                           1: ramp up/down endpoints (default)

                   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}
             W2: movvariance(w1, 3)

             returns the series {0, 0.5, 2.333, 6.333, 4.5, 0}

    Example:
             W1: {1, 2, 4, 7}
             W3: movvariance(w1, length(w1))

             W3[length(w1)] == var(w1) == 7.0

    Remarks:
             For speed, this routines uses the builtin function MOVSTDEV.

    See Also:
             Movavg
             Movstd
             Std
             Var
#endif


/* moving variance */
ITERATE movvariance(s, n, rampflag = 1, dof = 0, flag1 = "", flag2 = "", flag3 = "")
{
        local mvar;

        /* hurdles */
        if (argc < 2)
        {
                error(sprintf("%s - series and block size required", __FUNC__));
        }

        if (isstring(rampflag))
        {
                flag3    = flag2;
                flag2    = flag1;
                flag1    = rampflag;
                rampflag = 1;
        }

        if (isstring(dof))
        {
                flag3 = flag2;
                flag2 = flag1;
                flag1 = dof;
                dof   = 0;
        }

        /* use faster, more accurate built-in */
        mvar = movstdev(s, n, rampflag, dof, flag1, flag2, flag3, "variance");

        return(mvar);
}