NCDF_FILE__DEFINE

Name

NCDF_FILE

Purpose

The pupose of this NCDF_File object is three-fold. (1) Allow the user to easily
determine what information is inside a netCDF file and allow easy access
to such information. (2) Allow the user to easily create a netCDF file from
scratch. (3) Allow the user to easily copy information from one netCDF
file to another.

Author

FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: david@idlcoyote.com
Coyote's Guide to IDL Programming: http://www.idlcoyote.com

File I/o

Calling Sequence

IDL> nCDFObject = Obj_New('NCDF_FILE', filename)

Arguments

filename: The name of a netCDF file to read, write to, or browse.

Keyword Parameters

ALERT: Set this keyword if you wish to have alert from the object's error logger.
Input. Default is 1.

BROWSE: If this keyword is set, the Browse Window is invoked as soon
as the object is initiated. Input. Default is 0.
CLOBBER: Set this keyword if you are opening a netCDF file that already exists and
you want to overwrite the existing file. Input. Default is 0.

CREATE: Set this keyword if you wish to create a new netCDF file to write
into. Input. Default is 0, which means the file will be opened as
"read-only".

DELETE_ON_DESTROY: Set this keyword if you wish to delete the error log file when
the ErrorLogger object is destroyed. This will only happen if the ErrorLogger
object is not in an error state. Input. Default is 1.

MODIFY: Set this keyword if you wish to modify (write to) a file you are opening.
If not set, the file will be opened as "read-only".
REQUIRES:
The following programs are required from the Coyote Library. And it is always a
good idea to make sure you have the latest version of the Coyote Library code,
as updates are irregular and frequent.
http://www.idlcoyote.com/programs/ncdf_attribute__define.pro
http://www.idlcoyote.com/programs/ncdf_data__define.pro
http://www.idlcoyote.com/programs/ncdf_browser.pro
http://www.idlcoyote.com/programs/ncdf_castdatatype.pro
http://www.idlcoyote.com/programs/ncdf_container__define.pro
http://www.idlcoyote.com/programs/ncdf_dimension__define.pro
http://www.idlcoyote.com/programs/ncdf_variable__define.pro
http://www.idlcoyote.com/programs/errorlogger__define.pro
http://www.idlcoyote.com/programs/error_message.pro
http://www.idlcoyote.com/programs/centertlb.pro
http://www.idlcoyote.com/programs/undefine.pro
http://www.idlcoyote.com/programs/textbox.pro
http://www.idlcoyote.com/programs/fsc_base_filename.pro
http://www.idlcoyote.com/programs/textlineformat.pro

These files may be (almost certainly are!) dependent on other Coyote Library files.

Methods

The following methods are available. Each is documented in front of the method.
ncdfObject -> Browse
ncdfObject -> CopyVarAttrTo, varName, attrName, destObj
ncdfObject -> CopyVarDataTo, varName, destObj, COUNT=count, OFFSET=offset, STRIDE=stride
ncdfObject -> CopyVarDefTo, varName, destObj
ncdfObject -> CopyGlobalAttrTo, attrName, destObj
ncdfObject -> CopyDimTo, dimName, destObj
dimNames = ncdfObject -> GetDimNames(COUNT=dimCount)
dimValue = ncdfObject -> GetDimValue(dimName)
fileID = ncdfObject -> GetFileID()
globalAttrNames = ncdfObject -> GetGlobalAttrNames(COUNT=attrCount)
attrValue = ncdfObject -> GetGlobalAttrValue(attrName, DATATYPE=datatype)
ncdfObject -> GetProperty, ....
property = ncdfObject -> GetProperty(thisProperty)
varAttrNames = ncdfObject -> GetVarAttrNames(varName, COUNT=attrCount)
varAttrValue = ncdfObject -> GetVarAttrValue(varName, varAttrName, COUNT=attrCount)
varNames = ncdfObject -> GetVarNames(COUNT=varCount)
varData = ncdfObject -> GetVarData(varName, COUNT=count, OFFSET=offset, STRIDE=stride)
answer = ncdfObject -> HasGlobalAttr(attrName, OBJECT=object)
answer = ncdfObject -> HasDim(dimName, OBJECT=object)
answer = ncdfObject -> HasVar(varName, OBJECT=object)
answer = ncdfObject -> HasVarAttr(varName, attrName, OBJECT=object)
ncdfObject -> PrintFileInfo
ncdfObject -> ParseFile
ncdfObject -> SetMode, DEFINE=define, DATA=data
ncdfObject -> WriteVarData, varName, data, COUNT=count, OFFSET=offset, STRIDE=stride
ncdfObject -> WriteVarDef, varName, dimNames, DATATYPE=datatype, VAROBJ=varObj
ncdfObject -> WriteDim, dimName, dimSize, UNLIMITED=unlimited
ncdfObject -> WriteGlobalAttr, attrName, attrValue, DATATYPE=datatype
ncdfObject -> WriteVarAttr, attrName, attrValue, varObj, DATATYPE=datatype

Notes

Note that all variable, attribute, and dimension names in a netCDF file are CASE SENSITIIVE!!
Thus, it is a good idea to use the methods provided in this object to obtain and examine
information in the file, as these names are handled in a case sensitive manner.

Whenever you are creating a new netCDF file, you should try to create the file in
the following way.
1. Create your global attributes.
2. Create the dimensions you will be using to describe the variables.
3. Define the variables. To do this correctly, dimensions MUST be defined.
4. Define variable attributes.
5. Load your variables with data.

Note that the data type of the _FillValue variable attribute MUST match the
data type of the variable data. Otherwise, you will have MANY problems! This
is a common source of error.

Note that in almost all cases where you see the names "varName", "dimName", or
"attrName" used as input variables, you can substitute the proper object
reference in place of the actual name. In other words, you could get the value
of a variable attribute by doing something like this:

check = ncdfObject -> HasAttr('history', OBJECT=attrObj)
IF check THEN attrValue = ncdfObject -> GetGlobalAttrValue(attrObj)

as opposed to this:

IF check THEN attrValue = ncdfObject -> GetGlobalAttrValue('history')

Example

IDL> filename = 'example.nc'
IDL> ncdfObj = Obj_New('NCDF_FILE', filename)
IDL> ncdfObj -> Browse
IDL> Obj_Destroy, ncdfObj

Modification History

Written by: David W. Fanning, 3 Feb 2010, using (stealing, really) plenty of ideas
from Mark Hadfield's Motley Library. Mark's mghncfile object is terrific, but it
had a number of limitations for my particular application, which I have attemped
to correct in my version of the software. But I wouldn't have even attempted this
had Mark not blazed the trail and Matt Savoie not insisted that I look at Mark's
wonderful library.
Changes in the way dimensions with a zero length are handled. 11 Feb 2010, DWF.
Added GetVarInfo method. 20 March 2010. DWF.
Added MISSINGINIDCES and FILLVALUE output keywords to GetVarData method. 20 March 2010. DWF.
Added output keywords SCALE_FACTOR, ADD_OFFSET, and DATATYPE to GetVarData method
so that these values can be obtained with the data. 29 Apr 2010. DWF.
I changed "missingValue" to "fillValue" some time ago, but I missed one in
the GetVarData method. Fixed. 7 June 2010. DWF.
Used the undefine procedure OBJ_DELETE, rather than OBJ_DESTROY. Sheesh! 18 June 2010. DWF.
Added NETCDF4_FORMAT keyword. 13 Feb 2012. DWF.
Added a bunch of new IDL 8.0 and 8.1 keyword to the WriteVarDef method to allow
access to these keywords in NCDF_VarDef. Also modified the NETCDF4_FORMAT keyword
to apply only in IDL versions 8.0 and higher. 21 Feb 2012. DWF.