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 <unread>.

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