CDF_VARCREATE ------------- The CDF_VARCREATE function creates a new variable in a Common Data Format file. CDF's "variable" is a generic name or an object that represents data where data can be 0-dimensional (scalar data) or multi-dimensional (up to 10-dimension), and it does not have any scientific context associated it. For example, a variable can be data representing an independent variable, a dependent variable, time and date value, or whatever data might be (e.g. image, XML file, etc.). In other words, the variable doesn't contain any hidden meanings other than the data itself. One may describe one variable's relationship with other variable(s) through CDF's "attributes". There are two types of variables (rVariable and zVariable) and they can coexist in the same CDF file. Every rVariable in a CDF must have the same number of dimensions and dimension sizes, whereas each zVariable has its own dimension and dimension size. Suppose there are 2 rVariables (v1, v2) in a CDF. Let's say v2 is defined as 2:[20,10] - 2-dimensional array with its size of 20 x 10 (20 rows and 10 columns). Then v1 MUST be defined as 2:[20,10] albeit it only needs 1:[8] (since it is a rVariable). But if this model is implemented using zVariables, then v1 and v2 can be defined as 1:[20,10] and 1:[8] instead of 1:[20,10] and 1:[20,10]. As you can see above, since all the rVariables must have the same dimensions and dimension sizes, there'll be a lot of disk space wasted if a few variables need big arrays and many variables need small arrays. So why would you want to use rVariables over zVariables? There's no reason to use rVariables at all (since zVariables are much more efficient) if you are creating a new CDF file. But if you are analyzing data files that were created with early CDF releases or contain rVariables for some reason, you'll need to use rVariables. One may wonder why there are rVariables and zVariables, not just zVariables. When CDF was first introduced in early 90's, only rVariables were available. The inefficiencies with rVariables were quickly realized and addressed with the introduction of zVariables in later CDF releases. Syntax Result = CDF_VARCREATE( Id, Name [, DimVary] [, /VariableType] [, ALLOCATERECS=records] [, DIMENSIONS=array] [, NUMELEM=characters] [, /REC_NOVARY | , /REC_VARY] [, /ZVARIABLE] ) Return Value Returns the variable of the type specified by the chosen keyword. Arguments Id The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE. Name A string containing the name of the variable to be created. DimVary A one-dimensional array containing one element per CDF dimension. If the element is non-zero or the string 'VARY', the variable will have variance in that dimension. If the element is zero or the string 'NOVARY' then the variable will have no variance with that dimension. If the variable is zero-dimensional, this argument may be omitted. Keywords VariableType You must specify the type variable being created. This is done by setting one of the following keywords: CDF_BYTE CDF_CHAR CDF_UCHAR CDF_INT1 CDF_UINT1 CDF_INT8 CDF_INT2 CDF_UINT2 CDF_TIME_TT2000 CDF_INT4 CDF_UINT4 CDF_FLOAT CDF_REAL4 CDF_DOUBLE CDF_REAL8 CDF_EPOCH CDF_LONG_EPOCH If no type is specified, CDF_FLOAT is assumed. CDF_LONG_EPOCH represents the CDF_EPOCH16 data type. ALLOCATERECS Set this keyword equal to the desired number of pre-allocated records for this variable in a SINGLE_FILE CDF file. Pre-allocating records ensure that variable data is stored contiguously in the CDF file. For discussion about allocating records, see section 2.3.12 ("Records") of the CDF User's Guide. DIMENSIONS Set this keyword to create a new zVariable with the specified dimensions. For example: id = CDF_CREATE("cdffile.cdf", [100] ) zid = CDF_VARCREATE(id, "Zvar", [1,1,1], DIM=[10,20,30], /ZVARIABLE) NUMELEM The number of elements of the data type at each variable value. This keyword only has meaning for string data types (CDF_CHAR, CDF_UCHAR). This is the number of characters in the string. The default is 1. REC_NOVARY If this keyword is set, all records will contain the same information. REC_VARY If this keyword is set, all records will contain unique data. This is the default. ZVARIABLE If this keyword is not set, a variable is assumed to be a rVariable. rVariable is a subset of zVariable, and it's highly recommended that variable should always be created as zVariable since it's much more efficient than rVariables. A variable is assumed to be a zVariable if its dimensions are specified by the DIMENSIONS keyword. If the dimension is not specified in the DIMENSIONS keyword, the variable is assumed to be a scalar (0-dimension). For example: id = CDF_CREATE("cdffile.cdf") zid1 = CDF_VARCREATE(id, "Zvar1", /ZVARIABLE) zid2 = CDF_VARCREATE(id, "Zvar2", ['VARY','VARY'], DIM=[3,10], /CDF_INT2, /ZVARIABLE) Examples Example 1 In this example, we create a CDF file to record the data retrieved from an array of temperature and salinity detectors. There is a 3 x 4 array of detectors at two depths, 10.0 meters and 20.2 meters: id = CDF_CREATE("temp_salinity.cdf", [3,4], /NETWORK_ENCODING, $ /SUN_DECODING, /CLOBBER) temp_id =CDF_VARCREATE(id, "Temperature", ['Vary', 'Vary'], $ /REC_VARY,/CDF_FLOAT) depth_id = CDF_VARCREATE(id, "Depth", [0,0], /REC_VARY, /CDF_FLOAT, $ /ZVARIABLE) sal_id = CDF_VARCREATE(id, "Salinity", [1,1], /REC_VARY, /CDF_DOUBLE, /ZVARIABLE) ; Create and fill the UNITS attribute: units_att = CDF_ATTCREATE(id, 'UNITS', /VARIABLE) CDF_ATTPUT, id, 'UNITS', 'Depth', 'Meters' CDF_ATTPUT, id, 'UNITS', temp_id, 'Kelvin' CDF_ATTPUT, id, units_att, sal_id, 'Percent' ; Create and write some fictitious data: data1 = 20.0 + FINDGEN(3,4) CDF_VARPUT, id, varid, data1 ; IDL will handle the type conversion, CDF will set all values ; of this record to a depth of 10.0. CDF_VARPUT, id, depth_id, '10.0' CDF_VARPUT, id, depth_id, 20.2,rec_start=1 ; Set the second depth. CDF_VARPUT, id, sal_id, DINDGEN(3,4)/10.0 ; Make more fictitious data. ; Demonstrate the non-variance of depth by retrieving the ; values. On the first pass, use CDF_VARGET1 to retrieve ; single values: CDF_VARGET1, id, depth_id, pth_0 ; Get single values. CDF_VARGET1, id, depth_id, depth_1, REC_START=1 ; Get single values. HELP, depth_0, depth_1 ; Now retrieve the full depth records: CDF_VARGET, id, depth_id, depth, REC_COUNT=2 ;Examine the depth variable: HELP, depth PRINT, depth IDL Output DEPTH_0 FLOAT = 10.0000 DEPTH_1 FLOAT = 20.2000 DEPTH FLOAT = Array(3, 4, 2) 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 Example 2 In this example, we create a variable, setting the data type from a string variable, which could have been returned by the DATATYPE keyword to a CDF_VARINQ call: VARTYPE = 'CDF_FLOAT' ; Use the _EXTRA keyword and the CREATE_STRUCT function to ; make the appropriate keyword. VarId = CDF_VARCREATE(Id, 'Pressure', [1,1], $ NUMELEM=2, _EXTRA=CREATE_STRUCT(VARTYPE,1)) CDF_CLOSE, id ; Close the CDF file. Version History Introduced: Pre 4.0