/*****************************************************************************
*                                                                            *
*   MOVVAR.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_MOVVAR

    MOVVAR

    Purpose: Calculates the centered moving variance of a series.

    Syntax:  MOVVAR(series, n, dof, "nanflag", "edgeflag")

                  series - A series, the input.

                        n - An integer, the block size.

                      dof - Optional. An integer, degrees of freedom
                            normalization.

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

                             1: Normalize by 1 / N

                 "naflag" - Optional. A string, the NA handling method.

                             "includenan" : include NA values (default)
                                "omitnan" : ignore NA values

               "edgeflag" - Optional. A string, the edge processing flag.

                                "full" : process all segments (default)

                             "discard" : ignore partial segments 

                              "shrink" : shrink the segment size to actual
                                         number of samples at the edge
                                         segments  


    Returns: A series or table.

    Example:
             W1: {1, 2, 4, 7}
             W2: movvar(w1, 3)

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

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

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

    Remarks:
             For speed, this routines uses the builtin function MOVSTDEV.
             
             See XMOVVAR to specify the interval N as a duration.

             See MOVAVG for details on NAFLAG and EDGEFLAG.

    See Also:
             Blockvar
             Movavg
             Movstd
             Std
             Var
             Xblockvar
             Xmovvar
#endif


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

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

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

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

        return(mvar);
}