NCDF_PARSE
The NCDF_PARSE function recursively descends through a NetCDF-3 or NetCDF-4 file and creates an ordered hash containing object information and data.
Tip: The NetCDF-4 format is similar to the HDF5 format, so technically this routine can also parse HDF5 files. However, we recommend using H5_PARSE with HDF5 files.
Tip: For an example of reading GOES-16 data using NCDF_PARSE, see GOES-16 on a Map in the images gallery.
Example
The following example shows how to parse a file and to use implied print to view the tags of the ordered hash:
IDL> file = FILEPATH('sample.nc', SUBDIR=['examples','data'])
IDL> result = NCDF_PARSE(file)
IDL> result
IDL prints:
{
"_NAME": "/usr/local/idl/examples/data/sample.nc",
"_TYPE": "GROUP",
"_FILE": "/usr/local/idl/examples/data/sample.nc",
"_PATH": "/",
"image": {
"_NAME": "image",
"_TYPE": "VARIABLE",
"_PATH": "/",
"_NDIMENSIONS": 2,
"_DIMENSION_NAMES": ["y", "x"],
"_DIMENSIONS": [768, 512],
"_DATATYPE": "BYTE",
"_DATA": "<unread>",
"TITLE": {
"_NAME": "TITLE",
"_TYPE": "ATTRIBUTE",
"_PATH": "/image",
"_DATATYPE": "CHAR",
"_LENGTH": 14,
"_DATA": "New York City"
}
},
"_NDIMENSIONS": 3,
"_DIMENSION_NAMES": ["x", "y", "z"],
"_DIMENSIONS": [512, 768, 0],
"_N_UNLIM_DIMS": 1,
"_UNLIM_DIM_NAMES": ["z"],
"_UNLIM_DIMS": [0],
"TITLE": {
"_NAME": "TITLE",
"_TYPE": "ATTRIBUTE",
"_PATH": "/",
"_DATATYPE": "CHAR",
"_LENGTH": 26,
"_DATA": "Incredibly Important Data"
},
"GALAXY": {
"_NAME": "GALAXY",
"_TYPE": "ATTRIBUTE",
"_PATH": "/",
"_DATATYPE": "CHAR",
"_LENGTH": 10,
"_DATA": "Milky Way"
},
"PLANET": {
"_NAME": "PLANET",
"_TYPE": "ATTRIBUTE",
"_PATH": "/",
"_DATATYPE": "CHAR",
"_LENGTH": 6,
"_DATA": "Earth"
}
}
Here is an example of accessing the data within an ordered hash:
IDL> print, result['GALAXY', '_DATA'] ; use array indexing to retrieve this element
IDL prints:
Milky Way
Syntax
Result = NCDF_PARSE(File, [/ READ_DATA])
Return Value
The Result is an ordered hash containing the parsed file. The tags in the hash depend upon the object type, as outlined in the tables below.
Tags associated with the top-level hash
|
Tag |
Description |
|---|---|
|
_FILE |
The filename to which the object belongs |
Tags common to all object types
|
Tag |
Description |
|---|---|
|
_NAME |
Object name (filename for the top level) |
|
_TYPE |
Object type. The possible values are GROUP, VARIABLE, or ATTRIBUTE. |
|
_PATH |
The full path within the file to the object. If the object is at the top level, then this field is set to ' |
Tags associated with groups
|
Tag |
Description |
|---|---|
|
_NDIMENSIONS |
Number of dimensions within the group |
|
_DIMENSION_NAMES |
Names of dimensions within the group. If the number of dimensions in the group is zero, then this field is set to an empty string. |
| _DIMENSIONS | Size of all dimensions in the group. If the number of dimensions in the group is zero, then this field is set to -1. |
|
_N_UNLIM_DIMS |
Number of unlimited dimensions in the group |
|
_UNLIM_DIM_NAMES |
Names of unlimited dimensions in the group. If there are no unlimited dimensions in the group, then this field is set to an empty string. |
|
_UNLIM_DIMS |
Size of the unlimited dimension(s) in the group. If there are no unlimited dimensions in the group, then this field is set to -1. |
Tags Associated with variables
|
Tag |
Description |
|---|---|
|
_NDIMENSIONS |
Number of dimensions associated with the variable |
|
_DIMENSION_NAMES |
Names of the variable's dimensions |
|
_DIMENSIONS |
Size of the variable's dimensions |
|
_DATATYPE |
The variable data type. Possible data types are BYTE, CHAR, INT, LONG, FLOAT, or DOUBLE. |
|
_DATA |
If the READ_DATA keyword is set, this field will contain the data from the variable. Otherwise, it contains the string |
Tags associated with attributes
|
Tag |
Description |
|---|---|
|
_DATATYPE |
Data type of the attribute. Possible values are BYTE, CHAR, INT, LONG, FLOAT, or DOUBLE. |
|
_LENGTH |
The number of values stored in the attribute. If the attribute is a string, the number of values indicates one more character than the string length to include the terminating null character. This is the NetCDF convention. |
|
_DATA |
The value of the attribute. The attribute value is always read regardless of whether the READ_DATA keyword is set. |
Arguments
File
A string that specifies the file to be parsed.
Keywords
READ_DATA
If you set this keyword, all data from NetCDF variables will be read from the file. If you do not set this keyword, the _DATA field for variables will be set to the string '<unread>'.
Version History
|
8.5.2 |
Introduced |