MAN page from Fedora 26 netcdf-mpich-22.214.171.124-4.fc26.i686.rpm
Section: UNIDATA UTILITIES (1)
ncdump - Convert netCDF file to text form (CDL)
The ncdump utility generates a text representation of aspecified netCDF file on standard output, optionally excluding some orall of the variable data in the output. The text representation is ina form called CDL (network Common Data form Language) that can beviewed, edited, or serve as input to ncgen, a companion programthat can generate a binary netCDF file from a CDL file. Hencencgen and ncdump can be used as inverses to transform thedata representation between binary and text representations. Seencgen documentation for a description of CDL and netCDFrepresentations.
ncdump may also be used to determine what kind of netCDF file is used(which variant of the netCDF file format) with the -k option.
If DAP support was enabled when ncdump was built, the file namemay specify a DAP URL. This allows ncdump to access data sourcesfrom DAP servers, including data in other formats than netCDF. Whenused with DAP URLs, ncdump shows the translation from the DAPdata model to the netCDF data model.
ncdump may also be used as a simple browser for netCDF datafiles, to display the dimension names and lengths; variable names, types,and shapes; attribute names and values; and optionally, the values ofdata for all variables or selected variables in a netCDF file. FornetCDF-4 files, groups and user-defined types are also included inncdump output.
ncdump uses `_' to represent data values that are equal to the`_FillValue' attribute for a variable, intended to represent data thathas not yet been written. If a variable has no `_FillValue'attribute, the default fill value for the variable type is used unlessthe variable is of byte type.
ncdump defines a default display format used for each type ofnetCDF data, but this can be changed if a `C_format' attribute isdefined for a netCDF variable. In this case, ncdump will usethe `C_format' attribute to format each value. For example, iffloating-point data for the netCDF variable `Z' is known to beaccurate to only three significant digits, it would be appropriate touse the variable attribute
- Z:C_format = "%.3g"
- Show the values of coordinate variables (1D variables with thesame names as dimensions) as well as the declarations of alldimensions, variables, attribute values, groups, and user-definedtypes. Data values of non-coordinate variables are not included inthe output. This is usually the most suitable option to use for a brief lookat the structure and contents of a netCDF file.
- Show only the header information in the output, that is, output onlythe declarations for the dimensions, variables, attributes,groups, and user-defined types of the input file, but no data values forany variables. The output is identical to using the -c option exceptthat the values of coordinate variables are not included. (At most one of-c or -h options may be present.)
- -v var1,...
- The output will include data values for the specified variables, inaddition to the declarations of all dimensions, variables, andattributes. One or more variables must be specified by name in thecomma-delimited list following this option. The list must be a singleargument to the command, hence cannot contain unescaped blanks orother white space characters. The named variables must be validnetCDF variables in the input-file. A variable within a group in anetCDF-4 file may be specified with an absolute path name, such as`/GroupA/GroupA2/var'. Use of a relative path name such as `var' or`grp/var' specifies all matching variable names in the file. Thedefault, without this option and in the absence of the -c or-h options, is to include data values for all variables inthe output.
- -b [c|f]
- A brief annotation in the form of a CDL comment (text beginning with thecharacters ``//'') will be included in the data section of the output foreach `row' of data, to help identify data values for multidimensionalvariables. If lang begins with `C' or `c', then C languageconventions will be used (zero-based indices, last dimension varyingfastest). If lang begins with `F' or `f', then Fortran languageconventions will be used (one-based indices, first dimension varyingfastest). In either case, the data will be presented in the same order;only the annotations will differ. This option may be useful for browsingthrough large volumes of multidimensional data.
- -f [c|f]
- Full annotations in the form of trailing CDL comments (text beginningwith the characters ``//'') for every data value (except individualcharacters in character arrays) will be included in the data section.If lang begins with `C' or `c', then C language conventions willbe used. If lang begins with `F' or `f', then Fortran languageconventions will be used. In either case, the data will be presentedin the same order; only the annotations will differ. This option maybe useful for piping data into other filters, since each data valueappears on a separate line, fully identified. (At most one of '-b' or '-f' options may be present.)
- -l length
- Changes the default maximum line length (80) used in formatting lists ofnon-character data values.
- -n name
- CDL requires a name for a netCDF file, for use by ncgen -b ingenerating a default netCDF file name. By default, ncdump constructsthis name from the last component of the file name of the input netCDF fileby stripping off any extension it has. Use the -n option to specify adifferent name. Although the output file name used by ncgen -b can bespecified, it may be wise to have ncdump change the default name toavoid inadvertently overwriting a valuable netCDF file when usingncdump, editing the resulting CDL file, and using ncgen -b togenerate a new netCDF file from the edited CDL file.
- -p float_digits[,double_digits]
- Specifies default precision (number of significant digits) to use indisplaying floating-point or double precision data values forattributes and variables. If specified, this value overrides thevalue of the C_format attribute, if any, for a variable.Floating-point data will be displayed with float_digitssignificant digits. If double_digits is also specified,double-precision values will be displayed with that many significantdigits. In the absence of any -p specifications, floating-pointand double-precision data are displayed with 7 and 15 significantdigits respectively. CDL files can be made smaller if less precisionis required. If both floating-point and double precisions arespecified, the two values must appear separated by a comma (no blanks)as a single argument to the command. (To represent every last bit ofprecision in a CDL file for all possible floating-point valueswould require -p 9,17.)
- Show kind of netCDF file the pathname references, one of`classic', `64-bit offset',`netCDF-4', or `netCDF-4 classic model'. Before version3.6, there was only one kind of netCDF file, designated as `classic'(also know as format variant 1). Large file support introducedanother variant of the format, designated as `64-bit offset' (known asformat variant 2). NetCDF-4, uses a third variant of the format,`netCDF-4' (format variant 3). Another format variant, designated`netCDF-4 classic model' (format variant 4), is restrictedto features supported by the netCDF-3 data model but represented usingthe HDF5 format, so that an unmodified netCDF-3 program can read orwrite the file just by relinking with the netCDF-4 library. The string output by using the `-k' option may be provided as thevalue of the `-k' option to ncgen(1) tospecify exactly what kind of netCDF file to generate, when you want tooverride the default inferred from the CDL.
- Output special virtual attributes that provide performance-relatedinformation about the file format and variable properties for netCDF-4data. These special virtual attributes are not actually part of thedata, they are merely a convenient way to display miscellaneousproperties of the data in CDL (and eventually NcML). They include `_ChunkSizes', `_DeflateLevel', `_Endianness', `_Fletcher32', `_Format',`_NoFill',`_Shuffle', and`_Storage'. `_ChunkSizes' is a list of chunk sizes for each dimension of the variable. `_DeflateLevel' is aninteger between 0 and 9 inclusive if compression has been specifiedfor the variable.`_Endianness' is either `little' or `big', depending onhow the variable was stored when first written. `_Fletcher32' is `true' if the checksum property was set forthe variable. `_Format' is a global attribute specifying the netCDF formatvariant, one of `classic', `64-bit offset', `netCDF-4', or `netCDF-4classic model'. `_NoFill' is `true' if the persistent NoFill property was set for thevariable when it was defined.`_Shuffle' is `true' if use of the shuffle filter was specified for the variable.`_Storage' is `contiguous' or `chunked', depending on how thevariable's data is stored.
- Controls display of time data, if stored in a variable that usesa udunits compliant time representation such as `days since1970-01-01' or `seconds since 2009-03-15 12:01:17', a variableidentified in a "bounds" attribute of such a time variable, or a numericattribute of a time variable. If this option isspecified, time data values are displayed as human-readable date-timestrings rather than numerical values, interpreted in terms of a `calendar' variable attribute, if specified. For numeric attributesof time variables, the human-readable time value is displayed after theactual value, in an associated CDL comment. Calendar attributevalues interpreted with this option include the CF Conventions values`gregorian' or `standard', `proleptic_gregorian', `noleap' or `365_day',`all_leap' or `366_day', `360_day', and `julian'.
- Same as the '-t' option, except output time data as date-time stringswith ISO-8601 standard 'T' separator, instead of a blank.
- -g grp1,...
- For netCDF-4 files, the output will include data values only for thespecified groups. One or more groups must be specified by name in thecomma-delimited list following this option. The list must be a singleargument to the command. The named groups must be valid netCDF groupsin the input-file. A group in a netCDF-4 file may be specified withan absolute or relative path name. Use of a relative path namespecifies all matching group names in the file. The default, withoutthis option and in the absence of the -c or -h options, isto include data values for all groups in the output.
- For file names that request remote access using DAP URLs, access datawith client-side caching of entire variables.
- Output XML (NcML) instead of CDL. The NcML does not include data values.The NcML output option currently only works for netCDF classic model data.
Look at the structure of the data in the netCDF file `foo.nc':
- ncdump -c foo.nc
Produce an annotated CDL version of the structure and data in thenetCDF file `foo.nc', using C-style indexing for the annotations:
- ncdump -b c foo.nc > foo.cdl
Output data for only the variables `uwind' and `vwind' from the netCDF file`foo.nc', and show the floating-point data with only three significantdigits of precision:
- ncdump -v uwind,vwind -p 3 foo.nc
Produce a fully-annotated (one data value per line) listing of the data forthe variable `omega', using Fortran conventions for indices, and changing thenetCDF dataset name in the resulting CDL file to `omega':
- ncdump -v omega -f fortran -n omega foo.nc > Z.cdl
Character arrays that contain a null-byte are treated like C strings, so nocharacters after the null byte appear in the output.
Multidimensional character string arrays are not handled well, since the CDLsyntax for breaking a long character string into several shorter lines isweak.
There should be a way to specify that the data should be displayed in`record' order, that is with the all the values for `record' variablestogether that have the same value of the record dimension.
- SEE ALSO
This document was created byman2html,using the manual pages.