/*****************************************************************************
*                                                                            *
*   COLAREA.SPL    Copyright (C) 2024 DSP Development Corporation            *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:    Randy Race                                                    *
*                                                                            *
*   Synopsis:  Computes the area of each column of a series                  *
*                                                                            *
*   Revisions: 13 Feb 2024  RRR  Creation                                    *
*                                                                            *
*****************************************************************************/


#if @HELP_COLAREA

    COLAREA

    Purpose: Computes the area of each column of a multi-column series.

    Syntax:  COLAREA(s, start, length)

               series - A multi-column series.
   
                start - Optional. An integer, the starting sample for the
                        area calculation. Defaults to 1, the first point.
      
               length - Optional. An integer, the length of the section.
                        Only valid if START has been specified. Defaults
                        to the length of the section from START to the 
                        last value of the series.
         

    Returns: A series, a 1xN array of area values where N is the number of
             columns of the input series.

    Example:
             W1: gsin(101, 1/101, 0.5);setvunits("V");sethunits("A")
             W2: 1..length(w1);setvunits("m");sethunits("m")
             W3: gcos(length(w1), deltax(w1), 0.125);setvunits("ft");sethunits("ft")
             W4: {{area(w1), area(w2), area(w3)}}
             W5: ravel(w1, w2, w3)
             W6: colarea(w5)

             W1, W2 and W3 contain three separate series.

             W4 computes the area of each series and combines the results as
             a 1x3 table

             W5 combines the series of W1, W2 and W3 into a single 3-column
             series.

             W6 computes the area of each column of W5 and returns a 1x3 table.

             W4 == W6 == {{0.636466, 5100.0, 0.893288}}

             The values of W4 and W6 are identical, but the COLAREA result
             in W6 has the correct area units, Watts, Meters^2 and Feet^2.

    Example:
             W7: {{area(w1, 1, 10), area(w2, 1, 10), area(w3, 1, 10)}}
             W8: colarea(w5, 1, 10)

             Same as above except only the first 10 samples from each series
             are used to compute the area.

             W7 == W8 == {{0.015275, 60.0, 0.098910}}

    Remarks:
             COLAREA iterates over the columns of a series and uses AREA
             to compute the area of each column. AREA uses the composite
             Simpson's rule to compute the area.

             COLAREA sets the appropriate area units for each resulting column.

             See AREA for more details.

    See Also:
             Area
             Cumsum
             Integ

#endif


/* return the area of each column using column iteration */
ITERATE colarea(s, start, len)
{
        local a, tmp;

        if (argc < 3)
        {
                if (argc < 2)
                {
                        if (argc < 1) error(sprintf("%s - input series required", __FUNC__));

                        start = 1;
                }

                len = length(s) - start + 1;
        }

        /* area */
        a = {area(s, start, len)};

        /* dummy integration to get units */
        tmp = integ(s[1..2]);

        /* set units */
        setvunits(a, getvunits(tmp));
        sethunits(a, gethunits(tmp));

        return(a);
}