The CDF_READVARIABLE function reads full information from a Common Data Format file's variable. The information includes the basic information, variable attributes and all data. The retrieved info will be in a key/value hash table. The value(s) can be a nested hash of hashes (HOHs).
Examples
The following examples show how CDF_READVARIABLE can be used.
id = CDF_OPEN('a1_k0_mpa_20050804_v02')
var = CDF_READVARIABLE(id, 'Epoch')
var = CDF_READVARIABLE('a1_k0_mpa_20050804_v02', 'Epoch')
var.keys()
[
"VarInfo",
"VarAttrs",
"VarData"
]
PRINT, var['VarInfo']
DataType: CDF_EPOCH
NumElems: 1
RecVary: VARY
NumDims: 2
DimSizes: 2 3
DimVary: NOVARY ...
NumWrittenRecs: 991
PRINT, var['VarInfo', 'DimVary']
NOVARY NOVARY
PRINT, var['VarAttrs']
FIELDNAM: Time
VALIDMIN: 62879846400000.000
VALIDMAX: 63776678399000.000
SCALEMIN: 62879846400000.000
SCALEMAX: 63776678399000.000
CATDESC: Time of proton collection (electrons 21.5 seconds later)
UNITS: ms
MONOTON: INCREASE
FILLVAL: -9.9999999999999996e+30
VAR_TYPE: support_data
DICT_KEY:
LABLAXIS: Epoch
AVG_TYPE:
DISPLAY_TYPE:
VAR_NOTES:
PRINT, var['VarData']
6.3290333e+13 6.3290333e+13
6.3290333e+13 6.3290333e+13
6.3290333e+13 6.3290333e+13
6.3290333e+13 6.3290333e+13
6.3290333e+13 6.3290333e+13
6.3290333e+13 6.3290333e+13
6.3290333e+13 6.3290333e+13
6.3290333e+13 6.3290333e+13
6.3290333e+13 6.3290333e+13
6.3290333e+13 6.3290333e+13
6.3290333e+13 6.3290333e+13
6.3290333e+13 6.3290333e+13
...
var2 = CDF_READVARIABLE('a1_k0_mpa_20050804_v02', 0, /ENCODING, /ZMODE2)
PRINT, var2['VarInfo']
DataType: CDF_EPOCH
NumElems: 1
RecVary: VARY
NumDims: 0
NumWrittenRecs: 991
PRINT, var2['VarAttrs']
FIELDNAM: Time
VALIDMIN: 1992-08-01T00:00:00.000
VALIDMAX: 2020-12-31T23:59:59.000
SCALEMIN: 1992-08-01T00:00:00.000
SCALEMAX: 2020-12-31T23:59:59.000
CATDESC: Time of proton collection (electrons 21.5 seconds later)
UNITS: ms
MONOTON: INCREASE
FILLVAL: -9.9999999999999996e+30
VAR_TYPE: support_data
DICT_KEY:
LABLAXIS: Epoch
AVG_TYPE:
DISPLAY_TYPE:
VAR_NOTES:
PRINT, var2['VarData']
6.3290333e+13
6.3290333e+13
6.3290333e+13
6.3290333e+13
6.3290333e+13
6.3290333e+13
...
CDF_READVARIABLE('a1_k0_mpa_20050804_v02', 'Epoch', /META, /ENCOD)
{
"Epoch": {
"FIELDNAM": "Time",
"VALIDMIN": "1992-08-01T00:00:00.000",
"VALIDMAX": "2020-12-31T23:59:59.000",
"SCALEMIN": "1992-08-01T00:00:00.000",
"SCALEMAX": "2020-12-31T23:59:59.000",
"CATDESC": "Time of proton collection (electrons 21.5 seconds later)",
"UNITS": "ms",
"MONOTON": "INCREASE",
"FILLVAL": -9.9999999999999996e+30,
"VAR_TYPE": "support_data",
"DICT_KEY": " ",
"LABLAXIS": "Epoch",
"AVG_TYPE": " ",
"DISPLAY_TYPE": " ",
"VAR_NOTES": " "
}
}
Syntax
Result = CDF_READVARIABLE( Id, Variable [, /DATAONLY] [, /ENCODING] [, /INFO] [, REC_COUNT=...] [, REC_START=...] [, /STRING] [, /TO_COLUMN_MAJOR] [, /VARATTRS] [, /ZMODE2] [, /ZVARIABLE] )
Return Value
If successful, a hash with the requested information from the variable in a CDF is returned.
There are fixed keys and variable keys. They are all case-sensitive strings. The fixed keys include VarInfo, VarAttrs and VarData. The variables keys are variable attribute names and variable names.
Arguments
Id
The CDF name or ID (returned from a previous call to CDF_OPEN or CDF_CREATE). If a CDF name is entered, the file will be closed after the operation is done.
Variable
A string containing the name of the variable or the variable number being read.
Keywords
DATAONLY
Set this keyword to ignore the variable's basic information and attributes, but only read the variable's data. The key for the returned hash is the variable name.
ENCODING
Set this keyword to encode the variable's attributes or basic information. It will convert variable's pad value or attributes' data to an encoded form. This is mainly used for the values of CDF epoch type.
INFO
Set this keyword to read only the basic information from a CDF and all variables in it. The key for the returned hash is the variable name.
REC_COUNT
Set this keyword to the number of records to read. If not specified, all records, starting from REC_START will be read. At least one record will be returned, even it is a virtual record.
REC_START
Set this keyword to the starting record number to read. If not specified, the variable's first record, record number 0, is assumed.
STRING
Set this keyword to return a variable's data of CDF_CHAR or CDF_UCHAR type from the CDF file as a string rather than byte data. This keyword is ignored if the variable data is not of type CDF_CHAR or CDF_UCHAR.
TO_COLUMN_MAJOR
Set this keyword to convert the returned value from row-major form to column-major form. When this keyword is used with an ISTP-compliant CDF file, the dimensions defined in the variable attribute DEPEND_1, DEPEND_2, etc., will match the returned data. This keyword is only applicable when reading full variable records.
VARATTRS
Set this keyword to read only the variable's metadata. The key for the returned hash is the variable name. If there is no metadata for the variable, an empty hash is returned.
ZMODE2
Set the zMODE on so a rVariable is going to be handled as a zVariable and its non-varying dimension(s) will not be shown. ZMODE2 and ZVARIABLE are mutually exclusive.
ZVARIABLE
If Variable is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that Variable is an rVariable ID. This keyword and ZMODE2 are mutually exclusive.
Version History