/*****************************************************************************
*                                                                            *
*   CUMMIN.SPL   Copyright (C) 2023 DSP Development Corporation              *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Cumulative minimum                                          *
*                                                                            *
*   Revisions:   11 Jun 2023  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_CUMMIN

    CUMMIN

    Purpose: Calculates the cumulative minimum of a series.

    Syntax:  CUMMIN(series, "nanflag", "cmpflag")

                 series - Any series, multi-series table, or expression
                          resulting in a series or table.

              "nanflag" - Optional. A string, the NaN handling method.

                          "omitnan"    : Ignore NaN values (default)

                          "includenan" : Include NaN values

              "cmpflag" - Optional. A string, the complex compare method.

                          "abs"  : Compare complex values based on the
                                   magnitude, use phase to break ties (default)

                          "real" : Compare complex values based on the real
                                   part, use the imaginary part to break ties.

    Returns: A series or table.

    Example:
             cummin({20, 15, 30, 10, 25}

             returns a new series containing the cumulative
             minimum {20, 15, 15, 10, 10}.

    Example:
             W1: integ(gnorm(1000, 1))
             W2: cummin(W1)

             max(W1) == W2[end] 
       
             The last point of CUMMIN is the overall minimum of the
             input data.

    Example:
             W1: {20, 15, nan, nan, 25}
             W2: cummin(w1)
             W3: cummin(w1, "omitnan")
             W4: cummin(w1, "includenan")

             W2 == {20, 15, 15, 15, 15}
             W3 == {20, 15, 15, 15, 15}
             W4 == {20, 15, nan, nan, nan}

             Both W2 and W3 ignore the NaN values.
             
             W4 includes the NaN values such that once an NaN is
             encountered, the cumulative minimum remains at NaN.

    Example:
             W1: {3 + i, 4 + 2i, 2 + 3i, 2 + 4i, 8 + 5i}
             W2: cummin(w1)
             W3: cummin(w1, "abs")
             W4: cummin(w1, "real")

             W2 == {3 + i, 3 + i, 3 + i,  3 + i,  3 + i} 
             W3 == {3 + i, 3 + i, 3 + i,  3 + i,  3 + i} 
             W4 == {3 + i, 3 + i, 2 + 3i, 2 + 3i, 2 + 3i} 

             Both W2 and W3 compare complex values based on the magnitude.

             W4 compares complex values based on the real part.

    Remarks:
             CUMMIN calculates the cumulative minimum of a series.

             The nth value of the output series is equal to the minimum of
             the first n points of the input series.

             "CMPFLAG" is ignored for real series.

             See CUMMAX for the cumulative maximum.

    See Also:
             CUMAVG
             CUMMAX
             CUMPROD
             CUMSUM
             MIN
#endif


/* cumulative minimum */
cummin(s, dim = 1, nanmode = "", cmp_method = "")
{
        local dof;

        /* args */
        (s, dim, dof, nanmode, cmp_method) = cumfun_parse_args(s, dim, 1, nanmode, cmp_method);

        if (dim > 1) 
        {
                if (dim > 2) 
                {
                        return(s);
                }

                s = s';
        }

        /* partmin computation */
        s = partmin(s, nanmode, cmp_method);

        if (dim > 1)
        {
                s = s';
        }

        return(s);
}