CALL SEQUENCE...
       tfilter  INFIL [GAINSQ/OUTFIL] INPUT OUTPUT [-a VAL1 -b VAL2 -kind VAL3]
 
 
      AUTHORS - F. Zwiers, N.E. Sargent AND B. Dugas, OCT 31/85.
      LAST REVISION: $Header: First-release @ Wed, 7 Jan 2015 16:36:15 -0500 (Bernard Dugas) $
 
 
      DESCRIPTION...
       TIME FILTER A SET OF SERIES BY CONVOLUTION FILTERS.
 
 
      PURPOSE - APPLY A GRID POINT TIME FILTER TO A TIME SERIES OF FIELDS.
                THE FILTER IS EITHER HIGH-PASS OR LOW-PASS DEPENDING ON THE
                INPUT CARD VALUES.
 
                THE FILTER APPLIED IS EITHER :
 
                1) - AN IDEAL LOW-PASS FILTER WITH CUTOFF FREQUENCY F
                     (CYCLES PER UNIT TIME) MODIFIED BY A HANNING WINDOW.
                     SEE 'THE SPECTRAL ANALYSIS OF TIME SERIES',
                     L.H. KOOPMANS, ACADEMIC PRESS, 1974.
 
                OR
 
                2) - SEQUENTIALLY APPLIED SYMMETRIC MOVING AVERAGE FILTERS.
 
 
      NOTE    - THE PROGRAM COMPUTES AND DISPLAYS THE SQUARED GAIN OF THE
                FILTER RESULTING FROM THE CHOICE OF F AND K.
 
 
      INPUT FILE...
       INFIL  = A SEQUENCE OF (MULTI-LEVEL,MULTI-VARIABLE) SETS OF FIELDS.
                THE FILE IS SUPPOSED TO BE SORTED ACCORDING TO A
                TIMESTEP/NAME/LEVEL RULE, FROM MOST TO LEAST SIGNIFICANT
 
      OUTPUT FILES...
       GAINSQ = A ONE RECORD OF FILE OF TYPE 'ZONL' WHICH CONTAINS THE
                SQUARED GAIN OF THE FILTER APPLIED TO INFIL. ONLY USED
                WHEN FILTER IF NEGATIVE
                               ********* OR *********
       OUTFIL = IF FILTER <= 0, THEN THIS FILE CONTAINS THE FILTERED TIME
                SERIES. THE FILTERED SERIES COUL BE 2*K SHORTER THAN THE
                UNFILTERED VERSION. ONLY USED WHEN FILTER IS POSITIVE
 
       ******** NOTE THAT ONLY ONE OF THESE TWO FILES IS WRITTEN ********
  
 
      PARAMETERS...
 
        ABS(F) (a) = IS THE CUTOFF FREQUENCY IN CYCLES PER SAMPLE TIME
                   > 0, CHOOSES A  LOW-PASS FILTER
                   < 0, CHOOSES A HIGH-PASS FILTER
        K      (b) > 0, THE NUMBER OF NON-ZERO WEIGHTS USED BY THE IDEAL FILTER.
                        THE SIZE OF K IS RESTRICTED BY THE NUMBER OF RECORDS IN
                        INFIL WHICH CAN BE STORED IN MEMORY SIMULTANEOUSLY AND
                        THE LENGTH OF THE ARRAY USED TO STORE THE WEIGHTS. A
                        LARGE VALUE OF K WILL PRODUCE A FILTER WITH A VERY SHARP
                        CUTOFF AT FREQUENCY F. AND, A SMALL VALUE OF K RESULTS
                        IN A FILTER WITH A GRADUAL CUTOFF AT FREQUENCY F.
        K          < 0, CHOOSES SEQUENTIALLY APPLIED SYMMETRIC FILTERS WITH A
                        NUMBER OF WEIGHTS DETERMINED BY F. THE LENGTH OF SUCH A
                        FILTER (AND THE CORRESPONDING MEMORY REQUIREMENTS) IS
                        INVERSELY PROPORTIONAL TO F.
 
        FILTER    >= 0, APPLY FILTER TO DATA IN INFIL.
        (kind)     = 1, ADDITIONALY, SUPPOSE THAT THE DATA IS PERIODIC IN TIME
                        AND THAT INFIL CONTAINS A INTEGER NUMBER OF FULL CYCLES.
                        INFIL IS THEN TREATED AS A CIRCULAR BUFFER AND OUTFIL
                        WILL HAVE THE SAME NUMBER OF RECORDS AS INFIL.
                  <  0, ONLY COMPUTE AND DISPLAY THE SQUARED GAIN OF THE FILTER.
                        THIS OPTION IS USEFUL WHEN CHOOSING FILTER PARAMETERS.
 
        READ(5010) F,K,FILTER
 5010   FORMAT(10X,E10.0,5X,I5,10X,I5)
 
        NOTE:        F,K AND FILTER CAN BE READ ON THE COMMAND LINE USING
                     THE a, b AND kind PARAMETER KEYS, RESPECTIVELY.
 
 
      EXAMPLE OF INPUT CARD...
 
  TFILTER.     -.001        20              0
 
         0123456789012345678901234567890123456789012345678901234567890
         1         2         3         4         5         6         7
 
 
      EXIT CONDITIONS...
        0 NO PROBLEMS
        1 BADLY SPECIFIED F AND/OR K
        2 UNABLE TO ALLOCATE ENOUGH WORKING MEMORY
        3 TIME SERIES SHORTER THAN 2*K+1
        4 ERROR READING INPUT PARAMETERS
        5 PREMATURE EOF ON SERIES