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


#if @HELP_CUMMAX

    CUMMAX

    Purpose: Calculates the cumulative maximum of a series.

    Syntax:  CUMMAX(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:
             cummax({20, 15, 30, 10, 25})

             returns a new series containing the cumulative
             maximum {20, 20, 30, 30, 30}.

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

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

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

             W2 == {20, 20, 20, 20, 25}
             W3 == {20, 20, 20, 20, 25}
             W4 == {20, 20, 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 maximum remains at NaN.

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

             W2 == {3 + i, 4 + 2i, 4 + 2i, 2 + 4i, 8 + 5i} 
             W3 == {3 + i, 4 + 2i, 4 + 2i, 2 + 4i, 8 + 5i} 
             W4 == {3 + i, 4 + 2i, 4 + 2i, 4 + 2i, 8 + 5i} 

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

             W4 compares complex values based on the real part.

    Remarks:
             CUMMAX calculates the cumulative maximum of a series.

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

             "CMPFLAG" is ignored for real series.

             See CUMMIN for the cumulative minimum.

    See Also:
             CUMAVG
             CUMMIN
             CUMPROD
             CUMSUM
             MAX
#endif


/* cumulative maximum */
cummax(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';
        }

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

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

        return(s);
}