NCDF_FILE
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.
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
IDL> nCDFObject = Obj_New('NCDF_FILE', filename)
filename: The name of a netCDF file to read, write to, or browse.
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".
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
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')
IDL> filename = 'example.nc' IDL> ncdfObj = Obj_New('NCDF_FILE', filename) IDL> ncdfObj -> Browse IDL> Obj_Destroy, ncdfObj
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. Small typo fixed in setting CHAR datatype for IDL 8.1 and higher. 22 May 2013. DWF. Typo (CONTINUOUS->CONTIGUOUS) fixed in WriteDefVar method. 30 July 2013. DWF. Modified CopyVarDefTo method to allow new NCDF4 keywords. 30 July 2013. DWF. Added DelGlobalAttr method to allow deletion of global attributes. 11 Jan 2014. DWF. Found typo in UBYTE variable code, which I fixed. 12 Fef 2016. DWF.