Crib Sheet for Editing trace.ctl for FVS

Disclaimers:

   1. This is a study note/crib sheet provided here for your
      convenience. As a crib sheet it is accurate as far as I know, but
      for more scientifically rigorous information, please consult
      
      http://www.emc.ncep.noaa.gov/mmb/papers/brill/edit_ctl.doc 
      and other FVS documents in 
      
      http://www.emc.ncep.noaa.gov/mmb/papers/ 
      under the heading
      'Brill' and the Verification System User Guide under 'DiMego'.
   2. The trace.ctl files provided here are for precipitation
      verification. If you are verifying other surface and upperair
      fields you might need further information from the aforementioned
      FVS documents. 
   3. This is not a part of the official FVS document; its scope is limited;
      it might not be up-to-date; and it is not a substitute for the official
      FVS document and FVS help pages.  This crib sheet is being provided 
      for your general information only and should not be relied upon as a 
      primary source of information in the creation of any particular type 
      of verification scores.  Should there be a conflict between this crib 
      sheet and any part of the official FVS document/FVS help pages, the 
      language of the official FVS document/FVS help pages will control.
      The reader is hereby advised to read, instead of this crib sheet, the 
      official FVS document and FVS help pages for information regarding 
      trace.ctl files.   


The following are annotations/study notes of two trace.ctl files.  Pair of 
numbers in square brackets refer to the [line,column] position of elements
in the trace.ctl.

Annotations of the first trace.ctl:

  1. [1,1]
     Trace number for this condition (ITRC)

  2. [1,2]
     Search parameter identification (IDDFLD)
      when IDDFLD=5: Verification YYYYMMDDHHNN  CHAR 4 
      (btw the 'Desc Field' in Keith's Table 1 refers to the appropriate
      column number in a vsdb file)
     Yes, this is supposed to be YYYYMMDDHHNN originally.  Here the definition
     has been 'expanded' to include the '1234': time period check for making 
     period averages.  
     
  3. [1,3]
     The variable type (IVRTYP=1: condition applies to an independent 
     variable

     What's the difference between an independent variable condition 
     and a dependent variable condition?  An independent variable condition
     determines how things are separated along x-axis; a dependent variable
     determines how one trace is separated from another trace, but not how
     data are separated along the x-axis.

     Usually in a plot there is only one independent variable.

     In the 'classic' threat/bias score plots, the precip threshold is the
     independent variable (it is the coordinate along the x-axis).  All 
     other things are dependent variables.

     In the old Eta vs. NGM performance metrics plot
     (The first trace.ctl ),

     we have a time series of the threat score, yet the beginning/ending
     times defining the verification period are not considered independent
     variables - the independent variable is the time period check for 
     making period averages ('1234' represents 'quarterly').  Here Keith's 
     definition is razor-sharp, almost Clintonesque: while the 
     beginning/ending times (YYYYMMDDHHNN) do affect how the data are 
     distributed along the x-axis, it is the 'time period check for making
     period averages' that determines how things are SEPARATED along the 
     x-axis.
   
  4. [1,4]
     The data combination code (ICMTYP=2: Sum data counts and the 
     count-value products [i.e., values are multiplied by the count])

  5. [1,5]
     Number of conditions following the header (NCN)

  6. [1,6]
     Plot number to which trace belongs (IDPLT)

  7. [1,7]
     Plot type.  This is not used in searching, but remember that 
     trace.ctl ends up at the top of trace.dat, but this is used when
     you do 'fvs p'.  

     when 'fvs u' is used to create trace.ctl, the user is asked ot
     select plot type:

     fvs u
        You may define up to 24 traces, including all overlain traces.

          Setting up for a new plot.  Please select type of plot:
        
                0 - STOP
                1 - Time series
                2 - Scatter plot
                3 - Skill score vs thresholds
                4 - Categorically binned data plot
        

  8. [1,8]

     Data consistency checking code sequence: KMCH/KASE/KPADZ/KLTP
       KMCH : triggers consistent data combination.
         =2 : Verification times and counts will be identical
                at corresponding points: points not found in ALL traces
                are eliminated
       KASE : specifies how the consistency checking associated with the
                KMCH value is applied
         =2 : Inter trace consistency (varying point to point)
              This means that if one were sitting on the x-axis (say at
              0.25" threshold) and looking up, only points with the
              same verification times for different traces are included
              in the count.  Though if the count for 0.5" threshold for
              the same verification times does not exist, it would be OK.
              Intra-trace consistency means that data for varification
              times must exist for all conditions along the x-axis (e.g.,
              verif times for Eta must exist for all thresholds, 0.01",
              0.1", 0.25" etc. for the verif time to be included in the
              count).  

       KPADZ: is provided to allow records with all zero FHO values to be
              absent in the input VSDB data file.  These values will be 
              padded in if KPADZ > 0.  Padding takes place only when the 
              independent variable is threshold.

       KLTP : is a value ranging from 0 to 99 that gives the percentage of
              data loss allowed before relaxation of the data combination 
              consistency checking specified by KMCH.  For example, if 
              KLTP = 66, then up to 66% of data can be lost and data 
              consistency checking will remain in force.  If KLTP = 10, 
              only 10% of data can be lost with consistency checking in 
              force---if consistency checks would eliminate more than 10% 
              of data the consistency requirements are removed.  This 
              percentage is applied to each trace.  If any one trace fails 
              the criterion, consistency checking is lifted.  KLTP is used 
              only when KASE = 0.

              with KMSH/KASE=2/2 (the usual set-up for all pcp verif
              plots), KLTP is actually not used at all.

     KLTP=90 in the 1st and 2nd header, but 60 else where?  This
     is just an oversight.

  9. [2,1]
     ICNTYP=20: Time period check for making period averages

 10. [2,4]
     1234: 1st, 2nd, 3rd and 4th quarters
     'real' conditions are located on the 2nd and 3rd column, while
     character conditions are located on the 4th and 5th column.  
     Various real and character conditions are listed in Keith's Table 2.

     Since here we have a single character condition, it is placed on 
     the 4th column.

     The unused columns are padded with '0'.

 11. [5,2]
     Search parameter identification (IDDFLD=2: model being verified)

 12. [5.3]
     The variable type (IVRTYP=0: condition applies to a dependent variable)
     Here the model names are dependent variables because they do not affect
     how data are separated along x-axis.

 13. [6,1]
     ICNTYP=18: Char check for elements in the list CHARCN (1,NCN)

 14. [9,2]
     Search parameter identification (IDDFLD=3: Forecast hour)

 15. [9,5]
     Number of conditions following the header (NCN.  Here it is '3' because
     we have 24, 36, and 48h of forecast times)

 16. [10,1]
     ICNTYP=9: real check for elements in the list REALCN (1,NCN)

 17. [10,2]
     Forecast hour.  Real number occupies 3rd column (or 3rd and 4th if
     there are a pair of real numbers)

 18. [17,2]
     Search parameter identification (IDDFLD=5: Verification YYYYMMDDHHNN)

 19. [18,1]
     ICNTYP=15 Char check CHARCN (1,*) <= c <= CHARCN (2,*)
     (beginning date/ending date - a pair of character elements)

 20. [21,2]
     Search parameter identification (IDDFLD=8: Verifying analysis CHAR)

 21. [22,1]
     ICNTYP=18: Char check for elements in the list CHARCN (1,NCN)

 22. [25,2]
     Search parameter identification (IDDFLD=9: Verifying region CHAR)

 23. [29,2]
     Search parameter identification (IDDFLD=10:Statistic type identifier)

 24. [33,2]
     Search parameter identification (IDDFLD=11: Threshold for data, REAL)

 25. [37,2]
     Search parameter identification (IDDFLD=12: Parameter name, CHAR)

 26. [41,2]
     Search parameter identification (IDDFLD=14: Level value REAL).  Actually
     it might have been better to use IDDFLD=13 (level identifier, CHAR),
     but since the first column in the next line ([42,1]='18') directs FVS 
     to look for a character string on the 4th column, FVS is able to read
     in the 'SFC' (i.e. [42,1] overrides the type designation part of
     [41,2]).

     Yes, 'level' can be a character string (e.g. 'P500') because in some
     cases levels closer by are used (something like that).

     Why do we need to specify level=SFC for precip verif?  It is optional,
     but since trace.ctl gets placed at the beginning of trace.dat, the level
     info would be passed on to the plotting program, so if default labeling
     is used, GEMPAK will put 'SFC' in the label.
     

Annotation of the second trace.ctl:

  1. [lines 1-6]
     Specify precip threshold as the variable along the x-axis by declaring
     the threshold as 'independent variable' and give it a value of '0'

  2. KMCH/KASE/KPADZ/KLTP [last column in the odd-numbered lines:
          = 2/2/1/0 

     That's fine.  KLTP is not used anyway.  After line 6, this gang-of-four
     is specified as 2/3/1/0 - that's a mistake that should be corrected to
     avoid confusion, but it doesn't really affect the outcome, since only
     the first appearance of this thing is being used.

     When precip threshold is the independent variable, 2/2/1/0 should work 
     even when plotting only one trace.

     When plotting time series for only one trace, make sure KMCH=0
     (no consistency check).  You can leave the rest unchanged, i.e.
     KMCH/KASE/KPADZ/KLTP=0/2/1/0 (KASE,KPADZ,KLTP will be ignored anyway).
     2/2/1/0 won't work.