This tutorial describes three different ways of reading from a file: reading from an IOAPI file, a CF netCDF file, and across multiple files. 

## import the ioapiTools package and 
## refer to it via the name 'ioT'
import ioapiTools as ioT

## open the file for reading
filename = "~/tmp/exampleData/CCTM_ACONC.D2.001"
f = ioT.open(filename)

This assumes that you have copied the exampleData directory from the ioapiTools package, <CDAT_SRC_DIR>/contrib/ioapiTools/build/ioapiTools-20050729/Test, to your 'tmp' directory. 

The ioapiTools 'open' function returns an iovar object, in this case 'f''.  The iovar object, as do all objects in python, has its own set of methods and attributes.  To see these methods and attributes and to find which variables are in this file:

## list of attributes and methods of iovar object 'f'
dir(f)
## ['__call__', '__class__', '__delattr__', '__dict__', '__doc__', '__getattribute__', '__hash__', '__init__', '__module__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__str__', '__weakref__', 'cdmsM', 'close', 'cols', 'dateConv', 'end', 'extract', 'f', 'fileDesc', 'fileName', 'ftype', 'getCdmsMeta', 'getGridMap', 'getTimes', 'getXlons', 'getYlats', 'gridName', 'gridType', 'grid_map', 'hasAxes', 'ioM', 'layers', 'listvariables', 'nthick', 'nvars', 'openFlag', 'padList', 'padNumeric', 'padText', 'parse', 'populateBdesc3', 'populateCdesc3', 'projectionName', 'rows', 'sdate', 'setNone', 'standparallel1', 'standparallel2', 'start', 'stime', 'times', 'typeFlag', 'upname', 'vdescLst', 'vertTop', 'vertType', 'vertcoords', 'vnameLst', 'vtypeLst', 'vunitsLst', 'write', 'writeFlag', 'xcellSize', 'xcent', 'xedge', 'xlonLst', 'xorigCross', 'xunits', 'ycellSize', 'ycent', 'yedge', 'ylatLst', 'yorigCross', 'yunits']

## list of variables in the IOAPI file
f.listvariables()
## ['O3', 'CO', 'NO2', 'NO']

## Get some general information on the iovar object:
print f
## <ioapiTools- file: /home/azubrow/tmp/exampleData/CCTM_ACONC.D2.001, mode: 'r', format: ioapi, status: open >

The list of methods and attributes can be broken into two sections.  All the methods that start and end with two underscores are "private" and most users will not need to call them directly.  The other methods and attributes can be called or modified directly.  I recommend that you do not modify attributes directly; rather you use the appropriate method.   Most users will only need to use the listvariables and the write methods.

The listvariables method does exactly what you would it expect, it returns a list of variable names.  In this case, the variables in the file are: O3, CO, NO2, and NO.

Finally, the print command will print some info about the file: name, mode, format, and status

2. Reading a CF netCDF file

The steps needed to read a CF netCDF file are identical to those for an IOAPI file:

## import the ioapiTools package and 
## refer to it via the name 'ioT'
import ioapiTools as ioT

## open the file for reading
filename2 = "~/tmp/exampleData/o3_aconc.nc"
g = ioT.open(filename2)

Note: this will not work with any netCDF file.  The file needs to have the unique metadata that comes with an IOAPI file.  If you use ncdump to look at the metadata for the CF netCDF file (from the unix prompt):

$ ncdump -c ~/tmp/exampleData/o3_aconc.nc | less

you'll find that there are two additional variables, Lambert_Conformal and ioapi_meta.  They contain the projection and IOAPI specific information, respectively.  Without those two additional variables, ioapiTools will not be able to read the files.  Any CF netCDF file written by ioapiTools will automatically contain these additional variables (see "Writing" tutorial).   If you wanted to read a non ioapiTools compliant netCDF file, simply use the underlying cdms commands (see "Files" under the Tutorials directory).

  Contents

3. Reading across multiple files

I often find that I want to extract data that spans multiple files.  To facilitate this, I created a scan function that uses a temporal range:

## import ioapiTools package
import ioapiTools as ioT

## Define 2 dates
## could also use cdtime and mx.DateTime objects
start = "1996-06-24 12:00"
end = "1996-06-26 22:00"

## create ioscan object
fs = ioT.scan("~/tmp/exampleData/CCTM_ACONC.D2.0*", start, end)

## print some general info about fs
print fs
##
 object: iofilescan
 dates: 1996-06-24 12:00 - 1996-06-26 22:00
 first file: /home/azubrow/tmp/exampleData/CCTM_ACONC.D2.001
 last file: /home/azubrow/tmp/exampleData/CCTM_ACONC.D2.003
##

The scan function returns an iofilescan object, 'fs', which is very similar to an iofile object except that it can span multiple physical files.  In the call sequence, it is searching for all files that match the regular expression "CCTM_ACONC.D2.0*".  It searches through those files and finds the specific files which cover the date range.  Future method calls of 'fs' will act on this range indepently of the number of files this range spans (see "Variables"). 

Note: when defining a search string, all matching files must be of the same format type (i.e. either all IOAPI or all CF netCDF).

	Contents	Previous	Next