ioapiTools
index
/net/home/azubrow/python/test/ioapiTools/ioapiTools.py

ioapiTools
 
    A series of tools that operate on ioapi files 
 
    Author:  Alexis Zubrow

 
Modules
       
mx.DateTime
MV
Numeric
cdms
cdtime
cdutil
copy
gdal
os
osr
pyIoapi
string
sys

 
Classes
       
cdms.tvariable.TransientVariable(cdms.avariable.AbstractVariable, MA.MA.MaskedArray)
iovar
__builtin__.object
cdmsmeta
fileindex
iofile
iofilescan
iometa

 
class cdmsmeta(__builtin__.object)
    cdmsmeta class: basically the spatial and temporal axes.
creates the meta data needed for a cdms file.
 
Notes/Assumptions:
    1.  Presently, only Lambert Conformal Conic is supported.
 
    2.  For Lambert Conformal, xlonAxis and ylatAxis are in meters
        from the x and y origin of the coordinate system.
 
  Methods defined here:
__init__(self, ioFile, typeFlag=1)
init
 
Inputs:
    ioFile - iofile object or cdms/iovar object
 
    typeFlag - iofileFlag, iofile from ioapi
               cffileFlag, iofile from CF netCDF
               cdmsvarFlag, cdms or iovar variable
copy(self)
getAxes(self, copyFlag=True)
latlonAxes(self, ioM)
Generate lat and lon cdms variables as functions of ylat and xlon:
  lat(yLat,xLon)
  lon(yLat,xLon)
 
Also generates the bounds of these cells (4 corners), irregular grid:
  lat_bounds(ylat,xlon,4)
  lon_bounds(ylat,xlon,4)
  
Only necessary if you are writing CF compliant netCDF.
 
Input:
   ioM    - iometa object, contains projection info
   
Output:
   axes   - tuple (lat, lon, lat_bounds, lon_bounds),
                   where each element is a cdms variables.
 
Note/Assumptions:
 
  1.  Internal method, not for general use.
  
  2.  The lon and lat coordinates (in Degrees) are a non-regular grid.
 
  3.  The bounds for each grid cell are the corners of the cell in
      degrees.  The order is [SW, SE, NE, NW]

Data and other attributes defined here:
__dict__ = <dictproxy object>
dictionary for instance variables (if defined)
__weakref__ = <attribute '__weakref__' of 'cdmsmeta' objects>
list of weak references to the object (if defined)

 
class fileindex(__builtin__.object)
    Very small object used to store the iofile and date indices.
Generated by date2Files.
 
Note/Assumptions:
 
   1.  Internal function.  Should not be used by normal users.
 
  Methods defined here:
__init__(self, ioFile, startInd, endInd)
Very small object used to store the iofile and date indices.
Generated by date2Files.
 
Note/Assumptions:
 
   1.  Internal function.  Should not be used by normal users.

Data and other attributes defined here:
__dict__ = <dictproxy object>
dictionary for instance variables (if defined)
__weakref__ = <attribute '__weakref__' of 'fileindex' objects>
list of weak references to the object (if defined)

 
class iofile(__builtin__.object)
    An iofile object is the object which retains file handles and
provides methods for extracting and writing variables.
 
Notes/Assumptions:
  1. Presently only tested for Lambert Conformal Conic projection.
 
  2. If instantiated via IO/API file, assumes that the spatial axes
     are regular, equally spaced.
     
Revisions:
 
    8/25/2003 --  Alexis Zubrow -- Initial Version (iometa)
    3/25/2004 --  Alexis Zubrow -- Added iometa.vertcoords (iometa)
    4/13/2004 --  Alexis Zubrow -- Added iometa.xlon and ylat (iometa)
    6/25/2004 --  Alexis Zubrow -- Shifted to cctmTools, added
                                   cdms variable option.  Corrected
                                   x and y origin to clarify grid center
                                   and grid edge locations.
    1/10/2005 --  Alexis Zubrow -- Shifted to ioapiTools, made this
                                   file object.
 
  Methods defined here:
__call__(self, vname, capFlag=True)
Extracts a variable.
 
Input:
  vname - variable name
 
  capFlag - True [default] - automatically capitalize vname
            False - do not capitalize
 
Output:
  ioVar - iovar object
__init__(self, fileName=None, rwFlag='r', typeFlag=2, newM=None, logFile=None, llaxesFlag=False)
Init
 
 
Input:
       fileName  - Either a fileName for an IO/API file or a CF
                   complient netcdf file.
 
       rwFlag    - 'r' - read
                   'w' - write / overwrite
 
       typeFlag  - cffileFlag (default), write a cf netcdf file
                   iofileFlag, write an ioapi format file
                   (Only needed for writes, reading automatically
                   determines file type)
 
       newM      - tuple (ioM, cdmsM) describes the ioapi metadata
                   domain, and geographic projection of the data
                   for this file. This tuple is the return of
                   combineMeta.  Only needed for multiple writes
                   to ioapi format files (see Notes).
 
       logFile -   log file name. Used to store ioapi library
                   log info.  Default is None, display log
                   info in stdout.  If a file is indicated, it
                   will overwrite any previous file of that name.
 
       llaxesFlag- True - write out alternative lat and lon coordinates
                   False [default] - do not write out alternative
                          coordinates
                
Notes/Assumptions:
 
   1.  If the file format is neither ioapi or cf compliant,
       but it is a netcdf file, it will raise an error.
       
   2.  If you are writing ioapi format and pass a logFile,
       the function sets up an environmental variable,
       LOGFILE.
 
   3.  If you are writing ioapi format file, the iofile
       object will setup an environmental variable for the
       output name.  The variable will be of the form,
       'OUTDDDDDDDDDD'.  This is needed for the ioapi
       library.
 
   4.  If you are writing to a file that already exists.
       the open command will print a warning and remove
       the file before writing.
 
   5.  Multiple writes and ioapi format. All the metadata
       for an ioapi file needs to be written in the
       beginning.  If you want to have multiple, seperate
       writes to the file, you need to open the file with
       the metadata for all the variables you plan to
       write to this file.  In order to do multiple
       writes, pass the newM parameter.  Here is an
       example of writing 3 variables:
 
         >>> newM = ioapiTools.combineMeta([o3, nh3, co])
         >>> f = ioapiTools.open('test.ioapi','w', newM,                                          ioapiTools.iofileFlag)
         >>> f.write(nh3)
         ...
         >>> f.write([o3,co])
         >>> f.close()
 
   6.  The llaxesFlag indicates whether or not to write out
       alternative coordinates, lat and lon.  This is only
       meaningful if you are writing to a CF netCDF file.
       These alternative coordinates are cdms variables in
       there own right.  They are both functions of yLat and
       xLon, e.g. lat(yLat,xLon).  To be truelly CF compliant,
       this flag should be on.  But, this slows down the write
       and may cause some programs to have problems displaying
       the data.  The values of lat are the latitude at each
       yLat,xLon grid point.  This basically translates the
       regular grid in the native projection to an irregular
       grid in degrees N,E.  It also creates a bounds_lon and
       bounds_lat variable, which correspond to the irregular
       corners of each grid cell.
__repr__(self)
__str__(self)
close(self)
Close a file.  Especially important if you are writing to the file.
dateConv(self, sdate, stime)
    Takes SDATE and STIME and creates a DateTime object
 
    SDATE is the start date from the IO/API file.  It
    has the form YYYYDDD.  E.g. 1992045 is the 45th day
    of 1992.
 
    STIME is the start time.  It has the form HHMMSS, but
    only hour is taken into consideration by this function.
    E.g. 60000 is 6 am.
 
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
extract(self, vname=None, capFlag=True)
Extracts a variable from ioFile and returns an iovar object.
 
Input:
    vname - variable name, string
 
    capFlag - True, [default] automatically capitalize vname
              False, do not capitalize vname
 
Output:
    var  - iovar object
 
Note:
 
    1.  The extract method is equivalent to making a call to
        the object.  For example, if the iofile object is 'f',
        then f.extract('o3') is equivalent to f('o3').
getCdmsMeta(self)
Returns a copy of the cdmsMeta object.  These are the cdms axes.
        
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
getGridMap(self)
Returns a copy of the grid_map, projection info stored in a
seperate cdms variable.
 
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
getTimes(self)
Returns a copy of the times list.  These are time steps
(probably hours) since the start time.
 
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
getXlons(self)
Returns a copy of the xlon list.  These are the longitude values
of the cross points (center) of each grid cell.  They are in the
projection coordinate units (probably meters). The 0th element is
the Western most grid cell.  The last element is the Eastern most
grid cell.
 
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
getYlats(self)
Returns a copy of the ylat list.  These are the latitude values
of the cross points (center) of each grid cell.  They are in the
projection coordinate units (probably meters). The 0th element is
the Southern most grid cell.  The last element is the Northern most
grid cell.
 
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
hasAxes(self)
Tests whether grid object has the cdmsMeta object and grid_map.
 
If this is True, one can directly access the axes through the
methods: getCdmsMeta and getGridMap.
 
returns:
   True - has the additional axes
   False - does not have them
   
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
listvariables(self, allFlag=False)
list variables in the file.
 
Input:
    allFlag  - True, list all variables in the file
               False,[default] try to remove metadata variables
 
Output:
    varLst   - list of variable names
 
Note/Assumptions:
 
   1.  If allFlag is False, this method will try and remove
       any of the metadata variables.  For ioapi files, it
       will remove TFLAG from the list.  For CF netCDF files,
       it will remove ioapi_meta, bounds_yLat, bounds,xLon,
       and lat, lon, bounds_lat, and bounds_lon if they exist.
       It will not remove the grid_mapping variable, because
       its name is not fixed, it depends on the projection
       type.
padList(self, textLst, elemLength=16, totalLength=1920, list2stringFlag=False)
Pads a list of strings w/ trailing spaces.  Can produce a list
of extended strings or can concatenate the list into one
string of length totalLength.
 
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
padNumeric(self, a, length=0, type='d')
Pads the end of a numeric array w/ zeros.
 
Inputs:
      a  - Numeric array
 
      length - length of new array
 
      type - Numeric type
Output:
      newArray  - array of size length.
      
Note/Assumptions:
   1.  Internal function.  Should generally not be used by
       normal users.
padText(self, text, length=16)
Pads a text string w/ trailing spaces.
 
Inputs:
      text  - text string
 
      length - length of new string, default is the IOAPI namelength
 
Output:
      newStr - string of size length
 
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
parse(self)
Parses the IO/API metadata
 
Note/Assumptions:
 
   1.  Internal function.  Should not be used by normal users.
populateBdesc3(self, bdesc3=None)
Populates the bdesc3 commonblock w/ data from
iometa and cdmsmeta.  This is required to write to an IOAPI
format file.
 
Note/Assumptions:
   1.  Internal function.  Should generally not be used by
       normal users.
populateCdesc3(self, cdesc3=None)
Populates the cdesc3 commonblock w/ data from
iometa.  This is required to write to an IOAPI format file.
 
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
setNone(self)
sets all the attributest to None.  This should only be called in the
__init__.  DO NOT call this directly, it will erase all the metadata.
 
Note/Assumptions:
 
   1.  Internal function.  Should not be used by normal users.
write(self, vars=None)
Write a variable or a variable list to the file.
 
Input:
   vars - iovar or list of iovar objects
 
Notes/Assumptions:
   1.  If you are writing ioapi format file, the iofile
       object will setup an environmental variable for the
       output name.  The variable will be of the form,
       'OUTDDDDDDDDDD'.  This is needed for the ioapi
       library.
 
   2.  If you are writing to an ioapi file, you have the
       choice of multiple writes or a single write.  If you
       did not open the file w/ a newM (see open notes), then
       you can only perform one write.  To write multiple
       variables at once:
       
         >>> f.ioapiTools.open('test.ioapi', 'w',                                        ioapiTools.iofileFlag)
         >>> f.write([o3, nh3, co])
         >>> f.close()
       
   3.  Multiple writes and ioapi format. All the metadata for
       an ioapi file needs to be written in the beginning.  If
       you want to have multiple, seperate writes to the file,
       you need to open the file with the metadata for all the
       variables you plan to write to this file.  In order to
       do multiple writes, pass the newM parameter to open.
       Here is an example of writing 3 variables:
 
         >>> newM = ioapiTools.combineMeta([o3, nh3, co])
         >>> f = ioapiTools.open('test.ioapi','w', newM,                                          ioapiTools.iofileFlag)
         >>> f.write(nh3)
         ...
         >>> f.write([o3,co])
         >>> f.close()

Data and other attributes defined here:
__dict__ = <dictproxy object>
dictionary for instance variables (if defined)
__weakref__ = <attribute '__weakref__' of 'iofile' objects>
list of weak references to the object (if defined)

 
class iofilescan(__builtin__.object)
     Methods defined here:
__call__(self, vname, capFlag=True)
Extracts a variable.
 
Input:
  vname - variable name
 
  capFlag - True [default] - automatically capitalize vname
            False - do not capitalize
 
Output:
  ioVar - iovar object
__init__(self, searchStr, startDate, endDate)
Scans files for the date range.  Opens up each of
the files (making a list of iofiles) for variable
extraction.
 
Input:
    searchStr - a search string
 
    startDate - beginning date
 
    endDate - last date.
 
Output:
    ioScan - iofilescan object.
 
Notes/Assumptions:
 
  1.  Search string is of unix form, use '*' for wild card.
      For example the search string 'CCTM_CONC.D1.*' will
      match:
         CCTM_CONC.D1.001, CCTM_CONC.D1.033.nc, ...
          
  2.  Search string should only match files of a single file
      type (either all ioapi format or all cf netcdf format).
 
  3.  A sort of the file names should put them in temporal order.
 
  4.  Only used for extraction, not for writing. See ioScan.extract.
__repr__(self)
__str__(self)
close(self)
closes all the iofiles in the file dictionary
extract(self, vname, capFlag=True)
Extracts a variable from iofilescan.  This variable will
span the whole temporal domain (even if it crosses file
boundaries).
 
Input:
   vname - variable name
 
   capFlag - True [default] automatically capitalize string
             False - do not capitalize
 
Output:
    ioVar  - iovar object for that variable name
listvariables(self, allFlag=False)
list variables in the files.
 
Input:
    allFlag  - True, list all variables in the file
               False,[default] try to remove metadata variables
 
Output:
    varLst   - list of all the variable names
 
Note/Assumptions:
 
   1.  If allFlag is False, this method will try and remove
       any of the metadata variables.  For ioapi files, it
       will remove TFLAG from the list.  For CF netCDF files,
       it will remove ioapi_meta, bounds_yLat, bounds,xLon.
       It will not remove the grid_mapping variable, because
       its name is not fixed, it depends on the projection
       type.
 
   2.  This actually only lists the variables in the first
       file.  It assumes that all files in the scan have the
       same variable list.

Data and other attributes defined here:
__dict__ = <dictproxy object>
dictionary for instance variables (if defined)
__weakref__ = <attribute '__weakref__' of 'iofilescan' objects>
list of weak references to the object (if defined)

 
class iometa(__builtin__.object)
    The iometa object is the repository for ioapi specific
metadata and projection info.
 
  Methods defined here:
IO2cdms(self)
Converts the iometa object into a cdms variable.  This cdms
variable is then stored in the CF compliant netCDF file as
ancillary data.  Allows a CF netCDF file to have necessary
metadata to recreate an IOAPI formatted file.
 
Output:
   iomCdms - a cdms variable that holds all the ioapi specific metadata.
   
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
 
   2.  This cdms variable is automatically written to the CF
       file by the iofile method write.
IO2gridmap(self, nameOnly=False, falseEast=0, falseNorth=0)
Returns grid_mapping cdms variable.  This has the projection
info in CF compliant form.  To be saved to the netCDF file.
 
Input:
   nameOnly  -  True, simply return the name of the grid_mapping variable
                False, return the grid_mapping variable [default]
 
   falseEast  -  False easting of the projection.  Default is 0.
 
   falseNorth  - False northing of the projection.  Default is 0.
 
Output:
   grid_map -  A grid map. A cdms variable that contains the
               projection info in CF compliant form.  This is
               automatically written to the file in the iofile
               write method, when writing to CF files. If
               nameOnly is True, then this will be the name of
               the grid_map, the attribute grid_mapping_name.
   
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
 
   2.  Presently, only Lambert Conformal Conic projection
       (gridtype = 2) is supported.
__init__(self, ioFile=None, typeFlag=None)
init
 
Inputs:
    ioFile -  iofile object 
 
    typeFlag -  None, means iofile object [default]
                byhandFlag, construct by hand [not yet implemented]
__str__(self)
copy(self)
Makes a copy of the iometa object.
fromCFFile(self, ioFile)
Extract ioapi metadate from CF netCDF w/ ioapi metadata
 
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
fromIOFile(self, ioFile)
Extract ioapi metadate from ioapi file
 
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
projCode2Name(self, gridtype)
Returns grid name based on IO/API gridtype code.
In addition, it populates some projection specific
variables
 
 
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
 
   2.  Presently, only Lambert Conformal Conic projection
       (gridtype = 2) is supported.
replVar(self, vars=None, units=None, desc=None)
Replace the variable metadata stored in iometa.
 
Updates the following fields:
       vnameLst
       vunitsLst
       vdescLst
       nvars
 
Input:
    vars - variable name(s), string or list of strings
 
    units - variable units, string or list of strings
 
    desc  - variable description, long name, string or list of strings
 
NOTE:
 
    1. For advanced users only.  Modifying iometadata
       directly should be done w/ utmost care.
 
    2. Length of vars, units, and desc must be equivalent.
       The length of the list determines the number of vars.
updateFromVar(self, var)
Update iometa from a cdms variable or iovar object.
 
Updates following fields:
       vnameLst
       vunitsLst
       vdescLst
       nvars
 
Note/Assumptions:
 
   1.  Internal function.  Should generally not be used by
       normal users.
 
   2.  That var has name, units, var_desc attributes

Data and other attributes defined here:
__dict__ = <dictproxy object>
dictionary for instance variables (if defined)
__weakref__ = <attribute '__weakref__' of 'iometa' objects>
list of weak references to the object (if defined)

 
class iovar(cdms.tvariable.TransientVariable)
    iovar object.  This inherits from cdms transient variables and
uses it as a model for many of its methods.  Major difference
is the addition of ioapi metadata and projection info, iometa
object.
 
 
Method resolution order:
iovar
cdms.tvariable.TransientVariable
cdms.avariable.AbstractVariable
cdms.cdmsobj.CdmsObj
cdms.internattr.InternalAttributesClass
PropertiedClasses.Properties.PropertiedClass
cdms.slabinterface.Slab
MA.MA.MaskedArray
__builtin__.object

Methods defined here:
IO2cdms(self, copyFlag=True)
Returns a cdms transient variable.  Retains all attributes
and axes, does not contain projection and ioapi specific
metadata (ioM).
 
Input:
   copyFlag  - True [Default] - copy the variable's data
               False - share variable's data
 
Output:
    cdmsVar  - a cdms transient variable
IOchangeDate(self, startDate)
Changes the start date of the time axis.
 
Input:
 
    startDate - start date as mx.DateTime object, cdtime
                object or string of form:
                   YYYY-MM-DD HH:MM:SS.SS
 
Example:
    If the original time axis had a range:
         1999-06-24 6:00 --> 1996-06-25 5:00
 
    After calling:
        IOchangeDate('1996-01-12 12:00')
    new temporal range:
         1996-01-12 12:00 --> 1996-01-13 11:00'
IOclone(self)
Creates a clone of the ioVar object.  This makes a copy of
the data and the imbedded metadata objects
 
Output:
    copyVar - copy of the iovar object
IOequal(self, other, exactFlag=False, rtol=1.0000000000000001e-05, atol=1e-08)
Tests whether the data is 'equal' between the variable
and 'other'.
 
 
Input:
   other  - another variable of the same size.
 
   exactFlag - whether to do an exact comparison (True) or an
               'all close' comparison (False).  Default is an
               'all close', a comparison with a small tolerance
               to take into account floating point error.
 
   rtol - 'relative' tolerance.  Default is 1.e-5.
 
   atol - 'absolute' tolerance.  Default is 1.e-8.
 
Output:
   status - True - data equal
            False - data not equal
 
Notes/Assumptions:
 
   1.  This does not test the metadata.  It only tests the MA data
       array.
 
   2.  If you simply do a test w/ 'equal' signs, eg. a == b,
       this will return a cdms variable of the same shape as
       'a' and 'b'.  The elements of this array will be the
       element wise comparison of the 2 arrays. A value of 1
       means equal, 0 means unequal.  The function IOequal
       with exactFlag = True does the same thing, then tests
       to see if there are any unequal elements (0).
 
   3.  If you use the 'all close' comparison, exactFlag =
       False, then this simply uses the Numeric allclose
       function.  Here, 'equality' means:
          abs(dat1 - dat2) < (atol + rtol*abs(dat2))
 
       Where dat1 is the element of the variable and dat2 is
       the element of the other variable.
       
   4.  The 2 variables must have identical shapes.
 
   5.  If you are doing an exact comparison, I do not
       recommned using this in a loop.  Because of the sort,
       this is not terribly quick.
IOmodVar(self, vname=None, vunits=None, desc=None)
Modify some of the variable metadata.  In particular:
name, unit, description
 
Input:
     vname - variable name, string
 
     vunits - variable units, string
 
     desc - variable description, long name, string
IOshiftTimeInd(self, startDate)
Shifts the time axis values.  This preserves
the actual dates, but changes the start date and
axes values.
 
Input:
   startDate - start date as mx.DateTime object,
               cdtime object or string of form:
                 YYYY-MM-DD HH:MM:SS.SS
 
Note/Assumptions:
 
   1.  Internal function.  Should not be used by normal users.
IOsubset(self, domainLst=None, layerLst=None, timeLst=None, coordFlag=1, indexFlag=False, layindexFlag=True, copyFlag=True)
Subsets the variable based on a spatial, temporal, or
layer domain.
 
Inputs:
 
    domainLst - List of coordinate tuples that define a
                spatial domain of interest.  Inclusive of
                endpoints.
 
                Default = None -- i.e. whole domain
 
                Example:
                    domainLst = [(-90.2, 38.), (-88.45, 42.)]
                [SW corner, NE corner] of domain. Coordinates are
                in x,y order:
 
                where x is column # (0 based), longitude
                (degrees E), or xlon (E-W meters from
                projection center -- projection specific)
 
                And y is row # (0 based), latitude (degrees
                N), or ylat (N-S meters from projection
                center -- projection specific)
 
                    domainLst = (-36000, 36000)
                Coordinates are in xlon and ylat (in meters
                from projection origin).  In this case,
                ioapi2var will extract one point.
 
                See typeFlag for specifics.
 
    layerLst -  List of layers to extract.
 
                Example:
                    layerLst = [0, 4]
                    
                In this case, will extract layers 0 through,
                and including, 4.
 
                    layerLst = [2,2] OR layerLst = 2
                In both cases, only extracts layer 2
 
                Default = None -- i.e. all layers
 
    timeLst -   A time/date or list of dates that define a temporal
                domain of interest.  Dates are mx.DateTime
                objects, cdtime objects, or strings of the
                form:
                    YYYY-MM-DD HH:MM:SS.SS
                
 
                Example:
                    timeLst = [startDate, endDate]
 
                Where both startDate and endDate are
                mx.DateTime objects.
 
                    timeLst = '1996-06-12 2:05'
                In this case, it will extract only this date.
 
                Default = None -- i.e. whole temporal domain
                of this cctm file
 
                If timeLst is a list of indices, make sure you
                set indexFlag and use a 0 based integer index.
 
    coordFlag -  what type of coordinates are being used:
                llFlag (1)      -   lon, lat (degrees)
                projFlag (2)    -   xlon, ylat (meters) (see coordConv
                                    for more details)
                crFlag (3)      -   col #, row # (0 based)
 
                Default = llFlag
                
    indexFlag  - True, time in indices (0 based)
                 False [Default], time is mx.DateTime object, cdtime
                                  or string.
 
    layindexFlag  - True [Default], layer in indices (0 based)
                    False, layer in sigma levels
                    
    copyFlag  -  True [Default] - copy data
                 False - share data
                 
Output:
    iosubVar -  subset of the variable, iovar object.
 
 
Notes / Assumptions:
 
    1.  If using indices, it returns the dimension
        inclusively. For example, layerLst = [0,2] will return
        a variable w/ layers 0,1, and 2.
 
    2.  If using time indices, the values must be integers.
 
    3.  If you are using a single coordinate for the spatial
        domain, there is a possibility that the spatial domain
        of isubVar will have length 2.  This is the case that
        the point of interest falls exactly on the boundary of
        2 cells.
 
    4.  Presently, only copyFlag = True is implemented.
 
    5.  The order of the subset matters.  For example, if you
        subset with:
            timeLst = ['1996-06-25 12:00','1996-06-24 6:00']
            
        the data will be reversed along the time axis.  In
        other words subVar[0] will refer to '1996-06-25
        12:00', subVar[1] will refer to '1996-06-25 11:00',
        etc. The same is true for the spatial subsets.  I
        recommend that you use spatial subsets which go from
        SW to NE corner to maintain the same spatial axes as
        the original variable.
__abs__(self)
Wrapper around cdms tvariable absolute
__add__(self, other)
Wrapper around cdms tvariable add
__call__(self, *args, **kwargs)
cdms style subsetting.  Uses cdms selectors.
 
Wrapper arround the cdms.tvariable call
__div__(self, other)
Wrapper around cdms tvariable divide
__getitem__(self, key)
Wrapper around cdms tvariable get item
__getslice__(self, low, high)
Get slice
 
Unlike cdms, I am simply passing this to getitem
__iadd__(self, other)
Wrapper around cdms tvariable iadd 'x+=2'
__idiv__(self, other)
Wrapper around cdms tvariable idiv
__imul__(self, other)
Wrapper around cdms tvariable imul
__init__(self, data, ioM, axes=None, id=None, attributes=None, copyFlag=True)
Creates an ioVar object.
 
Input:
   data - a data array. The data array can be a
          Numeric, MV, cdmsVariable or an ioVar.
 
 
   ioM - iometa object.
 
   axes - cdms axes list [time, layer, latitude, longitude]
 
   id - identifier of variable
 
   attributes - dictionary of attribute values
 
   copyFlag - True [default] - copy the data
              False - share the data
 
Output:
   ioVar - iovar object
 
Notes/Assumptions:
 
   1.  If you are passing a cdms or iovar variable, you will
       not need to give axes, id, or attributes.  These will
       simply be taken from the variable's metadata.
 
   2.  The iovar inherits many of its properties from cdms
       transient variables.  See cdat's documentation for more
       specifics.
__isub__(self, other)
Wrapper around cdms tvariable isub
__mod__(self, other)
Wrapper around cdms tvariable module
__mul__(self, other)
Wrapper around cdms tvariable multiply
__neg__(self)
Wrapper around cdms tvariable negative
__pow__(self, other)
Wrapper around cdms tvariable raised to the power
__repr__(self)
__str__(self)
__sub__(self, other)
Wrapper around cdms tvariable subtract

Methods inherited from cdms.tvariable.TransientVariable:
__len__(self)
Length of first dimension
assignValue(self, data)
astype(self, tc)
return self as array of given type.
clone(self, copyData=1)
clone (self, copyData=1)
Return a copy of self as a transient variable.
If copyData is 1 (default), make a separate copy of the data.
copyAxis(self, n, axis)
Set n axis of self to a copy of axis. (0-based index)
Invalidates grid.
copyDomain(self, other)
Set the axes and grid by copying variable other.
copydimension(self, idim, other, jdim)
Set idim dimension of self to variable other's jdim'th 
This is for old cu compatibility. Use copyAxis for new code.
expertSlice(self, slicelist)
getAxis(self, n)
getDomain(self)
getGrid(self)
getValue(self, squeeze=1)
initDomain(self, axes, copyaxes=1)
isEncoded(self)
Transient variables are not encoded
setAxis(self, n, axis, savegrid=0)
Set n axis of self to a copy of axis. (0-based index)
setAxisList(self, axislist)
Set the axes to axislist.
setMaskFromGridMask(self, mask, gridindices)
Set the mask for self, given a grid mask and the variable domain
indices corresponding to the grid dimensions.
setMissing(self, value)
Set missing value attribute and fill value
set_fill_value(self, value)
Set missing value attribute and fill value
setdimattribute(self, dim, field, value)
Set the attribute named field from the dim'th dimension.
typecode(self)

Data and other attributes inherited from cdms.tvariable.TransientVariable:
count = 0

Methods inherited from cdms.avariable.AbstractVariable:
__array__(self, t=None)
__eq__(self, other)
__ge__(self, other)
__gt__(self, other)
__le__(self, other)
__lshift__(self, n)
__lt__(self, other)
__ne__(self, other)
__radd__ = __add__(self, other)
__rdiv__(self, other)
__rmul__ = __mul__(self, other)
__rshift__(self, n)
__rsub__(self, other)
__sqrt__(self)
crossSectionRegrid(self, newLevel, newLatitude, missing=None, order=None, method='log')
Return the variable regridded to new pressure levels and latitudes.
The variable should be a function of lat, level, and (optionally) time.
<newLevel> is an axis of the result pressure levels.
<newLatitude> is an axis of latitude values.
<method> is optional, either "log" to interpolate in the log of pressure (default),
  or "linear" for linear interpolation.
<missing> and <order> are as for regrid.CrossSectionRegridder.
decode(self, ar)
Decode compressed data. ar is a masked array, scalar, or MA.masked
generateGridkey(self, convention, vardict)
generateGridkey(): Determine if the variable is gridded, 
and generate ((latname, lonname, order, maskname, class), lat, lon) if gridded,
or (None, None, None) if not gridded. vardict is the variable dictionary of the parent
generateRectGridkey(self, lat, lon)
generateRectGridkey(): Determine if the variable is gridded, rectilinear,
and generate (latname, lonname, order, maskname, class) if gridded,
or None if not gridded
getAxisIds(self)
Get a list of axis identifiers
getAxisIndex(self, axis_spec)
Return the index of the axis specificed by axis_spec.
Argument axis_spec and be as for axisMatches
Return -1 if no match.
getAxisList(self, axes=None, omit=None, order=None)
Get the list of axis objects; 
If axes is not None, include only certain axes.
If omit is not None, omit those specified by omit.
Arguments omit or axes  may be as specified in axisMatchAxis
order is an optional string determining the output order
getAxisListIndex(self, axes=None, omit=None, order=None)
Return a list of indices of axis objects;
If axes is not None, include only certain axes.
less the ones specified in omit. If axes is None,
use all axes of this variable.
Other specificiations are as for axisMatchIndex.
getConvention(self)
Get the metadata convention associated with this object.
getGridIndices(self)
Return a tuple of indices corresponding to the variable grid.
getLatitude(self)
Get the first latitude dimension, or None if not found.
getLevel(self)
Get the first vertical level dimension in the domain, 
or None if not found.
getLongitude(self)
Get the first latitude dimension, or None if not found.
getMissing(self, asarray=0)
Return the missing value as a scalar, or as
a Numeric array if asarray==1
getOrder(self, ids=0)
getOrder(ids=0) returns the order string, such as tzyx.
 
if ids == 0 (the default) for an axis that is not t,z,x,y
the order string will contain a '-' in that location.
The result string will be of the same length as the number 
of axes. This makes it easy to loop over the dimensions.
 
if ids == 1 those axes will be represented in the order
string as (id) where id is that axis' id. The result will
be suitable for passing to order2index to get the 
corresponding axes, and to orderparse for dividing up into
components.
getRegion(self, *specs, **keys)
getRegion
Read a region of data. A region is an n-dimensional
rectangular region specified in coordinate space.
'slices' is an argument list, each item of which has one of the following forms:
- x, where x is a scalar
  Map the scalar to the index of the closest coordinate value
- (x,y)
  Map the half-open coordinate interval [x,y) to index interval
- (x,y,'cc')
  Map the closed interval [x,y] to index interval. Other options are 'oo' (open),
  'oc' (open on the left), and 'co' (open on the right, the default).
- (x,y,'co',cycle)
   Map the coordinate interval with wraparound. If no cycle is specified, wraparound
   will occur iff axis.isCircular() is true.
   NOTE: Only one dimension may be wrapped.
- Ellipsis
   Represents the full range of all dimensions bracketed by non-Ellipsis items.
- ':' or None
   Represents the full range of one dimension.
 
For example, suppose the variable domain is (time,level,lat,lon). Then
 
         getRegion((10,20),850,Ellipsis,(-180,180))
 
retrieves:
    - all times t such that 10.<=t<20.
    - level 850
    - all values of all dimensions between level and lon (namely, lat)
    - longitudes x such that -180<=x<180. This will be wrapped unless
      lon.topology=='linear'
getSlice(self, *specs, **keys)
x.getSlice takes arguments of the following forms and produces
a return array. The keyword argument squeeze determines whether
or not the shape of the returned array contains dimensions whose
length is 1; by default this argument is 1, and such dimensions
are 'squeezed out'.
There can be zero or more positional arguments, each of the form:
(a) a single integer n, meaning slice(n, n+1)
(b) an instance of the slice class
(c) a tuple, which will be used as arguments to create a slice
(d) None or ':', which means a slice covering that entire dimension
(e) Ellipsis (...), which means to fill the slice list with ':'
    leaving only enough room at the end for the remaining
    positional arguments
There can be keyword arguments of the form key = value, where
key can be one of the names 'time', 'level', 'latitude', or
'longitude'. The corresponding value can be any of (a)-(d) above.
 
There must be no conflict between the positional arguments and
the keywords.
 
In (a)-(c) negative numbers are treated as offsets from the end
of that dimension, as in normal Python indexing.
getTime(self)
Get the first time dimension, or None if not found
isAbstractCoordinate(self)
pressureRegrid(self, newLevel, missing=None, order=None, method='log')
Return the variable regridded to new pressure levels.
The variable should be a function of lat, lon, pressure, and (optionally) time.
<newLevel> is an axis of the result pressure levels.
<method> is optional, either "log" to interpolate in the log of pressure (default),
  or "linear" for linear interpolation.
<missing> and <order> are as for regrid.PressureRegridder.
rank(self)
reg_specs2slices(self, initspeclist, force=None)
regrid(self, togrid, missing=None, order=None, mask=None)
return self regridded to the new grid. Keyword arguments
are as for regrid.Regridder.
reorder(self, order)
return self reordered per the specification order
select = __call__(self, *args, **kwargs)
Selection of a subregion using selectors
setGrid(self, grid)
# Set the variable grid
specs2slices(self, speclist, force=None)
Create an equivalent list of slices from an index specification
An index specification is a list of acceptable items, which are
-- an integer
-- a slice instance (slice(start, stop, stride))
-- the object "unspecified"
-- the object None
-- a colon
The size of the speclist must be rank()
subRegion(self, *specs, **keys)
subSlice(self, *specs, **keys)

Methods inherited from cdms.cdmsobj.CdmsObj:
dump(self, path=None, format=1)
dump(self,path=None,format=1)
Dump an XML representation of this object to a file.
'path' is the result file name, None for standard output.
'format'==1 iff the file is formatted with newlines for readability
matchPattern(self, pattern, attribute, tag)
# Match a pattern in a string-valued attribute. If attribute is None,
# search all string attributes. If tag is not None, it must match the internal node tag.
matchone(self, pattern, attname)
# Return true iff the attribute with name attname is a string
# attribute which matches the compiled regular expression pattern, or
# if attname is None and pattern matches at least one string
# attribute. Return false if the attribute is not found or is not a string
searchPattern(self, pattern, attribute, tag)
# Search for a pattern in a string-valued attribute. If attribute is None,
# search all string attributes. If tag is not None, it must match the internal node tag.
searchPredicate(self, predicate, tag)
# Apply a truth-valued predicate. Return a list containing a single instance: [self]
# if the predicate is true and either tag is None or matches the object node tag.
# If the predicate returns false, return an empty list
searchone(self, pattern, attname)
Return true iff the attribute with name attname is a string
attribute which contains the compiled regular expression pattern, or
if attname is None and pattern matches at least one string
attribute. Return false if the attribute is not found or is not 
a string.

Methods inherited from cdms.internattr.InternalAttributesClass:
is_internal_attribute(self, name)
is_internal_attribute(name) is true if name is internal.
replace_external_attributes(self, newAttributes)
replace_external_attributes(newAttributes)
Replace the external attributes with dictionary newAttributes.

Methods inherited from PropertiedClasses.Properties.PropertiedClass:
__delattr__(self, name)
__getattr__(self, name)
__setattr__(self, name, value)
get_property_d(self, name)
Return the 'del' property handler for name that self uses.
Returns None if no handler.
get_property_g(self, name)
Return the 'get' property handler for name that self uses.
Returns None if no handler.
get_property_s(self, name)
Return the 'set' property handler for name that self uses.
Returns None if no handler.
set_property(self, name, actg=None, acts=None, actd=None, nowrite=None, nodelete=None)
Set attribute handlers for  name to methods actg, acts, actd
None means no change for that action.
nowrite = 1 prevents setting this attribute.
    nowrite defaults to 0. 
nodelete = 1 prevents deleting this attribute.
    nodelete defaults to 1 unless actd given.
if nowrite and nodelete is None: nodelete = 1

Methods inherited from cdms.slabinterface.Slab:
createattribute(self, name, value)
Create an attribute and set its name to value.
deleteattribute(self, name)
Delete the named attribute.
getattribute(self, name)
Get the attribute name.
getdimattribute(self, dim, field)
Get the attribute named field from the dim'th dimension.
For bounds returns the old cu one-dimensional version.
info(self, flag=None, device=None)
Write info about slab; include dimension values and weights if flag
listall(self, all=None)
Get list of info about this slab.
listattributes(self)
Return a list of attribute names.
listdimattributes(self, dim)
List the legal axis field names.
listdimnames(self)
Return a list of the names of the dimensions.
setattribute(self, name, value)
Set the attribute name to value.
showdim(self)
Show the dimension attributes and values.

Data and other attributes inherited from cdms.slabinterface.Slab:
std_slab_atts = ['filename', 'missing_value', 'comments', 'grid_name', 'grid_type', 'time_statistic', 'long_name', 'units']

Methods inherited from MA.MA.MaskedArray:
__and__(self, other)
Return bitwise_and
__float__(self)
Convert self to float.
__floordiv__(self, other)
Return divide(self, other)
__int__(self)
Convert self to int.
__or__(self, other)
Return bitwise_or
__pos__(self)
Return array(self)
__rand__ = __and__(self, other)
Return bitwise_and
__rfloordiv__(self, other)
Return divide(other, self)
__rmod__(self, other)
Return remainder(other, self)
__ror__ = __or__(self, other)
Return bitwise_or
__rtruediv__(self, other)
Return divide(other, self)
__rxor__ = __xor__(self, other)
Return bitwise_xor
__setitem__(self, index, value)
Set item described by index. If value is masked, mask those locations.
__setslice__(self, i, j, value)
Set slice i:j; if value is masked, mask those locations.
__truediv__(self, other)
Return divide(self, other)
__xor__(self, other)
Return bitwise_xor
byte_swapped(self)
Returns the raw data field, byte_swapped. Included for consistency
with Numeric but doesn't make sense in this context.
compressed(self)
A 1-D array of all the non-masked data.
dot(self, other)
s.dot(other) = innerproduct(s, other)
fill_value(self)
Get the current fill value.
filled(self, fill_value=None)
A Numeric array with masked values filled. If fill_value is None,
use fill_value(). 
 
If mask is None, copy data only if not contiguous.
Result is always a contiguous, Numeric array.
ids(self)
Return the ids of the data and mask areas
iscontiguous(self)
Is the data contiguous?
itemsize(self)
Item size of each data item.
mask(self)
Return the data mask, or None. Result contiguous.
outer(self, other)
s.outer(other) = outerproduct(s, other)
put(self, values)
Set the non-masked entries of self to filled(values). 
No change to mask
putmask(self, values)
Set the masked entries of self to filled(values). 
Mask changed to None.
raw_data(self)
The raw data; portions may be meaningless. 
May be noncontiguous. Expert use only.
raw_mask(self)
The raw mask; portions may be meaningless. 
May be noncontiguous. Expert use only.
savespace(self, value)
Set the spacesaver attribute to value
size(self, axis=None)
Number of elements in array, or in a particular axis.
spacesaver(self)
spacesaver() queries the spacesaver attribute.
tolist(self, fill_value=None)
Convert to list
tostring(self, fill_value=None)
Convert to string
unmask(self)
Replace the mask by None if possible.
unshare_mask(self)
If currently sharing mask, make a copy.

Properties inherited from MA.MA.MaskedArray:
flat
Access array in flat form.
get = _get_flat(self)
Calculate the flat value.
set = _set_flat(self, value)
x.flat = value
imag
Access the imaginary part of the array
get = _get_imaginary(self)
Get the imaginary part of a complex array.
set = _set_imaginary(self, value)
x.imaginary = value
imaginary
Access the imaginary part of the array
get = _get_imaginary(self)
Get the imaginary part of a complex array.
set = _set_imaginary(self, value)
x.imaginary = value
real
Access the real part of the array
get = _get_real(self)
Get the real part of a complex array.
set = _set_real(self, value)
x.real = value
shape
tuple giving the shape of the array
get = _get_shape(self)
Return the current shape.
set = _set_shape(self, newshape)
Set the array's shape.

Data and other attributes inherited from MA.MA.MaskedArray:
__dict__ = <dictproxy object>
dictionary for instance variables (if defined)
__weakref__ = <attribute '__weakref__' of 'MaskedArray' objects>
list of weak references to the object (if defined)
handler_cache_key = 'MA.MaskedArray'

 
Functions
       
binAverager(var, axisIn=0, binwidth=24, units='days since', updateFlag=True, forcelinear=False, weights=None, action='average', returned=0, combinewts=None)
binAverager-
 
    Creates a binned average over a specific axis.  For example,
    this could calculate the daily average from hourly data.
 
Input:
    var - cdms or iovar variable to average
 
    axisIn - the axis index, number, over which to average over.
             The default is 0, which usually indicates the time
             access.  Axis needs to be designated as either time
             level, latitude, or longitude (see Notes below) and
             have bounds.
 
    binwidth - the width of the bin.  Default value is 24.  The
               axis to be averaged over needs to be a multiple of
               the binwidth.  This is an index width, not in the
               units of the axis.
 
    units - the value used to update the units in the new axis
            created for the returned averaged variable. The
            default units are 'days since'.  This will use the
            first date as the starting point for the time axis.
            For example, if you are averaging over the time axis:
 
             old_timeAxis.units = 'hours since 1996-07-29 06:00:00.00'
             new_timeAxis.units = 'days since 1996-07-29 06:00:00.00'
 
    updateFlag - True [default] if update units on modified axis
                 False do not update units
 
    forcelinear - True force longitude axis to be linear topology
                  False [default] do not force topology to be
                  linear
 
    weights - parameter for cdutil.averager.  Passed directly to
              cdutil.averager.  See cdutil documentation.
 
    action - parameter for cdutil.averager.  Passed directly to
             cdutil.averager.  See cdutil documentation.
 
    returned - parameter for cdutil.averager.  Passed directly to
               cdutil.averager.  See cdutil documentation.
 
    combinewts - parameter for cdutil.averager.  Passed directly
                 to cdutil.averager.  See cdutil documentation.
    
Output:
 
    averVar - bin averaged variable.  The axis over which you
              averaged will be modified to reflect the new length.
              This axis may also have its units modified, see
              updateFlag and units above. If var is a cdms
              variable then averVar is a cdms variable.  If var is
              an iovar, then this will return an iovar.
 
Notes/Assumptions:
 
    1.  Axis to average over needs to be designated as one of the
        cdms fundamental axes (i.e. time, level, latitude, or
        longitude).  For example, to designate a longitude axis
        with linear topology:
            my_axis.designateLongitude(modulo=None)
 
    2.  Axis to average over needs to have bounds.  For example to
        test for bounds on the time axis:
           var.getTime().getBounds()
           
        If time axis and need to set the bounds, use the cdutil
        module.  For example:
           cdutil.setTimeBoundsDaily(var.getTime(), frequency=24)
 
    3.  If averaging over level, latitude or longitude, you will
        likely need to hand construct that axis values and bounds.
    
    4.  Copies id and attributes from var to averVar. 
 
    5.  Only tested for default values of cdutil.averager
        parameters (weights, action, returned, combinewts).
 
    6.  The forcelinear flag is needed b/c of problem with linear
        topology in the longitude axis.  Without this flag, the
        function cdutil.averager, which is called in this
        function, will change the topology to circular.  This flag
        will force the topology back to linear.
combineMeta(varLst)
Combines the metadata from a series of variables.
 
Input:
   varLst --  a list of variables that you want to combine
              their metadata.  They should be iovar objects.
Output:
   metaNew -- a tuple consisting of (ioM, cdmsM).  Where ioM
              is the new iometa object for all the variables, and
              cdmsM is the cdmsmeta object for the variables.
 
Notes/Assumptions:
 
   1.  The ioM and cdmsM are based primarily on the first variable
       in varLst.
concatenate(varLst)
Concatenates a series of variables into one variable.
 
Input:
   varLst - a list of variables to concatenate.
 
Output:
   ioVar - iovar object, concatenation of all variables
           in varLst
           
Notes/Assumptions:
 
 1.  Only concatenates along the time axis.  All other axes should
     be identical.
 
 2.  Assumes that the order of varLst is in temporal order and the
     variables' time axes do not overlap.
 
 3.  Uses the first variable in varLst to define metadata
     for the return variable.
coordConv(ioM, coordLst, typeFlag=1, cdmsM=None, cellLocFlag=1)
Converts b/w different types of spatial coordinates.
 
 
Inputs:
    ioM -      Projection and domain info.  IoM is a ioMmeta object 
 
    coordLst -  List of coordinate tuples to be converted.
                Example:
                    coordLst = [(-90.2, 40.), (-78.45, 42.3), (-88.1, 44.2)]
                Coordinates are in x,y order:
 
                where x is column # (0 based), longitude (degrees E), or
                xlon (E-W meters from projection center -- projection
                specific)
                
                And y is row # (0 based), latitude (degrees N), or
                ylat (N-S meters from projection center -- projection
                specific)
                (See typeFlag below)
 
    typeFlag -  indicates conversion between which 2 'coordinates systems':
 
        ll2projFlag (1) -   lon, lat (degrees) --> xlon, ylat (meters) [Default]
                                 
        ll2crFlag (2)   -   lon, lat (degrees) --> col #, row #  (0 based)
 
        proj2llFlag (3) -   xlon, ylat (meters) --> lon, lat (degrees)   
 
        proj2crFlag (4) -   xlon, ylat (meters) --> col #, row # (0 based)
 
        cr2llFlag (5)   -   col #, row # (0 based) --> lon, lat (degrees)
        
        cr2projFlag (6) -   col #, row # (0 based) --> xlon, ylat (meters)
 
    cdmsM -    Domain info, cdmsmeta object.  Only needed if you are doing
               conversions from or to cr (column, row).  Default is None.
               
    cellLocFlag - Where in the cell to locate the point:
        crossFlag (1)   -   center of cell [Default]
        SWFlag (2)      -   Southwest corner of cell
        SEFlag (3)      -   Southeast corner of cell
        NEFlag (4)      -   Northeast corner of cell
        NWFlag (5)      -   Northwest corner of cell
 
        Only  meaningful for cr2ll or cr2proj conversion.
 
 
Returns:
 
    convCoordLst - List of coordinate tuples that have been
                    converted from coordLst.  The list has a
                    similar format to coordLst, but also has a z
                    value:          
                    [(x1,y1,z1), (x2,y2,z2),...]
 
                    Conversions from cells, cr2proj and cr2ll, only have
                    spatial coordinates:
                    [(x1,y1), (x2,y2), ...]
                    
                    See coordLst and typeFlag above for format and
                    coordinate types specifics.
 
Notes/Assumptions:
 
    1.  z coordinates (vertical distance) are simply passed
        through to the projection software.  In most cases, the z
        value will simply be returned w/o modification.
        
    2.  Projections presently supported:
            Lambert Conformal Conic
 
    3.  Grid cells are assumed to be regularly spaced in the
        projection coordinate system. For example, the grid cells
        might be 4000 x 6000 meters in a lambert conformal
        coordinate system.  When they are transformed to lon/lat
        or if you imagine them on the surface of the earth, they
        will NOT be regularly spaced or equal area.
 
    4.  Out of domain errors are only checked for conversions from
        cr (col,row). Otherwise, coordConv will calculate the new
        coordinates w/o warning, even if they are outside the
        extent of the grid domain.  To test for domain errors, use
        the function coordInDomain.
 
    5.  For conversions to or from col,row, one needs to pass
        cdmsM, a cdmsMeta object.
 
    6.  For conversions to col,row, coordinates that exactly hit
        the boundary between 2 cells are promoted to the larger
        col or row number.  For example, if the boundary b/w row
        30 and 31 is at 24000, then a ylat value of 24000 will be
        converted to row 31.  The one exception is the North or
        East edge of the domain.  A coordinate exactly on these
        boundaries will be demoted to the last col or row.
 
    7.  One should be careful with ll2cr conversions near the
        boundary.  A coordinate that is very near the domain
        boundary may be determined as outside the boundary during
        the intermediary conversions.  This is due to the problem:
 
             xlon1,ylat1 -- > lon, lat --> xlon2, ylat2
        Where, xlon1, ylat1 are slightly different than xlon2, ylat2
coordInDomain(ioM, cdmsM, coord=(0, 0, 0), typeFlag=1, domainFlag=False)
Simply tests whether or not a coordinate is in the grid's
    spatial domain.
 
Input:
    ioM -  projection info, iometa object
 
    cdmsM - domain info, axes. cdmsmeta object
    
    coord - coordinate tuple to be tested.
                Example:
                    coord = (-90.2, 40.)
                Coordinates are in x,y order:
 
                where x is column # (0 based), longitude (degrees E), or
                xlon (E-W meters from projection center -- projection
                specific)
                
                And y is row # (0 based), latitude (degrees N), or
                ylat (N-S meters from projection center -- projection
                specific)
                
                (See typeFlag below)
 
    typeFlag -  what type of coordinates are being used:
            llFlag (1)      -   lon, lat (degrees) [Default]
            projFlag (2)    -   xlon, ylat (meters) (see coordConv for
                                more details)
            crFlag (3)      -   col #, row # (0 based) Should be integers,
                                see Notes below.
 
    domainFlag - True. Returns the domain extent as a coordLst:
                        [(xminDomain, yminDomain, zminDomain),
                        (xmaxDomain, ymaxDomain, zmaxDomain)]
                        Coordinates reflect the typeFlag.  When
                        this flag is set, coord is ignored.  For
                        projection and lon,lat coordinates, this
                        is the external edge of the 1st and last
                        grid cells.
 
                        zmin and zmax indicate the top and bottom
                        layer for crFlag.  Otherwise, zmin and
                        zmax are set to 0
                        
                 False. Default. Checks the coord.
 
Returns:
    True    -   coordinate within the grid's domain
 
    False   -   coordinate outside of grid's domain
 
    If domainFlag is True - returns domain range as a coordLst:
                        [(xminDomain, yminDomain, zminDomain),
                        (xmaxDomain, ymaxDomain, zmaxDomain)]
                        Coordinates reflect the typeFlag.  When this flag
                        is set, coord is ignored.
 
                        zmin and zmax indicate the top and bottom layer for crFlag.
                        Otherwise, zmin and zmax are set to 0
                    
 
Notes/Assumptions:
 
    1.  z coordinates (vertical distance) is not tested.
    
    2.  For crFlag, a return of True means that there is an exact
        match.  For example if the cols are 0 - 50, a coord of 40
        would return True, a coord of 40.2 would return False.
createVariable(data, ioM, axes=None, id=None, attributes=None, copyFlag=True)
Creates an ioVar object.
 
Input:
   data - a data array. The data array can be a
          Numeric, MV, cdmsVariable or an ioVar.
 
 
   ioM - iometa object.
 
   axes - cdms axes list [time, layer, latitude, longitude]
 
   id - identifier of variable
 
   attributes - dictionary of attribute values
 
   copyFlag - True [default] - copy the data
              False - share the data
 
Output:
   ioVar - iovar object
 
Notes/Assumptions:
 
   1.  If you are passing a cdms or iovar variable, you will
       not need to give axes, id, or attributes.  These will
       simply be taken from the variable's metadata.
 
   2.  The iovar inherits many of its properties from cdms
       transient variables.  See cdat's documentation for more
       specifics.
date2Files(searchStr, startDate, endDate)
Determines a list of cctm files that span a date range.  Given
    a basename (path plus file identifier) and a start and end
    date, it will return a dictionary of files that span that date
    with the appropriate index from each file.
 
    Input:
        searchStr    -  identifier for files to search.  Uses a unix
                        type wildcard.  For example:
                        '/data/CCTM_CONC.D1.00*'
                        will match files:
                           /data/CCTM_CONC.D1.001
                           /data/CCTM_CONC.D1.002
                           /data/CCTM_CONC.D1.009.nc
 
                        But will not match:
                           /data/CCTM_CONC.D1.020
                           
 
        startDate   -   first date of interest.  This is a mx.DateTime object,
                        cdtime object or string.
 
 
        endDate   -     end date of interest.  This is a mx.DateTime object,
                        cdtime object or string.
 
    Returns:
        indexDict   -   Dictionary, keys are the filenames , values are
                        fileindex objects which have attributes: iofile
                        handle (still open), startInd, endInd.
 
                        Where startInd is the time index to begin
                        extracting data from, and endInd is the
                        last index w/in this file to extract data
                        from.
 
Note/Assumptions:
 
   1.  Internal function.  Should not be used by normal users.
dateInDomain(cdmsM, testDate, simpleFlag=True)
Tests if date is in temporal domain.
 
Input:
    
    cdmsM - cdmsmeta object - domain info
 
    testDate - date to test, mx.DateTime object, cdtime object, or
               string of form:
               YYYY-MM-DD HH:MM:SS.SS
 
               e.g. '1996-07-12 2:00'
 
    simpleFlag - True [Default] simply tests if w.in temporal domain
                 False - checks if date exactly matches one of the dates
                         in the timeAxis
                         
Return:
    True - in domain
    False - not in domain
    
Note:
 
    1.  If simpleFlag is False, only returns true if testDate is
    an exact match to one of the dates from timeAxis.
dates2Cdtime(indate)
Converts dates to cdtime objects
 
input:
    indate -- a string or DateTime object of a properly formatted date.
 
Output:
    cdtime object corresponding to indate
 
Note:
   1.  proper string format:  'YYYY-MM-DD HH:MM:SS.SS'
       eg.  '1996-02-14 6:00:01'
dates2DateTime(indate)
Converts dates to mx.DateTime objects
 
input:
    indate -- a string or cdtime object of a properly formatted date.
 
Output:
    DateTime object corresponding to indate
 
Note:
   1.  proper string format:  'YYYY-MM-DD HH:MM:SS.SS'
       eg.  '1996-02-14 6:00:01'
iom2proj(ioM, coordsys='NAD83', falseEast=0, falseNorth=0)
Converts a iometa object projection info into an osr object.
  The osr object is used by gdal for all projection conversions.
  
Inputs:
   ioM  -  iometa object
 
   coordsys - coordinate system.  Default is 'NAD83'.  See osr/gdal
              documentation for acceptable coordinate systems
 
   falseEast - false easting, in coordinates of projection.  Default is 0.
 
   falseNorth - false northing, in coordinates of projection. Default is 0.
 
Returns:
      proj - osr object.  Can be used for osr and gdal coordinate
             transformations. 
 
Notes:
 
  1.  Internal function.  Should not be used by normal users.
 
  2.  Presently only supports the following projections:
            Lambert Conformal Conic
isIOAPI(fileHandle)
Tests whether or not a file is in IO/API format.   All it does is check
if the file has a global attribute IOAPI_VERSION.
 
Input:
    fileHandle - a CdmsFile object, the return of cdms.open(fileName)
 
Return:
     True  -   Is recognized as IO/API format.
     False -   Is not recognized as IO/API format
 
Note:
   Internal Function.
isIOCDMS(fileHandle)
Tests whether or not a file is a CF netCDF w/ ioapi metadata.
All it does is check if the file has:
      ioapi_meta variable
      grid_map variable
 
Input:
    fileHandle - a CdmsFile object, the return of cdms.open(fileName)
 
Return:
     True  -   Is recognized as CF netCDF w/ IOAPI metadata.
     False -   Is not recognized as CF netCDF w/ IOAPI metadata
 
Note:
   Internal Function.
layerInDomain(cdmsM, testLay, simpleFlag=True)
Tests if layer in layer domain
.   
    Input:
        
        cdmsM - cdmsmeta object - domain info
 
        testLay - sigma layer
 
        simpleFlag - True [Default] simply tests if w.in layer domain
                     False - checks if layer exactly matches one of the sigma
                             layers in the layAxis
                             
    Return:
        True - in domain
        False - not in domain
        
    Note:
 
       1.  Assumes that sigma layers go from highest value to smallest value.
open(fileName, rwFlag='r', typeFlag=2, newM=None, logFile=None, llaxesFlag=False)
Opens a file and returns an iofile object.
 
Input:
   fileName  - Either a fileName for an IO/API file or a CF
               complient netcdf file.
 
   rwFlag    - 'r' - read
               'w' - write / overwrite
 
   typeFlag  - cffileFlag (default), write a cf netcdf file
               iofileFlag, write an ioapi format file
               (Only needed for writes, reading automatically
               determines file type)
 
   newM      - tuple (ioM, cdmsM) describes the ioapi metadata
               domain, and geographic projection of the data
               for this file. This tuple is the return of
               combineMeta.  Only needed for multiple writes
               to ioapi files (see Notes).
 
   logFile   - log file name. Used to store ioapi library
               log info.  Default is None, display log
               info in stdout.  If a file is indicated, it
               will overwrite any previous file of that name.
 
   llaxesFlag- True - write out alternative lat and lon coordinates
               False [default] - do not write out alternative
                                 coordinates
                
Output:
   ioFile    - iofile object
 
Notes/Assumptions:
 
   1.  If the file format is neither ioapi or cf compliant,
       but it is a netcdf file, it will raise an error.
       
   2.  If you are writing ioapi format and pass a logFile,
       the function sets up an environmental variable,
       LOGFILE.
 
   3.  If you are writing ioapi format file, the iofile
       object will setup an environmental variable for the
       output name.  The variable will be of the form,
       'OUTDDDDDDDDDD'.  This is needed for the ioapi
       library.
 
   4.  If you are writing to a file that already exists.
       the open command will print a warning and remove
       the file before writing.
 
   5.  Multiple writes and ioapi format. All the metadata
       for an ioapi file needs to be written in the
       beginning.  If you want to have multiple, seperate
       writes to the file, you need to open the file with
       the metadata for all the variables you plan to
       write to this file.  In order to do multiple
       writes, pass the newM parameter.  Here is an
       example of writing 3 variables:
 
         >>> newM = ioapiTools.combineMeta([o3, nh3, co])
         >>> f = ioapiTools.open('test.ioapi','w', newM,                                          ioapiTools.iofileFlag)
         >>> f.write(nh3)
         ...
         >>> f.write([o3,co])
         >>> f.close()
 
   6.  The llaxesFlag indicates whether or not to write out
       alternative coordinates, lat and lon.  This is only
       meaningful if you are writing to a CF netCDF file.
       These alternative coordinates are cdms variables in
       there own right.  They are both functions of yLat and
       xLon, e.g. lat(yLat,xLon).  To be truelly CF compliant,
       this flag should be on.  But, this slows down the write
       and may cause some programs to have problems displaying
       the data.  The values of lat are the latitude at each
       yLat,xLon grid point.  This basically translates the
       regular grid in the native projection to an irregular
       grid in degrees N,E.  It also creates a bounds_lon and
       bounds_lat variable, which correspond to the irregular
       corners of each grid cell.
pipethrough(cmd, lineLst=[])
Allows one to send a command to the shell and get back the
stdout and stderror.  This is a very general program w/
applications outside of ioapi related projects.
 
Based on 'Python in a Nutshell' by Alex Martelli, pg 290.
 
input:
  cmd -   a command to run, simply a string.
 
  lineLst - not sure??? I leave it blank and it seems to work.
 
Output:
  resultLst -  the stdout and stderror.  Each line is the element of the
               list.
 
Example:
    buff = pipethrough('ls -l *.py')
 
    buff will contain the result of:
       $ ls -l *.py
    With each line of stdout or stderror as a seperate element of the
    buff list.
scan(searchStr, startDate, endDate)
Scans files for the date range.  Opens up each of the files
(making a list of iofiles) for variable extraction.
 
Input:
    searchStr - a search string
 
    startDate - beginning date
 
    endDate - last date.
 
 
Output:
    ioScan - iofilescan object.
 
Notes/Assumptions:
 
  1.  Search string is of unix form, use '*' for wild card.
      For example the search string 'CCTM_CONC.D1.*' will
      match:
         CCTM_CONC.D1.001, CCTM_CONC.D1.033.nc, ...
          
  2.  Search string should only match files of a single file
      type (either all ioapi format or all cf netcdf format).
 
  3.  A sort of the file names should put them in temporal order.
 
  4.  Only used for extraction, not for writing. See ioScan.extract.

 
Data
        NEFlag = 4
NWFlag = 5
SEFlag = 3
SWFlag = 2
byhandFlag = 4
cdmsvarFlag = 3
cffileFlag = 2
cr2llFlag = 5
cr2projFlag = 6
crFlag = 3
crossFlag = 1
grid2mapFlag = 2
grid2projFlag = 1
iofileFlag = 1
ll2crFlag = 2
ll2projFlag = 1
llFlag = 1
map2gridFlag = 3
proj2crFlag = 4
proj2llFlag = 3
projFlag = 2