 
      CALL SEQUENCE...
       accumul NEW  ACCUM [MISSACC] [MISSING] OUTPUT [ -mvalue VAL1 -kind VAL2 ]
       timavg  SERA AVGA  [MISSOUT] [MISSING] OUTPUT [ -mvalue VAL1 -kind VAL2 -def VAL3 -npg VAL4 ]
       timmax  SERA MAXA  [MISSOUT] [MISSING] OUTPUT [ -mvalue VAL1 -def  VAL2 -npg VAL3 ]
       timmin  SERA MINA  [MISSOUT] [MISSING] OUTPUT [ -mvalue VAL1 -def  VAL2 -npg VAL3 ]
 
 
      DESCRIPTIONS...
       (1) accumul - ADDS THE CONTENT OF NEW TO THAT OF ACCUM
       (2) timavg  - COMPUTES THE AVERAGE OF ALL SAMPLES IN A FILE
       (3) timmax  - FINDS MAXIMUM TIME-SERIES VALUE AT EACH POINT
       (4) timmin  - FINDS MINIMUM TIME-SERIES VALUE AT EACH POINT
 
 
      AUTHOR  - J.D.Henderson, MAY 07/80.
      LAST REVISION: $Header: /data/armnraid1/cvs/RMNLIB/utils/rdiag/lspgm/timavg.ptn,v 4.35 2010/02/15 22:57:41 dugas Exp $
 
 
      PURPOSE - (1) PERFORMS AS AN ACCUMULATOR: ADDS INFORMATION FROM FILE
                    NEW TO THAT OF FILE ACCUM. THE RESULT IS A SAMPLE AVERAGE
                (2) COMPUTES THE 2-D SAMPLE AVERAGE FOR EACH VARIABLE AND
                    LEVEL OF A SERIES OF (MULTI-LEVEL) SETS OF DATA,
                    EACH HAVING THE SAME SIZE AND TYPE.
            (3)/(4) FINDS THE TIMEWISE MAXIMUM/MINIMUM FOR EACH
                    GRID POINT AND SAVES IT IN THE OUTPUT FILE.
 
 
      INPUT FILES...
       SERA/NEW = SERIES OF MULT-VARIABLE MULTI-LEVEL SETS, WHERE
                  THE DATA MAY BE REAL OR COMPLEX. THE FILE IS SUPPOSED
                  TO BE SORTED ACCORDING TO A TIMESTEP/NAME/LEVEL RULE,
                  FROM MOST TO LEAST SIGNIFICANT.
       ACCUM    = (OPTIONALLY) A SINGLE STEP OF MULT-VARIABLE MULTI-LEVEL
                  ACCUMULATIONS RESULTING FROM PREVIOUS JOB STEPS. THE
                  PREVIOUS SAMPLE SIZE FOUND IN ACCUM IS USED TO
                  CORRECTLY ADD THE NEW FILE TO ACCUM
 
      OUTPUT FILE...
         (1)  ACCUM     = UPDATED ACCUMULATOR SET. OVEWRITES ORIGINAL FILE.
         (2)  AVGA      = ONE SET WHICH IS THE MEAN OF ALL THE SETS IN SERA.
     (3)/(4)  MAXA/MINA = TIMEWISE MAXIMUM/MINIMUM VALUES AT EACH GRID POINT
 
 
      Command-line arguments...
       mvalue = Real number used to identify missing values (DEF = none)
       kind   = "SAMPLES", modifies the way sample sizes are handled (see notes)
              = "SQUARE", does the sum of the square input fields with ACCUMUL.
       def    = "KEEPTIME", turns off all of the descriptor management (see notes)
       npg    = Output packing density (DEF = -32)
 
 
      Missing value mode...
       Missing value treatment is activated by providing a real number to be
       used as a missing value flag with the "-mvalue" command-line argument.
       Data that has this value will be disregarded by the program. Accessory
       files can also be provided to indicate how many samples were used to
       build values read in input. Otherwise, the program assumes that the
       total sample size gives this information for all valid points. The
       program will write this updated information in the MISSACC/MISSOUT
       files.
 
      Files associated with the missing value mode...
       MISSING  = Number of samples in input file that had valid data and
                  where used in the calculation of NEW at each point.
       MISSOUT  = Number of samples that had valid data and where used
                  in the calculation of AVGA,MAXA or MINA at each point.
       MISSACC  = Same as MISSING/MISSOUT when running ACCUMUL.
 
 
      Notes: 1) Specifying the "-npg" command-line parametre with a valid
                value forces TIMAVG/TIMMIN/TIMMAX to use this packing density
                on output.
             2) The first file's sample size may also be used by ACCUMUL to
                correctly build the ensemble mean. This will always occurr
                with RPN Standard files, but will only occurr with CCRN
                files when the command-line parameter sequence "-kind SAMPLES"
                is specified. In the latter case, the number in IBUF(2) will
                be assumed to be a sample size and not a date/step number.
             3) Each record in a file can also be representative of several
                samples. Specifying the same "-kind SAMPLES" arguments with
                TIMAVG will correctly account for the sample sizes.
             4) When dealing with RPN Standard files, accumul and timavg modify
                the file's time descriptors such that the earliest sample time
                is saved in DATEO, while the latest can be reconstructed from
                new values of DATEO, NPAS and DEET. In addition, IP3 will then
                contain the number of time samples used to construct the average.
                Other R.DIAG modules such as TIMGEN and the statistical testing
                modules (FTEST, ...) can then use this information directly.
 
     ************************************************************************
    *** All of the above descriptor modifications can be avoided in timavg ***
   ***    by specifying the "-def KEEPTIME" parametre on the command line   ***
    ***     !!! But usage of this key is  generally NOT RECOMMENDED !!!    ***
     ************************************************************************
 
 
      EXIT CONDITIONS...
        0 NO PROBLEMS
        1 TOO MANY OR NOT ENOUGH VERTICAL LEVELS IN INPUT FILE
        2 PREMATURE EOF IN FILE SERA
        3 MORE THAN ONE SIZE FOUND IN SERA/NEW
        4 AT LEAST ONE TIMESTEP SET IS INCOMPLETE
        5 ACCUMUL: VARIABLES AND/OR LEVELS DIFFER IN NEW AND ACCUM
        6 UNABLE TO ALLOCATE ENOUGH WORKING MEMORY
        7 BAD ARGUMENT VALUE WITH A COMMAND-LINE PARAMETRE
        8 UNRECOGNIZED OUTPUT FILE IN ACCUMUL MODE
        9 MISSING VALUES: VARIABLES AND/OR LEVELS DIFFER, OR UNABLE TO READ
       10 MISSING VALUES: TYPVAR .NE. 'MV' IN FILE MISSACC/MISSING
