Forecast support in CDAT

CDAT has a 'forecasts' class; a forecasts object contains a list of 'forecast' objects, each one representing a single forecast. Once you assemble the data and load it into CDAT, you should be able to the same kinds of things which you can do with any CDAT dataset - e.g. picking out data items or slices.

At present, the forecast features of CDAT expect data for each forecast to be in a separate file or dataset. The variables should depend on an ordinary time variable (standard_name 'time'). The forecast base time (standard_name 'forecast_reference_time') should be specified by int variables nbdate and nbsec. The base date is encoded in nbdate as a decimal number of the form YYYYMMDD, and nbsec expresses the time of day within that date, in seconds.

It is expected that all the forecasts will have a high degree of consistency in the time direction - they should forecast over the same time intervals with the same units and calendars. Let me know if you need more flexibility in this respect.

The first step is to combine all the forecast files (or datasets) into a single dataset using cdscan (in cdms2/Script), as in the following example:

cdscan --forecast file1.nc file2.nc file3.nc > out.xml

Edit out of out.xml anything which may have been written before the line ''.

Now run cdat. Here is an example:

>>> import cdms2.forecast
>>> fcs = cdms2.forecast.forecasts( out.xml, ( "1999-01-31 12:01:00", "2010-08-25 15:26:00" ) )
>>> frhs0 = fcs.fcs[0]['rhs']  # FileVariable for rhs (relative humidity) and first forecast
>>> trhs = fcs('rhs')          # TransientVariable for rhs and all forecasts
>>> trhs1 = fcs('rhs',("1999-01-31 12:00:00", "2000-01-31 12:00:00")) # same, but restricted to forecasts based
                                                                      # on the specified 1-year period
>>> frhs = fcs['rhs']          # FileVariable for rhs and all forecasts
>>> vs1 = trhs[1,:,:,:,:]      # rhs for forecast #1, all time and space
>>> vs2 = trhs[:,1,:,:,:]      # rhs for one time, all forecasts and all space
>>> fcs.close()                # Note that making fcs (above) involved opening a file, out.xml.

From the source code, here is a description of all the ways you can initialize a "forecasts" object (like fcs in the example):

f = forecasts( 'file.xml', (min_time, max_time) )
*or*
f = forecasts( 'file.xml', (min_time, max_time), '/home/me/data/' )
*or*
f = forecasts( 'file.xml', [ time1, time2, time3, time4, time5 ] )

where the two or three arguments are::
  1. The name of a dataset xml file generated by "cdscan --forecast ..."
  2. Times here are the times when the forecasts began (tau=0).
      (i)   If you use a 2-item tuple, forecasts will be chosen which start at a time
            t between the min and max times, e.g. min_time <= t < max_time .
      (ii)  If you use a list, it will be the exact start (tau=0) times for the forecasts to be included.
      (iii) If you use a 3-item tuple, the first items are (min_time,max_time) as in a 2-item tuple.  
            The third component of the tuple is the open-closed string.  
            This determines whether endpoints are included. 
            The first character should be 'o' or 'c' depending on whether you want t with min_time<t or min_time<=t.  
            Similarly the second character should be 'o' or c' for t<max_time or t<=max_time .  
            Any other characters will be ignored.
            Thus ( min_time, max_time, 'co' ) is equivalent to ( min_time, max_time ).
      (iv)  The string 'All' means to use all available forecasts.
            Times can be specified either as 13-digit long integers, e.g.
            2006012300000 for the first second of January 23, 2006, or as component times (comptime) in the cdtime module, 
            or as a string in the format "2010-08-25 15:26:00".
  3. An optional path for the data files; use this if the xml file contains filenames without complete paths.
     As for the forecast class, this opens files when initiated, so when you are finished with the forecasts, 
     you should close the files by calling forecasts.close() .
     Please direct questions, bug reports, feature requests, etc. to Jeff Painter at PCMDI,
     Lawrence Livermore National Laboratory.